# Database Connections > 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. - Area: Desktop, mobile and web - Plans: All plans - Last checked against the product: 2026-10-01 - Web page: https://agentsroom.dev/docs/database-connections ## 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 ?" 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](https://agentsroom.dev/docs/rds-ssm-tunnel.md) 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 - [SSH Connections](https://agentsroom.dev/docs/ssh-connections.md): the tunnels a connection can be reached through. - [RDS through AWS SSM](https://agentsroom.dev/docs/rds-ssm-tunnel.md): Amazon RDS without a bastion. - [Secret Manager](https://agentsroom.dev/docs/secret-manager.md): where the password lives. - [Dev Terminals](https://agentsroom.dev/docs/dev-terminals.md): the tab strip the console lives in.