dbctl 0.5.3__tar.gz → 0.6.2__tar.gz

{dbctl-0.5.3 → dbctl-0.6.2}/.dbctl/connections.yaml

@@ -23,7 +23,7 @@ connections:
           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"
+        query: "SELECT name, credits_daily, is_active FROM users ORDER BY credits_daily DESC LIMIT 10"
     safety:
       confirm: true
       read_only: false
@@ -41,7 +41,7 @@ connections:
     healthcheck: { query: "SELECT 1" }
     info:
       - name: top_users
-        query: "SELECT name, quota_daily, is_active FROM users ORDER BY quota_daily DESC LIMIT 10"
+        query: "SELECT name, credits_daily, is_active FROM users ORDER BY credits_daily DESC LIMIT 10"
     safety:
       confirm: true
       read_only: false
@@ -62,7 +62,7 @@ connections:
     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"
+        query: "SELECT TOP 10 name, credits_daily, is_active FROM dbo.users ORDER BY credits_daily DESC"
     safety:
       confirm: true
       read_only: true
@@ -191,4 +191,38 @@ connections:
     safety:
       confirm: true
       read_only: true
-      allowed_operations: []
+      allowed_operations: []
+  # --------------------------------------------------------------------- #
+  # Full SQLAlchemy URL + Windows SSO reference templates.
+  # --------------------------------------------------------------------- #
+
+  # Full SQLAlchemy connection string — use when you need ODBC-specific
+  # query params, Azure AD auth, or any scheme dbctl's individual fields
+  # don't model. When `url:` is set, the tunnel's local bind is NOT
+  # injected — the URL's own host:port wins.
+  azure-sql:
+    description: "REFERENCE: Azure SQL via full SQLAlchemy URL (edit before using)"
+    aliases: []
+    type: direct
+    url: "mssql+pyodbc://app_admin@myserver.database.windows.net:1433/app?driver=ODBC+Driver+18+for+SQL+Server&Encrypt=yes&Authentication=ActiveDirectoryPassword"
+    direct: { host: myserver.database.windows.net, port: 1433 }
+    healthcheck: { query: "SELECT 1", timeout_seconds: 10 }
+    safety:
+      confirm: true
+      read_only: true
+
+  # SQL Server with Windows Integrated Security (Trusted_Connection=yes).
+  # No username / password / password_env / prompt needed — the ODBC
+  # driver uses the current Windows user's credentials.
+  mssql-sso:
+    description: "REFERENCE: SQL Server with Windows SSO (edit before using)"
+    aliases: []
+    type: direct
+    driver: mssql+pyodbc
+    database: app
+    windows_sso: true
+    direct: { host: 10.0.0.5, port: 1433 }
+    healthcheck: { query: "SELECT 1", timeout_seconds: 5 }
+    safety:
+      confirm: true
+      read_only: true

dbctl-0.6.2/.dbctl/operations.yaml

