dbly 0.0.1__tar.gz

dbly-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,58 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+# Cancel in-progress runs for the same ref when a new commit arrives.
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: Tests (Python ${{ matrix.python }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ['3.12', '3.13']
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python }}
+        run: uv python install ${{ matrix.python }}
+
+      - name: Install project + dev dependencies
+        run: uv sync --python ${{ matrix.python }}
+
+      # Live database tests are gated on the presence of local *.connection.properties
+      # files and the optional drivers (oracledb / pymssql). On CI runners they skip
+      # automatically, so this runs the unit suite only.
+      - name: Run tests
+        run: uv run python -m pytest -q --tb=short
+
+  build:
+    name: Build sdist + wheel
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - run: uv build
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist-${{ github.sha }}
+          path: dist/
+          retention-days: 7

dbly-0.0.1/.github/workflows/publish.yml

@@ -0,0 +1,53 @@
+name: Publish to PyPI
+
+# Triggered when a GitHub Release is published. Tag the release with
+# the version (e.g. `v0.1.0`) — the workflow builds wheel + sdist and
+# publishes via PyPI Trusted Publishing (OIDC, no API token).
+#
+# One-time setup on PyPI (Trusted Publisher), with these values:
+#   * PyPI Project name: dbly
+#   * Owner:             angrydat
+#   * Repository name:   dbly
+#   * Workflow name:     publish.yml
+#   * Environment:       pypi
+# For the FIRST release (project does not exist on PyPI yet) add a *pending*
+# publisher at https://pypi.org/manage/account/publishing/ — the first publish
+# then creates the project. Afterwards manage it under
+#   https://pypi.org/manage/project/dbly/settings/publishing/
+on:
+  release:
+    types: [published]
+
+  # Allow manual runs for emergencies / re-publishes from a tag.
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/dbly
+    permissions:
+      id-token: write  # required for Trusted Publishing (OIDC)
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          verify-metadata: true

dbly-0.0.1/.gitignore

@@ -0,0 +1,27 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+
+# uv
+.uv/
+
+# Test / coverage
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# IDE (never committed — see project policy)
+.idea/
+.vscode/
+
+# Local secrets / connection profiles with credentials
+*.local.properties
+*.connection.properties
+secrets/

