mpx-db 1.1.3 → 1.2.0

package/README.md

@@ -1,293 +1,167 @@
-# mpx-db
+# mpx-db 🗄️
 
-**Database management CLI** — Connect, query, migrate, and manage databases from the terminal.
+**Database management CLI — connect, query, migrate, and manage databases from the terminal.**
 
-Stop juggling multiple database tools. `mpx-db` gives you one clean interface for SQLite, PostgreSQL, and MySQL.
+Stop juggling multiple database tools. One clean interface for SQLite, PostgreSQL, and MySQL.
+
+Part of the [Mesaplex](https://mesaplex.com) developer toolchain.
+
+[![npm version](https://img.shields.io/npm/v/mpx-db.svg)](https://www.npmjs.com/package/mpx-db)
+[![License: Dual](https://img.shields.io/badge/license-Dual-blue.svg)](LICENSE)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org)
 
 ## Features
 
-✅ **Multi-database support** — SQLite, PostgreSQL, MySQL  
-✅ **Beautiful output** — Colored tables, not raw dumps  
-✅ **Connection management** — Save connections, no more copy-pasting URLs  
-✅ **Migration system** — Git-friendly SQL migration files  
-✅ **Schema operations** — Dump, describe, visualize database structure  
-✅ **Data export** — Export to JSON/CSV with one command  
-✅ **Secure** — Encrypted credential storage  
-✅ **AI-native** — JSON output, MCP server, schema discovery for AI agents  
+- **Multi-database support** — SQLite, PostgreSQL, MySQL
+- **Beautiful output** — Colored tables, not raw dumps
+- **Connection management** — Save connections, no more copy-pasting URLs
+- **Migration system** — Git-friendly SQL migration files
+- **Schema operations** — Dump, describe, visualize database structure
+- **Data export** — Export to JSON/CSV with one command
+- **Secure** — Encrypted credential storage (AES-256-GCM)
+- **MCP server** — Integrates with any MCP-compatible AI agent
+- **Self-documenting** — `--schema` returns machine-readable tool description
 
 ## Installation
 
 ```bash
 npm install -g mpx-db
+```
+
+Install database drivers you need (optional peer dependencies):
 
-# Install database drivers you need (optional peer deps)
+```bash
 npm install -g better-sqlite3  # For SQLite
 npm install -g pg              # For PostgreSQL
 npm install -g mysql2          # For MySQL
 ```
 
-## Quick Start
+Or run directly with npx:
 
 ```bash
-# Connect to a database
-mpx-db connect sqlite://./mydb.db
-
-# Save a connection for reuse
-mpx-db connect --save dev sqlite://./dev.db
-mpx-db connect --save prod postgres://user:pass@localhost:5432/mydb
+npx mpx-db --help
+```
 
-# List saved connections
-mpx-db connections list
+**Requirements:** Node.js 18+ · macOS, Linux, Windows
 
-# Query a database
-mpx-db query dev "SELECT * FROM users LIMIT 10"
+## Quick Start
 
-# Show database info
-mpx-db info dev
+```bash
+# Connect and save
+mpx-db connect --save dev sqlite://./dev.db
 
-# List all tables
+# List tables
 mpx-db tables dev
 
+# Run a query
+mpx-db query dev "SELECT * FROM users LIMIT 10"
+
 # Describe a table
 mpx-db describe dev users
-```
-
-## Connection Strings
-
-```bash
-# SQLite (file-based)
-sqlite://./database.db
-sqlite:///absolute/path/to/db.sqlite
-
-# PostgreSQL
-postgres://user:password@localhost:5432/database
-postgresql://user:password@host:5432/db
 
-# MySQL
-mysql://user:password@localhost:3306/database
+# Export data
+mpx-db export dev users --format json
 ```
 
-## Commands
+## Usage
 
 ### Connection Management
 
 ```bash
-# Test and save a connection
-mpx-db connect --save <name> <url>
+mpx-db connect --save <name> <url>     # Save a connection
+mpx-db connections list                 # List saved connections
+mpx-db connections remove <name>        # Remove a connection
+```
 
-# List saved connections
-mpx-db connections list
+Connection string formats:
 
-# Remove a saved connection
-mpx-db connections remove <name>
+```
+sqlite://./database.db
+postgres://user:password@localhost:5432/database
+mysql://user:password@localhost:3306/database
 ```
 
 ### Querying
 
 ```bash
-# Run a query
 mpx-db query <connection> "SELECT * FROM users WHERE active = 1"
-
-# Query with saved connection
-mpx-db query dev "SELECT COUNT(*) FROM orders"
 ```
 
 ### Schema Operations
 
 ```bash
-# Show database information
-mpx-db info <connection>
-
-# List all tables with row counts
-mpx-db tables <connection>
-
-# Describe table structure
-mpx-db describe <connection> <table>
-
-# Dump entire schema as SQL
-mpx-db schema dump <connection>
+mpx-db info <connection>                # Database information
+mpx-db tables <connection>              # List tables with row counts
+mpx-db describe <connection> <table>    # Table structure
+mpx-db schema dump <connection>         # Dump schema as SQL
 ```
 
 ### Migrations
 
 ```bash
-# Initialize migrations directory
-mpx-db migrate init
-
-# Create a new migration
-mpx-db migrate create add_users_table
-
-# Show migration status
-mpx-db migrate status <connection>
-
-# Run pending migrations
-mpx-db migrate up <connection>
-
-# Rollback last migration
-mpx-db migrate down <connection>
+mpx-db migrate init                     # Initialize migrations directory
+mpx-db migrate create <name>            # Create a new migration
+mpx-db migrate status <connection>      # Show migration status
+mpx-db migrate up <connection>          # Run pending migrations
+mpx-db migrate down <connection>        # Rollback last migration
 ```
 
-#### Migration File Format
-
-Migrations are SQL files in `./migrations/` directory:
+Migration file format (`./migrations/`):
 
 ```sql
--- Migration: add_users_table
--- Created: 2026-02-15T10:30:00.000Z
-
 -- Up migration
 CREATE TABLE users (
   id INTEGER PRIMARY KEY AUTOINCREMENT,
   email TEXT UNIQUE NOT NULL,
-  name TEXT NOT NULL,
-  created_at TEXT DEFAULT CURRENT_TIMESTAMP
+  name TEXT NOT NULL
 );
 
-CREATE INDEX idx_users_email ON users(email);
-
--- Down migration (rollback)
 -- DOWN
-DROP INDEX idx_users_email;
 DROP TABLE users;
 ```
 
-### Data Operations
+### Data Export
 
 ```bash
-# Export table data to JSON
-mpx-db export dev users --format json
-
-# Export to CSV
-mpx-db export dev users --format csv --output data.csv
-```
-
-## Examples
-
-### Setting Up a New Project
-
-```bash
-# Initialize migrations
-mpx-db migrate init
-
-# Create your first migration
-mpx-db migrate create create_initial_schema
-
-# Edit migrations/YYYYMMDD_HHMMSS_create_initial_schema.sql
-# Add your CREATE TABLE statements
-
-# Connect to database
-mpx-db connect --save dev sqlite://./dev.db
-
-# Run migrations
-mpx-db migrate up dev
-
-# Verify
-mpx-db tables dev
-mpx-db info dev
-```
-
-### Managing Multiple Environments
-
-```bash
-# Save connections for each environment
-mpx-db connect --save dev sqlite://./dev.db
-mpx-db connect --save staging postgres://user:pass@staging-host/mydb
-mpx-db connect --save prod postgres://user:pass@prod-host/mydb
-
-# Run migrations on each
-mpx-db migrate up dev
-mpx-db migrate up staging
-mpx-db migrate up prod
-
-# Compare schemas (visual inspection)
-mpx-db schema dump dev > dev-schema.sql
-mpx-db schema dump prod > prod-schema.sql
-diff dev-schema.sql prod-schema.sql
-```
-
-### Daily Workflow
-
-```bash
-# Check database status
-mpx-db info dev
-mpx-db tables dev
-
-# Run a quick query
-mpx-db query dev "SELECT COUNT(*) FROM orders WHERE created_at > date('now', '-1 day')"
-
-# Describe a table before modifying it
-mpx-db describe dev orders
-
-# Create a migration for changes
-mpx-db migrate create add_order_status_field
-
-# Export data for backup/analysis
-mpx-db export dev orders --format csv --output orders-backup.csv
+mpx-db export <connection> <table> --format json
+mpx-db export <connection> <table> --format csv --output data.csv
 ```
 
 ## AI Agent Usage
 
-`mpx-db` is **AI-native** — designed for both humans and AI agents. Every command supports machine-readable output and schema discovery.
+mpx-db is designed to be used by AI agents as well as humans.
 
 ### JSON Output
 
-Add `--json` to any command for structured output:
+Add `--json` to any command for structured, machine-readable output:
 
 ```bash
-# Query with JSON output
 mpx-db query dev "SELECT * FROM users LIMIT 3" --json
+```
+
+```json
 {
   "success": true,
   "type": "query",
   "rows": [
-    { "id": 1, "name": "Alice", "email": "alice@example.com" },
-    { "id": 2, "name": "Bob", "email": "bob@example.com" },
-    { "id": 3, "name": "Charlie", "email": "charlie@example.com" }
+    { "id": 1, "name": "Alice", "email": "alice@example.com" }
   ],
-  "rowCount": 3,
+  "rowCount": 1,
   "duration": 12
 }
-
-# List tables with JSON
-mpx-db tables dev --json
-{
-  "tables": [
-    { "name": "users", "type": "table", "rowCount": 150 },
-    { "name": "orders", "type": "table", "rowCount": 892 }
-  ]
-}
-
-# Migration status
-mpx-db migrate status dev --json
-{
-  "migrations": [
-    { "name": "20260215_100000_create_users", "status": "applied", "appliedAt": "2026-02-15T10:05:00.000Z" },
-    { "name": "20260216_120000_add_orders", "status": "pending", "appliedAt": null }
-  ]
-}
 ```
 
 ### Schema Discovery
 
-Get the full command schema for AI agent integration:
-
 ```bash
 mpx-db --schema
 ```
 
-Returns a comprehensive JSON schema describing all commands, flags, inputs, outputs, and examples.
-
-### MCP (Model Context Protocol) Server
-
-Run `mpx-db` as an MCP server for seamless AI agent integration:
+Returns a complete JSON schema describing all commands, flags, inputs, outputs, and examples.
 
-```bash
-mpx-db mcp
-```
+### MCP Integration
 
-#### Claude Desktop Integration
-
-Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+Add to your MCP client configuration (Claude Desktop, Cursor, Windsurf, etc.):
 
 ```json
 {
@@ -300,181 +174,84 @@ Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_
 }
 ```
 
-Now Claude can directly query your databases, inspect schemas, and run migrations!
+The MCP server exposes these tools:
+- **`query`** — Execute SQL queries
+- **`list_tables`** — Get all tables with row counts
+- **`describe_table`** — Show table schema
+- **`get_info`** — Database information
+- **`export_table`** — Export table data as JSON
+- **`get_schema`** — Get full command schema
 
-#### Available MCP Tools
+### Exit Codes
 
-- `query` — Execute SQL queries
-- `list_tables` — Get all tables with row counts
-- `describe_table` — Show table schema
-- `get_info` — Database information
-- `export_table` — Export table data as JSON
-- `get_schema` — Get full command schema
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | Error (connection failed, query failed, etc.) |
 
-### Quiet Mode
+### PDF Reports
 
-Suppress non-essential output with `--quiet`:
+Generate professional PDF reports from queries and schema dumps:
 
 ```bash
-# Just the data, no banners or progress messages
-mpx-db query dev "SELECT COUNT(*) FROM users" --quiet --json
-```
-
-### Exit Codes
-
-Predictable exit codes for CI/CD and scripting:
+# Schema report — full database structure as PDF
+mpx-db schema dump <connection> --pdf schema-report.pdf
 
-- `0` — Success
-- `1` — Error (connection failed, query failed, etc.)
-
-```bash
-#!/bin/bash
-if mpx-db query dev "SELECT 1" --quiet; then
-  echo "Database is up"
-else
-  echo "Database is down"
-  exit 1
-fi
+# Query results as PDF
+mpx-db query <connection> "SELECT * FROM users" --pdf results.pdf
 ```
 
-### Example: AI Agent Workflow
-
-```javascript
-// AI agent discovers available commands
-const schema = await exec('mpx-db --schema');
+PDFs include formatted tables, database metadata, and Mesaplex branding. Great for sharing with teammates or archiving.
 
-// Agent queries database
-const result = await exec('mpx-db query dev "SELECT * FROM orders WHERE status = \'pending\'" --json');
-const orders = JSON.parse(result.stdout);
+### Automation Tips
 
-// Agent inspects schema
-const tables = await exec('mpx-db tables dev --json');
+- Use `--json` for machine-parseable output
+- Use `--pdf <file>` for formatted reports
+- Use `--quiet` to suppress banners and progress info
+- Pipe output to `jq` for filtering
+- Check exit codes for pass/fail in CI/CD
 
-// Agent runs migration
-await exec('mpx-db migrate up dev --json --quiet');
-```
+## Database Support
 
-## Architecture
+| Database   | Driver Package    | Notes                    |
+|------------|-------------------|--------------------------|
+| SQLite     | better-sqlite3    | File-based, great for dev|
+| PostgreSQL | pg                | Full support             |
+| MySQL      | mysql2            | Full support             |
 
-```
-mpx-db/
-├── bin/
-│   └── mpx-db.js          # CLI entry point
-├── src/
-│   ├── cli.js             # Command definitions
-│   ├── commands/          # Command implementations
-│   │   ├── connections.js
-│   │   ├── query.js
-│   │   ├── schema.js
-│   │   ├── migrate.js
-│   │   └── data.js
-│   ├── db/                # Database adapters
-│   │   ├── base-adapter.js
-│   │   ├── sqlite-adapter.js
-│   │   ├── postgres-adapter.js
-│   │   ├── mysql-adapter.js
-│   │   └── connection.js
-│   └── utils/             # Utilities
-│       ├── crypto.js      # Credential encryption
-│       └── config.js      # Config management
-└── test/                  # Test suite
-```
+Drivers are optional peer dependencies — install only what you need. If a driver is missing, you'll get a helpful error message.
 
 ## Security
 
 - **Encrypted credentials** — Connection strings with passwords are encrypted using AES-256-GCM
 - **Local storage** — Credentials stored in `~/.mpx-db/connections.json` with 600 permissions
-- **Key management** — Encryption key stored in `~/.mpx-db/.key` (auto-generated)
-
-⚠️ **Note:** While credentials are encrypted at rest, this is not a substitute for proper secrets management in production. For production deployments, use environment variables or a secrets manager.
-
-## Database Support
-
-| Database   | Status | Driver Package    | Notes                    |
-|------------|--------|-------------------|--------------------------|
-| SQLite     | ✅     | better-sqlite3    | File-based, great for dev|
-| PostgreSQL | ✅     | pg                | Full support             |
-| MySQL      | ✅     | mysql2            | Full support             |
-
-**Note:** Database drivers are optional peer dependencies. Install only what you need:
-
-```bash
-npm install -g better-sqlite3  # For SQLite
-npm install -g pg              # For PostgreSQL  
-npm install -g mysql2          # For MySQL
-```
-
-If you try to connect without the required driver, you'll get a helpful error message:
+- **Key management** — Encryption key in `~/.mpx-db/.key` (auto-generated)
 
-```
-✗ SQLite driver not found. Install it with:
-  npm install better-sqlite3
-```
-
-## Testing
-
-```bash
-# Run all tests
-npm test
-
-# Run tests in watch mode
-npm run test:watch
-```
-
-Test suite includes:
-- Connection management (4 tests)
-- Schema operations (4 tests)
-- Query operations (5 tests)
-- Migrations (4 tests)
-- Data export (3 tests)
+⚠️ For production, use environment variables or a secrets manager rather than saved connections.
 
-**Total: 23 tests** ✅
+## Free vs Pro
 
-## Why mpx-db?
+All features are currently available in the free tier.
 
-**The problem:** Developers juggle multiple CLI tools (psql, mysql, sqlite3), each with different syntax. Schema changes require hand-written migrations. No easy way to compare schemas across environments.
+**Upgrade to Pro:** [https://mesaplex.com/mpx-db](https://mesaplex.com/mpx-db)
 
-**The solution:** One tool, consistent interface, automatic schema inspection, git-friendly migrations.
-
-**Inspiration:** Tools like [Skeema](https://www.skeema.io/) prove this model works. But Skeema is MySQL-only and expensive for small teams. `mpx-db` is open source, multi-database, and focused on developer ergonomics.
-
-## Roadmap
-
-**v1.1 (Current)** ✅
-- SQLite, PostgreSQL, MySQL support
-- Connection management
-- Query execution with beautiful output
-- Schema inspection (dump, describe, tables, info)
-- Migration system (create, up, down, status)
-- Data export (JSON, CSV)
-- **AI-native features:** JSON output (`--json`), schema discovery (`--schema`), MCP server mode
-- **Quiet mode** (`--quiet`) for scripting
-- Predictable exit codes
-
-**v1.2 (Planned)**
-- Interactive query REPL mode
-- Query history and favorites
-- Auto-complete for table/column names
-- Migration templates (create table, add column, etc.)
+## License
 
-**v2.0 (Future)**
-- Schema diff between environments
-- Auto-generate migrations from schema changes
-- Visual schema diagrams (ASCII art)
-- Data seeding from JSON/CSV
-- Database backup & restore
-- Support for MongoDB, Redis
+Dual License — Free tier for personal use, Pro license for commercial use and advanced features. See [LICENSE](LICENSE) for full terms.
 
-## Contributing
+## Links
 
-Issues and PRs welcome! This is an open-source project.
+- **Website:** [https://mesaplex.com](https://mesaplex.com)
+- **npm:** [https://www.npmjs.com/package/mpx-db](https://www.npmjs.com/package/mpx-db)
+- **GitHub:** [https://github.com/mesaplexdev/mpx-db](https://github.com/mesaplexdev/mpx-db)
+- **Support:** support@mesaplex.com
 
-## License
+### Related Tools
 
-MIT
+- **[mpx-scan](https://www.npmjs.com/package/mpx-scan)** — Website security scanner
+- **[mpx-api](https://www.npmjs.com/package/mpx-api)** — API testing, mocking, and documentation
+- **[mpx-secrets-audit](https://www.npmjs.com/package/mpx-secrets-audit)** — Secret lifecycle tracking and audit
 
 ---
 
-**Built with:** Node.js, Commander.js, better-sqlite3, chalk, cli-table3
-
-**Made by Mesaplex** — Build tools that actually work.
+**Made with ❤️ by [Mesaplex](https://mesaplex.com)**

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mpx-db",
-  "version": "1.1.3",
-  "description": "Database management CLI - Connect, query, migrate, and manage databases from the terminal",
+  "version": "1.2.0",
+  "description": "Database management CLI. Connect, query, migrate, and manage databases. AI-native with JSON output and MCP server.",
   "main": "src/index.js",
   "bin": {
     "mpx-db": "bin/mpx-db.js"
@@ -12,20 +12,23 @@
     "test:watch": "node --test --watch test/**/*.test.js",
     "dev": "node bin/mpx-db.js"
   },
+  "funding": "https://mesaplex.com/pricing",
   "keywords": [
-    "database",
     "cli",
+    "devtools",
+    "mesaplex",
+    "ai-native",
+    "mcp",
+    "model-context-protocol",
+    "automation",
+    "json-output",
+    "database",
     "migration",
     "postgresql",
     "mysql",
     "sqlite",
     "schema",
-    "sql",
-    "mcp",
-    "ai-native",
-    "model-context-protocol",
-    "automation",
-    "json-output"
+    "sql"
   ],
   "author": "Mesaplex <support@mesaplex.com>",
   "license": "SEE LICENSE IN LICENSE",
@@ -34,7 +37,9 @@
     "url": "git+https://github.com/mesaplexdev/mpx-db.git"
   },
   "homepage": "https://github.com/mesaplexdev/mpx-db#readme",
-  "bugs": "https://github.com/mesaplexdev/mpx-db/issues",
+  "bugs": {
+    "url": "https://github.com/mesaplexdev/mpx-db/issues"
+  },
   "engines": {
     "node": ">=18.0.0"
   },
@@ -43,7 +48,8 @@
     "better-sqlite3": "^12.6.2",
     "chalk": "^5.3.0",
     "cli-table3": "^0.6.5",
-    "commander": "^12.1.0"
+    "commander": "^12.1.0",
+    "pdfkit": "^0.17.2"
   },
   "peerDependencies": {
     "mysql2": "^3.11.5",
@@ -62,6 +68,6 @@
     "bin/",
     "README.md",
     "LICENSE",
-    "package.json"
+    "CHANGELOG.md"
   ]
 }

package/src/cli.js

@@ -31,15 +31,24 @@ program
   .version(pkg.version)
   .option('--json', 'Output as JSON (machine-readable)')
   .option('-q, --quiet', 'Suppress non-essential output')
+  .option('--no-color', 'Disable colored output')
   .option('--schema', 'Output JSON schema describing all commands and flags')
-  .hook('preAction', (thisCommand) => {
+  .option('--pdf <file>', 'Export results as a PDF report');
+
+// Error handling — must be set BEFORE .command() so subcommands inherit exitOverride
+program.exitOverride();
+program.configureOutput({
+  writeErr: () => {} // Suppress Commander's own error output; we handle it in the catch below
+});
+
+program.hook('preAction', (thisCommand) => {
     // Merge parent options with command options
     const parentOpts = thisCommand.parent?.opts() || {};
     const opts = thisCommand.opts();
     globalOptions = { ...parentOpts, ...opts };
     
-    // Disable chalk if JSON mode
-    if (globalOptions.json) {
+    // Disable chalk if JSON mode or --no-color
+    if (globalOptions.json || globalOptions.color === false) {
       chalk.level = 0;
     }
   });
@@ -74,7 +83,8 @@ program
   .description('Execute a SQL query')
   .argument('<target>', 'Connection name or URL')
   .argument('<sql>', 'SQL query to execute')
-  .action((target, sql) => handleQuery(target, sql, globalOptions));
+  .option('--pdf <file>', 'Export query results as PDF report')
+  .action((target, sql, options) => handleQuery(target, sql, { ...globalOptions, ...options }));
 
 // Info command
 program
@@ -107,7 +117,8 @@ schema
   .command('dump')
   .description('Dump database schema as SQL')
   .argument('<target>', 'Connection name or URL')
-  .action((target) => dumpSchema(target, globalOptions));
+  .option('--pdf <file>', 'Export schema as PDF report')
+  .action((target, options) => dumpSchema(target, { ...globalOptions, ...options }));
 
 // Migration commands
 const migrate = program
@@ -218,7 +229,7 @@ program
       if (jsonMode) {
         console.log(JSON.stringify({ error: err.message, code: 'ERR_UPDATE' }, null, 2));
       } else {
-        console.error(chalk.red.bold('\n❌ Update check failed:'), err.message);
+        console.error(chalk.red('Error:'), err.message);
         console.error('');
       }
       process.exit(1);
@@ -245,9 +256,6 @@ if (process.argv.includes('--schema')) {
   process.exit(0);
 }
 
-// Error handling
-program.exitOverride();
-
 try {
   await program.parseAsync(process.argv);
 } catch (err) {
@@ -256,7 +264,8 @@ try {
     process.exit(0);
   }
   if (err.code !== 'commander.help' && err.code !== 'commander.helpDisplayed') {
-    console.error(chalk.red(`Error: ${err.message}`));
-    process.exit(1);
+    const msg = err.message.startsWith('error:') ? `Error: ${err.message.slice(7)}` : `Error: ${err.message}`;
+    console.error(chalk.red(msg));
+    process.exit(2);
   }
 }

package/src/commands/query.js

@@ -2,6 +2,7 @@ import chalk from 'chalk';
 import Table from 'cli-table3';
 import { getConnection } from '../utils/config.js';
 import { createConnection } from '../db/connection.js';
+import { generateQueryPDF } from '../reporters/pdf.js';
 
 /**
  * Execute a query or statement
@@ -27,8 +28,15 @@ export async function handleQuery(target, sql, options = {}) {
       const rows = await db.query(sql);
       const duration = Date.now() - startTime;
       
+      // PDF output
+      if (options.pdf) {
+        await generateQueryPDF(rows, { sql, duration }, options.pdf);
+        if (!options.quiet) {
+          console.log(chalk.green(`✓ Query report saved to ${options.pdf} (${rows.length} rows)`));
+        }
+      }
       // JSON output
-      if (options.json) {
+      else if (options.json) {
         console.log(JSON.stringify({
           success: true,
           type: 'query',

package/src/commands/schema.js

@@ -2,6 +2,7 @@ import chalk from 'chalk';
 import Table from 'cli-table3';
 import { createConnection } from '../db/connection.js';
 import { resolveConnection } from './query.js';
+import { generateSchemaPDF } from '../reporters/pdf.js';
 
 /**
  * Show database info
@@ -135,9 +136,9 @@ export async function describeTable(target, tableName, options = {}) {
       if (options.json) {
         console.log(JSON.stringify({ error: `Table "${tableName}" not found` }, null, 2));
       } else {
-        console.log(chalk.yellow(`Table "${tableName}" not found or has no columns`));
+        console.error(chalk.yellow(`Table "${tableName}" not found or has no columns`));
       }
-      return;
+      process.exit(1);
     }
     
     // JSON output
@@ -216,19 +217,38 @@ export async function dumpSchema(target, options = {}) {
       sqlOutput += `-- Table: ${table.name}\n`;
       sqlOutput += `-- Rows: ${table.rows}\n`;
       
-      // This is a simplified dump - real implementations would generate proper DDL
+      const pkCols = schema.filter(c => c.primaryKey).map(c => c.name);
       const cols = schema.map(c => {
         let def = `  ${c.name} ${c.type}`;
-        if (!c.nullable) def += ' NOT NULL';
+        if (c.primaryKey && pkCols.length === 1) def += ' PRIMARY KEY';
+        if (!c.nullable && !c.primaryKey) def += ' NOT NULL';
         if (c.default) def += ` DEFAULT ${c.default}`;
         return def;
       });
       
       sqlOutput += `CREATE TABLE "${table.name}" (\n`;
       sqlOutput += cols.join(',\n');
+      if (pkCols.length > 1) {
+        sqlOutput += `,\n  PRIMARY KEY (${pkCols.join(', ')})`;
+      }
       sqlOutput += '\n);\n\n';
     }
     
+    // PDF output
+    if (options.pdf) {
+      const tableSchemas = [];
+      for (const table of tables) {
+        if (table.type !== 'table') continue;
+        const cols = await db.getTableSchema(table.name);
+        tableSchemas.push({ name: table.name, columns: cols });
+      }
+      await generateSchemaPDF(info, tables, tableSchemas, options.pdf);
+      if (!options.quiet) {
+        console.log(chalk.green(`✓ Schema report saved to ${options.pdf}`));
+      }
+      return;
+    }
+
     // JSON output
     if (options.json) {
       console.log(JSON.stringify({ sql: sqlOutput }, null, 2));

package/src/reporters/pdf.js

@@ -0,0 +1,286 @@
+/**
+ * PDF Report Generator for mpx-db
+ * 
+ * Generates professional database reports using PDFKit.
+ * Style consistent with mpx-scan and mpx-api PDF reports.
+ */
+
+import PDFDocument from 'pdfkit';
+import { createWriteStream, readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const pkg = JSON.parse(readFileSync(join(__dirname, '../../package.json'), 'utf8'));
+
+// Color palette (consistent with mpx-scan / mpx-api)
+const COLORS = {
+  primary: '#1a56db',
+  dark: '#1f2937',
+  gray: '#6b7280',
+  lightGray: '#e5e7eb',
+  white: '#ffffff',
+  pass: '#16a34a',
+  warn: '#ea580c',
+  fail: '#dc2626',
+  headerBg: '#1e3a5f',
+  sectionBg: '#f3f4f6',
+};
+
+/**
+ * Check for page overflow and add page if needed
+ */
+function checkPage(doc, minSpace = 120) {
+  if (doc.y > doc.page.height - minSpace) {
+    doc.addPage();
+    doc.y = 50;
+  }
+}
+
+/**
+ * Draw consistent header bar
+ */
+function drawHeader(doc, title, subtitle) {
+  const pageWidth = doc.page.width - doc.page.margins.left - doc.page.margins.right;
+  doc.rect(0, 0, doc.page.width, 100).fill(COLORS.headerBg);
+  doc.fontSize(22).fillColor(COLORS.white).font('Helvetica-Bold')
+    .text(title, 50, 30);
+  doc.fontSize(10).fillColor('#a0b4cc').font('Helvetica')
+    .text(subtitle, 50, 60);
+  doc.y = 120;
+  return pageWidth;
+}
+
+/**
+ * Draw footers on all pages
+ */
+function drawFooters(doc, pageWidth) {
+  const now = new Date().toLocaleDateString('en-US', {
+    year: 'numeric', month: 'long', day: 'numeric',
+    hour: '2-digit', minute: '2-digit',
+  });
+  const range = doc.bufferedPageRange();
+  for (let i = range.start; i < range.start + range.count; i++) {
+    doc.switchToPage(i);
+    const footerY = doc.page.height - 35;
+    doc.fontSize(7).fillColor(COLORS.gray).font('Helvetica')
+      .text(
+        `Generated by mpx-db v${pkg.version} on ${now}`,
+        50, footerY, { width: pageWidth, align: 'center' }
+      );
+    doc.text(
+      `Page ${i + 1} of ${range.count}`,
+      50, footerY + 12, { width: pageWidth, align: 'center' }
+    );
+  }
+}
+
+/**
+ * Draw a data table
+ */
+function drawTable(doc, headers, rows, pageWidth, options = {}) {
+  const colWidths = options.colWidths || headers.map(() => pageWidth / headers.length);
+  const startX = 50;
+  
+  // Header row
+  checkPage(doc, 80);
+  let x = startX;
+  doc.roundedRect(startX, doc.y, pageWidth, 22, 3).fill(COLORS.primary);
+  for (let i = 0; i < headers.length; i++) {
+    doc.fontSize(9).fillColor(COLORS.white).font('Helvetica-Bold')
+      .text(headers[i], x + 6, doc.y + 5, { width: colWidths[i] - 12 });
+    x += colWidths[i];
+  }
+  doc.y += 26;
+
+  // Data rows
+  for (let r = 0; r < rows.length; r++) {
+    checkPage(doc, 40);
+    const row = rows[r];
+    const bg = r % 2 === 0 ? COLORS.sectionBg : COLORS.white;
+    
+    // Calculate row height
+    let maxH = 16;
+    for (let i = 0; i < row.length; i++) {
+      const h = doc.heightOfString(String(row[i] ?? ''), { width: colWidths[i] - 12, fontSize: 8 });
+      if (h + 8 > maxH) maxH = h + 8;
+    }
+
+    doc.rect(startX, doc.y, pageWidth, maxH).fill(bg);
+    x = startX;
+    for (let i = 0; i < row.length; i++) {
+      const val = row[i] === null || row[i] === undefined ? '—' : String(row[i]);
+      const color = val === '—' ? COLORS.gray : COLORS.dark;
+      doc.fontSize(8).fillColor(color).font('Helvetica')
+        .text(val, x + 6, doc.y + 4, { width: colWidths[i] - 12 });
+      x += colWidths[i];
+    }
+    doc.y += maxH;
+  }
+  doc.y += 10;
+}
+
+/**
+ * Generate schema report PDF
+ */
+export function generateSchemaPDF(dbInfo, tables, tableSchemas, outputPath) {
+  return new Promise((resolve, reject) => {
+    try {
+      const now = new Date().toLocaleDateString('en-US', {
+        year: 'numeric', month: 'long', day: 'numeric',
+        hour: '2-digit', minute: '2-digit',
+      });
+
+      const doc = new PDFDocument({
+        size: 'A4',
+        margins: { top: 50, bottom: 50, left: 50, right: 50 },
+        info: {
+          Title: `mpx-db Schema Report — ${dbInfo.database || dbInfo.path || 'Database'}`,
+          Author: 'mpx-db',
+          Subject: 'Database Schema Report',
+          Creator: `mpx-db v${pkg.version}`,
+        },
+        bufferPages: true,
+      });
+
+      const stream = createWriteStream(outputPath);
+      doc.pipe(stream);
+
+      const dbName = dbInfo.database || dbInfo.path || 'Database';
+      const pageWidth = drawHeader(doc,
+        'mpx-db Schema Report',
+        `v${pkg.version}  •  ${now}  •  ${dbName}`
+      );
+
+      // ─── Summary Box ───
+      doc.roundedRect(50, doc.y, pageWidth, 80, 6).fill(COLORS.sectionBg);
+      const summaryTop = doc.y + 12;
+
+      doc.circle(100, summaryTop + 28, 26).fill(COLORS.primary);
+      doc.fontSize(20).fillColor(COLORS.white).font('Helvetica-Bold')
+        .text(String(dbInfo.tables), 100 - 20, summaryTop + 16, { width: 40, align: 'center' });
+
+      doc.fontSize(14).fillColor(COLORS.dark).font('Helvetica-Bold')
+        .text(`${dbInfo.type} Database`, 145, summaryTop + 5);
+      doc.fontSize(10).fillColor(COLORS.gray).font('Helvetica')
+        .text(`${dbInfo.tables} tables  •  ${dbInfo.totalRows.toLocaleString()} total rows  •  ${dbInfo.sizeFormatted}`, 145, summaryTop + 25);
+
+      doc.y = summaryTop + 68;
+
+      // ─── Tables Overview ───
+      doc.y += 10;
+      doc.fontSize(14).fillColor(COLORS.dark).font('Helvetica-Bold')
+        .text('Tables', 50, doc.y);
+      doc.y += 20;
+
+      const tableRows = tables.map(t => [t.name, t.type, t.rows.toLocaleString()]);
+      drawTable(doc, ['Table', 'Type', 'Rows'], tableRows, pageWidth, {
+        colWidths: [pageWidth * 0.5, pageWidth * 0.25, pageWidth * 0.25]
+      });
+
+      // ─── Table Schemas ───
+      for (const { name, columns } of tableSchemas) {
+        checkPage(doc, 100);
+
+        doc.y += 5;
+        doc.roundedRect(50, doc.y, pageWidth, 26, 4).fill(COLORS.headerBg);
+        doc.fontSize(11).fillColor(COLORS.white).font('Helvetica-Bold')
+          .text(name, 60, doc.y + 7);
+        doc.fontSize(9).fillColor('#a0b4cc').font('Helvetica')
+          .text(`${columns.length} columns`, 60, doc.y + 7, { width: pageWidth - 20, align: 'right' });
+        doc.y += 32;
+
+        const colRows = columns.map(c => [
+          c.name,
+          c.type,
+          c.nullable ? 'YES' : 'NO',
+          c.default || '—',
+          c.primaryKey ? 'PRI' : '—'
+        ]);
+
+        drawTable(doc, ['Column', 'Type', 'Nullable', 'Default', 'Key'], colRows, pageWidth, {
+          colWidths: [pageWidth * 0.28, pageWidth * 0.22, pageWidth * 0.15, pageWidth * 0.2, pageWidth * 0.15]
+        });
+      }
+
+      drawFooters(doc, pageWidth);
+      doc.end();
+
+      stream.on('finish', () => resolve(outputPath));
+      stream.on('error', reject);
+    } catch (err) {
+      reject(err);
+    }
+  });
+}
+
+/**
+ * Generate query results PDF
+ */
+export function generateQueryPDF(rows, meta, outputPath) {
+  return new Promise((resolve, reject) => {
+    try {
+      const now = new Date().toLocaleDateString('en-US', {
+        year: 'numeric', month: 'long', day: 'numeric',
+        hour: '2-digit', minute: '2-digit',
+      });
+
+      const doc = new PDFDocument({
+        size: 'A4',
+        layout: rows.length > 0 && Object.keys(rows[0]).length > 5 ? 'landscape' : 'portrait',
+        margins: { top: 50, bottom: 50, left: 50, right: 50 },
+        info: {
+          Title: `mpx-db Query Report`,
+          Author: 'mpx-db',
+          Subject: 'Database Query Results',
+          Creator: `mpx-db v${pkg.version}`,
+        },
+        bufferPages: true,
+      });
+
+      const stream = createWriteStream(outputPath);
+      doc.pipe(stream);
+
+      const pageWidth = drawHeader(doc,
+        'mpx-db Query Report',
+        `v${pkg.version}  •  ${now}`
+      );
+
+      // Query info
+      doc.roundedRect(50, doc.y, pageWidth, 60, 6).fill(COLORS.sectionBg);
+      const summaryTop = doc.y + 10;
+
+      doc.fontSize(9).fillColor(COLORS.gray).font('Helvetica').text('SQL Query:', 60, summaryTop);
+      doc.fontSize(9).fillColor(COLORS.dark).font('Helvetica-Bold')
+        .text(meta.sql || '—', 60, summaryTop + 14, { width: pageWidth - 20 });
+      
+      doc.fontSize(9).fillColor(COLORS.gray).font('Helvetica')
+        .text(`${rows.length} row(s)  •  ${meta.duration || 0}ms`, 60, summaryTop + 34);
+
+      doc.y = summaryTop + 56;
+
+      if (rows.length === 0) {
+        doc.y += 20;
+        doc.fontSize(12).fillColor(COLORS.gray).font('Helvetica')
+          .text('No rows returned.', 50, doc.y, { width: pageWidth, align: 'center' });
+      } else {
+        doc.y += 10;
+        const columns = Object.keys(rows[0]);
+        const colWidth = pageWidth / columns.length;
+        const dataRows = rows.map(row => columns.map(c => row[c]));
+        drawTable(doc, columns, dataRows, pageWidth, {
+          colWidths: columns.map(() => colWidth)
+        });
+      }
+
+      drawFooters(doc, pageWidth);
+      doc.end();
+
+      stream.on('finish', () => resolve(outputPath));
+      stream.on('error', reject);
+    } catch (err) {
+      reject(err);
+    }
+  });
+}

package/src/schema.js

@@ -139,7 +139,7 @@ export function getSchema() {
       },
       query: {
         description: 'Execute a SQL query',
-        usage: 'mpx-db query <target> <sql> [--json]',
+        usage: 'mpx-db query <target> <sql> [--json] [--pdf file.pdf]',
         arguments: {
           target: {
             type: 'string',
@@ -158,6 +158,10 @@ export function getSchema() {
             default: false,
             description: 'Output results as JSON'
           },
+          '--pdf': {
+            type: 'string',
+            description: 'Export query results as a formatted PDF report'
+          },
           '--quiet': {
             type: 'boolean',
             default: false,
@@ -318,7 +322,7 @@ export function getSchema() {
       },
       'schema dump': {
         description: 'Dump database schema as SQL',
-        usage: 'mpx-db schema dump <target>',
+        usage: 'mpx-db schema dump <target> [--pdf file.pdf]',
         arguments: {
           target: {
             type: 'string',
@@ -332,6 +336,10 @@ export function getSchema() {
             default: false,
             description: 'Output as JSON with SQL content'
           },
+          '--pdf': {
+            type: 'string',
+            description: 'Export schema as a formatted PDF report'
+          },
           '--quiet': {
             type: 'boolean',
             default: false,
@@ -586,6 +594,35 @@ export function getSchema() {
         }
       }
     },
+    globalFlags: {
+      '--json': {
+        type: 'boolean',
+        default: false,
+        description: 'Output results as structured JSON'
+      },
+      '--pdf': {
+        type: 'string',
+        description: 'Export results as a formatted PDF report (supported by query, schema dump)'
+      },
+      '-q, --quiet': {
+        type: 'boolean',
+        default: false,
+        description: 'Suppress non-essential output'
+      },
+      '--schema': {
+        type: 'boolean',
+        default: false,
+        description: 'Output this schema as JSON'
+      },
+      '--version': {
+        type: 'boolean',
+        description: 'Show version number'
+      },
+      '--help': {
+        type: 'boolean',
+        description: 'Show help information'
+      }
+    },
     exitCodes: {
       0: 'Success',
       1: 'Error (connection failed, query failed, etc.)'