mirror of
https://github.com/Kaelio/ktx.git
synced 2026-06-07 07:55:13 +02:00
e1e9c4af91
* fix(cli): clean up connection commands * test(cli): update connection smoke coverage * Fix setup output formatting * fix notion setup picker exit
79 lines
2.1 KiB
Text
79 lines
2.1 KiB
Text
---
|
|
title: "ktx connection"
|
|
description: "List and test configured data sources."
|
|
---
|
|
|
|
Inspect configured connections in your KTX project. Connections define how KTX
|
|
reaches your data warehouse, BI tools, and context sources. Use `ktx setup` to
|
|
add, remove, or reconfigure connections.
|
|
|
|
## Command signature
|
|
|
|
```bash
|
|
ktx connection <subcommand> [options]
|
|
```
|
|
|
|
## Subcommands
|
|
|
|
| Subcommand | Description |
|
|
|-----------|-------------|
|
|
| `list` | List configured connections |
|
|
| `test <connectionId>` | Test a configured connection |
|
|
|
|
## Options
|
|
|
|
The `connection` command has command-level options for listing and testing
|
|
existing connections.
|
|
|
|
### `connection list`
|
|
|
|
| Flag | Description | Default |
|
|
|------|-------------|---------|
|
|
| `--json` | Print JSON output | `false` |
|
|
|
|
### `connection test`
|
|
|
|
| Flag | Description | Default |
|
|
|------|-------------|---------|
|
|
| `--json` | Print JSON output | `false` |
|
|
|
|
## Examples
|
|
|
|
```bash
|
|
# List all configured connections
|
|
ktx connection list
|
|
|
|
# Test a connection
|
|
ktx connection test my-warehouse
|
|
```
|
|
|
|
## 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
|
|
|
|
Commands with `--json` return machine-readable JSON suitable for scripts and
|
|
agents.
|
|
|
|
```json
|
|
{
|
|
"connections": [
|
|
{
|
|
"id": "my-warehouse",
|
|
"driver": "postgres",
|
|
"readonly": false
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
## Common errors
|
|
|
|
| Error | Cause | Recovery |
|
|
|-------|-------|----------|
|
|
| Connection test fails | Credentials, network access, database, warehouse, or schema is invalid | Verify the same URL with the database's native client, then rerun `ktx setup` and reconfigure the connection |
|
|
| Mapping validation fails during setup | BI database mappings do not point at valid warehouse connections | Rerun `ktx setup` and update the source mapping selections |
|
|
| 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 |
|