ticketwright 2.0.0__py3-none-any.whl

ticketwright/_kit/adapters/warehouse/databricks.md

@@ -0,0 +1,58 @@
+---
+seam: warehouse
+tool: databricks
+transport: both        # `dbsqlcli` / Statement Execution API for SQL; a Databricks SQL MCP for interactive
+requires: [warehouse_id, catalog, schema]   # stack.yaml seams.warehouse.{warehouse_id, catalog, schema, dev_catalog, profile}
+auth: |
+  A Databricks SQL warehouse + a token. Either: `dbsqlcli` (pip install databricks-sql-cli) configured
+  via `~/.dbsqlclirc` or env (`DBSQLCLI_HOST_NAME`, `DBSQLCLI_HTTP_PATH`, `DBSQLCLI_ACCESS_TOKEN`); or
+  the `databricks` CLI profile (~/.databrickscfg) for the Statement Execution API; or a SQL MCP.
+  Verify: `databricks --profile {profile} current-user me` (read-only).
+note: |
+  The `databricks` CLI has NO ad-hoc "run this SQL" command (`databricks sql` is API CRUD, not a query
+  runner). Execute SQL via `dbsqlcli`, the Statement Execution API, or the SQL MCP — all below.
+---
+
+# Databricks adapter
+
+Maps the `warehouse` verb contract to Databricks (Unity Catalog, Spark SQL). Same verbs as Snowflake;
+only commands + `dialect_notes` differ, so `review` / `spec-and-build` / `refresh context` run
+unchanged.
+
+## verb: query
+```bash
+# Preferred: databricks-sql-cli (returns rows; --csv-friendly via -e + redirection)
+dbsqlcli -e "<SQL>"                                   # ad-hoc
+dbsqlcli -e "$(cat path/to/file.sql)"                 # bundled
+# Or the Statement Execution API (no extra tool; good for CI):
+databricks --profile {profile} api post /api/2.0/sql/statements \
+  --json '{"warehouse_id":"{warehouse_id}","statement":"<SQL>","wait_timeout":"30s"}'
+# Or route through the Databricks SQL MCP for interactive exploration.
+```
+- Deterministic exports: explicit `ORDER BY` (Spark result order is not guaranteed).
+- Reference objects three-part: `{catalog}.{schema}.<object>`.
+- The Statement API is async beyond `wait_timeout`: poll `GET /api/2.0/sql/statements/<id>` until
+  `status.state=SUCCEEDED`, then read `result`.
+
+## verb: describe
+```bash
+dbsqlcli -e "DESCRIBE TABLE EXTENDED {catalog}.{schema}.<obj>"
+dbsqlcli -e "SHOW CREATE TABLE {catalog}.{schema}.<obj>"     # DDL
+```
+Inventory: `SHOW TABLES IN {catalog}.{schema}`. Lineage: Unity Catalog `system.access.table_lineage`
+/ `information_schema` (not a naive `SHOW TABLES`, which misses views' upstreams).
+
+## verb: dialect_notes  (read by the review skill)
+- **Functions:** `coalesce`/`nvl`, `try_divide(a,b)` (div-by-zero → NULL), `try_cast`, `collect_list`
+  / `array_agg` (vs LISTAGG), `date_trunc`. `= NULL` never matches — use `IS NULL`.
+- **Sizing:** SQL warehouse / cluster size + **partitioning / Z-ORDER / liquid clustering**; pruning
+  the partition (or clustered) column is the main scan lever. `SELECT *` on wide Delta tables is the
+  costly anti-pattern — list columns.
+- **Joins:** type-match keys with `cast`/`try_cast`; mind `STRING` vs `BIGINT`. Broadcast small dims.
+- **Dev/deploy:** dev objects in `{dev_catalog}`; promote with scripted `CREATE OR REPLACE`.
+
+## gotchas
+- Non-SELECT / DDL ⇒ policy `db_write_requires_approval` (show SQL, explain, wait).
+- **Pause before any prod job deploy** — stop for human confirmation before writing prod job
+  definitions or PR-ing to a jobs repo.
+- The `databricks` CLI is for workspace/API management; SQL runs through `dbsqlcli` / the SQL API / MCP.

ticketwright/_kit/adapters/warehouse/postgres.md

@@ -0,0 +1,44 @@
+---
+seam: warehouse
+tool: postgres
+transport: cli         # `psql`
+requires: [conn]       # stack.yaml seams.warehouse.{conn, dev_schema}  (conn = libpq URL or service name)
+auth: |
+  libpq env (`PGHOST`/`PGUSER`/`PGPASSWORD`/`PGDATABASE`) or a connection URL in `{conn}`; `~/.pgpass`
+  for non-interactive. Verify: `psql "{conn}" -c "SELECT 1"` (read-only).
+---
+
+# PostgreSQL adapter
+
+Maps the `warehouse` verb contract to PostgreSQL via `psql`. Same three verbs as every warehouse —
+only commands + `dialect_notes` differ, so the data skills run unchanged.
+
+## verb: query
+```bash
+psql "{conn}" --csv -c "<SQL>"            # ad-hoc, CSV (header row 1)
+psql "{conn}" --csv -f <file.sql>         # bundled multi-statement
+```
+- `--csv` emits clean CSV (no `psql` table borders). Add `-t` to drop the header if needed.
+- Deterministic exports: explicit `ORDER BY` (row order is otherwise unspecified).
+
+## verb: describe
+```bash
+psql "{conn}" -c "\d+ <schema.table>"                     # columns, types, indexes
+psql "{conn}" -c "SELECT pg_get_viewdef('<schema.view>', true)"   # view DDL
+```
+Inventory: `\dt <schema>.*`; lineage via `information_schema` / `pg_depend`.
+
+## verb: dialect_notes  (read by the review skill)
+- **Functions:** `COALESCE`, `NULLIF(a,0)` (div-by-zero guard), `string_agg(x, ',')` (vs LISTAGG),
+  `array_agg`, `date_trunc`. `= NULL` never matches — use `IS NULL`. Cast with `::type` or `CAST()`.
+- **Sizing:** no "warehouse size" — performance is **indexes** + query plans. Use `EXPLAIN (ANALYZE,
+  BUFFERS)`; ensure join/filter columns are indexed; beware sequential scans on big tables.
+- **Joins:** type-match keys (`int` vs `text` won't use an index); `CAST` explicitly.
+- **Anti-patterns:** `SELECT *` in shipped queries; functions on indexed columns in `WHERE` (kills
+  index use); missing `ORDER BY` on exports.
+- **Dev/deploy:** build dev objects in `{dev_schema}` (or set `search_path`); promote with scripted
+  `CREATE OR REPLACE` / migrations.
+
+## gotchas
+- Non-SELECT (UPDATE/INSERT/DELETE/DDL) ⇒ policy `db_write_requires_approval`.
+- Wrap multi-statement deploys in a transaction (`BEGIN; … COMMIT;`) so a failure rolls back.

ticketwright/_kit/adapters/warehouse/redshift.md

@@ -0,0 +1,49 @@
+---
+seam: warehouse
+tool: redshift
+transport: cli         # `aws redshift-data` (Data API) or `psql` (Redshift speaks the pg wire protocol)
+requires: [database]   # stack.yaml seams.warehouse.{database, workgroup_name | cluster_identifier, dev_schema}
+auth: |
+  Data API: AWS creds (`aws sts get-caller-identity`) + Secrets Manager/IAM for the DB. **Serverless**
+  passes `--workgroup-name {workgroup_name}`; **provisioned** passes `--cluster-identifier
+  {cluster_identifier}` (+ `--db-user`). Or `psql` with the endpoint creds. Verify (serverless):
+  `aws redshift-data list-databases --database {database} --workgroup-name {workgroup_name}` — or `psql … -c "SELECT 1"`.
+---
+
+# Amazon Redshift adapter
+
+Maps the `warehouse` verb contract to Redshift. Two transports: the **Data API** (no driver, good for
+CI/Serverless) and **`psql`** (Redshift is Postgres-wire-compatible). Pick one per `{conn}`.
+
+## verb: query
+```bash
+# Data API (async: execute → wait → fetch). Serverless:
+id=$(aws redshift-data execute-statement --database {database} \
+      --workgroup-name {workgroup_name} --sql "<SQL>" --query Id --output text)
+# Provisioned cluster instead: --cluster-identifier {cluster_identifier} --db-user <user>
+aws redshift-data describe-statement --id "$id" --query Status   # poll until FINISHED
+aws redshift-data get-statement-result --id "$id"                 # JSON rows
+# or direct: psql "host=<endpoint> dbname={database} ..." --csv -c "<SQL>"
+```
+- Deterministic exports: explicit `ORDER BY`.
+
+## verb: describe
+```bash
+# columns:  SELECT * FROM svv_columns WHERE table_name='<t>' AND table_schema='<s>';
+# DDL:      SELECT pg_get_viewdef('<schema.view>', true);  -- or pg_table_def for tables
+```
+Inventory via `svv_tables` / `svv_columns`.
+
+## verb: dialect_notes  (read by the review skill)
+- **Functions:** `NVL`/`COALESCE`, `NULLIF`, `LISTAGG(x, ',') WITHIN GROUP (ORDER BY …)`,
+  `DATE_TRUNC`. Postgres-derived SQL, but a reduced function set vs Postgres.
+- **Sizing/perf:** the real levers are **DISTKEY** (join co-location) and **SORTKEY** (range-scan
+  pruning) + column compression (ENCODE). Columnar store ⇒ `SELECT *` scans every column — list them.
+  Run `VACUUM`/`ANALYZE` after big loads; check `EXPLAIN`.
+- **Joins:** matching DISTKEY avoids data redistribution (the main cost); type-match keys.
+- **Dev/deploy:** dev objects in `{dev_schema}`; promote with scripted `CREATE TABLE AS` / `CREATE OR
+  REPLACE VIEW`.
+
+## gotchas
+- Data API is **async** — always poll `describe-statement` to `FINISHED` before `get-statement-result`.
+- Non-SELECT/DDL ⇒ policy `db_write_requires_approval`.

ticketwright/_kit/adapters/warehouse/snowflake.md

@@ -0,0 +1,54 @@
+---
+seam: warehouse
+tool: snowflake
+transport: both        # `snow` CLI for scripts/exports; Snowflake MCP for interactive/semantic
+requires: [cli]        # stack.yaml seams.warehouse.{cli, default_warehouse, pii_role, dev_db}
+auth: |
+  CLI:  ~/.snowflake/config.toml connection (USERNAME_PASSWORD_MFA for CLI/MCP).
+  Verify: `snow connection test` (read-only).
+  Duo lockout signature: instant 250001/370001 = locked (wait 15 min); hang = push pending.
+---
+
+# Snowflake adapter
+
+Maps the `warehouse` verb contract to Snowflake via the `snow` CLI (preferred for repeatable scripts
+and CSV export) and the Snowflake MCP (preferred for interactive exploration + the semantic layer).
+
+## verb: query
+```bash
+snow sql -q "<SQL>" --format csv          # ad-hoc
+snow sql -f <path/to/file.sql>            # bundled multi-statement (minimizes MFA prompts)
+```
+- **Bundle** multi-step work into one `.sql` run via `-f` (one MFA prompt, not many).
+- CSV: always `--format csv`; **strip** the `status` / `Statement executed successfully.` preamble
+  the multi-statement `-f` run prints ahead of the result. Robust, documented norm:
+  `bin/split_and_export.sh --strip-only <csv>` (drops through the *last* "Statement executed
+  successfully." then leading blanks) — and its split mode turns one multi-`SELECT` file into N CSVs.
+- Set warehouse/role inside the SQL: `USE WAREHOUSE {default_warehouse}; USE ROLE {pii_role};`.
+- **Deterministic exports:** always end exports with explicit `ORDER BY` (Snowflake doesn't preserve
+  insertion order on `SELECT *`) — required for byte-identical golden replays.
+
+## verb: describe
+```bash
+snow sql -q "DESCRIBE TABLE <schema.object>" --format csv
+snow sql -q "SELECT GET_DDL('VIEW','<schema.object>')" --format csv
+# semantic view: snow sql -q "DESCRIBE SEMANTIC VIEW <name>"
+```
+Discover objects via `INFORMATION_SCHEMA.TABLES` + `ACCOUNT_USAGE.OBJECT_DEPENDENCIES` (NOT
+`SHOW VIEWS` — it misses dynamic tables / base tables).
+
+## verb: dialect_notes  (read by the review skill's anti-pattern sweep)
+- **Functions:** `IFF`, `NVL/COALESCE`, `NULLIF` (div-by-zero guard), `LISTAGG` (many-to-many),
+  `DATE_TRUNC`. `=NULL` never matches — use `IS NULL`.
+- **Sizing:** use a named virtual warehouse for heavy QC (e.g. `{default_warehouse}`), not slots.
+- **Joins:** `CAST()` keys when joining across sources (NUMBER vs VARCHAR mismatches); apply any
+  required tenant/schema filter your shared views expect; where a view unions migrated + native
+  data, filter to the rows you actually want (e.g. a `IS_MIGRATED` / source flag).
+- **Layering:** prefer your curated layers (e.g. `RAW → STAGING → ANALYTICS → REPORTING`); avoid
+  legacy/raw schemas and point-in-time snapshot tables unless the work is compliance/historical.
+- **Dynamic-table chains:** never interpose a regular view between dynamic tables (`target_lag='DOWNSTREAM'`).
+- **Dev/deploy:** build dev objects in `{dev_db}`; promote with your multi-env deploy template (COPY GRANTS).
+
+## gotchas
+- Non-SELECT (UPDATE/CREATE/DELETE/DDL) ⇒ policy `db_write_requires_approval`: show the SQL, explain,
+  wait for explicit `yes` before running.

ticketwright/_kit/adapters/warehouse/synapse.md

@@ -0,0 +1,52 @@
+---
+seam: warehouse
+tool: synapse
+transport: cli         # `sqlcmd` (go-sqlcmd) — also covers Azure SQL / SQL Server / Fabric Warehouse
+requires: [server, database]   # stack.yaml seams.warehouse.{server, database, dev_schema}
+auth: |
+  `sqlcmd` (go-sqlcmd) with Azure AD: `-G --authentication-method ActiveDirectoryDefault` after
+  `az login` (or a service principal / `ActiveDirectoryInteractive`). Verify:
+  `sqlcmd -S {server} -d {database} -G --authentication-method ActiveDirectoryDefault -Q "SELECT 1"`.
+---
+
+# Azure Synapse / Azure SQL adapter (T-SQL)
+
+Maps the `warehouse` verb contract to T-SQL backends — Synapse (dedicated SQL pool / serverless),
+Azure SQL Database, SQL Server, or Fabric Warehouse — via `sqlcmd`. Only commands + `dialect_notes`
+differ from the other warehouses, so the data skills run unchanged.
+
+## verb: query
+```bash
+sqlcmd -S {server} -d {database} -G --authentication-method ActiveDirectoryDefault \
+       -s"," -W -Q "<T-SQL>"            # comma-separated + trimmed; add `-h -1` to drop the header row
+sqlcmd -S {server} -d {database} -G --authentication-method ActiveDirectoryDefault \
+       -s"," -W -i <file.sql>
+```
+- CSV via `-s"," -W` (column separator + trim trailing spaces); `-h -1` suppresses the header.
+  go-sqlcmd's `--format` only supports `horizontal`/`vertical`/`json` — there is **no** `csv` value
+  (pipe `--format json` through a JSON→CSV step if you prefer). Deterministic exports: explicit
+  `ORDER BY` (T-SQL only guarantees order with an outer `ORDER BY`).
+
+## verb: describe
+```bash
+# columns:  sqlcmd ... -Q "SELECT column_name, data_type FROM information_schema.columns WHERE table_name='<t>'"
+# view DDL: sqlcmd ... -Q "SELECT definition FROM sys.sql_modules WHERE object_id=OBJECT_ID('<schema.view>')"  -- portable; sp_helptext is SQL-Server/Azure-SQL only (not Synapse pools)
+```
+Inventory via `information_schema.tables` / `sys.objects`.
+
+## verb: dialect_notes  (read by the review skill)
+- **Functions:** `ISNULL`/`COALESCE`, `NULLIF`, `TRY_CAST`/`TRY_CONVERT`, `STRING_AGG(x, ',')`
+  (2017+/Synapse), `TOP n` (not `LIMIT`), `GETDATE()`/`SYSDATETIME()`. `[bracketed]` identifiers.
+- **Sizing/perf (Synapse dedicated):** table **distribution** (`HASH` on the join key / `ROUND_ROBIN`
+  / `REPLICATE` for small dims) is the main lever; avoid data movement by aligning distributions.
+  Resource classes govern memory. Serverless: cost = bytes scanned (partition/prune).
+- **Joins:** type-match keys (`TRY_CAST`); matching HASH distribution avoids shuffles.
+- **Anti-patterns:** `SELECT *` (columnstore scans all columns); row-by-row cursors; missing `ORDER BY`.
+- **Dev/deploy:** dev objects in `{dev_schema}`; promote views with `CREATE OR ALTER VIEW`. For
+  tables: `CTAS` (`CREATE TABLE … AS SELECT`) on Synapse dedicated / Fabric; on Azure SQL DB /
+  SQL Server use `SELECT … INTO` instead (they don't support CTAS).
+
+## gotchas
+- Non-SELECT/DDL ⇒ policy `db_write_requires_approval`.
+- Synapse dedicated pools don't support every T-SQL construct (e.g. some `MERGE`/constraint features)
+  — check the pool type before assuming.