dbtool-cli-v1/PRODUCT_REQUIREMENTS.md

# dbtool-cli-v1 Product Requirements

## Document Purpose

This document defines the first release boundary for `dbtool-cli-v1` so the CTO can split implementation work without guessing and QA can derive a repeatable acceptance checklist.

## Current Demo Audit

- As of 2026-03-26, the repository contains a Rust workspace, a runnable CLI surface, demo fixtures, smoke runbooks, and future GUI foundation artifacts.
- The current demo already implements the shared operator flow for PostgreSQL, MySQL, and SQLite: `connect`, `inspect`, `query`, and `export`.
- Current user-visible behavior includes `.sql` file execution, parameterized query support, CSV / JSON export, and password injection via `--password-env` with redacted output.
- The remaining product work is not “invent the first scope from zero”; it is “freeze the first release boundary, clarify database support levels, and prevent advanced admin workflows from leaking into the current project.”
- `DATABASE_SUPPORT_MATRIX.md` is the controlling reference for database tiers, phase boundaries, and what “full support” means in product terms.

## Target Users

### Primary User

Terminal-comfortable technical operators who need one consistent way to work across PostgreSQL, MySQL, and SQLite without switching between three native tools.

Typical roles:

- backend engineers investigating application data
- data engineers validating schema and query output
- QA or support engineers collecting evidence from a database during debugging

### User Need

The user needs a single local CLI that can:

1. verify a connection
2. inspect database structure
3. execute SQL
4. export query results

The value is consistency across supported databases, not feature depth equal to a full SQL IDE.

## Product Problem Statement

Today, the operator would otherwise need to learn different connection rules, inspection commands, and export workflows across `psql`, MySQL tools, and SQLite tooling. `dbtool-cli-v1` should reduce that tool-switching cost for the most common technical workflows.

This product does not aim to replace native admin consoles or general-purpose SQL IDEs. Its first promise is a consistent core workflow, not full database-administration parity.

## Primary V1 Workflow

The most important end-to-end flow is:

1. choose a supported database target
2. confirm the tool can connect
3. inspect schemas, tables, and columns to find the right object
4. execute SQL against that object
5. export the result for analysis, sharing, or evidence capture

If this flow is not smooth, V1 is not successful.

## V1 Scope

### In Scope

- local CLI only
- database support for PostgreSQL, MySQL, and SQLite only
- Tier A core support for those three databases as defined in `DATABASE_SUPPORT_MATRIX.md`
- explicit connection selection for each run
- schema and table inspection
- column-level metadata inspection
- ad hoc SQL execution
- `.sql` file execution
- export of query results to CSV and JSON
- clear terminal output and actionable failure messages

### Product Boundaries

- V1 is an operator tool, not a visual database client.
- V1 “full support” means complete support for the core operator workflow, not complete coverage of every database-native administrative feature.
- V1 must optimize for correctness and consistency before convenience features.
- Exact command names, flag shapes, crate boundaries, and config storage are implementation choices owned by the CTO as long as they satisfy the acceptance criteria below.

## Non-Goals

The following are explicitly out of scope for V1:

- desktop GUI or web GUI
- support for databases beyond PostgreSQL, MySQL, and SQLite
- saved profile management as a user-facing workflow
- migration management or schema-editing workflows
- import workflows
- transaction management UX
- stored procedure or function management UX
- permission or user administration
- backup or restore workflows
- ORM features, query builders, or notebook-style authoring
- background sync, job scheduling, alerts, or long-running daemon behavior
- shared team workspaces, cloud sync, or centralized connection management
- dashboards, charting, or analytics visualization
- advanced IDE features such as autocomplete, visual explain plans, or query history UX beyond what is minimally needed for CLI execution

## Acceptance Criteria

### Global Acceptance

- All supported flows use one coherent CLI mental model across PostgreSQL, MySQL, and SQLite.
- Every failure returns a non-zero exit path and an actionable terminal message.
- Secrets are not echoed back in plain text error output.
- Driver-specific differences that affect user behavior are documented in the project README or command help.

### Connect

The `connect` flow is acceptable when:

