fixup! Support: Add dedicated documentation page about poly-fills and…

… utilities

docs/support.md

@@ -14,6 +14,12 @@ hogs.
 
 ## Synthetic Autoincrement using Timestamps
 
+:::{rubric} Introduction
+:::
+Todo.
+
+:::{rubric} Utility
+:::
 In order to emulate some kind of autoincrement behavior, this poly-fill patch
 will simply assign `sa.func.now()` as a column `default`. You can use it if
 adjusting ORM models is out of reach for your database adapter at hand.
@@ -40,10 +46,15 @@ class FooBar(Base):
 
 ## Synthetic UNIQUE Constraints
 
+:::{rubric} Introduction
+:::
 CrateDB does not provide `UNIQUE` constraints. Because of its distributed
-nature, it would be an expensive operation. This feature emulates corresponding
-functionality by querying the table for unique values before invoking the SQL
-`INSERT` operation. 
+nature, it would be an expensive operation.
+
+:::{rubric} Utility
+:::
+This feature emulates corresponding functionality by querying the table for
+unique values before invoking the SQL `INSERT` operation.
 
 When the uniqueness constraint is violated, the adapter will raise a
 corresponding exception.
@@ -73,8 +84,10 @@ listen(FooBar, "before_insert", check_uniqueness_factory(FooBar, "name"))
 ```
 
 
-## Automatic Table REFRESH
+## Automatic Table REFRESH after DML
 
+:::{rubric} Introduction
+:::
 CrateDB is [eventually consistent]. Data written with a former statement is
 not guaranteed to be fetched with the next following select statement for the
 affected rows.
@@ -84,23 +97,34 @@ by default, and can be changed), there are situations where stronger
 consistency is required, for example when needing to satisfy test suites
 of 3rd party frameworks, which usually do not take special needs of CrateDB
 into consideration. More details can be found in the reference documentation
-at [](inv:crate-reference#refresh_data).
+about [table refreshing](inv:crate-reference#refresh_data).
+
+:::{rubric} Utility
+:::
+The `refresh_after_dml` utility will configure an SQLAlchemy engine or session
+to automatically invoke relevant `REFRESH TABLE` statements after each DML
+operation (INSERT, UPDATE, DELETE), for the corresponding entities / tables.
 
 Please note refreshing the table after each DML operation can cause serious
 performance degradation, and should only be used on low-volume, low-traffic
 data, when applicable, and if you know what you are doing.
 
 ```python
 import sqlalchemy as sa
-from sqlalchemy.orm import declarative_base
 from sqlalchemy_cratedb.support import refresh_after_dml
 
-# Define database schema.
-Base = declarative_base()
+engine = sa.create_engine("crate://")
+refresh_after_dml(engine)
+```
 
-class FooBar(Base):
-    id = sa.Column(sa.String, primary_key=True)
-    name = sa.Column(sa.String)
+```python
+import sqlalchemy as sa
+from sqlalchemy.orm import sessionmaker
+from sqlalchemy_cratedb.support import refresh_after_dml
+
+engine = sa.create_engine("crate://")
+session = sessionmaker(bind=engine)()
+refresh_after_dml(session)
 ```