CLI Reference

Complete reference for all DBSurveyor command-line options.

dbsurveyor-collect

Database schema collection tool.

Synopsis

dbsurveyor-collect [OPTIONS] [DATABASE_URL]
dbsurveyor-collect <COMMAND>

Global Options

Option	Short	Description
`--verbose`	`-v`	Increase verbosity (-v, -vv, -vvv)
`--quiet`	`-q`	Suppress all output except errors
`--help`	`-h`	Print help information
`--version`	`-V`	Print version information

Collection Options

Option	Description	Default	Status
`--database-url <URL>`	Database connection string	From `DATABASE_URL` env var	✅ Implemented
`--output <PATH>`	Output file path	`schema.dbsurveyor.json`	✅ Implemented
`--sample <N>`	Number of sample rows per table	`100`	🚧 Planned
`--throttle <MS>`	Delay between operations (ms)	None	🚧 Planned
`--compress`	Compress output using Zstandard	`false`	✅ Implemented
`--encrypt`	Encrypt output using AES-GCM	`false`	✅ Implemented
`--enable-quality`	Enable data quality analysis on sampled data	`false`	✅ Implemented
`--quality-threshold <LIST>`	Quality thresholds (e.g., `completeness:0.9,uniqueness:0.95,consistency:0.85`)	None	✅ Implemented
`--all-databases`	Collect all accessible databases	`false`	🚧 Planned
`--include-system-databases`	Include system databases	`false`	🚧 Planned
`--exclude-databases <LIST>`	Comma-separated list to exclude	None	🚧 Planned

Commands

collect

Collect schema from database.

dbsurveyor-collect collect <DATABASE_URL> [--output <PATH>]

test

Test database connection without collecting schema.

dbsurveyor-collect test <DATABASE_URL>

list

List supported database types and connection formats.

dbsurveyor-collect list

Examples

# Basic collection
dbsurveyor-collect postgres://user:pass@localhost/db

# With custom output file
dbsurveyor-collect --output my-schema.json postgres://localhost/db

# Encrypted and compressed
dbsurveyor-collect --encrypt --compress postgres://localhost/db

# Multi-database collection
dbsurveyor-collect --all-databases --exclude-databases postgres,template0 postgres://localhost

# Test connection only
dbsurveyor-collect test mysql://root:password@localhost/mydb

# Throttled collection (stealth mode)
dbsurveyor-collect --throttle 1000 postgres://localhost/db

Connection String Formats

Database	Format	Example	Status
PostgreSQL	`postgres://user:pass@host:port/db`	`postgres://admin:secret@localhost:5432/mydb`	✅ Implemented
SQLite	`sqlite:///path/to/file`	`sqlite:///home/user/data.db`	✅ Implemented
MySQL	`mysql://user:pass@host:port/db`	`mysql://root:password@localhost:3306/mydb`	🚧 In Development
MongoDB	`mongodb://user:pass@host:port/db`	`mongodb://admin:secret@localhost:27017/mydb`	🚧 Planned
SQL Server	`mssql://user:pass@host:port/db`	`mssql://sa:password@localhost:1433/mydb`	🚧 Planned

Environment Variables

Variable	Description
`DATABASE_URL`	Default database connection string
`RUST_LOG`	Logging configuration (`error`, `warn`, `info`, `debug`, `trace`)
`DBSURVEYOR_MAX_CONNECTIONS`	Maximum connection pool size (default: `10`)
`DBSURVEYOR_MIN_IDLE_CONNECTIONS`	Minimum idle connections in pool (default: `2`)
`DBSURVEYOR_CONNECT_TIMEOUT_SECS`	Connection timeout in seconds (default: `30`)
`DBSURVEYOR_IDLE_TIMEOUT_SECS`	Idle connection timeout in seconds (default: `600`)
`DBSURVEYOR_MAX_LIFETIME_SECS`	Maximum connection lifetime in seconds (default: `3600`)

dbsurveyor

Database schema documentation and analysis tool.

Synopsis

dbsurveyor [OPTIONS] [INPUT_FILE]
dbsurveyor <COMMAND>

Global Options

Option	Short	Description
`--verbose`	`-v`	Increase verbosity (-v, -vv, -vvv)
`--quiet`	`-q`	Suppress all output except errors
`--help`	`-h`	Print help information
`--version`	`-V`	Print version information

Documentation Options

Option	Short	Description	Default
`--format <FORMAT>`	`-f`	Output format	`markdown`
`--output <PATH>`	`-o`	Output file path	Auto-detected
`--redact-mode <MODE>`		Data redaction level	`balanced`
`--no-redact`		Disable all data redaction	`false`

