localvectordb.versioning module

Metadata-migration version tracking for LocalVectorDB.

This module tracks the version of the USER’s metadata-schema migration lineage – the semver stamped by localvectordb.migration.MigrationEngine after each user-authored migration – in SQLite’s PRAGMA user_version plus the config table, with a migration_log history. Every database starts that lineage at INITIAL_MIGRATION_VERSION.

It does NOT describe localvectordb’s own table layout. That is the integer config.schema_version maintained by localvectordb._schema (SCHEMA_VERSION / SCHEMA_MIGRATIONS), which moves only when the on-disk layout changes. The two registers are independent on purpose.

Classes:: DatabaseVersion: Manages version comparison and representation VersionManager: Handles version tracking and database migrations

class localvectordb.versioning.DatabaseVersion(version: str)

Bases: object

Represents a database version with semantic versioning support.

Supports semantic versioning format (MAJOR.MINOR.PATCH) and provides comparison operations and conversion to/from SQLite’s integer user_version.

Parameters:: version (str) – Version string in semantic versioning format (e.g., “1.0.0”)

Examples

Basic usage:

version = DatabaseVersion("1.2.3")
print(version.major)  # 1
print(version.minor)  # 2
print(version.patch)  # 3
print(version.to_sqlite_version())  # 1002003

Version comparison:

v1 = DatabaseVersion("1.0.0")
v2 = DatabaseVersion("1.1.0")
print(v1 < v2)  # True
print(v2.is_compatible_with(v1))  # True (same major)

__init__(version: str)

to_sqlite_version() → int

Convert version to SQLite PRAGMA user_version integer format.

Uses format: MAJOR * 1,000,000 + MINOR * 1,000 + PATCH This allows for versions up to 999.999.999 which should be sufficient.

Returns:: Integer representation suitable for SQLite PRAGMA user_version
Return type:: int

classmethod from_sqlite_version(sqlite_version: int) → DatabaseVersion

Create DatabaseVersion from SQLite PRAGMA user_version integer.

Parameters:: sqlite_version (int) – Integer from SQLite PRAGMA user_version
Returns:: Parsed version object
Return type:: DatabaseVersion

is_compatible_with(other: DatabaseVersion) → bool

Check if this version is compatible with another version.

Versions are considered compatible if they have the same major version. This follows semantic versioning rules where major version changes indicate breaking changes.

Parameters:: other (DatabaseVersion) – Version to compare against
Returns:: True if versions are compatible
Return type:: bool

class localvectordb.versioning.VersionManager(db_path: str | Path)

Bases: object

Manages database version tracking and migration metadata.

Handles SQLite PRAGMA user_version, version metadata in the config table, and migration tracking through the migration_log table.

Parameters:: db_path (Union[str, Path]) – Path to the SQLite database file

__init__(db_path: str | Path)

get_database_version(conn: Connection | None = None) → DatabaseVersion

Get the current database version.

Reads from PRAGMA user_version and falls back to config table if needed.

Parameters:: conn (sqlite3.Connection, optional) – Database connection to use. If None, creates a new connection.
Returns:: Current database version
Return type:: DatabaseVersion

set_database_version(version: DatabaseVersion, conn: Connection | None = None) → None

Set the database version using both PRAGMA user_version and config table.

Parameters:

version (DatabaseVersion) – Version to set
conn (sqlite3.Connection, optional) – Database connection to use. If None, creates a new connection.

get_migration_history(conn: Connection | None = None) → List[Dict]

Get the history of applied migrations.

Parameters:: conn (sqlite3.Connection, optional) – Database connection to use. If None, creates a new connection.
Returns:: List of migration records with version, timestamp, and metadata
Return type:: List[Dict]

record_migration(version: str, rollback_script: str | None = None, checksum: str | None = None, conn: Connection | None = None) → None

Record a completed migration in the migration log.

Parameters:

version (str) – Version that was migrated to
rollback_script (str, optional) – SQL script for rolling back this migration
checksum (str, optional) – Checksum of the migration for integrity verification
conn (sqlite3.Connection, optional) – Database connection to use. If None, creates a new connection.

needs_migration(target_version: DatabaseVersion | None = None, conn: Connection | None = None) → bool

Check if database needs migration to target version.

Parameters:

target_version (DatabaseVersion) – Target metadata-migration version to check against (required).
conn (sqlite3.Connection, optional) – Database connection to use. If None, creates a new connection.

Returns:

True if migration is needed

Return type:

bool

initialize_version_tracking(conn: Connection | None = None) → None

Start a new database’s metadata-migration lineage at the baseline.

Stamps INITIAL_MIGRATION_VERSION and records it in migration_log so user migrations (and rollbacks to the baseline) have an anchor.

Parameters:: conn (sqlite3.Connection, optional) – Database connection to use. If None, creates a new connection.