dbly-0.0.1/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: dbly
+Version: 0.0.1
+Summary: State-based, cross-engine database deployment — git-driven, parser-assisted, SQL-first.
+Project-URL: Homepage, https://angrydata.info/dbly
+Project-URL: Repository, https://github.com/angrydat/dbly
+Project-URL: Issues, https://github.com/angrydat/dbly/issues
+Author-email: Jürgen Zornig <info@angrydata.info>
+License: MIT
+Keywords: ci-cd,database,deployment,git,migration,oracle,postgres,schema,sql,sqlite,sqlserver,state-based
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: SQL
+Classifier: Topic :: Database
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: pathspec>=0.12
+Requires-Dist: psycopg[binary]>=3.1
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.7
+Requires-Dist: sqlalchemy>=2.0
+Requires-Dist: sqlglot>=25.0
+Requires-Dist: typer>=0.12
+Provides-Extra: all
+Requires-Dist: oracledb>=2.0; extra == 'all'
+Requires-Dist: pymssql>=2.3; extra == 'all'
+Provides-Extra: mssql
+Requires-Dist: pymssql>=2.3; extra == 'mssql'
+Provides-Extra: oracle
+Requires-Dist: oracledb>=2.0; extra == 'oracle'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="docs/dbly_head.png" alt="dbly — state-based database deployment" width="100%">
+</p>
+
+<p align="center"><b>Declare your desired database state in git. dbly makes it real.</b></p>
+
+---
+
+**dbly** deploys your database objects — tables, views, functions, procedures, packages,
+triggers, grants — from version control to **PostgreSQL, SQL Server, Oracle and SQLite**.
+You keep one SQL file per object, like normal source code; dbly works out what changed and
+brings the target database in sync. Think *Terraform for your database*: **declarative,
+predictable, repeatable.**
+
+## Why
+
+- **Declarative** — your repo is the source of truth. No hand-written migration chains, no
+  version-number collisions on parallel branches.
+- **Plan before apply** — preview exactly what will run, then execute. No surprises.
+- **Idempotent & safe** — only the necessary changes are applied. Additive changes go
+  automatically; destructive ones (dropping columns, etc.) are flagged and never run unless
+  you explicitly allow them.
+- **Multi-database** — one workflow across all four engines.
+
+## Install
+
+```sh
+uv sync                 # PostgreSQL + SQLite work out of the box
+uv sync --extra oracle  # add the Oracle driver
+uv sync --extra mssql   # add the SQL Server driver
+uv sync --extra all     # both
+```
+
+## Organize your repo
+
+One file per object; folder names map to database schemas. Use any extension you like
+(`.sql`, `.tbl`, `.vw`, `.prc`, …) — dbly reads the SQL to know what each object is.
+
+```
+db/
+  sales/
+    customer.tbl
+    v_open_orders.vw
+    grants.sql
+  init/                 # optional: privileged greenfield groundwork (CREATE DATABASE/ROLE…)
+hooks/pre/  hooks/post/  # optional: .sql or .py hooks (e.g. ArcGIS/ArcPy steps)
+.dbignore               # files in the repo that should not be deployed
+```
+
+## Connect
+
+A connection profile (reuses the familiar `connection.properties` format):
+
+```properties
+environment=postgres            # postgres | sqlserver | oracle | sqlite
+service=db.example.com:5432
+username=app
+password=${DB_PASSWORD}         # ${ENV} placeholders → keep secrets out of the repo (CI/CD-safe)
+database=appdb
+```
+
+## Use
+
+```sh
+# preview the changes between the deployed state and a git ref
+dbly plan  --to main --target prod.connection.properties
+
+# apply them
+dbly apply --to main --target prod.connection.properties
+
+# export a plain SQL script to run by hand (e.g. through a customer VPN, no dbly needed)
+dbly plan  --to main --target prod.connection.properties --sql deploy.sql
+
+# what is currently deployed?
+dbly status --target prod.connection.properties
+
+# has the database drifted from the desired state?
+dbly check  --target prod.connection.properties
+
+# greenfield only: run privileged groundwork once under a superuser profile
+dbly init   --init-target super.connection.properties
+```
+
+**Typical workflow:** edit your object files → commit → `dbly plan` to review → `dbly apply`.
+
+Deploying a *subset* of features is just choosing the git ref you deploy (a release tag or
+branch). Destructive steps require `--allow-destructive`.
+
+## Built for trunk-based development
+
+Database teams are usually locked out of trunk-based development: migration scripts collide
+on parallel branches, and "merge" effectively means "deploy to the customer". dbly is
+designed to break that deadlock for teams who write their logic **in SQL, in the database**:
+
+- **No migration numbers, no collisions.** Two developers edit different objects — git
+  merges them like any other code. Integrate early, every day.
+- **Merge ≠ deploy.** The trunk is your desired state; `dbly apply --to <tag>` ships the ref
+  you choose, in the maintenance window you choose. Release *what* you want, *when* you want.
+- **One trunk, every customer.** dbly reads each database's real state, so customers on
+  different versions are no problem.
+
+Integrate continuously, deploy on your own schedule — trunk-based development, finally
+practical for state-based database developers.
+
+## Status
+
+Early alpha — all four engines are implemented and tested against live databases.
+
+## License
+
+MIT

dbly-0.0.1/README.md

