Database Connections

  • Desktop, mobile and web
  • All plans
View as MarkdownFeature page

What it does

Save your MySQL / MariaDB, PostgreSQL and MongoDB connections once and open them as a tab next to your terminals: schema tree on the left, a statement editor, a result grid, plus a Data mode to browse and edit rows. A database in a private subnet is reached through one of your saved SSH or AWS SSM connections, by a port tunnel opened on demand. Agents get the same connections over MCP, read-only, by name, and never see the password. Guardrails are on by default: every connection is read-only when created, one statement per call, capped result sets, and a "production" flag that hardens every write confirmation. You can also export a database to a file, import a dump, or copy one database onto another of the same engine.

Where to find it

  • Inside a project, the terminal bar: Databases ("Browse your SQL connections, directly or through a tunnel"). The room dock: Commands & connections, then the Databases tab of the modal (Commands · Servers · Databases · Secrets).
  • Command palette (Cmd K / Ctrl K): saved connections are a source.
  • Phone: the Databases sheet of the project.

How to use it

  1. New connection: name, Engine (fixed once saved), host, port, user, optional default database, Password (typed once, kept in the OS keychain), Reach through (Direct connection, or one of your SSH / AWS SSM connections), Read-only connection (on), This is production, Require TLS, description, scope (this project only or every project of your account). Test connection checks host and credentials without opening a tab. Engine-specific fields: Default schema (PostgreSQL), Authentication database and Replica set (MongoDB).
  2. Open: the tab has three modes, Data (open a table: search every column, sort, page, hide or pin columns, double-click a cell to edit on a writable connection, New row, Delete), SQL (or Query for MongoDB) and the schema tree (filter, refresh, Keep this table on top, row estimates, sort by name or size). Double-clicking a table pre-fills a SELECT ... LIMIT 50 without running it; the empty tab also offers Write SQL instead (Write a query instead on MongoDB). Switching to another project and back brings the tab back on the same database, table, mode and typed statement. The tab also has a menu (the three-dot button in its header, or a right-click anywhere in the pane) with Data, SQL (Query on MongoDB), Show this pane alone, Connection settings and Close this connection; when an editable table is open in Data mode, its first entry is New row.

Adding a row: New row opens an insert form at the top of the grid; fill the cells (auto for a generated value, NULL for an empty one), then press Enter or Insert this row, or simply click anywhere else: both open the confirmation "Insert a row into <table>?" and nothing is written until you confirm. A form you left empty closes on its own, without a dialog. 3. Type a statement and press Cmd/Ctrl+Enter (Run). A read runs at once. A write on a read-only connection is refused ("This connection is read-only"); on a writable one it asks "Run this write?" naming the connection, and in production it makes you type the database name for the irreversible cases. A script with several statements runs them in order and stops at the first error, one result tab per statement. 4. Saved queries: save a statement for this Connection, this Project or your whole Account; loading puts it in the editor, never runs it. 5. Describe the query you want (AI assistant above the editor): describe it in your words, the model writes a read-only statement into the editor; you read it and run it yourself. Only the schema shape is sent, never data. 6. Export (structure and data, routines, gzip), Import (from a dump file or from another saved connection, with Back this database up first on by default and Replace the database off by default). Transfers run in the background and notify when done. 7. The tab's bell, Notify me if it drops, warns you when a connection is lost (dead tunnel, sleeping machine).

Settings

  • mysqlClientDir, postgresClientDir, mongodbClientDir (global): folders holding the engine's client tools (mysqldump / mysql, pg_dump / psql, mongodump / mongorestore) used by export, import and copy. Set when the app says "Client tools not found" (Choose the folder…).
  • agentConnectionWrites (global, Agents can manage connections, Settings > AI providers, ON by default): agents may save, update and delete database (and SSH) connections on their own through db_connection_save / db_connection_delete, with no form for you to review. The password is never accepted as a value: the agent names a secret of your vault (passwordSecret) and the desktop copies it into the keychain, so nothing appears in a conversation. Turn it off and an agent can only propose a connection through the pre-filled form.
  • Read-only, production, TLS and tunnel are per connection, in its form.

