localvectordb.versioning module

Database versioning and migration tracking system for LocalVectorDB.

This module provides comprehensive database versioning capabilities using SQLite’s built-in PRAGMA user_version along with additional metadata tracking for migrations and schema evolution.

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, optional) – Target version to check against. Defaults to CURRENT_SCHEMA_VERSION.
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

Initialize version tracking for a new database.

Sets the database to the current schema version and records initial state.

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