Skip to content

A native macOS / windows / Linux database IDE built with Swift and AppKit. Connect to PostgreSQL, MySQL, SQLite, and Redis from a single app with a fast, keyboard-driven interface.

C++

chore: Readme

Tobif9d0d3ebccf4
diff --git a/README.md b/README.md
index b87768e..9bd0278 100644
--- a/README.md
+++ b/README.md
@@ -1,117 +1,178 @@
-# Gridex
+<h1 align="center">Gridex</h1>
-A native database IDE for macOS and Windows with built-in AI chat. Connect to PostgreSQL, MySQL, SQLite, Redis, MongoDB, and SQL Server from a single app.
+<p align="center">
+ <strong>AI-native database IDE for macOS and Windows.</strong><br>
+ One app for PostgreSQL, MySQL, SQLite, Redis, MongoDB, and SQL Server — with a built-in MCP server and AI chat.
+</p>
+
+<p align="center">
+ <img src="https://img.shields.io/badge/macOS-14%2B-blue" alt="macOS 14+">
+ <img src="https://img.shields.io/badge/Windows-10%2B-0078D4" alt="Windows 10+">
+ <img src="https://img.shields.io/badge/Swift-5.10-orange" alt="Swift 5.10">
+ <img src="https://img.shields.io/badge/license-Apache%202.0-blue" alt="License">
+</p>
+
+<p align="center">
+ <img src="assets/show-case.png" alt="Gridex overview" width="100%">
+</p>
+
+---
-![macOS 14+](https://img.shields.io/badge/macOS-14%2B-blue)
-![Windows 10+](https://img.shields.io/badge/Windows-10%2B-0078D4)
-![Swift 5.10](https://img.shields.io/badge/Swift-5.10-orange)
-![License](https://img.shields.io/badge/license-Apache%202.0-blue)
+## Supported Databases
+
+<p align="center">
+ <img src="https://img.shields.io/badge/PostgreSQL-316192?style=for-the-badge&logo=postgresql&logoColor=white" alt="PostgreSQL">
+ <img src="https://img.shields.io/badge/MySQL-4479A1?style=for-the-badge&logo=mysql&logoColor=white" alt="MySQL">
+ <img src="https://img.shields.io/badge/SQLite-003B57?style=for-the-badge&logo=sqlite&logoColor=white" alt="SQLite">
+ <img src="https://img.shields.io/badge/Redis-DC382D?style=for-the-badge&logo=redis&logoColor=white" alt="Redis">
+ <img src="https://img.shields.io/badge/MongoDB-47A248?style=for-the-badge&logo=mongodb&logoColor=white" alt="MongoDB">
+ <img src="https://img.shields.io/badge/SQL_Server-CC2927?style=for-the-badge&logo=microsoftsqlserver&logoColor=white" alt="SQL Server">
+</p>
<p align="center">
- <img src="assets/screenshot.jpg" alt="Gridex Screenshot" width="100%">
+ <em>Six drivers in one native binary. All share the same <code>DatabaseAdapter</code> protocol (~50 methods) so every feature — grid, query editor, ER diagram, backup, MCP — works identically across engines.</em>
</p>
-## Features
+---
-### Database Support
+## Why Gridex
+
+- **Native.** AppKit on macOS, WinUI 3 on Windows. No Electron, no web views for the grid.
+- **Multi-database.** Six drivers in one binary, each with the right primitives (SCAN for Redis, aggregations for MongoDB, stored procedures for SQL Server, sequences for Postgres).
+- **AI that sees your schema.** Claude, GPT, Gemini, and Ollama can read your tables, run read-only queries, and write SQL scoped to the connection you pick.
+- **MCP server built in.** Plug Gridex into Claude Desktop, Cursor, or any MCP client over stdio — 13 tools with a 3-tier permission model and audit trail.
+- **Credentials stay local.** macOS Keychain / Windows Credential Manager. No cloud sync, no telemetry, no proxy.
+
+---
+
+## Driver Highlights
| Database | Driver | Highlights |
|----------|--------|------------|
-| **PostgreSQL** | [PostgresNIO](https://github.com/vapor/postgres-nio) | Parameterized queries, SSL/TLS, sequences, full schema inspection |
-| **MySQL** | [MySQLNIO](https://github.com/vapor/mysql-nio) | Character set handling, parameterized queries, SSL |
+| **PostgreSQL** | [PostgresNIO](https://github.com/vapor/postgres-nio) | Parameterized queries, mTLS, sequences, full schema inspection |
+| **MySQL** | [MySQLNIO](https://github.com/vapor/mysql-nio) | Charset handling, parameterized queries, TLS, auto-reconnect with keepalive |
| **SQLite** | System `libsqlite3` | File-based, WAL mode, zero config |
-| **Redis** | [RediStack](https://github.com/swift-server/RediStack) | Key browser, SCAN filter, Server INFO dashboard, Slow Log viewer |
-| **MongoDB** | [MongoKitten](https://github.com/orlandos-nl/MongoKitten) | Document editor, NDJSON export/restore, aggregation |
-| **SQL Server** | [CosmoSQLClient](https://github.com/vkuttyp/CosmoSQLClient-Swift) | TDS 7.4 protocol, native BACKUP DATABASE, stored procedures |
+| **Redis** | [RediStack](https://github.com/swift-server/RediStack) | Key browser, SCAN filter, Server INFO dashboard, Slow Log viewer, `rediss://` TLS |
+| **MongoDB** | [MongoKitten](https://github.com/orlandos-nl/MongoKitten) | Document editor, NDJSON backup/restore, aggregation pipeline |
+| **SQL Server** | [CosmoSQLClient](https://github.com/vkuttyp/CosmoSQLClient-Swift) | TDS 7.4 (no FreeTDS), native `BACKUP DATABASE`, stored procedures |
-### AI Chat
+---
-Built-in AI assistant that understands your schema and writes SQL for you.
+## MCP Server
-- **Anthropic Claude** — streaming responses, direct API
-- **OpenAI GPT** — full API support
-- **Google Gemini** — Flash model support
-- **Ollama** — local LLM, no API key needed
+Expose any saved connection to MCP clients (Claude Desktop, Cursor, custom agents) over stdio. Every tool call runs through a permission gate and is recorded in the audit log.
-All requests go directly from your machine to the provider. Gridex never proxies prompts. API keys are stored in the macOS Keychain.
+<p align="center">
+ <img src="assets/mcp.png" alt="MCP Server configuration" width="100%">
+</p>
-### Data Grid
+**13 tools across 3 permission tiers:**
-- Inline cell editing with type-aware parsing
-- Sort, filter, and paginate large datasets
-- Add/delete rows with pending change tracking and commit workflow
-- Column resize, multi-column sort
-- Copy rows, export to CSV/JSON/SQL
+| Tier | Tools | When it runs |
+|------|-------|--------------|
+| **Read** (metadata) | `list_connections`, `list_schemas`, `list_tables`, `describe_table`, `list_relationships`, `get_sample_rows` | Always allowed for enabled connections |
+| **Read** (query) | `query`, `explain_query`, `search_across_tables` | Allowed in `read_only`+ modes; SQL sanitizer rejects write statements |
+| **Write** (mutations) | `insert_rows`, `update_rows`, `delete_rows`, `execute_write_query` | Only in `read_write` mode; row-count estimator flags bulk changes; user approval required |
-### Query Editor
+**Security layers** in [`macos/Services/MCP/Security/`](macos/Services/MCP/Security/):
-- Multi-tab with connection-grouped Chrome-style tab bar
-- Syntax highlighting (keywords, strings, numbers, comments, functions)
-- Full query history persisted via SwiftData
-- Execute selection, execute all
-- Redis CLI mode
+- `MCPPermissionEngine` — per-connection mode (`locked`, `read_only`, `read_write`)
+- `MCPSQLSanitizer` — rejects DDL/DML that escape the declared tier
+- `MCPIdentifierValidator` — guards against SQL injection in identifiers
+- `MCPRowCountEstimator` — previews how many rows a mutation will touch
+- `MCPRateLimiter` — caps calls per tool per minute
+- `MCPApprovalGate` — prompts the user for destructive actions
-### Schema Tools
+<p align="center">
+ <img src="assets/mcp-logs.png" alt="MCP activity log" width="100%">
+</p>
-- Table structure viewer (columns, indexes, foreign keys, constraints)
-- ER Diagram with auto-layout, zoom, pan, and FK relationship lines
-- Function inspector with source code and parameter signatures
-- Stored procedure support (MSSQL)
+Every tool invocation lands in the activity log with tier, SQL, duration, row count, and approval state — so you can answer *"what did the agent do last night?"* without guessing.
-### SSH Tunnel
+---
-- Password and private-key authentication
-- Local port forwarding through bastion hosts
-- Managed by `SSHTunnelService` actor (thread-safe, async/await)
+## ER Diagram
-### Import & Export
+<p align="center">
+ <img src="assets/diagram.png" alt="ER diagram canvas" width="100%">
+</p>
-- **Export**: CSV, JSON, SQL (INSERT statements), SQL (full DDL with sequences/indices), schema DDL
-- **Import**: CSV (with column mapping), SQL dumps
+- Pure Swift renderer on macOS; Dagre + WebView on Windows — no external d2/Graphviz binary.
+- Auto-layout, pan, zoom, fit-to-view, FK relationship routing.
+- Reads live schema from the active adapter — no separate import step.
+- Click a column to jump to its table; double-click to open data.
-### Backup & Restore
+---
-| Database | Backup Method |
-|----------|---------------|
-| PostgreSQL | pg_dump (custom, SQL, tar) / pg_restore |
-| MySQL | mysqldump / mysql CLI |
-| SQLite | File copy |
-| MongoDB | NDJSON (one document per line) |
-| Redis | JSON snapshot via SCAN |
-| SQL Server | Native `BACKUP DATABASE` |
+## AI Chat
+
+Built-in chat that understands your schema and writes SQL scoped to the selected connection.
+
+- **Anthropic Claude** — streaming, tool use, extended thinking
+- **OpenAI** — GPT-4.x / 5.x, function calling
+- **Google Gemini** — Flash and Pro
+- **Ollama** — local LLMs, no API key needed
+
+Requests go direct from your machine to the provider. Gridex never proxies prompts. API keys live in the macOS Keychain / Windows Credential Manager.
+
+---
+
+## Editor & Grid
+
+**Data grid**
+- Inline cell editing with type-aware parsing
+- Sort, filter, paginate, column resize, multi-column sort
+- Add/delete rows with pending-change tracking — commit as one transaction
+- Copy rows, export to CSV / JSON / SQL
+
+**Query editor**
+- Multi-tab with Chrome-style tab bar grouped by database
+- Syntax highlighting (keywords, strings, numbers, comments, functions)
+- Execute selection or all
+- Redis CLI mode for Redis connections
+- Query history persisted via SwiftData — searchable, favoritable
+
+**Schema tools**
+- Structure viewer: columns, indexes, foreign keys, constraints
+- Function and stored-procedure inspector (source + parameters)
+- Create Table / Create Database sheets with type-aware defaults
+
+---
-Supports selective table backup, compression options, and progress callbacks.
+## SSH Tunnel
-### Redis Management
+Password, private-key, or key-with-passphrase auth. Local port forwarding via `swift-nio-ssh`. Managed by the `SSHTunnelService` actor — one tunnel per active connection, torn down on disconnect.
-- Virtual "Keys" table with SCAN-based browsing
-- Key Detail View — edit hash fields, list items, set/zset members
-- Pattern-based filter bar (glob syntax: `user:*`, `cache:?`)
-- Server INFO dashboard with auto-refresh
-- Slow Log viewer, Flush DB, key rename/duplicate, TTL management
+## mTLS (Teleport-style)
-### MongoDB Document Editor
+Connections support `sslKeyPath` + `sslCertPath` + `sslCACertPath` for mutual TLS. Works end-to-end for PostgreSQL, MySQL, and Redis — drop in the certs a tool like Teleport issues and connect as usual.
-- NDJSON document editing with syntax-aware editor
-- Document insert/update/delete
-- Aggregation pipeline support
+## Backup & Restore
-### Other
+| Database | Backup |
+|----------|--------|
+| PostgreSQL | `pg_dump` (custom / SQL / tar) + `pg_restore` |
+| MySQL | `mysqldump` + `mysql` |
+| SQLite | File copy |
+| MongoDB | NDJSON (one doc per line, pure Swift) |
+| Redis | JSON snapshot via SCAN (pure Swift) |
+| SQL Server | Native `BACKUP DATABASE` |
+
+Selective table backup, compression, and progress reporting for the CLI-backed formats.
-- Multi-window support (Cmd+N)
-- macOS Keychain for all credential storage
-- Dark mode native
-- Connection save/load with SSH tunnel config and SSL/TLS options
+## Import
+
+Connections import from **TablePlus**, **Navicat** (NCX with Blowfish decrypt), **DataGrip**, and **DBeaver** — including SSH configs and keychain-stored passwords.
+
+---
## Requirements
### macOS
-
- macOS 14.0 (Sonoma) or later
- Swift 5.10+ / Xcode 15+
### Windows
-
- Windows 10 or later (64-bit)
- Visual Studio 2022+, .NET 8 SDK, vcpkg
@@ -136,20 +197,16 @@ open dist/Gridex.app
```bash
# Apple Silicon
-./scripts/release.sh
-# → dist/Gridex-<version>-arm64.dmg
+./scripts/release.sh # → dist/Gridex-<version>-arm64.dmg
# Intel
-ARCH=x86_64 ./scripts/release.sh
-# → dist/Gridex-<version>-x86_64.dmg
+ARCH=x86_64 ./scripts/release.sh # → dist/Gridex-<version>-x86_64.dmg
# Both architectures
./scripts/release-all.sh
```
-Release pipeline: `swift build` → `.app` bundle → code sign → notarize → staple → DMG → sign DMG → notarize DMG.
-
-**Environment variables for release:**
+Pipeline: `swift build` → `.app` bundle → code sign → notarize → staple → DMG → sign DMG → notarize DMG.
| Variable | Description |
|----------|-------------|
@@ -158,51 +215,54 @@ Release pipeline: `swift build` → `.app` bundle → code sign → notarize →
| `NOTARY_PROFILE` | `notarytool` keychain profile (default: `gridex-notarize`) |
| `NOTARIZE` | Set to `0` to skip notarization |
+Auto-update is delivered via [Sparkle](https://sparkle-project.org). Release artifacts are signed, stapled, and advertised via an appcast feed.
+
+---
+
## Architecture
-Clean Architecture with 5 layers. Dependencies point inward — Presentation → Services → Data → Domain → Core.
+Clean Architecture, 5 layers. Dependencies point inward.
```
gridex/
-├── macos/ macOS app (Swift, AppKit)
-│ ├── App/ Lifecycle, DI container, AppState, constants
-│ ├── Core/ Protocols, models, enums, errors — zero deps
-│ │ ├── Protocols/ DatabaseAdapter, LLMService, SchemaInspectable
-│ │ ├── Models/ RowValue, ConnectionConfig, QueryResult, etc.
-│ │ └── Enums/ DatabaseType, GridexError
+├── macos/ macOS app (Swift, AppKit + SwiftUI)
+│ ├── App/ Lifecycle, DI container, AppState
+│ ├── Core/ Protocols, models, enums — zero deps
+│ │ ├── Protocols/ DatabaseAdapter, LLMService, SchemaInspectable, MCPTool
+│ │ └── Models/ RowValue, ConnectionConfig, QueryResult, MCPAuditEntry
│ ├── Domain/ Use cases, repository protocols
-│ ├── Data/ Adapters, SwiftData persistence, Keychain
-│ │ ├── Adapters/ SQLite, PostgreSQL, MySQL, MongoDB, Redis, MSSQL
-│ │ ├── Persistence/ SwiftData models (connections, query history)
-│ │ └── Keychain/ macOS Keychain service
-│ ├── Services/ Cross-cutting concerns
-│ │ ├── QueryEngine/ QueryEngine actor, ConnectionManager, QueryBuilder
-│ │ ├── AI/ Anthropic, OpenAI, Ollama, Gemini providers
-│ │ ├── SSH/ SSHTunnelService (NIOSSH port forwarding)
+│ ├── Data/ Adapters + SwiftData persistence + Keychain
+│ │ └── Adapters/ SQLite, PostgreSQL, MySQL, MongoDB, Redis, MSSQL
+│ ├── Services/ Cross-cutting
+│ │ ├── QueryEngine/ ConnectionManager, QueryEngine, QueryBuilder
+│ │ ├── AI/ Anthropic, OpenAI, Gemini, Ollama providers
+│ │ ├── MCP/ MCPServer, StdioTransport, Tools (Tier1/2/3), Security
+│ │ ├── SSH/ SSHTunnelService (NIOSSH)
│ │ └── Export/ ExportService, BackupService
│ └── Presentation/ AppKit views, SwiftUI settings, ViewModels
-│ ├── Views/ 18 view groups (DataGrid, QueryEditor, AIChat, etc.)
-│ └── Windows/ macOS window management
├── windows/ Windows app (C++, WinUI 3)
├── scripts/ Build and release automation
└── Package.swift SPM manifest
```
-### Key Protocols
+**Key protocols**
+
+- `DatabaseAdapter` — connection lifecycle, queries, schema, CRUD, transactions, pagination. All 6 adapters conform.
+- `LLMService` — streaming AI responses via `AsyncThrowingStream`. All 4 providers conform.
+- `SchemaInspectable` — full schema snapshot for the AI context engine and ER diagram.
+- `MCPTool` — MCP tool contract with tier, input schema, and permission-checked execute.
-- **`DatabaseAdapter`** — ~50 methods covering connection, queries, schema, CRUD, transactions, pagination. All 6 database adapters conform to this.
-- **`LLMService`** — Streaming AI responses via `AsyncThrowingStream`. All 4 AI providers conform.
-- **`SchemaInspectable`** — Full schema snapshot (tables, views, indices, constraints).
+**Concurrency**
-### Concurrency
+- `actor` for thread-safe services: `QueryEngine`, `ConnectionManager`, `SSHTunnelService`, `BackupService`, `MCPServer`.
+- `async/await` throughout — no completion handlers.
+- `Sendable` on all data models.
-- `actor` for thread-safe services: `QueryEngine`, `ConnectionManager`, `SSHTunnelService`, `BackupService`, `SchemaInspectorService`
-- `async/await` throughout — no completion handlers
-- `Sendable` constraints on all data models
+**Dependency injection**
-### Dependency Injection
+`DependencyContainer` (singleton) composes services at launch. SwiftData `ModelContainer` is shared across windows. Services are injected via the SwiftUI environment.
-`DependencyContainer` (singleton) manages service creation. SwiftData `ModelContainer` shared across windows. Services injected via SwiftUI environment.
+---
## Dependencies
@@ -210,19 +270,22 @@ gridex/
|---------|---------|---------|
| [postgres-nio](https://github.com/vapor/postgres-nio) | 1.21.0+ | PostgreSQL driver |
| [mysql-nio](https://github.com/vapor/mysql-nio) | 1.7.0+ | MySQL driver |
-| [swift-nio-ssl](https://github.com/apple/swift-nio-ssl) | 2.27.0+ | TLS for NIO connections |
+| [swift-nio-ssl](https://github.com/apple/swift-nio-ssl) | 2.27.0+ | TLS for NIO-based drivers |
| [swift-nio-ssh](https://github.com/apple/swift-nio-ssh) | 0.8.0+ | SSH tunnel support |
| [RediStack](https://github.com/swift-server/RediStack) | 1.6.0+ | Redis driver |
| [MongoKitten](https://github.com/orlandos-nl/MongoKitten) | 7.9.0+ | MongoDB driver (pure Swift) |
-| [CosmoSQLClient-Swift](https://github.com/vkuttyp/CosmoSQLClient-Swift) | main | MSSQL via TDS 7.4 (no FreeTDS) |
+| [CosmoSQLClient-Swift](https://github.com/vkuttyp/CosmoSQLClient-Swift) | main | MSSQL via TDS 7.4 |
+| [Sparkle](https://github.com/sparkle-project/Sparkle) | 2.6.0+ | macOS auto-update |
System library: `libsqlite3` (linked at build time).
+---
+
## Contributing
Contributions are welcome. Please open an issue first to discuss what you'd like to change.
-See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for community standards.
+See [CONTRIBUTING.md](CONTRIBUTING.md) and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
## License
diff --git a/assets/diagram.png b/assets/diagram.png
new file mode 100644
index 0000000..0d3c0c2
Binary files /dev/null and b/assets/diagram.png differ
diff --git a/assets/mcp-logs.png b/assets/mcp-logs.png
new file mode 100644
index 0000000..4a3d1e0
Binary files /dev/null and b/assets/mcp-logs.png differ
diff --git a/assets/mcp.png b/assets/mcp.png
new file mode 100644
index 0000000..63b2e6d
Binary files /dev/null and b/assets/mcp.png differ
diff --git a/assets/screenshot.jpg b/assets/screenshot.jpg
deleted file mode 100644
index a225c3b..0000000
Binary files a/assets/screenshot.jpg and /dev/null differ
diff --git a/assets/show-case.png b/assets/show-case.png
new file mode 100644
index 0000000..4b3eb2d
Binary files /dev/null and b/assets/show-case.png differ