CLI Reference

Note. RUST_LOG belonged to the retired Rust implementation and is not read by this one. Verbosity is controlled by --quiet on the collector, which suppresses progress output entirely. Progress decoration is suppressed automatically when TERM=dumb or when standard output is not a terminal.

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	[OK] Implemented
`--output <PATH>`	Output file path	`schema.dbsurveyor.json`	[OK] Implemented
`--sample <N>`	Number of sample rows per table	`100`	[WIP] Planned
`--throttle <MS>`	Delay between operations (ms)	None	[WIP] Planned
`--compress`	Compress output using Zstandard (`.zst` appended to output path if missing). Combine with `--encrypt` to compress before encrypting	`false`	[OK] Implemented
`--encrypt`	Encrypt output using AES-GCM (`.enc` appended to output path if missing). Password read from `DBSURVEYOR_ENCRYPTION_PASSWORD` or prompted. Combine with `--compress` to produce a single `.enc` file containing zstd-compressed then AES-GCM encrypted data	`false`	[OK] Implemented
`--enable-quality`	Enable data quality analysis on sampled data	`false`	[OK] Implemented
`--quality-threshold <LIST>`	Quality thresholds (e.g., `completeness:0.9,uniqueness:0.95,consistency:0.85`)	None	[OK] Implemented
`--all-databases`	Collect all accessible databases	`false`	[WIP] Planned
`--include-system-databases`	Include system databases	`false`	[WIP] Planned
`--exclude-databases <LIST>`	Comma-separated list to exclude	None	[WIP] 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 (produces single .enc file with compressed then encrypted data)
DBSURVEYOR_ENCRYPTION_PASSWORD='mypassword' dbsurveyor-collect --encrypt --compress --output schema.json postgres://localhost/mydb

# 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`	[OK] Implemented
SQLite	`sqlite:///path/to/file`	`sqlite:///home/user/data.db`	[OK] Implemented
MySQL	`mysql://user:pass@host:port/db`	`mysql://root:password@localhost:3306/mydb`	[WIP] In Development
MongoDB	`mongodb://user:pass@host:port/db`	`mongodb://admin:secret@localhost:27017/mydb`	[WIP] Planned
SQL Server	`mssql://user:pass@host:port/db`	`mssql://sa:password@localhost:1433/mydb`	[WIP] Planned

Environment Variables

Variable	Description
`DATABASE_URL`	Default database connection string
`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_ENCRYPTION_PASSWORD`	Encryption password for non-interactive use with `--encrypt` (minimum 8 characters)

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`	[OK] Implemented
`json`	JSON analysis report	`.json`	[OK] Implemented
`html`	HTML report with search	`.html`	[WIP] Placeholder
`mermaid`	Mermaid ERD diagram	`.mmd`	[WIP] 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 ([WIP] Placeholder)
mysql - MySQL dialect ([WIP] Placeholder)
sqlite - SQLite dialect ([WIP] Placeholder)
sqlserver - SQL Server dialect ([WIP] Placeholder)
generic - Generic SQL (ANSI standard) ([WIP] 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
`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`)
`DBSURVEYOR_ENCRYPTION_PASSWORD`	Decryption password for non-interactive use with encrypted files (minimum 8 characters)

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