Add draft changelog file and migration blurb

diff --git a/doc/build/changelog/migration_13.rst b/doc/build/changelog/migration_13.rst
index c133bd6620c8d22a7597bb891a41b3534bdbf8fa..946ef1ba5327861eccb138b09d2ed4fcdcee165b 100644 (file)
--- a/doc/build/changelog/migration_13.rst
+++ b/doc/build/changelog/migration_13.rst
@@ -1662,3 +1662,40 @@ primary key column::
 :ticket:`4362`
 
 :ticket:`4235`
+
+Changed StatementError formatting (newlines and %s) 
+=================================================================================
+
+Two changes are introduced to ``StatementError``'s string representation.
+
+#. Previously: single line.
+   Now: each "detail" on it's own line.
+#. Previously: SQL in the message was emitted using ``__repr__``
+   Now: SQL in the message is emitted using ``__str__``
+
+This means that an error message that previously looked like this:
+    
+    sqlalchemy.exc.StatementError: (sqlalchemy.exc.InvalidRequestError) A value is required for bind parameter 'id' [SQL: 'select * from reviews where id = %(id)s'] (Background on this error at: http://sqlalche.me/e/cd3x)
+
+    (sqlalchemy.exc.InvalidRequestError) A value is required for bind parameter 'id' [SQL: 'select * from reviews where id = %(id)s'] (Background on this error at: http://sqlalche.me/e/cd3x)
+
+Will now look like this:
+
+    sqlalchemy.exc.StatementError: (sqlalchemy.exc.InvalidRequestError) A value is required for bind parameter 'id'
+    [SQL: select * from reviews where id = %(id)s]
+    (Background on this error at: http://sqlalche.me/e/cd3x)
+    
+    (sqlalchemy.exc.InvalidRequestError) A value is required for bind parameter 'id'
+    [SQL: select * from reviews where id = %(id)s]
+    (Background on this error at: http://sqlalche.me/e/cd3x)
+
+The primary impact of this change is that consumers can no longer assume:
+
+#. an exception message is on a single line
+#. SQL contained in an exception message will be escaped and on a single line.
+
+SQL being rendered with ``__str__`` instead of ``__repr__`` is the more interesting of the two.
+For one example, newlines will actually be rendered instead of escaped.
+
+:ticket:`4500`
+

diff --git a/doc/build/changelog/unreleased_13/4500.rst b/doc/build/changelog/unreleased_13/4500.rst
new file mode 100644 (file)
index 0000000..70792e1
--- /dev/null
+++ b/doc/build/changelog/unreleased_13/4500.rst
@@ -0,0 +1,18 @@
+.. change::
+   :tags: errors
+   :tickets: 4500
+
+   Change StatementError formatting (newlines and %s)
+    
+   This changes the error formatting for StatementError in two ways:
+   
+   1) Break each error detail up over multiple newlines instead of
+      spaced out on a single line. Hopefully, this helps readers scan
+      the error message more easily.
+   
+   2) Change the SQL representation in the message to use __str__ (%s)
+      instead of the current behavior that uses __repr__ (%r). This
+      should help readers recognize the structure of their SQL,
+      particularly if it is a multiline SQL statement. In the multiline
+      case, the SQL would be printed over multiple lines instead of
+      printing an escaped "\n".