Skip to content

cli-reference.md

Latest commit

 

History

History
319 lines (224 loc) · 11.5 KB

cli-reference.md

File metadata and controls

319 lines (224 loc) · 11.5 KB

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