@@ -0,0 +1,179 @@
+# 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 credits by default)"
+    scope: single
+    mode: execute
+    confirm: true
+    parameters:
+      - { name: name,  type: string,  required: true,  position: 1, description: "Unique user name" }
+      - { name: credits, type: integer, required: true,  position: 2, description: "Daily credits (used as daily limit)" }
+      - { name: type,  type: string,  default: "Daily", position: 3, description: "Account type" }
+    sql: |
+      INSERT INTO users (name, credits_daily, credits_yearly, type)
+        VALUES ($name, $credits, $credits * 365, $type)
+      ON CONFLICT (name) DO UPDATE
+        SET credits_daily  = EXCLUDED.credits_daily,
+            credits_yearly = EXCLUDED.credits_yearly,
+            type         = EXCLUDED.type,
+            updated_at   = NOW()
+
+  increase-credits:
+    description: "Increase a user's daily and yearly credits by a percentage"
+    scope: single
+    mode: execute
+    confirm: true
+    parameters:
+      - { name: name, type: string, required: true, position: 1, description: "User to bump" }
+      - { name: pct,  type: float,  required: true, position: 2, description: "Percentage increase (e.g. 10 = +10%)" }
+    sql: |
+      UPDATE users
+         SET credits_daily  = (credits_daily  * (1 + $pct / 100.0))::integer,
+             credits_yearly = (credits_yearly * (1 + $pct / 100.0))::integer,
+             updated_at   = NOW()
+       WHERE name = $name
+
+  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, credits_daily, credits_yearly, type, is_active
+      FROM users
+      ORDER BY credits_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, credits_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-credits:
+    description: "Side-by-side credits 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 credits JOIN users ON credits.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 credits JOIN users ON credits.user_id = users.id
+        WHERE period = $period GROUP BY period
+    diff:
+      key: [t]
+      show: [n_rows, total_limit]
+
+  # compare row counts of every user table side-by-side.
+  # Uses the `table_counts` strategy so we don't have to spell out the
+  # SELECT 'users' AS t, COUNT(*) ... boilerplate per table.
+  # NOTE: list the tables explicitly — `["*"]` introspection is only
+  # supported by `copy`/`replay`, not by the `table_counts` diff strategy.
+  table-counts:
+    description: "Compare row counts of every declared table across two DBs"
+    scope: multi
+    mode: diff
+    roles: [src, trg]
+    diff:
+      strategy: table_counts
+      tables: [users, credits, usage, logs]
+      key: [t]
+      show: [n]
+
+  # bulk-copy the `users` table from src to trg in batches of 1000 rows.
+  # `--on-conflict truncate` is the safe refresh path; `--dry-run` simulates.
+  copy-users:
+    description: "Bulk-copy users table src → trg (batches of 1000)"
+    scope: multi
+    mode: copy
+    roles: [src, trg]
+    copy_spec:
+      batch_size: 1000
+      tables: [users]                 # omit `tables:` to introspect all src tables
+      on_conflict: error              # error | skip | update | truncate
+
+  # converge the `users` table on trg to match src: insert missing rows,
+  # update differing rows, and (with --delete-extras) delete trg-only rows.
+  # Both queries MUST return the same column shape; `key` identifies rows.
+  sync-users:
+    description: "Converge trg users to match src (insert + update; --delete-extras to also remove)"
+    scope: multi
+    mode: sync
+    roles: [src, trg]
+    queries:
+      src: "SELECT id, name, credits_daily, credits_yearly, type, is_active FROM users"
+      trg: "SELECT id, name, credits_daily, credits_yearly, type, is_active FROM users"
+    sync_spec:
+      key: [id]
+      target_table: users
+      delete_extras: false             # CLI `--delete-extras` overrides per run
+
+  # detect schema drift: compare columns + types for each table present in
+  # both schemas. Leave `tables:` null to introspect the intersection.
+  validate-schema:
+    description: "Detect column/type drift between src and trg schemas"
+    scope: multi
+    mode: validate
+    roles: [src, trg]
+    validate_spec:
+      tables: [users, credits, usage, logs]
+      # include: []                  # restrict to these column names
+      # exclude: [created_at]         # drop these column names from the diff
+
+  # copy with a per-row Python transform. `identity` is a no-op; to mutate
+  # rows set `transform:` to a `package.module:callable` import path that
+  # takes a row dict and returns a dict.
+  replay-users:
+    description: "Copy users src → trg with a per-row transform (identity = no-op)"
+    scope: multi
+    mode: replay
+    roles: [src, trg]
+    replay_spec:
+      tables: [users]
+      batch_size: 500
+      transform: identity

{dbctl-0.5.3 → dbctl-0.6.2}/.github/workflows/ci.yml

@@ -62,14 +62,14 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        # requires-python = ">=3.11" in pyproject.toml
-        python-version: ["3.11", "3.12", "3.13"]
+        # requires-python = ">=3.12" in pyproject.toml
+        python-version: ["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).
+          # Trim the matrix: skip 3.13 on mac to keep minutes in check
+          # (Linux covers the linux/3.13 case).
           - os: macos-latest
-            python-version: "3.11"
+            python-version: "3.12"
     steps:
       - uses: actions/checkout@v4
       - name: Install uv