diff --git a/docs/support.md b/docs/support.md index 25ebfef..8685c66 100644 --- a/docs/support.md +++ b/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,7 +97,13 @@ 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 @@ -92,15 +111,20 @@ 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) ```