SA14: Final adjustments to the changelog

Author: amotl

CHANGES.txt

@@ -22,7 +22,13 @@ Unreleased
 - Added support for enabling SSL using SQLAlchemy DB URI with parameter
   ``?ssl=true``.
 
-- Add support for SQLAlchemy 1.4
+- Added support for SQLAlchemy 1.4
+
+.. note::
+
+    For learning about the transition to SQLAlchemy 1.4, we recommend the
+    corresponding documentation `What’s New in SQLAlchemy 1.4?`_.
+
 
 
 Breaking changes
@@ -31,31 +37,29 @@ Breaking changes
 Textual column expressions
 ''''''''''''''''''''''''''
 
-On the update to SQLAlchemy 1.4, some test cases had to be adjusted in order
-to compensate for apparent additional strictness of SQLAlchemy on some details.
+SQLAlchemy 1.4 became stricter on some details. Where it was ok to use a
+textual column expression in *plain text* beforehand, a
+`SQLAlchemy literal_column`_ type should be used now. This specifically
+applies to `CrateDB system columns`_ like ``_score``.
 
-Where it was ok to use a textual column expression in plain text beforehand,
-a `SQLAlchemy literal_column`_ type should be used now. Otherwise, for example
-when accessing `CrateDB system columns`_ like ``_score``, the engine might
-complain like::
+For example, when a query might have looked like this beforehand::
 
-    sqlalchemy.exc.ArgumentError: Textual column expression '_score' should be
-    explicitly declared with text('_score'), or use column('_score') for more
-    specificity
+    session.query(Character.name, '_score')
 
-The changes to be made look like this::
+it should now be written like::
 
-    old: session.query(Character.name, '_score')
-    new: session.query(Character.name, sa.literal_column('_score'))
+    session.query(Character.name, sa.literal_column('_score'))
 
-::
+Otherwise, SQLAlchemy will complain like::
 
-    old: .order_by(sa.desc(sa.text('_score')))
-    new: .order_by(sa.desc(sa.literal_column('_score')))
+    sqlalchemy.exc.ArgumentError: Textual column expression '_score' should be
+    explicitly declared with text('_score'), or use column('_score') for more
+    specificity
 
 
-.. _SQLAlchemy literal_column: https://docs.sqlalchemy.org/en/14/core/sqlelement.html#sqlalchemy.sql.expression.literal_column
 .. _CrateDB system columns: https://crate.io/docs/crate/reference/en/4.8/general/ddl/system-columns.html
+.. _SQLAlchemy literal_column: https://docs.sqlalchemy.org/en/14/core/sqlelement.html#sqlalchemy.sql.expression.literal_column
+.. _What’s New in SQLAlchemy 1.4?: https://docs.sqlalchemy.org/en/14/changelog/migration_14.html
 
 
 2020/09/28 0.26.0