dbnexus 0.4.1 → 0.5.0

package/README.md

@@ -1,38 +1,111 @@
 # DB Nexus
 
-> Database management tool with web UI
+> A **local-first database management tool** with a modern web UI, CLI, and production safety guardrails for PostgreSQL, MySQL, and SQLite.
 
 [![npm version](https://img.shields.io/npm/v/dbnexus.svg)](https://www.npmjs.com/package/dbnexus)
-[![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
+[![License](https://img.shields.io/badge/license-AGPL--3.0-blue.svg)](LICENSE)
+[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org)
 
-## Features
+**[Documentation](https://akademskig.github.io/dbnexus/)** • **[Installation](#-quick-start)** • **[Features](#-features)** • **[CLI Usage](#-cli-usage)**
 
-- 🖥️ **Modern Web UI** - Beautiful interface for database management
-- 🔌 **Multiple Databases** - PostgreSQL, MySQL, SQLite
-- 🔄 **Schema Sync** - Compare and migrate schemas between databases
-- 📊 **Data Sync** - Synchronize table data with conflict resolution
+## 📸 Screenshots
+
+<div align="center">
+
+### Query Editor
+
+![Query Page](https://akademskig.github.io/dbnexus/screenshots/query.png)
+
+### Schema Diagram
+
+![Schema Diagram](https://akademskig.github.io/dbnexus/screenshots/schemadiagram.png)
+
+### Compare & Sync
+
+![Compare Data](https://akademskig.github.io/dbnexus/screenshots/compare-data.png)
+
+<details>
+<summary>📷 More Screenshots</summary>
+
+### Connection Management
+
+![Connection Management](https://akademskig.github.io/dbnexus/screenshots/dbmanagement.png)
+
+### Activity Logs
+
+![Logs Page](https://akademskig.github.io/dbnexus/screenshots/logs.png)
+
+### Database Scanner
+
+![Scan Databases](https://akademskig.github.io/dbnexus/screenshots/scandbs.png)
+
+### Settings
+
+![Settings](https://akademskig.github.io/dbnexus/screenshots/settings.png)
+
+</details>
+
+</div>
+
+## ✨ Features
+
+### Core
+
+- 🖥️ **Modern Web UI** - Beautiful, dark-themed interface with glassmorphism design
+- 🔌 **Multiple Connections** - Manage and switch between multiple database connections
+- 🔒 **Encrypted Credentials** - Passwords stored securely with AES-256-GCM encryption
+- 🛡️ **Safety Guardrails** - Blocks dangerous queries (UPDATE/DELETE without WHERE) on production databases
+- 🔐 **Identity Verification** - Password confirmation required before viewing sensitive server credentials
+
+### Query & Data
+
+- ⚡ **Query Editor** - Execute SQL with syntax highlighting and results table
+- 🔗 **Foreign Key Navigation** - Click FK values to instantly query referenced rows
+- 📜 **Query History** - Track and replay previous queries
+- ✏️ **Inline Editing** - Edit table data directly in the results grid
+
+### Schema Tools
+
+- 📊 **Schema Browser** - Explore tables, columns, indexes, and relationships
 - 🗺️ **Schema Diagram** - Visual database schema editor with drag-and-drop
-- 🔗 **FK Navigation** - Click foreign key values to query referenced rows
-- 📜 **Query History** - Track and replay queries
-- 🔒 **Secure** - Encrypted credentials with AES-256-GCM
-- 🛡️ **Safety First** - Production guardrails for dangerous queries
-- 🔎 **Auto-Discovery** - Scan for databases via ports, Docker, env files
+- 🔄 **Schema Sync** - Compare and sync database schemas between connections
+- 🎯 **Per-Table Migration** - Apply schema changes table-by-table with copy/apply actions
+
+### Data Management
+
+- 📦 **Data Sync** - Sync table data between databases with conflict resolution
+- 🔎 **Connection Scanning** - Auto-discover databases via ports, Docker, env files, and SQLite
+- 💾 **Backup & Restore** - Full database backups with optional compression and restore capability
+
+### Server Management
 
-## Installation
+- 🖧 **Server Configuration** - Manage PostgreSQL and MySQL servers with admin credentials
+- 📊 **Server Monitoring** - View server version, uptime, and active connections
+- 🗄️ **Database Operations** - Create, drop, and import databases directly on servers
 
-### Global Installation
+### Organization
+
+- 🏷️ **Connection Tags** - Organize connections with customizable tags (dev, staging, prod)
+- 📁 **Projects & Groups** - Group related connections together
+- 🎨 **Customizable Theme** - Configure colors and styles in Settings
+
+## 🚀 Quick Start
+
+### Installation
+
+Install DB Nexus globally using npm:
 
 ```bash
 npm install -g dbnexus
 ```
 
-### Using npx
+Or run directly with npx (no installation required):
 
 ```bash
 npx dbnexus
 ```
 
-## Usage
+### Usage
 
 Start DB Nexus:
 
@@ -40,123 +113,266 @@ Start DB Nexus:
 dbnexus
 ```
 
-This will start the server and open your browser to `http://localhost:3001`.
+This will:
+
+- Start the server on `http://localhost:3001`
+- Automatically open your browser
+- Store metadata in `~/.dbnexus/metadata.db`
 
-### Options
+#### Options
 
 ```bash
-dbnexus --port 8080           # Run on custom port
-dbnexus --data-dir /path      # Use custom data directory
-dbnexus --no-open             # Don't open browser automatically
-dbnexus --help                # Show help
+dbnexus --port 8080           # Custom port
+dbnexus --data-dir /path      # Custom data directory
+dbnexus --no-open             # Don't open browser
+dbnexus --help                # Show all options
 ```
 
-### Commands
+### Supported Databases
+
+- PostgreSQL
+- MySQL
+- SQLite
+
+---
+
+## 🛠️ Development Setup
+
+### Prerequisites
+
+- Node.js 18+
+- pnpm
+- PostgreSQL/MySQL (for target databases)
+
+### Installation
 
 ```bash
-dbnexus                       # Start DB Nexus (default)
-dbnexus start                 # Explicit start command
-dbnexus --version             # Show version
+# Clone the repository
+git clone https://github.com/akademskig/dbnexus.git
+cd dbnexus
+
+# Install dependencies
+pnpm install
+
+# Build all packages
+pnpm build
 ```
 
-## Data Storage
+### Running in Development
+
+```bash
+# Start development servers (API + Web UI)
+pnpm dev
+```
 
-DB Nexus stores its metadata database in:
+- **Web UI**: <http://localhost:5173>
+- **API**: <http://localhost:3001>
 
-- **Linux/Mac**: `~/.dbnexus/metadata.db`
-- **Windows**: `%USERPROFILE%\.dbnexus\metadata.db`
+## 💻 CLI Usage
 
-You can customize this location:
+### Start the UI (default command)
 
 ```bash
-# Using flag
-dbnexus --data-dir /custom/path
+# Start DB Nexus (default)
+dbnexus
 
-# Using environment variable
-DBNEXUS_DATA_DIR=/custom/path dbnexus
-```
+# Custom port
+dbnexus --port 4000
+
+# Don't open browser
+dbnexus --no-open
 
-## Features Overview
+# Custom data directory
+dbnexus --data-dir ~/my-data
+```
 
 ### Connection Management
 
-- Add and manage multiple database connections
-- Organize connections into projects and groups
-- Test connection health
-- Encrypted credential storage
-- Auto-discover databases via port scanning and Docker
+```bash
+# Add a new connection
+dbnexus connect add \
+  --name prod-db \
+  --host db.example.com \
+  --port 5432 \
+  --database myapp \
+  --user admin \
+  --password secret \
+  --ssl \
+  --tags prod,main
+
+# List all connections
+dbnexus connect list
+
+# Test a connection
+dbnexus connect test prod-db
+
+# Remove a connection
+dbnexus connect remove prod-db
+```
 
-### Query Editor
+### Query Execution
+
+```bash
+# Run a query
+dbnexus query --conn prod-db --sql "SELECT * FROM users LIMIT 10"
+
+# Execute from file
+dbnexus query --conn prod-db --file ./query.sql
+
+# Dangerous queries require --confirm
+dbnexus query --conn prod-db --sql "DROP TABLE temp" --confirm
+```
+
+### Database Scanning
 
-- Execute SQL queries with syntax highlighting
-- View results in a data grid
-- Edit data inline
-- **Click FK values to navigate to referenced rows**
-- Query history and saved queries
+```bash
+# Scan for databases (ports, Docker, .env files, SQLite)
+dbnexus scan
+
+# Auto-add discovered connections
+dbnexus scan --add
+
+# Scan specific directories for .env files
+dbnexus scan --env-dirs ~/projects,/var/www
+```
+
+### Data Export
 
-### Schema Management
+```bash
+# Export table to CSV
+dbnexus export --conn prod-db --table users --format csv --output users.csv
 
-- Browse tables, columns, indexes, and foreign keys
-- Visual schema diagram with drag-and-drop
-- Compare schemas between databases
-- Generate migration SQL
-- Apply schema changes
+# Export query results to JSON
+dbnexus export --conn prod-db --sql "SELECT * FROM orders" --format json --output orders.json
+```
 
-### Data Synchronization
+### Schema Tools
 
-- Compare data between tables
-- Sync data with conflict resolution
-- Bulk data operations
-- Dump and restore databases
+```bash
+# Show schema for a connection
+dbnexus schema show --conn prod-db
 
-## Requirements
+# Show specific table schema
+dbnexus schema show --conn prod-db --table users
 
-- Node.js 18 or higher
-- One of: PostgreSQL, MySQL, or SQLite
+# Compare schemas between connections
+dbnexus schema compare --source dev-db --target prod-db
 
-## Supported Databases
+# Generate migration SQL
+dbnexus schema diff --source dev-db --target prod-db --output migration.sql
+```
 
-- **PostgreSQL** 9.6+
-- **MySQL** 5.7+
-- **MariaDB** 10.2+
-- **SQLite** 3.0+
+## 🔧 Scripts
 
-## Configuration
+| Command       | Description                     |
+| ------------- | ------------------------------- |
+| `pnpm dev`    | Start development servers       |
+| `pnpm build`  | Build all packages              |
+| `pnpm lint`   | Run ESLint                      |
+| `pnpm format` | Format code with Prettier       |
+| `pnpm check`  | Run lint + format check + build |
 
-### Environment Variables
+## 📦 Distribution
 
-- `DBNEXUS_DATA_DIR` - Custom data directory
-- `PORT` - Server port (default: 3001)
-- `NODE_ENV` - Environment (development/production)
+### Docker
 
-## Uninstallation
+Build and run DB Nexus as a Docker container:
 
 ```bash
-# Remove the package
-npm uninstall -g dbnexus
+# Build the Docker image
+pnpm docker:build
 
-# Remove all data
-rm -rf ~/.dbnexus
+# Run with Docker
+pnpm docker:run
+
+# Or use Docker Compose for production
+pnpm docker:compose
 ```
 
-## Documentation
+The application will be available at `http://localhost:3001`.
 
-- [GitHub Repository](https://github.com/akademskig/dbnexus)
-- [Issue Tracker](https://github.com/akademskig/dbnexus/issues)
+### Desktop Application (Electron)
 
-## Contributing
+Build standalone desktop applications for Windows, macOS, and Linux:
 
-Contributions are welcome! Please see our [Contributing Guide](https://github.com/akademskig/dbnexus/blob/main/CONTRIBUTING.md).
+```bash
+# Build for all platforms
+pnpm desktop:build
 
-## License
+# Build for specific platforms
+pnpm desktop:build:win    # Windows (.exe, portable)
+pnpm desktop:build:mac    # macOS (.dmg, .zip)
+pnpm desktop:build:linux  # Linux (.AppImage, .deb, .rpm)
+```
 
-AGPL-3.0 © DB Nexus Team
+Built applications will be in `apps/desktop/out/`.
 
-## Support
+### Manual Installation
 
-- 🐛 Issues: [GitHub Issues](https://github.com/akademskig/dbnexus/issues)
-- 💬 Discussions: [GitHub Discussions](https://github.com/akademskig/dbnexus/discussions)
+For manual deployment:
+
+```bash
+# Build all packages
+pnpm build
+
+# Start in production mode
+NODE_ENV=production node apps/api/dist/main.js
+```
+
+## 🐳 Docker Compose (Development)
+
+For testing with multiple database instances:
+
+```bash
+# Start test databases (PostgreSQL, MySQL)
+docker-compose up -d
+
+# Stop test databases
+docker-compose down
+```
+
+## 📖 Documentation
+
+- **[Full Documentation](https://akademskig.github.io/dbnexus/)** - Complete guide with screenshots and examples
+- **[Architecture & Design](./DESIGN.md)** - Technical details and design decisions
+- **[Installation Guide](./INSTALLATION.md)** - Detailed installation instructions
+- **[Changelog](./CHANGELOG.md)** - Release notes and version history
+
+## 🌟 Why DB Nexus?
+
+- **🏠 Local-First** - Your data stays on your machine. No cloud dependencies.
+- **🎨 Modern UI** - Beautiful, intuitive interface with dark mode and glassmorphism design
+- **🛡️ Production Safe** - Built-in guardrails prevent accidental data loss
+- **🔒 Secure** - AES-256-GCM encryption for stored credentials
+- **⚡ Fast** - Native performance with direct database connections
+- **🆓 Open Source** - AGPL-3.0 licensed, free forever
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## 🐛 Bug Reports
+
+Found a bug? Please [open an issue](https://github.com/akademskig/dbnexus/issues) with:
+
+- Steps to reproduce
+- Expected behavior
+- Actual behavior
+- Database type and version
+- DB Nexus version (`dbnexus --version`)
+
+## 📄 License
+
+AGPL-3.0 - See [LICENSE](./LICENSE) for details.
 
 ---
 
-**Like Prisma Studio, but for any database** - Manage PostgreSQL, MySQL,and SQLite databases with a beautiful web interface.
+**Made with ❤️ by the DB Nexus team**
+
+[⭐ Star us on GitHub](https://github.com/akademskig/dbnexus) • [📖 Read the docs](https://akademskig.github.io/dbnexus/) • [🐛 Report a bug](https://github.com/akademskig/dbnexus/issues)