BerryDB Documentation

BerryDB features an intuitive macOS layout with a collapsible connection sidebar, multi-tab SQL scratchpad, split-pane result grid, and interactive AI assistant sidebar.

Figure 1: Main BerryDB Workspace with Sidebar Schema Catalog, Multi-tab Query Editor, and Inline Results Grid.

Option 1: Official DMG Release (Recommended)

Download for Apple Silicon, macOS 15.0 Sequoia or later:

Option 2: Build From Source with Swift SPM & Makefile

The AppKit NSTableView DataGrid shows rows as they stream in and creates cell views only for the rows on screen. It supports inline cell editing, and table tabs sort and filter on the server (1,000 rows by default).

Figure 2: The DataGrid with inline editing, sticky column headers, and execution metric indicators.

Turn plain English prompts into SQL for PostgreSQL, MySQL, SQLite, and SQL Server. The assistant reads your schema, foreign key relationships, and data types. In cloud mode (free trial, then paid), your questions, the database type, your schema (table and column names) and the results of queries the assistant runs (up to 100 rows each) are sent to BerryDB's AI service; table sample rows are shared only if you turn that on.

Figure 3: AI SQL Copilot Assistant side panel generating complex multi-table JOINs and query fixes.

Claude Code, Codex and Antigravity can read the database schema BerryDB has already cached. They do it through berrydb-mcp, a small helper inside BerryDB.app that the agent starts itself and talks to over standard input and output (an MCP stdio server). The helper answers from the schema metadata BerryDB cached for the connections you add to an MCP project: tables, columns, keys, indexes, relationships and the schema graph. It opens BerryDB's local store read-only, never connects to a database and never reads connection passwords.

Before you start

• Run BerryDB from the Applications folder. Every setup command points at the helper inside the app by its full path. When BerryDB runs from a read-only location such as the mounted disk image, Settings shows “Move BerryDB to the Applications folder and open it from there to set up agents.” instead of commands.
• Open each connection once in BerryDB. Connecting caches its schema, and Database → Refresh Schema updates the cache after the schema changes. Agents see the schema as of that moment, not the live database.
• Production connections are never cached. BerryDB does not cache the schema of a connection while it is marked as production (Production environment in the connection settings, the PROD badge in the sidebar), so agents see no schema for it. A schema cached before the label was set stays.
• SQL and DynamoDB only. PostgreSQL, MySQL/MariaDB, SQLite, SQL Server and DynamoDB connections are cached. MongoDB, Redis/Valkey, Elasticsearch and Qdrant connections are not, so agents see no schema for them.

Set up a project

1. Open Settings (⌘,) and choose the AI Agents tab.
2. Click New Project…, give the project a name and turn on Enabled; new projects start disabled.
3. Under Workspace Folders, click Add Folder… and choose every folder whose code uses these connections. Subfolders and worktrees inside a folder are included. You can skip this if you name the project per repository (below).
4. Under Connections, turn on each connection agents may read.
5. Click Save.

Project names are matched ignoring letter case and surrounding spaces. Settings refuses a name another project already uses or one that has the form of a project ID, and two projects cannot share a workspace folder.

Choose how agents find the project

The project's Agent Setup section shows ready-to-run entries with the helper's path and your project filled in. Copy them from there. The examples below assume BerryDB is in /Applications and a project named Shop API. Every entry is named berrydb. The per-repository and “always this project” entries appear once the project is saved: click Edit… next to it.

# Claude Code
claude mcp add --scope user berrydb -- '/Applications/BerryDB.app/Contents/Helpers/berrydb-mcp'
# Codex
codex mcp add berrydb -- '/Applications/BerryDB.app/Contents/Helpers/berrydb-mcp'
# Antigravity
agy mcp add berrydb -- '/Applications/BerryDB.app/Contents/Helpers/berrydb-mcp'

claude mcp add --scope project berrydb -- '/Applications/BerryDB.app/Contents/Helpers/berrydb-mcp' --project 'Shop API'

[mcp_servers.berrydb]
command = "/Applications/BerryDB.app/Contents/Helpers/berrydb-mcp"
args = ["--project", "Shop API"]