@@ -0,0 +1,111 @@
+<p align="center">
+  <img src="docs/dbly_head.png" alt="dbly — state-based database deployment" width="100%">
+</p>
+
+<p align="center"><b>Declare your desired database state in git. dbly makes it real.</b></p>
+
+---
+
+**dbly** deploys your database objects — tables, views, functions, procedures, packages,
+triggers, grants — from version control to **PostgreSQL, SQL Server, Oracle and SQLite**.
+You keep one SQL file per object, like normal source code; dbly works out what changed and
+brings the target database in sync. Think *Terraform for your database*: **declarative,
+predictable, repeatable.**
+
+## Why
+
+- **Declarative** — your repo is the source of truth. No hand-written migration chains, no
+  version-number collisions on parallel branches.
+- **Plan before apply** — preview exactly what will run, then execute. No surprises.
+- **Idempotent & safe** — only the necessary changes are applied. Additive changes go
+  automatically; destructive ones (dropping columns, etc.) are flagged and never run unless
+  you explicitly allow them.
+- **Multi-database** — one workflow across all four engines.
+
+## Install
+
+```sh
+uv sync                 # PostgreSQL + SQLite work out of the box
+uv sync --extra oracle  # add the Oracle driver
+uv sync --extra mssql   # add the SQL Server driver
+uv sync --extra all     # both
+```
+
+## Organize your repo
+
+One file per object; folder names map to database schemas. Use any extension you like
+(`.sql`, `.tbl`, `.vw`, `.prc`, …) — dbly reads the SQL to know what each object is.
+
+```
+db/
+  sales/
+    customer.tbl
+    v_open_orders.vw
+    grants.sql
+  init/                 # optional: privileged greenfield groundwork (CREATE DATABASE/ROLE…)
+hooks/pre/  hooks/post/  # optional: .sql or .py hooks (e.g. ArcGIS/ArcPy steps)
+.dbignore               # files in the repo that should not be deployed
+```
+
+## Connect
+
+A connection profile (reuses the familiar `connection.properties` format):
+
+```properties
+environment=postgres            # postgres | sqlserver | oracle | sqlite
+service=db.example.com:5432
+username=app
+password=${DB_PASSWORD}         # ${ENV} placeholders → keep secrets out of the repo (CI/CD-safe)
+database=appdb
+```
+
+## Use
+
+```sh
+# preview the changes between the deployed state and a git ref
+dbly plan  --to main --target prod.connection.properties
+
+# apply them
+dbly apply --to main --target prod.connection.properties
+
+# export a plain SQL script to run by hand (e.g. through a customer VPN, no dbly needed)
+dbly plan  --to main --target prod.connection.properties --sql deploy.sql
+
+# what is currently deployed?
+dbly status --target prod.connection.properties
+
+# has the database drifted from the desired state?
+dbly check  --target prod.connection.properties
+
+# greenfield only: run privileged groundwork once under a superuser profile
+dbly init   --init-target super.connection.properties
+```
+
+**Typical workflow:** edit your object files → commit → `dbly plan` to review → `dbly apply`.
+
+Deploying a *subset* of features is just choosing the git ref you deploy (a release tag or
+branch). Destructive steps require `--allow-destructive`.
+
+## Built for trunk-based development
+
+Database teams are usually locked out of trunk-based development: migration scripts collide
+on parallel branches, and "merge" effectively means "deploy to the customer". dbly is
+designed to break that deadlock for teams who write their logic **in SQL, in the database**:
+
+- **No migration numbers, no collisions.** Two developers edit different objects — git
+  merges them like any other code. Integrate early, every day.
+- **Merge ≠ deploy.** The trunk is your desired state; `dbly apply --to <tag>` ships the ref
+  you choose, in the maintenance window you choose. Release *what* you want, *when* you want.
+- **One trunk, every customer.** dbly reads each database's real state, so customers on
+  different versions are no problem.
+
+Integrate continuously, deploy on your own schedule — trunk-based development, finally
+practical for state-based database developers.
+
+## Status
+
+Early alpha — all four engines are implemented and tested against live databases.
+
+## License
+
+MIT

dbly-0.0.1/examples/ci/README.md

@@ -0,0 +1,35 @@
+# CI: the trunk-based-development gate
+
+These pipelines make *“the trunk is always deployable”* an automatic, enforced fact —
+the one guarantee trunk-based development depends on. Drop one into the repo that holds
+your database object files (not the dbly repo).
+
+On every change, against a **throwaway database**, the pipeline proves:
+
+| Check | Command | Proves |
+|---|---|---|
+| **Greenfield** | `dbly apply --to HEAD` on an empty DB | the trunk builds a correct database from scratch |
+| **Drift** | `dbly check --to HEAD` | desired state == the live DB after apply |
+| **Upgrade** (PRs) | `dbly apply --to origin/main` → `dbly plan/apply --from origin/main --to HEAD` | the path from the released baseline applies cleanly and stays additive |
+| **Behaviour** | `dbression run ./tests` | no regressions in schema or business logic |
+
+Together: `dbly` deploys, `dbression` verifies → a green gate that keeps the trunk
+releasable. Developers integrate early and often; deployment to customers stays a separate,
+scheduled act (`dbly apply --to <release-tag>` in the maintenance window, or
+`dbly plan --sql` for a hand-deploy through a VPN).
+
+## Notes
+
+- **No secrets in the repo.** CI starts an ephemeral Postgres and writes the
+  `connection.properties` at runtime. For real targets, use repository/pipeline secrets and
+  `${ENV}` placeholders in the profile.
+- **One profile, two tools.** dbly reads it via `--target`; dbression discovers it next to
+  the suite. The extra `environment=` key is ignored by dbression.
+- **The release artifact** (`dbly plan --sql`) is only an accurate *diff* when generated
+  against a copy of production (read access). Against an empty CI DB it is the full bootstrap
+  script — fine for a fresh customer, not for an upgrade.
+- Postgres is dbly’s reference engine here; the same pattern works for SQL Server / Oracle by
+  swapping the service image, the `environment=` value, and installing the matching extra
+  (`uv tool install "dbly[mssql]"` / `"dbly[oracle]"`).
+
+Files: [`bitbucket-pipelines.yml`](bitbucket-pipelines.yml) · [`github-actions.yml`](github-actions.yml)

