From 6afca20b2a637ef9ea8842f406947d3dc0141a77 Mon Sep 17 00:00:00 2001 From: Andrey Avtomonov Date: Sun, 24 May 2026 01:29:13 +0200 Subject: [PATCH] docs: document query history readiness probes --- docs-site/content/docs/cli-reference/ktx-setup.mdx | 10 ++++++++++ docs-site/content/docs/cli-reference/ktx-status.mdx | 4 ++-- 2 files changed, 12 insertions(+), 2 deletions(-) diff --git a/docs-site/content/docs/cli-reference/ktx-setup.mdx b/docs-site/content/docs/cli-reference/ktx-setup.mdx index a52a3eba..541a2460 100644 --- a/docs-site/content/docs/cli-reference/ktx-setup.mdx +++ b/docs-site/content/docs/cli-reference/ktx-setup.mdx @@ -134,6 +134,16 @@ window flag applies to BigQuery and Snowflake; Postgres reads the current Enabling query history makes deep ingest readiness matter for later `ktx ingest` runs. +When query history is enabled for PostgreSQL, Snowflake, or BigQuery, +`ktx setup` runs a non-blocking readiness probe after the connection test +passes. A failed probe still writes setup changes, prints the warehouse-specific +grant or extension remediation, and leaves query-history ingest disabled until +you fix the prerequisite. + +For BigQuery, the remediation tells you to grant `roles/bigquery.resourceViewer` +on the BigQuery project, or grant a custom role that contains +`bigquery.jobs.listAll`. + ### Context Sources | Flag | Description | diff --git a/docs-site/content/docs/cli-reference/ktx-status.mdx b/docs-site/content/docs/cli-reference/ktx-status.mdx index c86c12e0..51c00148 100644 --- a/docs-site/content/docs/cli-reference/ktx-status.mdx +++ b/docs-site/content/docs/cli-reference/ktx-status.mdx @@ -21,7 +21,7 @@ ktx status [options] | `--json` | Print JSON output | `false` | | `-v`, `--verbose` | Show every check, including passing ones | `false` | | `--validate` | Only validate the `ktx.yaml` schema; skip readiness checks | `false` | -| `--fast` | Skip checks that require external communication (Postgres query-history probe, Claude Code auth probe) | `false` | +| `--fast` | Skip checks that require external communication (query-history readiness probes and Claude Code auth probe) | `false` | | `--no-input` | Disable interactive terminal input | - | ## Examples @@ -39,7 +39,7 @@ ktx status --verbose # Validate ktx.yaml without running readiness checks ktx status --validate -# Skip slow probes (Postgres pg_stat_statements, Claude Code auth) +# Skip slow probes (query-history readiness, Claude Code auth) ktx status --fast # Check a project from another directory