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