dbly-0.0.1/examples/ci/bitbucket-pipelines.yml

@@ -0,0 +1,97 @@
+# ─────────────────────────────────────────────────────────────────────────────
+# Trunk-based-development gate for a dbly-managed *database* repository.
+#
+# Place this at the ROOT of the repo that holds your SQL object files (not the
+# dbly repo itself). On every change it proves — against a throwaway Postgres —
+# that the trunk is always deployable and green:
+#
+#   • GREENFIELD : the trunk builds a correct database from scratch
+#   • UPGRADE    : the path from the released baseline (main) applies cleanly
+#   • BEHAVIOUR  : the dbression regression suite passes
+#
+# That is exactly the guarantee trunk-based development needs. No secrets live in
+# the repo — CI spins up an ephemeral database and writes the connection at runtime.
+# ─────────────────────────────────────────────────────────────────────────────
+
+image: python:3.12-slim
+
+clone:
+  depth: full            # dbly diffs git refs (origin/main..HEAD) — needs history
+
+definitions:
+  services:
+    postgres:
+      image: postgres:16
+      variables:
+        POSTGRES_DB: ci
+        POSTGRES_USER: ci
+        POSTGRES_PASSWORD: ci
+
+pipelines:
+  # Every feature branch: prove it is integrable AND deployable from scratch.
+  branches:
+    '**':
+      - step:
+          name: "dbly · trunk is deployable + green (greenfield)"
+          services: [postgres]
+          script:
+            - pip install -q uv
+            - uv tool install "git+https://github.com/angrydat/dbly@main"
+            - uv tool install dbression
+            # one profile for BOTH dbly (--target) and dbression (auto-discovered)
+            - |
+              cat > connection.properties <<'EOF'
+              environment=postgres
+              connection-string=postgresql://ci:ci@127.0.0.1:5432/ci
+              EOF
+            # empty DB → `apply` bootstraps the full desired state
+            - dbly apply --to HEAD --target connection.properties
+            # desired state must now equal the live DB (no drift)
+            - dbly check --to HEAD --target connection.properties
+            # behaviour gate — JUnit feeds Bitbucket's test report (adjust the path)
+            - dbression run ./tests --junit-xml test-reports/dbression.xml
+
+  # Pull requests into main: also prove the UPGRADE path from production baseline.
+  pull-requests:
+    '**':
+      - step:
+          name: "dbly · upgrade path from main applies cleanly"
+          services: [postgres]
+          script:
+            - pip install -q uv
+            - uv tool install "git+https://github.com/angrydat/dbly@main"
+            - uv tool install dbression
+            - git fetch origin main:refs/remotes/origin/main
+            - |
+              cat > connection.properties <<'EOF'
+              environment=postgres
+              connection-string=postgresql://ci:ci@127.0.0.1:5432/ci
+              EOF
+            # 1) build the released baseline (production state == main)
+            - dbly apply --to origin/main --target connection.properties
+            # 2) review the upgrade — gate here if destructive steps appear
+            - dbly plan  --from origin/main --to HEAD --target connection.properties
+            # 3) apply the upgrade and re-check behaviour on the upgraded DB
+            - dbly apply --from origin/main --to HEAD --target connection.properties
+            - dbression run ./tests --junit-xml test-reports/dbression.xml
+
+  # On a release tag: emit the hand-deploy SQL as a downloadable artifact.
+  tags:
+    'v*':
+      - step:
+          name: "dbly · build hand-deploy SQL for the maintenance window"
+          services: [postgres]
+          script:
+            - pip install -q uv
+            - uv tool install "git+https://github.com/angrydat/dbly@main"
+            - |
+              cat > connection.properties <<'EOF'
+              environment=postgres
+              connection-string=postgresql://ci:ci@127.0.0.1:5432/ci
+              EOF
+            # NOTE: for an accurate additive table-diff, point --target at a *copy of
+            # production* (read access). Against an empty CI DB this yields the full
+            # bootstrap script instead.
+            - dbly plan --to "$BITBUCKET_TAG" --target connection.properties --sql "deploy-$BITBUCKET_TAG.sql"
+          artifacts:
+            - "deploy-*.sql"

