dbctl 0.1.1__tar.gz

dbctl-0.1.1/.dbctl/connections.yaml

@@ -0,0 +1,150 @@
+# Sample dbctl config for the docker-compose test fleet in this repo.
+#   cp .dbctl/connections.yaml ~/.dbctl/connections.yaml
+#   cp .dbctl/operations.yaml  ~/.dbctl/operations.yaml
+# This file points at the three databases started by `docker compose up -d`.
+
+connections:
+  pg:
+    description: "Postgres dev (docker compose)"
+    aliases: [postgres]
+    type: direct
+    driver: postgresql+psycopg
+    database: app
+    username: app_admin
+    password_env: DBCTL_PG_PASSWORD
+    direct: { host: 127.0.0.1, port: 5433 }
+    healthcheck: { query: "SELECT 1", timeout_seconds: 5 }
+    info:
+      - name: row_counts
+        description: "Top tables by row count"
+        query: |
+          SELECT relname AS table, n_live_tup AS rows
+          FROM pg_stat_user_tables
+          ORDER BY n_live_tup DESC LIMIT 10
+      - name: top_users
+        query: "SELECT name, quota_daily, is_active FROM users ORDER BY quota_daily DESC LIMIT 10"
+    safety:
+      confirm: true
+      read_only: false
+
+  my:
+    description: "MySQL dev (docker compose)"
+    aliases: [mysql]
+    type: direct
+    driver: mysql+pymysql
+    database: app
+    username: app_admin
+    password_env: DBCTL_MY_PASSWORD
+    direct: { host: 127.0.0.1, port: 3307 }
+    healthcheck: { query: "SELECT 1" }
+    info:
+      - name: top_users
+        query: "SELECT name, quota_daily, is_active FROM users ORDER BY quota_daily DESC LIMIT 10"
+    safety:
+      confirm: true
+      read_only: false
+
+  ms:
+    description: "SQL Server dev (docker compose)"
+    aliases: [mssql]
+    type: direct
+    driver: mssql+pyodbc
+    database: app
+    username: sa
+    password_env: DBCTL_MS_PASSWORD
+    # SQL Server needs a configured ODBC driver on the host. Use pyodbc's
+    # connection string by overriding connect_args in your own config:
+    #   connect_args: { driver: "ODBC Driver 18 for SQL Server", TrustServerCertificate: "yes" }
+    direct: { host: 127.0.0.1, port: 1434 }
+    healthcheck: { query: "SELECT 1" }
+    info:
+      - name: top_users
+        query: "SELECT TOP 10 name, quota_daily, is_active FROM dbo.users ORDER BY quota_daily DESC"
+    safety:
+      confirm: true
+      read_only: true
+
+  # --------------------------------------------------------------------- #
+  # Reference templates for tunneled Postgres connections.
+  # These are NOT meant to connect to anything in the docker compose fleet;
+  # they are full-blown reference examples you can copy + edit in your own
+  # ~/.dbctl/connections.yaml. They are marked read_only so accidental runs
+  # are safe.
+  # --------------------------------------------------------------------- #
+
+  # AWS SSM port-forward through an EC2 bastion to a private RDS Postgres.
+  # Requires the `aws` CLI on PATH with an active SSO session in
+  # ~/.aws/cache/sso/*.json for the named `profile`.
+  pg-ssm:
+    description: "REFERENCE: Postgres via AWS SSM (edit before using)"
+    aliases: []
+    type: ssm
+    driver: postgresql+psycopg
+    database: app
+    username: app_admin
+    password_env: DBCTL_PG_SSM_PASSWORD
+    ssm:
+      region: eu-west-1
+      profile: prod                       # AWS SSO profile; tokens in ~/.aws/cache
+      # Resolve the bastion at tunnel-open time via aws ec2 describe-instances.
+      # Useful when the bastion is in an ASG / is replaced often — the tag
+      # set stays stable while the instance id rotates.
+      bastion_tags: { Name: bastion-prod, Env: prod }
+      # alt: hardcode the id and skip the ec2:DescribeInstances call:
+      # bastion_instance_id: i-0abcd1234ef
+      remote_host: mydb.xxxx.eu-west-1.rds.amazonaws.com
+      remote_port: 5432
+      local_port: 0                       # 0 = dbctl picks a free local port
+      ssm_document: AWS-StartPortForwardingSessionToRemoteHost
+    healthcheck: { query: "SELECT 1" }
+    info:
+      - name: row_counts
+        description: "Top tables by row count"
+        query: |
+          SELECT relname AS table, n_live_tup AS rows
+          FROM pg_stat_user_tables
+          ORDER BY n_live_tup DESC LIMIT 10
+      - name: active_conns
+        description: "Active backend connections"
+        query: "SELECT count(*) FROM pg_stat_activity"
+      - name: db_size
+        description: "Database size in bytes"
+        query: "SELECT pg_database_size(current_database()) AS bytes"
+    safety:
+      confirm: true
+      read_only: true
+      allowed_operations: []
+
+  # Classic SSH port-forward through a bastion host to an internal Postgres.
+  # Requires the `ssh` CLI on PATH and a working key file at `identity`
+  # (tilde is expanded). The operator's ~/.ssh/config + agent keep working.
+  pg-ssh:
+    description: "REFERENCE: Postgres via SSH tunnel (edit before using)"
+    aliases: []
+    type: ssh
+    driver: postgresql+psycopg
+    database: app
+    username: app_admin
+    password_env: DBCTL_PG_SSH_PASSWORD
+    ssh:
+      host: bastion.example.com           # reachable from your workstation
+      user: ec2-user
+      identity: ~/.ssh/id_rsa             # ~ is expanded by dbctl
+      remote_host: db.internal            # the database's own hostname, as the bastion sees it
+      remote_port: 5432
+      local_port: 0                       # 0 = dbctl picks a free local port
+      port: 22                            # bastion's SSH port
+    healthcheck: { query: "SELECT 1" }
+    info:
+      - name: row_counts
+        description: "Top tables by row count"
+        query: |
+          SELECT relname AS table, n_live_tup AS rows
+          FROM pg_stat_user_tables
+          ORDER BY n_live_tup DESC LIMIT 10
+      - name: active_conns
+        query: "SELECT count(*) FROM pg_stat_activity"
+    safety:
+      confirm: true
+      read_only: true
+      allowed_operations: []