First use: the Keychain prompt

The first time an agent uses BerryDB with a project selected, macOS may ask whether berrydb-mcp may use a key that BerryDB keeps in your login keychain (dev.berrydb.mcp.access-key). Choose Always Allow. The key lets the helper check that the project's settings are the ones BerryDB saved; it is not a database password. Allowing it once lets that one request through, and macOS asks again on the next (Apple's Keychain Access guide). If you deny it, the helper still serves the schema, but berrydb_status reports "integrity": "unavailable".

Check that it works

Start a new agent session and ask the agent to call berrydb_status. A working setup answers with "state": "selected", your project's name, and selected_by:

• explicit: the entry names the project with --project (options 2 and 3).
• roots: a workspace folder the agent reported is inside one of the project's Workspace Folders.
• working_directory: the folder the agent started the helper in is inside one of them.

"integrity": "verified" means the project's saved settings check out. "unavailable" means the key could not be read (see above) or the settings could not be verified; the schema is served either way. If Settings shows “Not verified — save to confirm” next to the project, open it, turn on Enabled and save. live_reads is always not_available.

With "state": "unconfigured", the agent sees only berrydb_status, and reason says why:

An agent can keep the tool list it loaded when its session started. If it does not see BerryDB's tools after you change a project in Settings, start a new agent session. A tool that answers “No schema graph has been harvested for this connection.” needs that connection opened in BerryDB first.

Limits today

• Metadata only. Agents get no rows from your tables and cannot run queries through BerryDB.
• Cached, not live. The schema is the one BerryDB cached when it last connected to, or refreshed, each connection.
• Built from source? make run and make app package the helper into the app. A build that skips that packaging step shows “The berrydb-mcp helper is not bundled in this build.” in Agent Setup.
• Agents. The tools were checked with Claude Code 2.1.294, Codex CLI 0.157.1 and Antigravity 1.3.1. Other MCP hosts may work but are not tested.

Configure direct connections, TLS (with client certificates for PostgreSQL and MySQL), and SSH jump hosts with Ed25519, RSA or ECDSA keys to access private cloud VPC databases safely.

Figure 4: Connection Profile Manager with Host, Port, Authentication, SSL/TLS, and SSH Tunnel tabs.

Inspect and alter columns, default constraints, primary keys, and B-Tree indexes visually without writing manual ALTER TABLE statements:

Figure 5: Table Schema Designer with column types, nullability, defaults, primary keys, and foreign key relations.

Press ⌘E to inspect the execution plan as an expandable tree of operator nodes:

Figure 6: EXPLAIN query plan shown as a tree.

Explore Redis databases (DB 0-15), search keys with wildcard patterns, inspect TTL values, and modify Strings, Hashes, Lists, Sets, Sorted Sets, and Streams directly:

Figure 7: Redis Key-Value Browser with live key filtering, TTL tracker, and data type inspector.

Import CSV files (column mapping, batch size, one transaction) and SQL files; export CSV, TSV, JSON, NDJSON, or SQL INSERT statements:

Figure 8: Import / Export Wizard with format selections, header mapping, and chunked batch writes.

Review past SQL statements with precise execution duration timestamps, rows affected, and one click to open a statement in a new SQL tab:

Figure 9: Query History and Execution Log with execution timing and status badges.

• PostgreSQL (tested on 16): JSONB, real socket cancellation (pg_cancel_backend).
• MySQL (tested on 8.4) & MariaDB: caching_sha2_password (with TLS on) and mysql_native_password.
• SQLite 3: Native C libsqlite3 binding, Write-Ahead Logging (WAL), and zero setup file loading.
• Microsoft SQL Server: T-SQL execution, table alteration, and stored procedure support.
• Redis: Key browser, TTL, and Strings, Hashes, Lists, Sets, Sorted Sets and Streams.
• DuckDB & ClickHouse: Planned, not yet implemented — contributions welcome.

Need assistance, have questions about database drivers, or want to contribute? Connect directly with the Berry Apps team: