velocity-python 0.1.9__tar.gz → 0.1.10__tar.gz

{velocity_python-0.1.9/src/velocity_python.egg-info → velocity_python-0.1.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: velocity-python
-Version: 0.1.9
+Version: 0.1.10
 Summary: A rapid application development library for interfacing with data storage
 Author-email: Velocity Team <info@codeclubs.org>
 License-Expression: MIT

{velocity_python-0.1.9 → velocity_python-0.1.10}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "velocity-python"
-version = "0.1.9"
+version = "0.1.10"
 authors = [
   { name="Velocity Team", email="info@codeclubs.org" },
 ]
@@ -29,6 +29,9 @@ dependencies = [
   "sqlparse>=0.5.0"
 ]
 
+[project.scripts]
+velocity = "velocity.db.migrations:cli"
+
 [project.urls]
 Homepage = "https://codeclubs.org/projects/velocity"
 Documentation = "https://codeclubs.org/projects/velocity"

{velocity_python-0.1.9 → velocity_python-0.1.10}/src/velocity/__init__.py

@@ -1,4 +1,4 @@
-__version__ = version = "0.1.9"
+__version__ = version = "0.1.10"
 
 import importlib as _importlib
 

velocity_python-0.1.10/src/velocity/db/migrations.py

@@ -0,0 +1,579 @@
+"""
+Schema migration framework for velocity-python.
+
+Provides versioned, transactional schema migrations with up/down support,
+a tracking table (``velocity_migrations``), and a CLI interface.
+
+Usage::
+
+    from velocity.db.migrations import migration, MigrationRunner
+
+    @migration(version=1, description="Create users table")
+    def migrate_001(tx):
+        tx.table("users").create({"name": "TEXT", "email": "TEXT"})
+
+    @migration(version=1, down=True, description="Drop users table")
+    def rollback_001(tx):
+        tx.table("users").drop()
+
+    # Apply all pending migrations
+    runner = MigrationRunner(engine)
+    runner.migrate()
+"""
+
+from __future__ import annotations
+
+import hashlib
+import inspect
+import logging
+import os
+import importlib
+import importlib.util
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional, Tuple
+
+logger = logging.getLogger("velocity.db.migrations")
+
+# ── Global migration registry ──────────────────────────────────────
+
+_registry: Dict[int, Dict[str, Any]] = {}
+
+TRACKING_TABLE = "velocity_migrations"
+
+
+def migration(version: int, description: str = "", down: bool = False):
+    """
+    Decorator that registers a function as a migration step.
+
+    Args:
+        version: Integer migration version (must be unique per direction).
+        description: Human-readable description of what this migration does.
+        down: If True, registers as the rollback (down) function for this version.
+
+    Example::
+
+        @migration(version=1, description="Add users table")
+        def migrate_001(tx):
+            tx.table("users").create({"name": "TEXT", "email": "TEXT"})
+
+        @migration(version=1, down=True)
+        def rollback_001(tx):
+            tx.table("users").drop()
+    """
+
+    def decorator(func: Callable) -> Callable:
+        if version not in _registry:
+            _registry[version] = {"up": None, "down": None, "description": ""}
+
+        direction = "down" if down else "up"
+        if _registry[version][direction] is not None:
+            raise ValueError(
+                f"Migration version {version} already has a '{direction}' function registered: "
+                f"{_registry[version][direction].__name__}"
+            )
+
+        _registry[version][direction] = func
+        if description and not down:
+            _registry[version]["description"] = description
+        elif description and down and not _registry[version]["description"]:
+            _registry[version]["description"] = description
+
+        return func
+
+    return decorator
+
+
+def clear_registry():
+    """Clear all registered migrations. Useful for testing."""
+    _registry.clear()
+
+
+def get_registry() -> Dict[int, Dict[str, Any]]:
+    """Return a copy of the current migration registry."""
+    return dict(_registry)
+
+
+# ── Migration Runner ────────────────────────────────────────────────
+
+
+class MigrationRunner:
+    """
+    Discovers, applies, and rolls back schema migrations.
+
+    Migrations are tracked in a ``velocity_migrations`` table with columns:
+
+    - ``version`` (INT, PRIMARY KEY) — migration version number
+    - ``description`` (TEXT) — human-readable description
+    - ``applied_at`` (TIMESTAMPTZ) — when the migration was applied
+    - ``checksum`` (TEXT) — SHA-256 of the migration function source
+    - ``execution_ms`` (INT) — how long the migration took in milliseconds
+
+    Args:
+        engine: A velocity Engine instance.
+        migrations_dir: Optional path to a directory containing migration .py files.
+            If provided, all .py files in that directory are imported to register
+            their ``@migration`` decorated functions.
+    """
+
+    def __init__(self, engine, migrations_dir: Optional[str] = None):
+        self.engine = engine
+        self._migrations_dir = migrations_dir
+
+        if migrations_dir:
+            self._load_migrations_from_dir(migrations_dir)
+
+    # ── Discovery ───────────────────────────────────────────────
+
+    def _load_migrations_from_dir(self, dir_path: str) -> None:
+        """Import all .py files from a directory to register @migration decorators."""
+        p = Path(dir_path)
+        if not p.is_dir():
+            raise FileNotFoundError(f"Migrations directory not found: {dir_path}")
+
+        for py_file in sorted(p.glob("*.py")):
+            if py_file.name.startswith("_"):
+                continue
+            module_name = f"velocity_migrations.{py_file.stem}"
+            spec = importlib.util.spec_from_file_location(module_name, py_file)
+            if spec and spec.loader:
+                mod = importlib.util.module_from_spec(spec)
+                spec.loader.exec_module(mod)
+
+    # ── Tracking table ──────────────────────────────────────────
+
+    def _ensure_tracking_table(self, tx) -> None:
+        """Create the velocity_migrations tracking table if it doesn't exist."""
+        table = tx.table(TRACKING_TABLE)
+        if not table.exists():
+            # Use raw SQL to avoid velocity system columns — we manage our own schema
+            tx.execute(
+                f"""
+                CREATE TABLE IF NOT EXISTS {TRACKING_TABLE} (
+                    version     INTEGER PRIMARY KEY,
+                    description TEXT NOT NULL DEFAULT '',
+                    applied_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+                    checksum    TEXT NOT NULL DEFAULT '',
+                    execution_ms INTEGER NOT NULL DEFAULT 0
+                )
+                """,
+                cursor=tx.cursor(),
+            )
+            logger.info("Created tracking table: %s", TRACKING_TABLE)
+
+    def _get_applied_versions(self, tx) -> Dict[int, Dict[str, Any]]:
+        """Return dict of {version: {description, applied_at, checksum, execution_ms}}."""
+        self._ensure_tracking_table(tx)
+        result = tx.execute(
+            f"SELECT version, description, applied_at, checksum, execution_ms "
+            f"FROM {TRACKING_TABLE} ORDER BY version",
+            cursor=tx.cursor(),
+        )
+        applied = {}
+        for row in result.all():
+            applied[row["version"]] = {
+                "description": row["description"],
+                "applied_at": row["applied_at"],
+                "checksum": row["checksum"],
+                "execution_ms": row["execution_ms"],
+            }
+        return applied
+
+    def _record_migration(self, tx, version: int, description: str, checksum: str, execution_ms: int) -> None:
+        """Insert a record into the tracking table."""
+        tx.execute(
+            f"INSERT INTO {TRACKING_TABLE} (version, description, checksum, execution_ms) "
+            f"VALUES (%s, %s, %s, %s)",
+            (version, description, checksum, execution_ms),
+            cursor=tx.cursor(),
+        )
+
+    def _remove_migration_record(self, tx, version: int) -> None:
+        """Delete a record from the tracking table."""
+        tx.execute(
+            f"DELETE FROM {TRACKING_TABLE} WHERE version = %s",
+            (version,),
+            cursor=tx.cursor(),
+        )
+
+    # ── Checksum ────────────────────────────────────────────────
+
+    @staticmethod
+    def _checksum(func: Callable) -> str:
+        """SHA-256 hash of a migration function's source code."""
+        try:
+            source = inspect.getsource(func)
+        except (OSError, TypeError):
+            source = func.__name__
+        return hashlib.sha256(source.encode()).hexdigest()[:16]
+
+    # ── Core operations ─────────────────────────────────────────
+
+    def pending(self) -> List[int]:
+        """
+        Return list of pending (unapplied) migration versions, sorted ascending.
+        """
+        tx = self.engine.transaction()
+        try:
+            applied = self._get_applied_versions(tx)
+            pending = sorted(v for v in _registry if v not in applied and _registry[v]["up"] is not None)
+            return pending
+        finally:
+            tx.close()
+
+    def status(self) -> List[Dict[str, Any]]:
+        """
+        Return migration status for all registered versions.
+
+        Returns a list of dicts with keys:
+        - version, description, status ("applied" | "pending"), applied_at, checksum_match
+        """
+        tx = self.engine.transaction()
+        try:
+            applied = self._get_applied_versions(tx)
+            result = []
+            all_versions = sorted(set(list(_registry.keys()) + list(applied.keys())))
+
+            for v in all_versions:
+                entry: Dict[str, Any] = {"version": v}
+                reg = _registry.get(v, {})
+                app = applied.get(v)
+
+                entry["description"] = reg.get("description", "") or (app["description"] if app else "")
+
+                if app:
+                    entry["status"] = "applied"
+                    entry["applied_at"] = app["applied_at"]
+                    entry["execution_ms"] = app["execution_ms"]
+                    # Check if source has changed since applied
+                    up_func = reg.get("up")
+                    if up_func:
+                        entry["checksum_match"] = self._checksum(up_func) == app["checksum"]
+                    else:
+                        entry["checksum_match"] = None  # Not in registry
+                else:
+                    entry["status"] = "pending"
+                    entry["applied_at"] = None
+                    entry["execution_ms"] = None
+                    entry["checksum_match"] = None
+
+                has_down = reg.get("down") is not None if reg else False
+                entry["reversible"] = has_down
+
+                result.append(entry)
+
+            return result
+        finally:
+            tx.close()
+
+    def migrate(self, target: Optional[int] = None, dry_run: bool = False) -> List[int]:
+        """
+        Apply pending migrations up to ``target`` version (inclusive).
+
+        Each migration runs in its own transaction — if a migration fails,
+        all previously applied migrations in this run remain committed.
+
+        Args:
+            target: Apply up to this version. None = apply all pending.
+            dry_run: If True, log what would be done without applying.
+
+        Returns:
+            List of versions that were applied.
+        """
+        pending = self.pending()
+        if target is not None:
+            pending = [v for v in pending if v <= target]
+
+        if not pending:
+            logger.info("No pending migrations.")
+            return []
+
+        if dry_run:
+            for v in pending:
+                desc = _registry[v].get("description", "")
+                logger.info("[DRY RUN] Would apply migration %d: %s", v, desc)
+            return pending
+
+        applied = []
+        for v in pending:
+            reg = _registry[v]
+            up_func = reg["up"]
+            desc = reg.get("description", "")
+            checksum = self._checksum(up_func)
+
+            logger.info("Applying migration %d: %s", v, desc)
+            start = time.perf_counter()
+
+            # Each migration gets its own transaction
+            tx = self.engine.transaction()
+            try:
+                # Temporarily unlock schema for migration DDL
+                was_locked = self.engine.schema_locked
+                if was_locked:
+                    self.engine.unlock_schema()
+                try:
+                    self._ensure_tracking_table(tx)
+                    up_func(tx)
+                    elapsed_ms = int((time.perf_counter() - start) * 1000)
+                    self._record_migration(tx, v, desc, checksum, elapsed_ms)
+                    tx.commit()
+                    applied.append(v)
+                    logger.info("Applied migration %d in %dms", v, elapsed_ms)
+                finally:
+                    if was_locked:
+                        self.engine.lock_schema()
+            except Exception:
+                tx.rollback()
+                logger.error("Migration %d failed — rolled back", v, exc_info=True)
+                raise
+            finally:
+                tx.close()
+
+        return applied
+
+    def rollback(self, target: Optional[int] = None, dry_run: bool = False) -> List[int]:
+        """
+        Roll back applied migrations down to ``target`` version (exclusive).
+
+        Migrations are rolled back in reverse order. Each rollback runs in its
+        own transaction.
+
+        Args:
+            target: Roll back to this version (this version stays applied).
+                None = roll back the most recent migration only.
+            dry_run: If True, log what would be done without applying.
+
+        Returns:
+            List of versions that were rolled back (in rollback order).
+
+        Raises:
+            ValueError: If a migration has no ``down`` function registered.
+        """
+        tx = self.engine.transaction()
+        try:
+            applied = self._get_applied_versions(tx)
+        finally:
+            tx.close()
+
+        applied_versions = sorted(applied.keys(), reverse=True)
+
+        if not applied_versions:
+            logger.info("No migrations to roll back.")
+            return []
+
+        if target is None:
+            # Roll back only the latest
+            to_rollback = [applied_versions[0]]
+        else:
+            to_rollback = [v for v in applied_versions if v > target]
+
+        if not to_rollback:
+            logger.info("No migrations to roll back (already at or below target %d).", target)
+            return []
+
+        # Check all have down functions before starting
+        for v in to_rollback:
+            reg = _registry.get(v, {})
+            if not reg.get("down"):
+                raise ValueError(
+                    f"Migration {v} has no 'down' function registered — cannot roll back."
+                )
+
+        if dry_run:
+            for v in to_rollback:
+                desc = _registry.get(v, {}).get("description", "")
+                logger.info("[DRY RUN] Would roll back migration %d: %s", v, desc)
+            return to_rollback
+
+        rolled_back = []
+        for v in to_rollback:
+            reg = _registry[v]
+            down_func = reg["down"]
+            desc = reg.get("description", "")
+
+            logger.info("Rolling back migration %d: %s", v, desc)
+            start = time.perf_counter()
+
+            tx = self.engine.transaction()
+            try:
+                was_locked = self.engine.schema_locked
+                if was_locked:
+                    self.engine.unlock_schema()
+                try:
+                    down_func(tx)
+                    self._remove_migration_record(tx, v)
+                    tx.commit()
+                    elapsed_ms = int((time.perf_counter() - start) * 1000)
+                    rolled_back.append(v)
+                    logger.info("Rolled back migration %d in %dms", v, elapsed_ms)
+                finally:
+                    if was_locked:
+                        self.engine.lock_schema()
+            except Exception:
+                tx.rollback()
+                logger.error("Rollback of migration %d failed", v, exc_info=True)
+                raise
+            finally:
+                tx.close()
+
+        return rolled_back
+
+    def diff(self) -> Dict[str, Any]:
+        """
+        Compare current database schema with the expected state from migrations.
+
+        Returns a dict with:
+        - ``pending_count``: Number of unapplied migrations.
+        - ``pending_versions``: List of unapplied version numbers.
+        - ``applied_count``: Number of applied migrations.
+        - ``modified``: List of versions where the source checksum differs
+          from what was applied (migration was edited after being applied).
+        - ``orphaned``: List of versions applied in DB but not in the registry
+          (migration file was deleted or not loaded).
+        """
+        tx = self.engine.transaction()
+        try:
+            applied = self._get_applied_versions(tx)
+        finally:
+            tx.close()
+
+        pending_versions = sorted(v for v in _registry if v not in applied and _registry[v].get("up"))
+        orphaned = sorted(v for v in applied if v not in _registry)
+        modified = []
+        for v, app in applied.items():
+            reg = _registry.get(v, {})
+            up_func = reg.get("up")
+            if up_func and self._checksum(up_func) != app["checksum"]:
+                modified.append(v)
+
+        return {
+            "pending_count": len(pending_versions),
+            "pending_versions": pending_versions,
+            "applied_count": len(applied),
+            "modified": sorted(modified),
+            "orphaned": orphaned,
+        }
+
+
+# ── CLI ─────────────────────────────────────────────────────────────
+
+
+def _cli_main(args: Optional[List[str]] = None) -> int:
+    """
+    CLI entry point for ``velocity migrate``.
+
+    Commands:
+        velocity migrate              Apply all pending migrations
+        velocity migrate --to 5       Apply up to version 5
+        velocity migrate --dry-run    Show what would be applied
+        velocity rollback             Roll back the latest migration
+        velocity rollback --to 3      Roll back to version 3
+        velocity status               Show migration status
+        velocity diff                 Compare DB schema with migration registry
+    """
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        prog="velocity",
+        description="Velocity-Python schema migration tool",
+    )
+    sub = parser.add_subparsers(dest="command")
+
+    # migrate
+    mig = sub.add_parser("migrate", help="Apply pending migrations")
+    mig.add_argument("--to", type=int, default=None, help="Apply up to this version (inclusive)")
+    mig.add_argument("--dry-run", action="store_true", help="Show what would be applied")
+    mig.add_argument("--dir", type=str, default=None, help="Directory containing migration .py files")
+
+    # rollback
+    rb = sub.add_parser("rollback", help="Roll back migrations")
+    rb.add_argument("--to", type=int, default=None, help="Roll back to this version (exclusive, version stays)")
+    rb.add_argument("--dry-run", action="store_true", help="Show what would be rolled back")
+    rb.add_argument("--dir", type=str, default=None, help="Directory containing migration .py files")
+
+    # status
+    st = sub.add_parser("status", help="Show migration status")
+    st.add_argument("--dir", type=str, default=None, help="Directory containing migration .py files")
+
+    # diff
+    df = sub.add_parser("diff", help="Compare DB schema with migration registry")
+    df.add_argument("--dir", type=str, default=None, help="Directory containing migration .py files")
+
+    parsed = parser.parse_args(args)
+
+    if not parsed.command:
+        parser.print_help()
+        return 1
+
+    # Configure logging for CLI
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(levelname)s %(message)s",
+    )
+
+    # Initialize engine from env vars (standard velocity pattern)
+    try:
+        from velocity.db.servers.postgres import initialize
+        engine = initialize()
+    except Exception as e:
+        logger.error("Failed to initialize database engine: %s", e)
+        logger.error("Set DBHost, DBDatabase, DBUser, DBPassword environment variables.")
+        return 1
+
+    migrations_dir = getattr(parsed, "dir", None)
+    runner = MigrationRunner(engine, migrations_dir=migrations_dir)
+
+    try:
+        if parsed.command == "migrate":
+            applied = runner.migrate(target=parsed.to, dry_run=parsed.dry_run)
+            if not parsed.dry_run:
+                print(f"{len(applied)} migration(s) applied.")
+            return 0
+
+        elif parsed.command == "rollback":
+            rolled = runner.rollback(target=parsed.to, dry_run=parsed.dry_run)
+            if not parsed.dry_run:
+                print(f"{len(rolled)} migration(s) rolled back.")
+            return 0
+
+        elif parsed.command == "status":
+            entries = runner.status()
+            if not entries:
+                print("No migrations registered or applied.")
+                return 0
+            print(f"{'Ver':>4}  {'Status':<9}  {'Rev':>3}  {'Time':>7}  Description")
+            print("-" * 60)
+            for e in entries:
+                status_str = e["status"]
+                if e.get("checksum_match") is False:
+                    status_str = "MODIFIED"
+                rev = "yes" if e.get("reversible") else "no"
+                ms = f"{e['execution_ms']}ms" if e.get("execution_ms") is not None else "-"
+                print(f"{e['version']:>4}  {status_str:<9}  {rev:>3}  {ms:>7}  {e['description']}")
+            return 0
+
+        elif parsed.command == "diff":
+            d = runner.diff()
+            print(f"Applied: {d['applied_count']}")
+            print(f"Pending: {d['pending_count']} {d['pending_versions'] or ''}")
+            if d["modified"]:
+                print(f"Modified since applied: {d['modified']}")
+            if d["orphaned"]:
+                print(f"Orphaned (in DB, not in code): {d['orphaned']}")
+            if not d["pending_versions"] and not d["modified"] and not d["orphaned"]:
+                print("Schema is up to date.")
+            return 0
+
+    except Exception as e:
+        logger.error("%s", e)
+        return 1
+
+    return 0
+
+
+def cli():
+    """Setuptools console_scripts entry point."""
+    import sys
+
+    sys.exit(_cli_main())