dbctl-0.1.1/.dbctl/operations.yaml

@@ -0,0 +1,95 @@
+# Sample dbctl operations.
+# Each operation is a parameterised SQL block declaring its inputs; the CLI
+# builds one Click option per parameter (positional + keyword).
+
+operations:
+  add-user:
+    description: "Create or update an application user (Daily quota by default)"
+    scope: single
+    mode: execute
+    confirm: true
+    parameters:
+      - { name: name,  type: string,  required: true,  position: 1, description: "Unique user name" }
+      - { name: quota, type: integer, required: true,  position: 2, description: "Daily quota (used as daily limit)" }
+      - { name: type,  type: string,  default: "Daily", position: 3, description: "Account type" }
+    sql: |
+      INSERT INTO users (name, quota_daily, quota_yearly, type)
+        VALUES ($name, $quota, $quota * 365, $type)
+      ON CONFLICT (name) DO UPDATE
+        SET quota_daily  = EXCLUDED.quota_daily,
+            quota_yearly = EXCLUDED.quota_yearly,
+            type         = EXCLUDED.type,
+            updated_at   = NOW()
+
+  list-users:
+    description: "List users (top N)"
+    scope: single
+    mode: fetch
+    output: table
+    parameters:
+      - { name: limit, type: integer, default: 10, position: 1 }
+    sql: |
+      SELECT name, quota_daily, quota_yearly, type, is_active
+      FROM users
+      ORDER BY quota_daily DESC
+      LIMIT $limit
+
+  find-user:
+    description: "Find a user by name prefix"
+    scope: single
+    mode: fetch
+    parameters:
+      - { name: prefix, type: string, required: true, position: 1 }
+    sql: |
+      SELECT name, quota_daily, is_active FROM users WHERE name ILIKE $prefix || '%'
+
+  report-logs:
+    description: "Summarise logs by level between two dates"
+    scope: single
+    mode: fetch
+    output: table
+    parameters:
+      - { name: since, type: string, required: true, position: 1, description: "ISO date (e.g. 2025-01-01)" }
+      - { name: until, type: string, required: true, position: 2, description: "ISO date" }
+    sql: |
+      SELECT level, COUNT(*) AS events, MIN(created_at) AS first_seen, MAX(created_at) AS last_seen
+      FROM logs
+      WHERE created_at >= $since::timestamp
+        AND created_at <  $until::timestamp
+      GROUP BY level
+      ORDER BY events DESC
+
+# --------------------------------------------------------------------------- #
+# multi-database operations - invoked as `dbctl diff A B --op <name>`
+# --------------------------------------------------------------------------- #
+  user-count:
+    description: "Compare user counts between two databases"
+    scope: multi
+    mode: diff
+    roles: [src, trg]
+    queries:
+      src: "SELECT 'users' AS t, COUNT(*) AS n FROM users"
+      trg: "SELECT 'users' AS t, COUNT(*) AS n FROM users"
+    diff:
+      key: [t]
+      show: [n]
+
+  compare-quotas:
+    description: "Side-by-side quota summary across two databases"
+    scope: multi
+    mode: diff
+    roles: [src, trg]
+    parameters:
+      - { name: period, type: string, default: "Daily", position: 1 }
+    queries:
+      src: |
+        SELECT period AS t, COUNT(*) AS n_rows, SUM(limit_value) AS total_limit
+        FROM quotas JOIN users ON quotas.user_id = users.id
+        WHERE period = $period GROUP BY period
+      trg: |
+        SELECT period AS t, COUNT(*) AS n_rows, SUM(limit_value) AS total_limit
+        FROM quotas JOIN users ON quotas.user_id = users.id
+        WHERE period = $period GROUP BY period
+    diff:
+      key: [t]
+      show: [n_rows, total_limit]