dbly-0.0.1/examples/ci/github-actions.yml

@@ -0,0 +1,49 @@
+# GitHub Actions variant of the dbly trunk-based-development gate.
+# Place at .github/workflows/dbly.yml in your *database* repo.
+# Greenfield + behaviour on every push; upgrade path on pull requests.
+
+name: dbly trunk gate
+
+on: [push, pull_request]
+
+jobs:
+  deployable:
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_DB: ci
+          POSTGRES_USER: ci
+          POSTGRES_PASSWORD: ci
+        ports: ["5432:5432"]
+        options: >-
+          --health-cmd "pg_isready -U ci" --health-interval 5s
+          --health-timeout 5s --health-retries 10
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0          # dbly diffs git refs — needs full history
+      - uses: astral-sh/setup-uv@v5
+      - run: uv tool install "git+https://github.com/angrydat/dbly@main"
+      - run: uv tool install dbression
+      - run: |
+          cat > connection.properties <<'EOF'
+          environment=postgres
+          connection-string=postgresql://ci:ci@127.0.0.1:5432/ci
+          EOF
+
+      - name: Greenfield — trunk builds a correct DB from scratch
+        run: |
+          dbly apply --to HEAD --target connection.properties
+          dbly check --to HEAD --target connection.properties
+
+      - name: Upgrade path from main (pull requests only)
+        if: github.event_name == 'pull_request'
+        run: |
+          git fetch origin main
+          # fresh DB instance recommended; here we just validate the plan is clean
+          dbly plan --from origin/main --to HEAD --target connection.properties
+
+      - name: Behaviour gate (dbression)
+        run: dbression run ./tests --junit-xml test-reports/dbression.xml

dbly-0.0.1/pyproject.toml

@@ -0,0 +1,76 @@
+[project]
+name = "dbly"
+version = "0.0.1"
+description = "State-based, cross-engine database deployment — git-driven, parser-assisted, SQL-first."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [
+    { name = "Jürgen Zornig", email = "info@angrydata.info" }
+]
+requires-python = ">=3.12"
+keywords = [
+    "database",
+    "deployment",
+    "migration",
+    "state-based",
+    "schema",
+    "postgres",
+    "oracle",
+    "sqlserver",
+    "sqlite",
+    "sql",
+    "git",
+    "ci-cd",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Information Technology",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: SQL",
+    "Topic :: Database",
+    "Typing :: Typed",
+]
+dependencies = [
+    "typer>=0.12",
+    "rich>=13.7",
+    "sqlalchemy>=2.0",
+    "sqlglot>=25.0",
+    "pyyaml>=6.0",
+    "pathspec>=0.12",
+    "psycopg[binary]>=3.1",
+]
+
+[project.optional-dependencies]
+oracle = ["oracledb>=2.0"]
+mssql = ["pymssql>=2.3"]
+all = ["oracledb>=2.0", "pymssql>=2.3"]
+
+[project.urls]
+Homepage = "https://angrydata.info/dbly"
+Repository = "https://github.com/angrydat/dbly"
+Issues = "https://github.com/angrydat/dbly/issues"
+
+[project.scripts]
+dbly = "dbly.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/dbly"]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "ruff>=0.6",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"

dbly-0.0.1/src/dbly/__init__.py

@@ -0,0 +1,7 @@
+"""dbly — state-based, cross-engine database deployment.
+
+git (what changed) + sqlglot (what it is) + live introspection (what's really there).
+See CONCEPT.md for the design rationale.
+"""
+
+__version__ = "0.0.1"