mpx-db 1.1.2 → 1.2.0

package/LICENSE

@@ -1,16 +1,26 @@
-MIT License
+Mesaplex Dual License
 
 Copyright (c) 2026 Mesaplex
 
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
+This software is available under two licensing options:
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
+1. FREE TIER (Personal Use)
+   - Limited daily usage
+   - Basic features only
+   - Personal and non-commercial use only
+   
+   Permission is granted to use this software for personal, non-commercial
+   purposes subject to the usage limits described in the documentation.
+
+2. PRO LICENSE (Commercial Use)
+   - Unlimited usage
+   - All features unlocked
+   - JSON/CSV export
+   - CI/CD integration
+   - Commercial use allowed
+   - Priority support
+   
+   To obtain a Pro license, visit: https://mesaplex.com
 
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,

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)**