dbctl-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,165 @@
+name: CI
+
+# Run on every push to main and on PRs touching python / packaging /
+# workflow files. Use path filters so doc-only edits don't burn CI minutes.
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+# Cancel any in-progress run when a new commit lands on the same ref —
+# saves CI minutes on rapid force-pushes and PR update churn.
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # ----------------------------------------------------------------------- #
+  # lint + typecheck — fast, no project deps installed
+  # ----------------------------------------------------------------------- #
+  lint:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+      - name: Set up Python
+        run: uv python install 3.12
+      - name: Install dev deps
+        # --frozen keeps CI honest: if uv.lock is out of date the job
+        # fails rather than silently re-resolving.
+        run: uv sync --frozen --extra dev
+      - name: Ruff (annotations PR-native)
+        # --output-format=github emits ::error/::warning annotations that
+        # show up directly on PR file diffs and the run summary.
+        run: uv run ruff check --output-format=github dbctl tests
+      - name: Ruff format check
+        run: uv run ruff format --check dbctl tests
+      - name: Mypy
+        # Non-blocking: the codebase has pre-existing annotation debt that
+        # is being paid down incrementally. Remove `continue-on-error`
+        # once the count reaches zero.
+        run: uv run mypy dbctl
+        continue-on-error: true
+
+  # ----------------------------------------------------------------------- #
+  # test — matrix across supported Python versions + OSes
+  # ----------------------------------------------------------------------- #
+  test:
+    needs: lint
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        # requires-python = ">=3.11" in pyproject.toml
+        python-version: ["3.11", "3.12", "3.13"]
+        os: [ubuntu-latest, macos-latest]
+        exclude:
+          # Trim the matrix: macos + 3.11 + 3.13 stay, but skip 3.13 on
+          # mac to keep minutes in check (Linux covers the linux/3.13 case).
+          - os: macos-latest
+            python-version: "3.11"
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+      - name: Install deps
+        # mssql extra needs ODBC at the system level (libodbc.so), which
+        # isn't on these runners by default; tests don't need it.
+        run: uv sync --frozen --extra dev --extra postgres --extra mysql
+      - name: Run pytest with coverage
+        # --junitxml so failed runs still produce a report artifact;
+        # --cov + --cov-report=xml for coverage upload.
+        run: |
+          uv run pytest tests/ \
+            --junitxml=reports/junit-${{ matrix.os }}-${{ matrix.python-version }}.xml \
+            --cov=dbctl \
+            --cov-report=xml:reports/coverage-${{ matrix.os }}-${{ matrix.python-version }}.xml \
+            --cov-report=term
+      - name: Upload test results
+        if: always()  # upload even on failure so flaky-test data survives
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-results-${{ matrix.os }}-${{ matrix.python-version }}
+          path: reports/
+          if-no-files-found: error
+          retention-days: 14
+      - name: Upload coverage to Codecov
+        # Codecov works tokenless on public repos via OIDC. On private
+        # repos add a CODECOV_TOKEN secret and uncomment `token:`.
+        if: always()
+        uses: codecov/codecov-action@v4
+        with:
+          files: reports/coverage-${{ matrix.os }}-${{ matrix.python-version }}.xml
+          disable_search: true
+          fail_ci_if_error: false
+          # token: ${{ secrets.CODECOV_TOKEN }}
+
+  # ----------------------------------------------------------------------- #
+  # build — wheel + sdist; upload artifact for inspection on every run
+  # ----------------------------------------------------------------------- #
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+      - name: Set up Python
+        run: uv python install 3.12
+      - name: Build distributions
+        run: uv build
+      - name: Verify metadata
+        run: uv run --with twine twine check dist/*
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  # ----------------------------------------------------------------------- #
+  # publish — only on a pushed v* tag, gated on test + build
+  # ----------------------------------------------------------------------- #
+  publish:
+    needs: [test, build]
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    # Dedicated environment — configure "pypi" under repo settings →
+    # Environments with required reviewers/wait-for-approval before the
+    # job can publish. PyPI trusted publishing needs id-token: write.
+    environment:
+      name: pypi
+      url: https://pypi.org/p/dbctl
+    permissions:
+      contents: read
+      id-token: write  # OIDC trusted publishing
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

dbctl-0.1.1/.gitignore

@@ -0,0 +1,35 @@
+# python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+build/
+dist/
+.eggs/
+
+# virtual envs
+.venv/
+venv/
+env/
+
+# test / lint caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+.tox/
+
+# editors / OS
+.idea/
+.vscode/
+.DS_Store
+*.swp
+*.swo
+*~
+
+# local dbctl runtime state (sample configs live under .dbctl/ in the repo;
+# ignore the per-user history/profile data that dbctl writes at runtime)
+.dbctl/history.jsonl
+.dbctl/profiles/

dbctl-0.1.1/CHANGELOG.md

@@ -0,0 +1,81 @@
+# Changelog
+
+All notable changes to this project will be documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.1] — 2026-08-01
+
+Retag of the initial public release (v0.1.0 publish failed; the trusted
+publisher had not yet been registered on PyPI). No code changes — only
+the version bump.
+
+## [0.1.0] — 2026-08-01
+
+Initial public release.
+
+### Added
+
+- **Connection registry** (`~/.dbctl/connections.yaml`) validated with pydantic
+  v2, supporting three tunnel types:
+  - `ssm` — AWS SSM port-forward through an EC2 bastion, shelled out to the
+    `aws` CLI. Supports `bastion_instance_id` or `bastion_tags` (resolved via
+    `aws ec2 describe-instances`).
+  - `ssh` — classic `ssh -N -L` port-forward, shelled out to the `ssh` CLI
+    with `ExitOnForwardFailure=yes` and `StrictHostKeyChecking=accept-new`.
+  - `direct` — no tunnel, connect to upstream host:port.
+- **Operations registry** (`~/.dbctl/operations.yaml`) with two scopes:
+  - `single` — `dbctl <conn> <op> ...` with `execute` / `fetch` / `fetch_one` /
+    `script` / `upsert` modes.
+  - `multi` — `dbctl diff <op> <src> <trg> ...` with `diff` mode (side-by-side
+    join on a `key`); `compare` / `sync` modes reserved for v2.
+- **Dynamic CLI** built from the registries: one Click subcommand per
+  connection, one per declared operation. Positional params via `position:`,
+  keyword params via `--flag`, all generated from the YAML declaration.
+- **`$name` placeholders** rewritten to SQLAlchemy bind-params (`:name`) —
+  values are always parameterised, never string-interpolated.
+- **Safety model**:
+  - `safety.confirm: true` makes DML **dry-run by default**; `--apply`
+    commits, `--yes` skips the prompt. Confirm happens *before* the
+    transaction opens so `N` leaves the DB untouched.
+  - `safety.read_only: true` blocks every DML op.
+  - `safety.allowed_operations: [...]` whitelists op names.
+- **Audit log** at `~/.dbctl/history.jsonl` — one JSON event per run; secret
+  parameters redacted. `dbctl history list` / `dbctl <conn> history` /
+  `dbctl <conn> again` (re-run last).
+- **Dashboard** — `dbctl` bare shows connections table; `dbctl <conn>` shows
+  a connection page with health, info queries, and available ops.
+- **`dbctl doctor`** — healthcheck every connection.
+- **`dbctl init`** — interactive wizard that writes/merges a new connection
+  and tests the tunnel + healthcheck before saving.
+- **Shell completion** via `dbctl --install-completion bash|zsh|fish`.
+- **`--profile <name>`** — swap config dir to `~/.dbctl/profiles/<name>/`.
+- **Connection aliases** — `prod` resolves to `db1`, etc.
+- **Bundled test fleet** — `docker-compose.yml` brings up postgres on
+  `:5433`, mysql on `:3307`, mssql on `:1434` with the same four-table
+  schema (`users`, `quotas`, `usage`, `logs`) and slightly different sample
+  data for diff testing.
+- **15 unit tests** against in-memory SQLite covering placeholder rewriting,
+  parameter binding/coercion, mode routing, side-by-side diff, and audit
+  redaction.
+
+### Documentation
+
+- `README.md` — usage, install, quick start, config layout, safety model.
+- `docs/connections.md` — full `connections.yaml` reference with examples.
+- `docs/operations.md` — full `operations.yaml` reference with the safety
+  check matrix.
+- `docs/DESIGN.md` — architecture, layering, dynamic CLI, placeholder
+  semantics, confirm-before-commit invariant, exit codes.
+
+### Known limitations (v1)
+
+- `mode: script` runs only the first statement in v1; multi-statement
+  scripts are v2.
+- `mode: upsert` is reserved — the autoload/dialect-aware conflict logic is
+  v2.
+- Operations are dialect-specific (no per-connection overrides).
+- `${var}` identifier interpolation is intentionally absent (would be a SQL
+  injection vector with naive `str.replace`); use one op per table for now.
+- Multi-DB tunnels open sequentially (parallel is v2).