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
1for 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
