delembic 0.2.0__tar.gz

delembic-0.2.0/.bumpversion.cfg

@@ -0,0 +1,13 @@
+[bumpversion]
+current_version = 0.2.0
+commit = True
+tag = True
+tag_name = v{new_version}
+
+[bumpversion:file:pyproject.toml]
+search = version = "{current_version}"
+replace = version = "{new_version}"
+
+[bumpversion:file:src/delembic/__init__.py]
+search = __version__ = "{current_version}"
+replace = __version__ = "{new_version}"

delembic-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,88 @@
+name: Build and Release
+
+on:
+  push:
+    branches:
+      - main   # only trigger on main branch
+
+permissions:
+  contents: write
+  id-token: write   
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0   # required to fetch tags
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Install bump2version & build tools
+        run: |
+          python -m pip install --upgrade pip
+          pip install bump2version build wheel
+
+      - name: Configure git user
+        run: |
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+      - name: Fetch tags
+        run: git fetch --tags
+
+      - name: Determine bump type
+        id: bump_type
+        run: |
+          msg="${{ github.event.head_commit.message }}"
+          if [[ "$msg" == *"bump: major"* ]]; then
+            echo "value=major" >> $GITHUB_OUTPUT
+          elif [[ "$msg" == *"bump: minor"* ]]; then
+            echo "value=minor" >> $GITHUB_OUTPUT
+          elif [[ "$msg" == *"bump: patch"* ]]; then
+            echo "value=patch" >> $GITHUB_OUTPUT
+          else
+            echo "ERROR: Commit must include 'bump: patch|minor|major'"
+            exit 1
+          fi
+
+      - name: Bump version
+        run: bump2version ${{ steps.bump_type.outputs.value }}
+
+      - name: Push new version and tag
+        run: |
+          git push origin HEAD --tags
+
+      - name: Get new version tag
+        id: new_tag
+        run: |
+          new_tag=$(git describe --tags `git rev-list --tags --max-count=1`)
+          echo "new_tag=$new_tag" >> $GITHUB_ENV
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: Upload release assets
+        uses: softprops/action-gh-release@v1
+        with:
+          tag_name: ${{ env.new_tag }}
+          name: "Delembic ${{ env.new_tag }}"
+          body: |
+            Release ${{ env.new_tag }}
+
+            Changes in this release:
+            - Auto-bumped version via GitHub Actions
+            - See commit history for details
+          files: |
+            dist/*.whl
+            dist/*.tar.gz
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

delembic-0.2.0/.gitignore

@@ -0,0 +1,32 @@
+# Python
+.venv/
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+*.egg-info/
+*.egg
+.eggs/
+
+# Build
+dist/
+build/
+
+# Test / coverage
+.pytest_cache/
+.coverage
+htmlcov/
+*.db
+
+# Type checkers / linters
+.mypy_cache/
+.ruff_cache/
+
+# Env
+.env
+.env.*
+
+# IDE
+.vscode/
+.idea/
+*.swp

delembic-0.2.0/.readthedocs.yaml

@@ -0,0 +1,17 @@
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+sphinx:
+  configuration: docs/conf.py
+
+python:
+  install:
+    - requirements: docs/requirements.txt
+    - method: pip
+      path: .
+      extra_requirements:
+        - dev

delembic-0.2.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: delembic
+Version: 0.2.0
+Summary: Data migration framework for versioning ETL and data operations alongside Alembic
+Author-email: htshpradhan5@gmail.com
+License: MIT
+Requires-Python: >=3.11
+Requires-Dist: click>=8.0
+Requires-Dist: sqlalchemy>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: furo>=2024.0; extra == 'docs'
+Requires-Dist: myst-parser>=3.0; extra == 'docs'
+Requires-Dist: sphinx-copybutton>=0.5; extra == 'docs'
+Requires-Dist: sphinx>=7.0; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# Delembic
+
+Data migration framework for Python — Alembic for ETL and data operations.
+
+Alembic versions schema changes. Delembic versions **data** changes: vocabulary loads, ETL runs, reference data inserts, corrections. Together they describe the complete database state.
+
+## Installation
+
+```bash
+pip install delembic
+```
+
+## Quick Start
+
+```bash
+# 1. Initialize in your project
+delembic init
+
+# 2. Edit delembic.ini — set your database URL
+# sqlalchemy.url = postgresql+psycopg://user:pass@host/dbname
+
+# 3. Create a migration
+delembic revision -m "load vocabulary"
+
+# 4. Fill in the generated file, then run
+delembic upgrade head
+```
+
+## Configuration
+
+`delembic init` creates:
+
+```
+your-project/
+├── delembic.ini          # config — commit this
+└── delembic/
+    ├── env.py            # optional connection helpers
+    └── versions/         # migration files live here
+```
+
+**`delembic.ini`:**
+
+```ini
+[delembic]
+script_location = delembic
+sqlalchemy.url = postgresql+psycopg://user:pass@localhost/mydb
+alembic_config = alembic.ini
+```
+
+You can name the script folder anything:
+
+```bash
+delembic init data-migrations
+```
+
+## Writing Migrations
+
+```python
+from delembic import DataMigration
+
+class LoadVocabulary(DataMigration):
+
+    revision = "D001"
+    depends_on = []
+    description = "Load OMOP vocabulary tables"
+
+    def upgrade(self, conn):
+        conn.execute(...)
+
+    def validate(self, conn):
+        count = conn.execute("SELECT COUNT(*) FROM concept").scalar()
+        assert count > 0, "vocabulary load produced no rows"
+```
+
+`conn` is a SQLAlchemy `Connection`. `validate` is optional — migration is marked failed if it raises.
+
+## Dependency Tracking
+
+Migrations declare explicit dependencies. Delembic builds a DAG and runs them in topological order.
+
+```python
+class LoadPerson(DataMigration):
+    revision = "D002"
+    depends_on = ["D001"]   # waits for D001
+```
+
+## Alembic Integration
+
+Point `alembic_config` at your `alembic.ini`:
+
+```ini
+[delembic]
+alembic_config = alembic.ini
+```
+
+When you create a migration, Delembic automatically captures the current Alembic head:
+
+```bash
+delembic revision -m "load person"
+# → depends_on = ['3d1e3e6abc12']   (current alembic head)
+```
+
+At upgrade time, Delembic verifies the required Alembic revision has been applied before running:
+
+```
+BLOCKED: Migration D002 requires Alembic revision(s) 3d1e3e6abc12 to be applied first.
+Run 'alembic upgrade head' before retrying.
+```
+
+## CLI Reference
+
+| Command | Description |
+|---|---|
+| `delembic init [DIR]` | Initialize project. DIR defaults to `delembic` |
+| `delembic revision -m "msg"` | Generate new migration file |
+| `delembic upgrade head` | Run all pending migrations |
+| `delembic upgrade D003` | Run migrations up to D003 |
+| `delembic current` | Show last applied revision |
+| `delembic history` | List all migrations with status |
+
+## Metadata Tables
+
+Delembic creates two tables:
+
+```sql
+delembic_version       -- current status per revision
+delembic_run_history   -- full audit log (start/end time, duration, exception, user, host)
+```
+
+Failed migration work is rolled back. The failure record is always committed — audit trail survives transaction failures.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```

delembic-0.2.0/README.md

@@ -0,0 +1,137 @@
+# Delembic
+
+Data migration framework for Python — Alembic for ETL and data operations.
+
+Alembic versions schema changes. Delembic versions **data** changes: vocabulary loads, ETL runs, reference data inserts, corrections. Together they describe the complete database state.
+
+## Installation
+
+```bash
+pip install delembic
+```
+
+## Quick Start
+
+```bash
+# 1. Initialize in your project
+delembic init
+
+# 2. Edit delembic.ini — set your database URL
+# sqlalchemy.url = postgresql+psycopg://user:pass@host/dbname
+
+# 3. Create a migration
+delembic revision -m "load vocabulary"
+
+# 4. Fill in the generated file, then run
+delembic upgrade head
+```
+
+## Configuration
+
+`delembic init` creates:
+
+```
+your-project/
+├── delembic.ini          # config — commit this
+└── delembic/
+    ├── env.py            # optional connection helpers
+    └── versions/         # migration files live here
+```
+
+**`delembic.ini`:**
+
+```ini
+[delembic]
+script_location = delembic
+sqlalchemy.url = postgresql+psycopg://user:pass@localhost/mydb
+alembic_config = alembic.ini
+```
+
+You can name the script folder anything:
+
+```bash
+delembic init data-migrations
+```
+
+## Writing Migrations
+
+```python
+from delembic import DataMigration
+
+class LoadVocabulary(DataMigration):
+
+    revision = "D001"
+    depends_on = []
+    description = "Load OMOP vocabulary tables"
+
+    def upgrade(self, conn):
+        conn.execute(...)
+
+    def validate(self, conn):
+        count = conn.execute("SELECT COUNT(*) FROM concept").scalar()
+        assert count > 0, "vocabulary load produced no rows"
+```
+
+`conn` is a SQLAlchemy `Connection`. `validate` is optional — migration is marked failed if it raises.
+
+## Dependency Tracking
+
+Migrations declare explicit dependencies. Delembic builds a DAG and runs them in topological order.
+
+```python
+class LoadPerson(DataMigration):
+    revision = "D002"
+    depends_on = ["D001"]   # waits for D001
+```
+
+## Alembic Integration
+
+Point `alembic_config` at your `alembic.ini`:
+
+```ini
+[delembic]
+alembic_config = alembic.ini
+```
+
+When you create a migration, Delembic automatically captures the current Alembic head:
+
+```bash
+delembic revision -m "load person"
+# → depends_on = ['3d1e3e6abc12']   (current alembic head)
+```
+
+At upgrade time, Delembic verifies the required Alembic revision has been applied before running:
+
+```
+BLOCKED: Migration D002 requires Alembic revision(s) 3d1e3e6abc12 to be applied first.
+Run 'alembic upgrade head' before retrying.
+```
+
+## CLI Reference
+
+| Command | Description |
+|---|---|
+| `delembic init [DIR]` | Initialize project. DIR defaults to `delembic` |
+| `delembic revision -m "msg"` | Generate new migration file |
+| `delembic upgrade head` | Run all pending migrations |
+| `delembic upgrade D003` | Run migrations up to D003 |
+| `delembic current` | Show last applied revision |
+| `delembic history` | List all migrations with status |
+
+## Metadata Tables
+
+Delembic creates two tables:
+
+```sql
+delembic_version       -- current status per revision
+delembic_run_history   -- full audit log (start/end time, duration, exception, user, host)
+```
+
+Failed migration work is rolled back. The failure record is always committed — audit trail survives transaction failures.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```

delembic-0.2.0/docs/_build/html/.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file records the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 40661e23bebe7cfbe895449f07b7020b
+tags: 645f666f9bcd5a90fca523b33c5a78b7

delembic-0.2.0/docs/_build/html/_sources/alembic-integration.md.txt

@@ -0,0 +1,112 @@
+# Alembic Integration
+
+Delembic integrates with Alembic to enforce that schema migrations are applied before data migrations that depend on them.
+
+## Setup
+
+Point `alembic_config` at your `alembic.ini`:
+
+```ini
+[delembic]
+script_location = delembic
+sqlalchemy.url = postgresql+psycopg://user:pass@localhost/mydb
+alembic_config = alembic.ini
+```
+
+`alembic_config` is resolved relative to `delembic.ini`.
+
+Install alembic if not already present:
+
+```bash
+pip install alembic
+```
+
+## Auto-Capture on Revision Generation
+
+When `alembic_config` is set, `delembic revision` automatically captures the current Alembic head revision(s) into `depends_on`:
+
+```bash
+# Alembic is at head: 3d1e3e6abc12
+delembic revision -m "load person"
+#   Alembic heads captured: ['3d1e3e6abc12']
+#   Created delembic/versions/D001_load_person.py
+```
+
+Generated file:
+
+```python
+class LoadPerson(DataMigration):
+    revision = "D001"
+    depends_on = ['3d1e3e6abc12']   # ← captured automatically
+    description = "load person"
+```
+
+If the database is unreachable at revision-generation time, Delembic prints a warning and generates the file with `depends_on = []` — you can fill it in manually.
+
+## Runtime Verification
+
+At `delembic upgrade head`, before running any migration, Delembic checks that all Alembic revisions in `depends_on` are applied:
+
+```
+Running D001: load person
+  BLOCKED: Migration D001 requires Alembic revision(s) ['3d1e3e6abc12'] to be applied first.
+  Run 'alembic upgrade head' before retrying.
+```
+
+The blocked migration is not attempted. Delembic exits with code 1.
+
+## Typical Workflow
+
+```bash
+# 1. Run schema migrations first
+alembic upgrade head
+
+# 2. Run data migrations
+delembic upgrade head
+```
+
+In CI/CD pipelines:
+
+```yaml
+- run: alembic upgrade head
+- run: delembic upgrade head
+```
+
+## Multiple Alembic Heads
+
+If your Alembic project uses multiple heads (branches), Delembic captures all current heads:
+
+```bash
+# Alembic has two active branches
+delembic revision -m "post-merge data load"
+#   Alembic heads captured: ['3d1e3e6abc12', 'a1b2c3d4e5f6']
+```
+
+```python
+depends_on = ['3d1e3e6abc12', 'a1b2c3d4e5f6']
+```
+
+Both must be applied before the migration runs.
+
+## Without Alembic
+
+Alembic integration is entirely optional. If `alembic_config` is not set in `delembic.ini`:
+- `delembic revision` generates files with `depends_on = []`
+- `delembic upgrade` skips Alembic checks
+- No alembic package needed
+
+## How It Works Internally
+
+Delembic uses two Alembic APIs:
+
+**`get_current_heads(conn)`** — reads `alembic_version` table via `MigrationContext`:
+
+```python
+from alembic.runtime.migration import MigrationContext
+ctx = MigrationContext.configure(conn)
+heads = list(ctx.get_current_heads())
+```
+
+**`get_alembic_applied_revisions(conn, alembic_ini)`** — walks script history from current heads back to base via `ScriptDirectory.iterate_revisions()`. Returns the set of all applied revision IDs (not just heads — ancestors included).
+
+This means a migration that depends on `3d1e3e6abc12` will pass verification even if Alembic has since advanced to `a1b2c3d4e5f6`, as long as `3d1e3e6abc12` is an ancestor of the current head.

delembic-0.2.0/docs/_build/html/_sources/changelog.md.txt

@@ -0,0 +1,11 @@
+# Changelog
+
+## 0.1.0 — Initial Release
+
+- `DataMigration` ABC with `upgrade()` and `validate()` hooks
+- DAG-based execution with topological sort (Kahn's algorithm)
+- `delembic init`, `revision`, `upgrade`, `current`, `history` CLI commands
+- `delembic_version` and `delembic_run_history` metadata tables
+- Dual-connection executor: audit records survive transaction rollbacks
+- Alembic integration: auto-capture heads on `revision`, verify deps on `upgrade`
+- `bump2version` + GitHub Actions release workflow