---
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 |
