How corridor/sqlalchemy-history works
1. What this repository is
- sqlalchemy-history is a SQLAlchemy ORM extension for audit/version tracking.
- It is a library, not an application: user models opt in with __versioned__, and the package injects history tables, transaction records, and version-aware relationships.
2. Public integration boundary
- The main entry point is the package root (sqlalchemy_history/__init__.py) plus a make_versioned(...)-style setup API described in the README.
- The user’s application must call versioning setup before mapper configuration, then define normal SQLAlchemy models with versioning metadata.
3. Core orchestration layer
- factory.py, manager.py, and unit_of_work.py appear to coordinate the runtime lifecycle of versioning.
- This layer is the bridge between SQLAlchemy mapper/session events and the internal history machinery: it decides what gets tracked, when history rows are produced, and how transactions are grouped.
4. Schema and model generation
- table_builder.py, model_builder.py, builder.py, and schema.py generate the versioning infrastructure around user models.
- They create the companion version tables, transaction tables, and mapped history classes that mirror the original model structure.
- relationship_builder.py handles relationship-specific version metadata so object graphs can be reconstructed over time.
5. How change data is captured
- operation.py, transaction.py, fetcher.py, and version.py represent the captured audit data and the mechanics of persisting it.
- The flow is: ORM mutation happens on a versioned object, the session flush/commit cycle is observed, changed attributes are detected, and a version row plus transaction metadata are written.
6. Attribute and query reconstruction
- expression_reflector.py and utils.py support translating SQLAlchemy expressions and object state into history-aware equivalents.
- This is what enables temporal querying and “what did this object look like at transaction X?” style access.
7. Reversion subsystem
- reverter.py is the rollback/restore engine.
- It uses the stored version history to restore scalar fields and related objects, including cases where the original object was deleted.
- This makes revert a first-class workflow, not just a read-only audit log.
8. Plugin architecture
- plugins/base.py defines the extension contract, and the concrete plugins are small, focused behaviors:
- activity.py for activity/user context,
- null_delete.py for delete handling semantics,
- property_mod_tracker.py for per-field modification tracking,
- transaction_changes.py for transaction-level change aggregation,
- transaction_meta.py for extra transaction metadata.
- The design suggests composable feature slices rather than one monolithic auditing path.
9. Async support boundary
- The README and tests/sqlalchemy_async/ show explicit async support.
- The versioning core is designed to work with both sync SQLAlchemy sessions and async engines/sessions, with querying and revert behavior preserved in async workflows.
10. Database and migration concerns
- The test matrix and docs reference SQLite, PostgreSQL, MSSQL, Oracle, and Alembic.
- This implies the architecture is intentionally database-portable and avoids backend-specific assumptions where possible.
- tests/databases/ contains docker-compose files for cross-database verification.
11. Versioning strategies and compatibility
- tests/schema/ and docs/schema.md, docs/transactions.md, docs/revert.md, and docs/queries.md indicate multiple internal concerns: schema layout, transaction semantics, and history querying.
- The presence of tests/test_validity_strategy.py suggests the library supports at least one explicit strategy for deciding version validity windows.
12. Behavioral coverage in tests
- The tests are organized around architecture boundaries: builders, plugins, relationships, inheritance, revert, schema, async, and reported bugs.
- That separation reflects the main subsystems of the library and shows which areas are considered stable public behavior.
13. Tooling and delivery
- The repo uses Ruff, pre-commit, MkDocs, and GitHub Actions for CI/docs/release automation.
- These are supporting concerns only; they don’t affect runtime architecture, but they explain how the library is validated and published.
14. Mental model for a diagram
- At the center is the user’s SQLAlchemy model/session layer.
- Around it sits the versioning manager and unit-of-work pipeline, which observes ORM events, builds version tables/models, stores transaction snapshots, and exposes history/revert/query APIs.
- Plugins extend that core pipeline, while async support and cross-database compatibility constrain the whole design.
Main entry points: version.py Version · base.py Plugin Base · builder.py Builder · transaction.py Transaction
Components 22
Public API
Entry points and integration setup for user applications.
- Package API · Public package surface and setup entry point.
sqlalchemy_history/__init__.py
Runtime Core
Event-driven orchestration that bridges SQLAlchemy lifecycle events to history capture.
- Factory · Creates and wires versioning infrastructure.
sqlalchemy_history/factory.py - Manager · Coordinates mapper/session integration and versioning state.
sqlalchemy_history/manager.py - Unit of Work · Tracks flush/commit lifecycle and groups changes into transactions.
sqlalchemy_history/unit_of_work.py
Schema Builders
Builds version tables, mapped history classes, and relationship metadata.
- Builder · High-level composition layer for schema and model generation.
sqlalchemy_history/builder.py - Schema · Defines versioning schema conventions and configuration.
sqlalchemy_history/schema.py - Table Builder · Generates companion version tables for mapped models.
sqlalchemy_history/table_builder.py - Model Builder · Creates mapped history classes for versioned entities.
sqlalchemy_history/model_builder.py - Rel Builder · Adds version-aware relationship metadata and reconstruction hooks.
sqlalchemy_history/relationship_builder.py
History Flow
Captured audit data, queries, and revert logic.
- Operation · Represents detected ORM mutations and operation types.
sqlalchemy_history/operation.py - Transaction · Stores transaction-level audit metadata and grouping.
sqlalchemy_history/transaction.py - Version · Represents a single historical row for an entity.
sqlalchemy_history/version.py - Fetcher · Extracts current object state and changed values from ORM instances.
sqlalchemy_history/fetcher.py - Reflector · Maps SQLAlchemy expressions to history-aware equivalents.
sqlalchemy_history/expression_reflector.py - Reverter · Restores prior object and relationship state from history.
sqlalchemy_history/reverter.py - Utils · Shared helpers used across the versioning pipeline.
sqlalchemy_history/utils.py
Plugins
Composable behaviors that extend the core versioning pipeline.
- Plugin Base · Defines the extension interface for plugin behaviors.
sqlalchemy_history/plugins/base.py - Activity · Adds actor or activity context to transactions.
sqlalchemy_history/plugins/activity.py - Null Delete · Customizes delete handling semantics.
sqlalchemy_history/plugins/null_delete.py - Mod Tracker · Tracks per-field modification flags.
sqlalchemy_history/plugins/property_mod_tracker.py - Tx Changes · Aggregates changes at transaction scope.
sqlalchemy_history/plugins/transaction_changes.py - Tx Meta · Attaches extra metadata to transactions.
sqlalchemy_history/plugins/transaction_meta.py
Connections 29
- Package API → Factory: setup API · User code enters versioning through the package API and setup call.
- Factory → Manager: builds · Factory creates the central manager and wires dependencies.
- Manager → Unit of Work: drives · Manager delegates session lifecycle work to the unit of work.
- Manager → Builder: configures · Manager coordinates schema/model construction for versioned entities.
- Builder → Schema: uses · Builder applies schema conventions and configuration.
- Builder → Table Builder: creates tables · Builder delegates version table generation.
- Builder → Model Builder: creates models · Builder delegates mapped history class generation.
- Builder → Rel Builder: adds relations · Builder delegates relationship metadata handling.
- Table Builder → Version: materializes · Generated tables back the version records.
- Model Builder → Version: maps · Generated history classes represent version rows.
- Rel Builder → Reverter: supports · Relationship metadata is used when restoring object graphs.
- Unit of Work → Fetcher: captures state · Unit of work reads current object state during flush processing.
- Fetcher → Operation: detects · Fetched state is compared to derive operations.
- Operation → Transaction: groups into · Operations are associated with a transaction boundary.
- Transaction → Version: persists · Transaction metadata is linked with version rows.
- Unit of Work → Version: writes · The write path produces version rows from detected changes.
- Reflector → Utils: relies on · Expression handling uses shared helper logic.
- Reflector → Reverter: adapts queries · Reflection helps query temporal state and restore targets.
- Reverter → Version: reads history · Reverter loads prior version rows to reconstruct state.
- Plugin Base → Activity: extends · Concrete plugins implement the shared extension contract.
- Plugin Base → Null Delete: extends · Concrete plugins implement the shared extension contract.
- Plugin Base → Mod Tracker: extends · Concrete plugins implement the shared extension contract.
- Plugin Base → Tx Changes: extends · Concrete plugins implement the shared extension contract.
- Plugin Base → Tx Meta: extends · Concrete plugins implement the shared extension contract.
- Activity → Transaction: annotates · Activity plugin enriches transaction records with context.
- Mod Tracker → Version: flags fields · Modification tracking annotates versioned properties.
- Tx Changes → Transaction: aggregates · Aggregates changes at the transaction layer.
- Tx Meta → Transaction: adds metadata · Attaches extra transaction metadata.
- Null Delete → Operation: changes deletes · Delete semantics alter captured operations.