Output Formats

Format	Description	Extension	Status
`markdown`	Markdown documentation	`.md`	✅ Implemented
`json`	JSON analysis report	`.json`	✅ Implemented
`html`	HTML report with search	`.html`	🚧 Placeholder
`mermaid`	Mermaid ERD diagram	`.mmd`	🚧 Placeholder

Redaction Modes

Mode	Description
`none`	No redaction (show all data)
`minimal`	Minimal redaction (only obvious sensitive fields)
`balanced`	Balanced redaction (recommended default)
`conservative`	Conservative redaction (maximum privacy)

Commands

generate

Generate documentation from schema file.

dbsurveyor generate <INPUT_FILE> [OPTIONS]

Options:

--format <FORMAT> - Output format
--output <PATH> - Output file path

analyze

Analyze schema for insights and statistics.

dbsurveyor analyze <INPUT_FILE> [--detailed]

Options:

--detailed - Show detailed analysis statistics

sql

Reconstruct SQL DDL from schema.

dbsurveyor sql <INPUT_FILE> [OPTIONS]

Options:

--dialect <DIALECT> - Target SQL dialect (default: postgresql)
--output <PATH> - Output file path

SQL Dialects:

postgresql - PostgreSQL dialect (🚧 Placeholder)
mysql - MySQL dialect (🚧 Placeholder)
sqlite - SQLite dialect (🚧 Placeholder)
sqlserver - SQL Server dialect (🚧 Placeholder)
generic - Generic SQL (ANSI standard) (🚧 Placeholder)

validate

Validate schema file format.

dbsurveyor validate <INPUT_FILE>

Examples

# Generate Markdown documentation
dbsurveyor generate schema.dbsurveyor.json

# Generate HTML report
dbsurveyor --format html --output report.html schema.json

# Process encrypted schema (will prompt for password)
dbsurveyor generate schema.enc

# Generate SQL DDL for MySQL
dbsurveyor sql schema.json --dialect mysql --output recreate.sql

# Analyze schema with detailed statistics
dbsurveyor analyze schema.json --detailed

# Validate schema file format
dbsurveyor validate schema.dbsurveyor.json

# Generate with conservative redaction
dbsurveyor --redact-mode conservative schema.json

# Generate without any redaction
dbsurveyor --no-redact schema.json

Input File Formats

DBSurveyor automatically detects input file formats:

Extension	Format	Description
`.json`	JSON	Standard schema format
`.zst`	Compressed	Zstandard compressed JSON
`.enc`	Encrypted	AES-GCM encrypted JSON

Exit Codes

Code	Description
`0`	Success
`1`	General error

Note: Both binaries currently use exit code 1 for all error conditions. Granular exit codes (e.g., file-not-found, connection failure) may be added in a future release.

Environment Variables

Variable	Description
`RUST_LOG`	Logging configuration
`NO_COLOR`	Disable colored output
`DBSURVEYOR_MAX_CONNECTIONS`	Maximum connection pool size (default: `10`)
`DBSURVEYOR_MIN_IDLE_CONNECTIONS`	Minimum idle connections in pool (default: `2`)
`DBSURVEYOR_CONNECT_TIMEOUT_SECS`	Connection timeout in seconds (default: `30`)
`DBSURVEYOR_IDLE_TIMEOUT_SECS`	Idle connection timeout in seconds (default: `600`)
`DBSURVEYOR_MAX_LIFETIME_SECS`	Maximum connection lifetime in seconds (default: `3600`)

Common Usage Patterns

Secure Workflow

# 1. Test connection
dbsurveyor-collect test postgres://user:pass@localhost/db

# 2. Collect with encryption
dbsurveyor-collect --encrypt postgres://user:pass@localhost/db

# 3. Generate documentation offline
dbsurveyor generate schema.enc

# 4. Validate output
dbsurveyor validate schema.enc

Multi-Database Documentation

# Collect from multiple databases
dbsurveyor-collect --all-databases postgres://localhost > collection.log

# Generate comprehensive report
dbsurveyor --format html --output full-report.html schema.dbsurveyor.json

# Extract SQL for specific database
dbsurveyor sql schema.json --dialect postgresql --output postgres-ddl.sql

Development Workflow

# Quick collection and documentation
dbsurveyor-collect sqlite://dev.db && dbsurveyor generate schema.dbsurveyor.json

# Analyze changes
dbsurveyor analyze schema.dbsurveyor.json --detailed

# Generate multiple formats
for format in markdown html mermaid; do
    dbsurveyor --format $format schema.dbsurveyor.json
done

Keyboard shortcuts