- the user can provide a supported database type plus connection input and the CLI validates that target
- success output clearly confirms which database type and target was reached without leaking secrets
- unsupported database types are rejected before an attempted connection
- authentication errors, network errors, unreachable hosts, and SQLite file path errors are distinguishable enough for the user to act
- a failed connection does not create the impression that later commands are safe to run

### Inspect

The `inspect` flow is acceptable when:

- after selecting a valid target, the user can list available schemas or equivalent top-level objects for that database
- the user can list tables or views within the chosen scope
- the user can inspect columns for a table or view and see at least name, type, nullability, and key or primary-key indication when the driver exposes it
- empty databases or empty scopes return a clear "no objects found" style outcome instead of a stack trace
- SQLite differences are handled gracefully even though it does not mirror server-database structure exactly

### Query

The `query` flow is acceptable when:

- the user can run SQL entered inline or from a `.sql` file
- row-returning statements show column headers and row output in a human-readable terminal format
- non-row-returning statements show a clear execution summary and affected row count when the driver provides it
- invalid SQL, permission failures, and driver execution failures return actionable errors
- empty result sets are treated as successful execution, not as a tool failure
- the output format remains suitable for terminal reading and shell piping

### Export

The `export` flow is acceptable when:

- the user can export query results to CSV or JSON
- the export path is explicit
- the CLI does not silently overwrite an existing file unless the user explicitly allows overwrite behavior
- exported row counts match the query result set
- text output is UTF-8 and stable for common multilingual content
- export failures never report success and leave the user with a clear next action

## Recommended User Scenarios

### Scenario A: Backend Debugging

A backend engineer needs to verify whether a bug is caused by bad data:

1. connect to a PostgreSQL or MySQL environment
2. inspect the relevant schema and table
3. run a targeted query
4. export the result to JSON or CSV for a bug report

### Scenario B: Local SQLite Verification

A QA engineer receives a local SQLite file:

1. point the CLI at the file path
2. inspect available tables
3. run a validation query
4. export evidence for a test record

These scenarios should remain happy-path examples in engineering docs and QA checks.

## Database Scope Reference

`DATABASE_SUPPORT_MATRIX.md` defines:

- the product meaning of Tier A / B / C
- the current release commitment for PostgreSQL, MySQL, and SQLite
- which capabilities must stay uniform across databases
- which capabilities are allowed to differ by database
- which future databases may be evaluated after the current release validates

## CLI To Product Evolution

GUI is not in the current scope, but the CLI should evolve in a way that supports a later product surface.

The CLI should establish stable product concepts:

- connection target
- catalog or schema browser state
- query execution
- result set
- export job

Future desktop or web surfaces should map directly to the same concepts:

- connection manager
- schema browser
- query editor
- results table
- export action

The repository already includes `gui/desktop-foundation.md` and `gui/prototype/` as a future-facing design reference. Those artifacts should guide information architecture and workflow mapping only; they do not expand the current release surface beyond CLI.

### Evolution Rule

The future GUI should reuse the same underlying product workflow, not invent a separate one. The CLI is the first validation surface for product behavior.

### Implication For Engineering

Engineering should avoid CLI-only shortcuts that would make later UI reuse difficult, especially around:

- connection target representation
- inspection result structure
- query result structure
- export request inputs and outputs

This is a product direction, not a mandate for a specific architecture.

## Handoff Notes For CTO

The following decisions are fixed for V1:

- supported databases: PostgreSQL, MySQL, SQLite
- surface: local CLI
- critical path: connect, inspect, query, export
- support policy: all three current databases must meet Tier A for the core workflow, but advanced admin capabilities stay outside the project
- GUI: out of scope
- acceptance must cover both success and obvious failure paths

The following decisions remain implementation-owned by the CTO:

- exact command names and flags
- Rust workspace structure
- connection config format and storage approach
- output rendering library choices
- packaging and distribution mechanics

## Release Readiness Definition

`dbtool-cli-v1` is ready for a first release when:

- the primary workflow works across PostgreSQL, MySQL, and SQLite
- the Tier A expectations in `DATABASE_SUPPORT_MATRIX.md` are met without scope creep into Tier C areas
- the documented non-goals have not crept into scope
- QA can execute acceptance checks directly from this document and companion test material
- CTO can map the remaining work into engineering tasks without reopening basic product questions