dbtool-cli-v1/SMOKE_RUNBOOK.md

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

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

2. Seed PostgreSQL

./examples/scripts/bootstrap-postgres.sh

Expected result:

• database: dbtool_demo
• schema: qa_demo
• tables: accounts, tickets

3. Seed MySQL

./examples/scripts/bootstrap-mysql.sh

Expected result:

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

4. Seed SQLite

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

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