SQLAlchemy-Continuum 1.5.1__tar.gz → 1.6.0__tar.gz

{sqlalchemy_continuum-1.5.1 → sqlalchemy_continuum-1.6.0}/CHANGES.rst

@@ -7,9 +7,27 @@ Unreleased changes
 ^^^^^^^^^^^^^^^^^^
 - None currently
 
+1.6.0 (2026-01-22)
+^^^^^^^^^^^^^^^^^^
+- Add ``version_at()`` class method on version objects for efficient retrieval of the version active at a specific transaction (#376)
+- Add ``all_versions()`` class method with ``link`` option to batch fetch all versions for an entity in a single query, avoiding N+1 queries by pre-populating previous/next navigation caches (#376)
+- Add automatic composite indexes on version tables for optimized version lookups: ``(pk_columns, transaction_id DESC)`` index and ``(pk_columns, transaction_id, end_transaction_id)`` for validity strategy temporal queries (#376)
+- Add ``create_composite_index`` configuration option to control composite index creation (#376)
+
+1.5.2 (2025-10-10)
+^^^^^^^^^^^^^^^^^^
+- Add Python 3.14 support
+
 1.5.1 (2025-10-01)
 ^^^^^^^^^^^^^^^^^^
 - Fix utc_now() to return a naive datetime (#373, thanks to dawhalen)
+- Remove SQLAlchemy-Utils dependency by porting required functions to internal _compat module (#352)
+  Note: if you use SQLAlchemy-Utils directly, you may need to add it as a dependency.
+  - Port core functions: ImproperlyConfigured, get_declarative_base, naturally_equivalent
+  - Port column utilities: get_columns, get_primary_keys, identity, get_column_key
+  - Port advanced functionality: has_changes, JSONType, generic_relationship with full SQLAlchemy 2.x compatibility
+  - Maintain full backward compatibility while eliminating external dependency
+  - Reduce installation footprint and potential version conflicts
 
 1.5.0 (2025-08-30)
 ^^^^^^^^^^^^^^^^^^
@@ -28,13 +46,6 @@ Unreleased changes
 - Fix datetime.utcnow() deprecation warnings with cross-version compatibility function supporting Python 3.9-3.13+
 - Eliminate cartesian product warnings in many-to-many relationship queries with non-versioned classes
 - Improve code quality by modernizing mixed string formatting patterns to f-strings
-- **MAJOR**: Remove SQLAlchemy-Utils dependency by porting required functions to internal _compat module (#352)
-  
-  - Port core functions: ImproperlyConfigured, get_declarative_base, naturally_equivalent
-  - Port column utilities: get_columns, get_primary_keys, identity, get_column_key
-  - Port advanced functionality: has_changes, JSONType, generic_relationship with full SQLAlchemy 2.x compatibility
-  - Maintain full backward compatibility while eliminating external dependency
-  - Reduce installation footprint and potential version conflicts
 
 1.4.2 (2024-03-26)
 ^^^^^^^^^^^^^^^^^^

{sqlalchemy_continuum-1.5.1/SQLAlchemy_Continuum.egg-info → sqlalchemy_continuum-1.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: SQLAlchemy-Continuum
-Version: 1.5.1
+Version: 1.6.0
 Summary: Versioning and auditing extension for SQLAlchemy.
 Author: Mark Steward, Jose Soto
 Author-email: Konsta Vesterinen <konsta@fastmonkeys.com>
@@ -16,6 +16,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.9

{sqlalchemy_continuum-1.5.1 → sqlalchemy_continuum-1.6.0/SQLAlchemy_Continuum.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: SQLAlchemy-Continuum
-Version: 1.5.1
+Version: 1.6.0
 Summary: Versioning and auditing extension for SQLAlchemy.
 Author: Mark Steward, Jose Soto
 Author-email: Konsta Vesterinen <konsta@fastmonkeys.com>
@@ -16,6 +16,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.9

{sqlalchemy_continuum-1.5.1 → sqlalchemy_continuum-1.6.0}/SQLAlchemy_Continuum.egg-info/SOURCES.txt

@@ -53,6 +53,7 @@ sqlalchemy_continuum/plugins/null_delete.py
 sqlalchemy_continuum/plugins/property_mod_tracker.py
 sqlalchemy_continuum/plugins/transaction_changes.py
 sqlalchemy_continuum/plugins/transaction_meta.py
+tests/.DS_Store
 tests/__init__.py
 tests/test_accessors.py
 tests/test_changeset.py
@@ -64,6 +65,7 @@ tests/test_configuration.py
 tests/test_custom_schema.py
 tests/test_custom_version_base_class.py
 tests/test_delete.py
+tests/test_efficient_queries.py
 tests/test_exotic_listener_chaining.py
 tests/test_exotic_operation_combos.py
 tests/test_insert.py

{sqlalchemy_continuum-1.5.1 → sqlalchemy_continuum-1.6.0}/docs/configuration.rst

@@ -113,6 +113,12 @@ Here is a full list of configuration options:
 * strategy (default: 'validity')
     The versioning strategy to use. Either 'validity' or 'subquery'
 
+* create_composite_index (default: True)
+    Whether to automatically create composite indexes on version tables for efficient version queries.
+    The composite index is created on ``(primary_key_columns, transaction_id DESC)`` which dramatically
+    speeds up common query patterns like finding a specific version of an entity. For validity strategy,
+    an additional index on ``(primary_key_columns, transaction_id, end_transaction_id)`` is also created.
+
 
 Example
 ::

sqlalchemy_continuum-1.6.0/docs/queries.rst

@@ -0,0 +1,254 @@
+Queries
+=======
+
+
+You can query history models just like any other sqlalchemy declarative model.
+
+::
+
+    from sqlalchemy_continuum import version_class
+
+
+    ArticleVersion = version_class(Article)
+
+    session.query(ArticleVersion).filter_by(name=u'some name').all()
+
+
+How many transactions have been executed?
+-----------------------------------------
+
+::
+
+    from sqlalchemy_continuum import transaction_class
+
+
+    Transaction = transaction_class(Article)
+
+
+    Transaction.query.count()
+
+
+Querying for entities of a class at a given revision
+----------------------------------------------------
+
+
+In the following example we find all articles which were affected by transaction 33.
+
+::
+
+    session.query(ArticleVersion).filter_by(transaction_id=33)
+
+
+
+Querying for transactions, at which entities of a given class changed
+---------------------------------------------------------------------
+
+In this example we find all transactions which affected any instance of 'Article' model. This query needs the TransactionChangesPlugin.
+
+::
+
+    TransactionChanges = Article.__versioned__['transaction_changes']
+
+
+    entries = (
+        session.query(Transaction)
+        .innerjoin(Transaction.changes)
+        .filter(
+            TransactionChanges.entity_name.in_(['Article'])
+        )
+    )
+
+
+
+Querying for versions of entity that modified given property
+------------------------------------------------------------
+
+In the following example we want to find all versions of Article class which changed the attribute 'name'. This example assumes you are using
+PropertyModTrackerPlugin.
+
+::
+
+    ArticleVersion = version_class(Article)
+
+    session.query(ArticleHistory).filter(ArticleVersion.name_mod).all()
+
+
+Efficient Version Queries
+=========================
+
+SQLAlchemy-Continuum provides several methods for efficiently querying version history
+without incurring N+1 query problems.
+
+
+Querying version at a specific transaction
+------------------------------------------
+
+The ``version_at`` class method efficiently retrieves the version that was active
+at a specific transaction. This is much faster than iterating through versions manually.
+
+::
+
+    ArticleVersion = version_class(Article)
+
+    # Get the version of Article #5 that was active at transaction #100
+    version = ArticleVersion.version_at(
+        session,
+        {'id': 5},
+        transaction_id=100
+    )
+
+For the validity strategy (default), this uses an efficient range query::
+
+    WHERE transaction_id <= 100
+      AND (end_transaction_id > 100 OR end_transaction_id IS NULL)
+
+For the subquery strategy, it finds the version with the highest transaction_id <= target.
+
+
+Batch fetching all versions
+---------------------------
+
+When you need to iterate through version history, avoid the N+1 query problem by
+using ``all_versions`` instead of repeatedly accessing ``.previous`` or ``.next``:
+
+::
+
+    ArticleVersion = version_class(Article)
+
+    # Fetch all versions for Article #5 in a single query
+    versions = ArticleVersion.all_versions(
+        session,
+        {'id': 5},
+        limit=10,      # Optional: limit to 10 most recent
+        desc=True,     # Newest first (default)
+        link=True      # Pre-populate previous/next caches (default)
+    )
+
+    # Now iteration doesn't trigger additional queries
+    for version in versions:
+        print(version.changeset)
+        print(version.previous)  # Uses cached value, no additional query!
+
+
+When ``link=True`` (the default), the returned versions will have their ``.previous``
+and ``.next`` properties pre-populated from the fetched results. This means accessing
+these properties won't trigger additional database queries.
+
+**Anti-pattern to avoid:**
+
+::
+
+    # BAD: This triggers N queries for N versions!
+    version = article.versions[-1]
+    while version:
+        process(version)
+        version = version.previous  # Each call is a separate query
+
+**Recommended pattern:**
+
+::
+
+    # GOOD: Single query, then iterate in memory
+    versions = ArticleVersion.all_versions(
+        session,
+        {'id': article.id}
+    )
+    for version in versions:
+        process(version)
+
+
+Index Recommendations
+=====================
+
+SQLAlchemy-Continuum automatically creates several indexes on version tables.
+Understanding these indexes helps you write efficient queries.
+
+
+Automatic Indexes
+-----------------
+
+The following indexes are created automatically:
+
+* ``transaction_id`` - Primary key index (always present)
+* ``end_transaction_id`` - For validity strategy (enables efficient range queries)
+* ``operation_type`` - For filtering INSERT/UPDATE/DELETE operations
+
+Starting with version 1.6.0, composite indexes are also created by default:
+
+* ``(primary_keys, transaction_id DESC)`` - For efficient entity version lookups
+* ``(primary_keys, transaction_id, end_transaction_id)`` - For validity strategy temporal queries
+
+These composite indexes dramatically speed up the most common query patterns.
+
+
+Disabling Composite Indexes
+---------------------------
+
+If you need to disable automatic composite index creation (e.g., for migration compatibility),
+you can set the ``create_composite_index`` option to ``False``::
+
+    make_versioned(options={'create_composite_index': False})
+
+Or per-model::
+
+    class Article(Base):
+        __versioned__ = {
+            'create_composite_index': False
+        }
+
+
+Recommended Additional Indexes
+------------------------------
+
+Depending on your query patterns, you may want to add these additional indexes:
+
+**For queries filtering by operation type and entity:**
+
+::
+
+    from sqlalchemy import Index
+
+    Index(
+        'ix_article_version_id_operation',
+        ArticleVersion.id,
+        ArticleVersion.operation_type,
+        ArticleVersion.transaction_id
+    )
+
+**For queries joining with Transaction table on issued_at:**
+
+If you frequently query versions by timestamp (e.g., "give me the version as of 2023-01-01"),
+ensure you have an index on ``Transaction.issued_at``::
+
+    Index('ix_transaction_issued_at', Transaction.issued_at.desc())
+
+**For PropertyModTrackerPlugin queries:**
+
+If you use PropertyModTrackerPlugin and frequently query for versions where specific
+fields changed, consider partial indexes::
+
+    # PostgreSQL partial index example
+    Index(
+        'ix_article_version_name_mod',
+        ArticleVersion.id,
+        postgresql_where=ArticleVersion.name_mod.is_(True)
+    )
+
+
+Query Performance Tips
+----------------------
+
+1. **Use the validity strategy** (default) for read-heavy workloads. It enables
+   O(log N) version lookups via direct equality conditions instead of correlated subqueries.
+
+2. **Batch fetch versions** using ``all_versions()`` instead of iterating with ``.previous``/``.next``.
+
+3. **Add composite indexes** on ``(entity_pk, transaction_id)`` for your most-queried version tables.
+
+4. **Use LIMIT** when you only need recent versions::
+
+       ArticleVersion.all_versions(session, {'id': 5}, limit=10)
+
+5. **Avoid relationship traversal** on version objects when possible. Relationship queries
+   on versions generate complex subqueries. If you need related data, fetch from the
+   parent object first or use explicit joins.

{sqlalchemy_continuum-1.5.1 → sqlalchemy_continuum-1.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "SQLAlchemy-Continuum"
-version = "1.5.1"
+version = "1.6.0"
 description = "Versioning and auditing extension for SQLAlchemy."
 readme = "README.rst"
 license = "BSD-3-Clause"
@@ -25,6 +25,7 @@ classifiers = [
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Topic :: Internet :: WWW/HTTP :: Dynamic Content",
     "Topic :: Software Development :: Libraries :: Python Modules"
 ]

{sqlalchemy_continuum-1.5.1 → sqlalchemy_continuum-1.6.0}/sqlalchemy_continuum/__init__.py

@@ -37,7 +37,7 @@ from .utils import (
     version_class as version_class,
 )
 
-__version__ = '1.5.1'
+__version__ = '1.6.0'
 
 
 versioning_manager = VersioningManager()