{velocity_python-0.1.9 → velocity_python-0.1.10/src/velocity_python.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: velocity-python
-Version: 0.1.9
+Version: 0.1.10
 Summary: A rapid application development library for interfacing with data storage
 Author-email: Velocity Team <info@codeclubs.org>
 License-Expression: MIT

{velocity_python-0.1.9 → velocity_python-0.1.10}/src/velocity_python.egg-info/SOURCES.txt

@@ -37,6 +37,7 @@ src/velocity/aws/tests/test_lambda_handler_json_serialization.py
 src/velocity/aws/tests/test_response.py
 src/velocity/db/__init__.py
 src/velocity/db/exceptions.py
+src/velocity/db/migrations.py
 src/velocity/db/utils.py
 src/velocity/db/core/__init__.py
 src/velocity/db/core/async_support.py
@@ -146,6 +147,7 @@ src/velocity/payment/stripe_adapter.py
 src/velocity_python.egg-info/PKG-INFO
 src/velocity_python.egg-info/SOURCES.txt
 src/velocity_python.egg-info/dependency_links.txt
+src/velocity_python.egg-info/entry_points.txt
 src/velocity_python.egg-info/requires.txt
 src/velocity_python.egg-info/top_level.txt
 tests/test_amplify_build.py
@@ -173,6 +175,7 @@ tests/test_psycopg3_upgrade.py
 tests/test_query_cache.py
 tests/test_row_batch_update.py
 tests/test_row_cache_staleness.py
+tests/test_schema_migrations.py
 tests/test_security_hardening.py
 tests/test_sqs_per_record_transactions.py
 tests/test_sys_modified_count_postgres_demo.py

velocity_python-0.1.10/src/velocity_python.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+velocity = velocity.db.migrations:cli