mirror of
https://github.com/Kaelio/ktx.git
synced 2026-06-07 07:55:13 +02:00
77 lines
2.4 KiB
Text
77 lines
2.4 KiB
Text
---
|
|
title: "ktx connection"
|
|
description: "List and test configured data sources."
|
|
---
|
|
|
|
Inspect configured connections in your KTX project. Connections define how KTX
|
|
reaches databases, warehouses, BI tools, source projects, and knowledge
|
|
systems. Use `ktx setup` to add, remove, or reconfigure them.
|
|
|
|
## Command signature
|
|
|
|
```bash
|
|
ktx connection <subcommand> [options]
|
|
```
|
|
|
|
## Subcommands
|
|
|
|
| Subcommand | Description |
|
|
|-----------|-------------|
|
|
| `list` | List configured connections |
|
|
| `test <connectionId>` | Test a configured connection |
|
|
|
|
## Options
|
|
|
|
`ktx connection` uses the shared global options such as `--project-dir` and
|
|
`--debug`. The `list` and `test` subcommands do not currently define
|
|
command-specific options.
|
|
|
|
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 list
|
|
|
|
# Test a connection
|
|
ktx connection test my-warehouse
|
|
|
|
# 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 list` prints a table of configured ids and drivers.
|
|
|
|
```text
|
|
ID DRIVER
|
|
my-warehouse postgres
|
|
```
|
|
|
|
`ktx connection test <connectionId>` performs a lightweight connection probe.
|
|
Database connections report a table count. Metabase connections report a
|
|
database count.
|
|
|
|
```text
|
|
Connection test passed: my-warehouse
|
|
Driver: postgres
|
|
Tables: 42
|
|
```
|
|
|
|
## Common errors
|
|
|
|
| Error | Cause | Recovery |
|
|
|-------|-------|----------|
|
|
| No connections configured | The project has no entries under `connections` | Run `ktx setup` and add a database or source connection |
|
|
| 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 |
|