Agent tools (MCP)

  • db_list: the saved connections, metadata only (engine, host, port, user, default database, read-only and production flags, tunnel, scope, whether a password is stored).
  • db_schema: schemas; with a database, its tables and views; with a table, its columns, types, nullability, keys and defaults. No SQL needed.
  • db_query: exactly one read statement, rows capped (200 by default, 5000 at most). Writes are refused whatever the connection allows a human to do.
  • db_connection_new: proposes a connection by opening the creation form pre-filled; you review, type the password and save. Nothing is stored otherwise.
  • db_connection_save / db_connection_delete (behind agentConnectionWrites): write, update or remove a connection outright. id updates an existing connection; engine picks mysql, postgres or mongodb; scope is project (default) or global; the password is a vault secret NAME, never a value. A delete also drops the stored password.

Providers

All providers, no difference. The read-only rule for agents lives in the desktop app, not in the MCP process.

Mobile

Yes: the Databases sheet lists the connections (same read-only, production and tunnel badges) and opens a read-only console (collapsible schema tree, editor, grid). Tap a database to pick it (the console opens on the connection's default database, or on the only one the server has): it is the database every statement runs against, and it is named above the editor. Tap a table to open it: its first 50 rows are read and shown, and the tree folds away to leave room. The SELECT pill next to a table only writes that statement in the editor, like the double-click on the desktop. Typing USE name (alone or before other statements) picks the database too. No connection form on the phone, and the password never reaches it.

Limits

  • Engines: MySQL / MariaDB, PostgreSQL, MongoDB. SQL Server, Oracle, SQLite and others are not supported; ask on the public backlog.
  • A tunnel needs key or agent authentication on the SSH connection ("A tunnel cannot use password authentication"), or an entry imported from ~/.ssh/config.
  • Connection metadata syncs with your account; the password stays in the keychain of the machine where you typed it ("Password needed: this connection came from another machine").
  • The engine of a saved connection cannot be changed, and copy works only between databases of the same engine.
  • Editing rows needs a primary key on the table.
  • AI assistant quota per month: 5 on Free, 100 on Plus, unlimited on Pro and Team (a guest gets one try).
  • The tunnel port is bound to the local loopback only.
  • A database tab is not reopened after relaunching the app, even with session restore: it has no terminal to bring back. Saved connections and saved queries do survive; reopen the tab from Databases.

Common questions

  • Can an agent write to my database? No. db_query only runs reads. Making a connection writable unlocks writes for you in the console, each one confirmed.
  • Can an agent add a connection? Yes: by default it can save, update and delete them on its own (db_connection_save, on by default since 2026-10-01), the password being copied from a vault secret it only names. Prefer the reviewed path (db_connection_new opens the pre-filled form) when you would rather decide each one; turn Agents can manage connections off (Settings > AI providers) to keep only that reviewed path.
  • How do I reach a database in a private subnet? Pick an SSH or AWS SSM connection in Reach through. See RDS through AWS SSM for the AWS case.
  • Do my agents see the password? Never: they name a connection, the app runs the statement.
  • Why "Client tools not found" on export? The engine's own tools ship with the database, not with AgentsRoom. Install them or point at their folder.
  • Can I run several statements at once? In the console, yes (sequentially, stop on first error). Over MCP, one statement per call.
  • Can I USE a database from my phone? Yes: USE name picks the database for the statements that follow, and the tree follows. The phone still only runs reads, so any other statement that is not a read is refused with a pointer to the desktop console.
  • I typed a new row and clicked elsewhere, was it lost? No. Since 2026-09-16, clicking outside the insert form asks for the INSERT confirmation exactly like Enter. Only a row with nothing typed in it closes silently.

Related