Runbook & FAQ¶

Release checklist (v1)¶

All CI gates green on main; no open release-blocking issues on the current milestone.
CHANGELOG updated at tag time (minor/major releases; patch only if user-visible or security-relevant — see the policy in CHANGELOG.md): curate git log v<prev>..HEAD --oneline down to what a deployer/user acts on, and mirror the entry into the GitHub Release body.
Backend image built + pushed to GHCR with an immutable tag (not latest).
DB migrations are backward-compatible; the migrate job runs alembic upgrade head before the app rolls.
Deploy via the Deploy workflow (workflow_dispatch); verify /healthz 200, /api/v1/me 401 (auth enforced), SPA + deep links load.
Docs site published (this site) and linked from the README.

Full deploy steps + verification: deploy/README.md.

Live smoke (deployed stack + harness data)¶

Snowflake window update (2026-07-04): the trial runs to ~2026-07-25 (same as Azure). The #588 retirement was rehearsed and reversed the same day — the leg is live again on a fresh 25-day PAT (schedules/bindings restore pending, see #588); the real retirement re-runs at actual lapse alongside the #590 wind-down. Scale numbers are in perf-baseline.md (all-datasource baseline, 2026-07-10).

Automated, opt-in (never CI):

API-level: DATAQ_API=https://<frontend-host> DATAQ_BEARER=<AAD token> python -m backend.scripts.e2e_smoke — read + authoring round-trips against the live API (12 checks).
Browser-level: E2E_LIVE_BASE_URL=https://<frontend-host> pnpm e2e in frontend/ — a headed one-time OIDC sign-in, then read-only specs (dashboard KPIs, live suite + checks, run-detail). See frontend/e2e/README.md.

Manual checklist (the mutating tail):

Trigger a live suite run (Run now) on a harness suite → completes green on real warehouse/file data.
Let a harness pipeline (ADF or Airflow) succeed → the bound suite auto-runs and correlates on Results → Pipelines.
Force a failing run → the Teams/Slack/email alert arrives with the right severity; a repeat failure is deduped.
MCP: point Claude Desktop at https://<frontend-host>/mcp/ (trailing slash — see AI assistants (MCP setup)) and run the 4 canonical queries (what failed today / run suite X / why did pipeline Y fail / add a null check).

Known limitations (v1)¶

GX-only check engine (Databricks DQX deferred to v1.1); batch-oriented (not streaming).
Single tenant, suite-level access sharing; workspace-admin is a config allowlist.
Interactive datasource browsing (container browser, 3-level UC catalog picker) is deferred — you specify targets explicitly. JSON flat files deferred (CSV/Parquet in v1).
Auth is Azure AD only (no API keys / service tokens yet — see ADR 0026 / #461).

FAQ¶

Is ADF/Airflow a datasource? No — they're orchestration providers DataQ monitors and can trigger from. You never write checks against them. See Concepts.

Do I need Azure to run it locally? No — local dev uses a dev-bypass auth and docker-compose. Azure is one deployment target behind the app's seams (ADR 0010/0013).

Where do failed-row samples go? Stored with the result, PII-redacted, and purged after a retention window — never written to logs.

Can an AI assistant use DataQ? Yes — 8 MCP tools at /mcp (Claude Desktop / Claude.ai / Copilot / Cursor), Azure-AD authenticated. See AI assistants (MCP setup).

An asset shows no lineage — is that right? Maybe not. "No lineage recorded" is what you see both when an asset genuinely has no upstreams and when DataQ has been unable to read your dbt artifacts — the two are indistinguishable in the UI today. Test the dbt connection first: its secret is the artifacts-store read credential, and when it expires the poll fails silently while your dbt builds keep succeeding. Note that fixing the credential alone will not backfill — the poll's 15-minute lookback means every build produced during the outage is already stranded, so you must re-run the dbt build to get a fresh artifact into the window. Full detail in Orchestration → When lineage is empty and #828.