127 lines
3.5 KiB
Markdown
127 lines
3.5 KiB
Markdown
# 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`
|