BerryDB Desktop Documentation
Comprehensive user guide and technical documentation for BerryDB Desktop (`berrydb-desktop`) — the multi-engine native database client engineered for PostgreSQL, MySQL, SQLite, MongoDB, DynamoDB, and Qdrant with local AI intelligence.
1. Getting Started with BerryDB Desktop
System requirements, installation steps, creating your first database connection, and activating trials.
System Requirements
- Operating System: macOS 14.0 (Sonoma) or later.
- Architecture: Native universal binary for Apple Silicon (M1/M2/M3/M4) and Intel.
- RAM: 4 GB minimum (8 GB recommended for streaming multi-gigabyte query buffers).
- Disk Space: 150 MB for application bundle and local metadata storage.
Installation Guide
- Download the latest official
BerryDB.dmgpackage. - Open the disk image and drag BerryDB.app into your
/Applicationsfolder. - Launch BerryDB via Spotlight (
⌘Space) or Launchpad. - Grant local network and file system privileges upon first initialization.
Establishing Your First Database Connection
Upon launching BerryDB, press ⌘⇧N to open the New Connection sheet (or press ⌘N for a fresh workspace window):
BerryDB offers an unrestricted 14-day free trial bound to your Mac's hardware signature (device hash). No credit card is required. To activate a purchased license key, navigate to BerryDB → License..., enter your email and paste your key (e.g., BERRY-PRO-...), then click Activate License.
2. Database Connections & Security Tunnels
Native driver support for 6 database systems, TLS/SSL configurations, OpenSSH tunneling, and production guardrails.
Full schema tree, views, functions, triggers, pgvector vector search columns, TLS, and SSH tunnel support.
Process list monitor, JSON column visual inspector, table designers, DDL export, and TLS security.
File picker (Choose...), instant local file browsing, schema editing, and zero-latency SQL execution.
Standard mongodb:// & mongodb+srv:// URI parsing, replica sets, and JS Mongo shell editor.
AWS SigV4 auth mapping (User $\rightarrow$ Access Key, Pass $\rightarrow$ Secret Key, DB $\rightarrow$ Region), DynamoDB Local support.
Vector database engine, HTTP api-key auth, nearest-neighbor vector payload queries, and payload filters.
TLS / SSL Security Modes
SSH Tunneling & Host Key Verification
Supports OpenSSH private keys: Ed25519, RSA, ECDSA, and password auth.
sshHostKeyChanged error if fingerprints change to prevent MITM attacks.Mark connection profiles with the Production Environment toggle in Advanced settings to display a prominent red badge across workspace tabs. Any write operations (UPDATE, DELETE, DROP, or inline grid modifications) on production connections trigger mandatory confirmation prompts before executing.
3. Multi-Engine Query Editors & Execution Plans
Relational SQL editor, Mongo Shell, Qdrant vector scripts, EXPLAIN tree visualizer, autocommit controls, and query history.
Relational SQL Editor Features
Engine-specific lexical coloring for PostgreSQL, MySQL, SQLite, and DynamoDB PartiQL. Press Esc or type to suggest keywords, tables, views, columns, and table alias resolutions (u.).
SELECT queries without explicit limits automatically append LIMIT 1000 to prevent memory overflow. Each execution tab reports duration (12ms) and row count (Rows: 250).
Generates EXPLAIN ANALYZE and renders an interactive tree diagram detailing node types, scan operations, index usage, and cost metrics.
Toolbar autocommit toggle with manual BEGIN, COMMIT, and ROLLBACK execution controls and active state indicators.
JavaScript Mongo shell with collection completion and JSON vector search scripts for Qdrant nearest-neighbor payload filters.
SELECT id, document_title, embedding <=> '[0.12, 0.45, 0.89]'::vector AS distance FROM document_embeddings WHERE created_at >= NOW() - INTERVAL '7 days' ORDER BY distance ASC LIMIT 10;
4. Data Grid, Cell Inspectors & DDL Table Designers
Batch streaming grid (500–1000 rows), staged ChangeSet inline editing, cell viewers, foreign key links, and table schema migration.
Batch Streaming Grid & ChangeSets
- Streaming Batches: Streams data from drivers in batches of 500–1000 rows via
ResultBuffer.swiftfor smooth RAM usage. - Inline Cell Editing: Double-click cell to modify values; staged modifications display distinct highlight colors.
- Explicit Values: Explicitly distinguishes between
NULL, empty string"", and columnDEFAULT. - Apply Changes: Click Apply to preview staged
UPDATE,INSERT, andDELETEstatements before committing.
Cell Viewers & Foreign Key Jumping
- Text Inspector: Wrapped text viewer with line numbers and search.
- JSON Inspector: Pretty-printed JSON tree with node folding and validation.
- Hex & Image Inspectors: Inspect raw binary byte grids or view stored image blobs.
- Foreign Key Links: Click foreign key cell badges to jump directly to target parent primary key records in a new tab.
Table Designer, DDL Migration & Data Export
pgvector, jsonb, uuid), configure indexes and foreign key cascades.CREATE TABLE DDL script and table stats (disk size, row count estimates, index size).INSERT INTO DML, or Markdown tables.5. AI Assistant Panel & Tool Approvals
Context-aware database AI assistant, tool execution guardrails, streaming responses, and Apple Intelligence local processing.
Dialect-Aware AI Chat & Automated Tools
The AI Assistant opens as a right-hand inspector attached to your active database connection. Answers are automatically informed by active driver dialect and background schema cache metadata.
| Tool Name | Action Performed | Approval Requirement |
|---|---|---|
| propose_sql | Streams proposed SQL query directly into active editor tab. | Real-time stream insertion |
| run_sql | Executes SQL statement against database connection. | Mandatory approval (unless safe SELECT) |
| explain_query | Runs EXPLAIN and parses structured execution tree. | Mandatory user confirmation |
| get_schema | Fetches schema tables, columns, and foreign key structures. | Auto-approved |
| get_sample_rows | Fetches sample row data to inform complex queries. | Opt-in toggle (OFF by default) |
On supported Apple Silicon Macs (M1/M2/M3/M4), enable Use on-device model (Apple Intelligence) in AI panel settings to process queries 100% locally via Apple Foundation Models — ensuring zero network requests leave your machine.
Prompts sent while a turn is actively streaming are added to the queuedMessages array and executed sequentially. Upon stream completion, keyboard focus automatically returns to the prompt field for uninterrupted typing.
6. Workspace Layout, Quick Open & Process Monitors
Multi-window sessions, Quick Open palette (⌘P), tab detaching, split panes, process list, and session recovery.
Press ⌘P anywhere to trigger fuzzy search across connections, tables, views, procedures, saved scripts, and open tabs with instant keyboard jump.
Drag any query or grid tab out of the tab bar to detach into a standalone window (DetachedTabWindow). Split editor and grid views horizontally or vertically with draggable dividers.
Inspect active server process lists (ProcessListView). Filter by Session ID, User, Command, or State, and terminate stuck queries with Kill Process.
7. Licensing, Free Core App & AI Credits
100% Free core desktop client, 14-day AI trial (1M tokens), and Pay-As-You-Go AI credit top-ups.
Free Core Client & Flexible AI Top-Ups
BerryDB is completely free for local database management. All 6 drivers (PostgreSQL, MySQL, SQLite, Mongo, DynamoDB, Qdrant), SQL editors, streaming data grid, ChangeSets, and SSH tunneling require no subscription.
AI Assistant chat tools use a flexible Pay-As-You-Go credit model ($2, $5, $10, $20 top-ups). You only pay for what you consume per token, or use local Apple Intelligence for $0.
macOS Keyboard Shortcuts Cheatsheet
Boost your workspace productivity with native macOS hotkeys.