chore: bootstrap independent git workflow
Co-Authored-By: Paperclip <noreply@paperclip.ing>
This commit is contained in:
Paperclip CTO
218
PRODUCT_REQUIREMENTS.md
Normal file
218
PRODUCT_REQUIREMENTS.md
Normal file
@@ -0,0 +1,218 @@
|
||||
# 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-25, the configured project workspace had no repository contents, no Rust workspace, no README, and no runnable CLI binary.
|
||||
- The current project state is therefore a scoped backlog plus a project goal, not an already-working demo.
|
||||
- This document should be treated as the product baseline for implementation, not as a polish pass on existing behavior.
|
||||
|
||||
## 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.
|
||||
|
||||
## 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
|
||||
- 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 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
|
||||
- migration management or schema-editing 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.
|
||||
|
||||
## 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
|
||||
|
||||
### 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
|
||||
- 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 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
|
||||
Reference in New Issue
Block a user