# dbtool-cli-v1 Smoke Runbook

## Purpose

This runbook defines the smallest repeatable cross-database validation path for `connect`, `inspect`, `query`, and `export`.

## Current Status

- Demo databases and query fixtures are prepared.
- A repeatable Docker path exists for PostgreSQL and MySQL.
- 推荐执行环境已明确为“宿主机执行 + Docker Compose 临时数据库”，详见 `QA_RUNTIME_ENVIRONMENT.md`。
- SQLite bootstrap exists for local execution.
- PostgreSQL `connect`, `inspect`, and `query` are now implemented in the Rust CLI.
- MySQL `connect`, `inspect`, and `query` are now implemented in the Rust CLI.
- SQLite `connect`, `inspect`, and `query` are now implemented in the Rust CLI.
- `export` to CSV / JSON is now implemented in the Rust CLI.
- Release artifact smoke is now defined separately in `RELEASE_RUNBOOK.md`.
- This runbook remains partially staged only because PostgreSQL / MySQL runtime smoke still requires a Docker-capable environment.

## Preconditions

- Docker with `docker compose`
- one of `sqlite3`, `node`, or `python3` for SQLite bootstrap
- compiled CLI binary from the Rust workspace baseline

## Bootstrap

### 1. Start PostgreSQL and MySQL

```bash
docker compose -f docker-compose.demo.yml up -d postgres mysql
```

### 2. Seed PostgreSQL

```bash
./examples/scripts/bootstrap-postgres.sh
```

Expected result:

- database: `dbtool_demo`
- schema: `qa_demo`
- tables: `accounts`, `tickets`

### 3. Seed MySQL

```bash
./examples/scripts/bootstrap-mysql.sh
```

Expected result:

- database: `qa_demo`
- tables: `accounts`, `tickets`
- user `dbtool` retains privileges on `qa_demo`

### 4. Seed SQLite

```bash
./examples/scripts/bootstrap-sqlite.sh
```

Expected result:

- file: `examples/tmp/dbtool-demo.sqlite`
- tables: `accounts`, `tickets`

## Smoke Inputs

### PostgreSQL

- connect target: host `127.0.0.1`, port `55432`, database `dbtool_demo`, user `dbtool`
- inspect scope: schema `qa_demo`
- happy query: `examples/sql/postgres/happy_path_query.sql`
- export query: `examples/sql/postgres/export_query.sql`
- failure query: `examples/sql/postgres/failing_query.sql`

### MySQL

- connect target: host `127.0.0.1`, port `53306`, database `qa_demo`, user `dbtool`
- inspect scope: database `qa_demo`
- happy query: `examples/sql/mysql/happy_path_query.sql`
- export query: `examples/sql/mysql/export_query.sql`
- failure query: `examples/sql/mysql/failing_query.sql`

### SQLite

- connect target: `examples/tmp/dbtool-demo.sqlite`
- inspect scope: schema `main`
- happy query: `examples/sql/sqlite/happy_path_query.sql`
- export query: `examples/sql/sqlite/export_query.sql`
- failure query: `examples/sql/sqlite/failing_query.sql`

## Required Assertions

Use `examples/fixtures/EXPECTED_RESULTS.md` as the shared oracle.

- `connect` succeeds for each valid target
- `inspect` reveals `accounts` and `tickets`
- `query` returns `3` account rows in the happy-path query
- `export` returns `4` ticket rows in deterministic order
- failure query exits non-zero and identifies a missing object
- secrets do not appear in terminal errors

## Failure Paths To Capture

- PostgreSQL wrong password
- PostgreSQL unreachable port
- MySQL wrong password
- SQLite missing file
- invalid SQL from `failing_query.sql`
- export path collision once the CLI contract exists

## Cleanup

```bash
docker compose -f docker-compose.demo.yml down -v
rm -f examples/tmp/dbtool-demo.sqlite
```

## Blocker

This runbook cannot be marked passed until engineering lands:

- full runtime smoke on a Docker-capable host as described in `QA_RUNTIME_ENVIRONMENT.md`