mirror of
https://github.com/Kaelio/ktx.git
synced 2026-06-07 07:55:13 +02:00
ce1516b357
* feat(cli): block context build when a required connection fails its live test A context build can take several minutes, so a connection that is unreachable or misconfigured should stop the build up front instead of failing partway through. Before the build starts, run a live connection test for every primary- and context-source connection the build depends on. Each test's output is captured in a discarded buffer so raw error text (and database paths) never reach the user; failures are surfaced only by connection id and connector type, with a pointer to `ktx connection test <id>` for the underlying error. - Interactive setup lets the user fix the connection and retry without restarting, re-resolving targets so an added/removed/reconfigured connection is honored. - `--no-input` exits non-zero and writes a failed context state with a failureReason, so scripts stop early and setup never reads as ready. Extract the buffered command IO helper out of setup-databases into src/io/buffered-command-io.ts so both call sites share one implementation. * feat(cli): use recovery primitive for database setup * feat(cli): use recovery primitive for source setup * docs: document setup connection recovery * fix(cli): close database recovery gaps * fix(cli): target failing project in gate hint and preserve missing-input Address two review findings on the connection-recovery work: - The connection-gate failure hint emitted `ktx connection test <id>` with no --project-dir, so a setup run started with `--project-dir ./analytics` pointed users at cwd/KTX_PROJECT_DIR instead of the project that just failed. Emit the resolved project dir, matching the contextBuildCommands convention. - The non-interactive database configure path returned `cancelled`, which the recovery primitive collapses to `failed`. Sibling paths still report `missing-input` for absent flags, so incomplete-flag runs were indistinguishable from real connection failures. The database wrapper now tracks the configure missing-input signal and restores the `missing-input` step status; the shared primitive keeps its four outcomes.
109 lines
3.7 KiB
Text
109 lines
3.7 KiB
Text
---
|
|
title: "ktx connection"
|
|
description: "List and test configured database and context-source connections."
|
|
---
|
|
|
|
Inspect configured connections in your **ktx** project. Connections define how **ktx**
|
|
reaches primary sources (databases and warehouses) and context sources (BI
|
|
tools, modeling projects, and knowledge systems). Use `ktx setup` to add,
|
|
remove, or reconfigure them.
|
|
|
|
## Command signature
|
|
|
|
```bash
|
|
ktx connection # list all configured connections
|
|
ktx connection list # explicit list
|
|
ktx connection test [connectionId] # test one (or all, when omitted)
|
|
```
|
|
|
|
Bare `ktx connection` lists configured connections. `ktx connection test`
|
|
with no positional and no flag tests every configured connection.
|
|
|
|
## Subcommands
|
|
|
|
| Subcommand | Description |
|
|
|-----------|-------------|
|
|
| (none) | List configured connections (alias for `list`) |
|
|
| `list` | List configured connections |
|
|
| `test [connectionId]` | Test one configured connection; omit the id (or pass `--all`) to test every connection |
|
|
|
|
## Options
|
|
|
|
`ktx connection` uses the shared global options such as `--project-dir` and
|
|
`--debug`.
|
|
|
|
### `connection test`
|
|
|
|
| Flag | Description | Default |
|
|
|------|-------------|---------|
|
|
| `--all` | Test every configured connection and print a summary list | implicit when no `connectionId` is supplied |
|
|
|
|
Project directory resolution defaults to `KTX_PROJECT_DIR`, then the nearest
|
|
`ktx.yaml`, then the current working directory.
|
|
|
|
## Examples
|
|
|
|
```bash
|
|
# List all configured connections
|
|
ktx connection
|
|
|
|
# Test every configured connection
|
|
ktx connection test
|
|
|
|
# Test one connection
|
|
ktx connection test my-warehouse
|
|
|
|
# Test every connection explicitly
|
|
ktx connection test --all
|
|
|
|
# Test a connection from outside the project
|
|
ktx connection test my-warehouse --project-dir ./analytics
|
|
```
|
|
|
|
## Setup-managed connections
|
|
|
|
Run `ktx setup` when you need to add or reconfigure a connection. Interactive
|
|
setup includes the rich Notion page picker for selected root pages and the
|
|
Metabase mapping prompts for BI-to-warehouse mappings.
|
|
|
|
## Output
|
|
|
|
`ktx connection` (or `ktx connection list`) prints a table of configured ids
|
|
and drivers.
|
|
|
|
```text
|
|
ID DRIVER
|
|
my-warehouse postgres
|
|
```
|
|
|
|
`ktx connection test <connectionId>` performs a lightweight connection probe.
|
|
Native database connections report `Status: ok` when the connector probe
|
|
passes. Context-source connectors report connector-specific details such as
|
|
Metabase database count, Looker user, Notion bot, or Git repo URL.
|
|
|
|
```text
|
|
Connection test passed: my-warehouse
|
|
Driver: postgres
|
|
Status: ok
|
|
```
|
|
|
|
`ktx connection test` (bare) and `ktx connection test --all` print one row per
|
|
configured connection and exit non-zero if any probe fails.
|
|
|
|
```text
|
|
╭ connection test --all
|
|
│
|
|
│ • warehouse postgres ✓ ok Status: ok
|
|
│ • metabase metabase ✓ ok Databases: 2
|
|
│
|
|
╰ 2 tested · 2 passed
|
|
```
|
|
|
|
## Common errors
|
|
|
|
| Error | Cause | Recovery |
|
|
|-------|-------|----------|
|
|
| No connections configured | The project has no entries under `connections` | Run `ktx setup` and add a database or context-source connection |
|
|
| Connection test fails | Credentials, network access, database, warehouse, or schema is invalid | Use the setup recovery menu to retry or re-enter details; if it still fails, verify the same URL with the database's native client |
|
|
| Mapping validation fails during setup | BI database mappings do not point at valid warehouse connections | Use the setup recovery menu to retry validation or re-enter mapping selections; rerun `ktx setup` if you already exited |
|
|
| Notion page picker cannot run | The terminal is non-interactive or Notion discovery failed | Rerun interactive `ktx setup`, or use non-interactive setup flags with explicit root page ids |
|