Database Connections

  • Desktop, mobile and web
  • All plans

What it does

Save your MySQL / MariaDB, PostgreSQL, SQL Server, MongoDB, SQLite and Google BigQuery 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, and a Google Cloud SQL instance through the Cloud SQL Auth Proxy, started with your own gcloud login. Agents get the same connections over MCP, by name, and never see the password; they only read unless you turn on Allow agents to write on a writable connection. Guardrails are on by default: every connection is read-only when created, agent writes are off, 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 (not on SQL Server, SQLite or BigQuery).

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), scope (this project only or every project of your account), Reach through (Direct connection, Google Cloud SQL for MySQL / PostgreSQL, or one of your SSH / AWS SSM connections; it comes before host and port because Cloud SQL replaces them), host, port, user, optional Database (the default one the tab opens on; once it is filled in, Only show this database hides the server's other databases), Password (typed once, kept in the OS keychain; leave it blank on a new connection when the server needs none, such as a local PostgreSQL in trust mode), Allow agents to write (off), Read-only connection (on), This is production, Require TLS, description. Test connection checks host and credentials without opening a tab. SQL Server (since 2026-11-08, also Azure SQL and Amazon RDS for SQL Server): default port 1433, SQL login (user and password); leave Database empty to land on master and list every database you may open. Turn on Require TLS for Azure SQL. Engine-specific fields: Default schema (PostgreSQL), Authentication database and Replica set (MongoDB). MongoDB Atlas: paste the whole mongodb+srv:// connection string into Host and it is split into host, user, password, database and TLS (a <password> placeholder is ignored), or type just the cluster host name. SQLite (since 2026-11-02): pick the engine, then type the path in Database file or click Browse…; host, port, user, password, default database, tunnel and TLS disappear because a local file has none of them. Test connection says if the file is there and really is a SQLite database. BigQuery (since 2026-11-09): pick the engine, then Project ID (the Google Cloud project that runs and pays for the queries), optional Default dataset, and Max billed per query (GiB); there is no host, port, user, password, tunnel or TLS. The login is your own Google one: run gcloud auth application-default login once in a terminal, nothing is stored in AgentsRoom or in the keychain. Test connection runs a free dry run in the project. In the tree a database is a dataset. Opening a table is free (rows in storage order, read-only, no search or sort); searching or sorting means writing a query in the editor, which is billed.
  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). The tab opens on the connection's default database and scrolls the tree to it, however long the list. Switching to another project and back brings the tab back on the same database, table, mode and typed statement (a database that would not open is not remembered: it comes back on the last one that did). 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.
  • Allow agents to write (per connection, in its form, off by default): "Agents can run writes immediately on this connection. Enable this only when you trust them with its data." It only takes effect if Read-only connection is also off. It is saved with the connection metadata, so it follows the connection to your other machines.
  • onlyDefaultDatabase (per connection, Only show this database under Database in its form, off by default, shown once a database is filled in): lists that database and no other, in the tree, on the phone, in the export and import pickers and for agents (db_schema). Follows the connection to your other machines. A display choice, not a permission: the server still decides what this user can open.
  • maxBytesBilled (per connection, BigQuery only, Max billed per query (GiB) in its form, empty = 1 GiB): the most one query may bill. Above it BigQuery refuses the query instead of charging it. Anything under 10 MiB is raised to 10 MiB (BigQuery bills at least that per table read). Stored in bytes, follows the connection to your other machines, and agents can set it with db_connection_save (on an existing connection an agent can only lower it, never raise it, since 2026-11-10).
  • verifyServerCertificate (per connection, PostgreSQL and SQL Server, Trust the server certificate under Require TLS in its form, shown on a direct connection with TLS): since 2026-11-09 a direct connection with Require TLS checks the server's certificate, so nobody on the network (public Wi-Fi, a proxy) can pose as the server and collect the password. Unticked by default on a new connection (verifyServerCertificate: true); ticked on connections saved before that date, which keep working exactly as before. Tick it only for a server with a self-signed certificate you trust. Through an SSH / SSM tunnel or Google Cloud SQL the certificate is not checked (it names the real host while the app talks to 127.0.0.1) and the box is hidden. Follows the connection to your other machines; agents set it with verifyServerCertificate in db_connection_new / db_connection_save (a new connection gets true unless they pass false; on an existing connection an agent can turn the check on, never off). MySQL and MongoDB already checked the certificate on a direct connection. Since 2026-11-10, Export, Import and copy follow the same rule as the connection (PostgreSQL and MySQL / MariaDB tools): a direct connection with Require TLS refuses a server whose certificate cannot be verified, with the same message.
  • Read-only, production, TLS and tunnel (or Google Cloud SQL, with Private IP and IAM database authentication) are per connection, in its form.

Agent tools (MCP)

  • db_list: the saved connections, metadata only (engine, host, port, user, default database, onlyDefaultDatabase (a SQLite connection has its file path in host, no port, user or password), read-only, agent-writes and production flags, tunnel, scope, whether a password is stored).
  • db_schema: schemas (only the connection's database when Only show this database is on); with a database, its tables and views; with a table, its columns, types, nullability, keys and defaults. No SQL needed.
  • db_query: exactly one statement per call, rows capped (200 by default, 5000 at most). Optional database runs the statement in that database of the connection (the names db_schema lists), otherwise the connection default; this is how a server-level connection with no default database reaches every project database. Reads always run. On BigQuery the answer carries bytesProcessed (what the query read, so what it billed), and the read path accepts only what BigQuery itself reports as a SELECT. A write runs only when the connection has Allow agents to write on AND is not read-only; otherwise it is refused with the switch to change. An allowed write runs immediately, with no confirmation dialog and no extra step for a production connection, so agents are told to write only when you asked for the change.
  • db_connection_new: proposes a connection by opening the creation form pre-filled; you review, type the password and save. Nothing is stored otherwise. The form opens on the agent's project scope (scope: "global" preselects every project) and on the engine the agent named (engine); you can change both before saving.
  • db_connection_save / db_connection_delete (behind agentConnectionWrites): write, update or remove a connection outright. id updates an existing connection, and an update only changes the fields the agent sends: engine, port, tunnel, read-only and production flags and scope keep their saved value, Allow agents to write is never changed by an agent, and an agent can only tighten the certificate check (verifyServerCertificate) and the BigQuery cap (maxBytesBilled), a weaker value keeps the saved one; engine picks mysql, postgres, sqlserver, mongodb, sqlite or bigquery (for sqlite, host is the full path of the file and nothing else is needed; for bigquery, host is the project ID, database the default dataset and maxBytesBilled the per-query cap in bytes); scope is project (the default for a new connection) or global; the password is a vault secret NAME, never a value. A delete also drops the stored password and is carried to your account, so the connection does not come back on the next sync.
  • db_folders_get / db_folders_apply (since 2026-10-26): read and reorganise the folders of the Databases list, same contract as ssh_folders_*: one all-or-nothing batch of folder creations and moves, saved and synced like a drag in the list. No connection setting is touched.

Providers

All providers, no difference. The agent write check lives in the desktop app, not in the MCP process, so an agent cannot bypass it by replacing its MCP server.

Mobile

Yes: the Databases sheet lists the connections (same read-only, production and tunnel badges) and opens a read-only console (even when agent writes are allowed on the desktop) (collapsible schema tree, editor, grid). Tap a database to pick it (the console opens on the connection's default database, scrolled to it, or on the only one the server has; Only show this database, set on the desktop, applies here too): 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. On a BigQuery connection the tap only writes that read in the editor without running it, because it would be billed. 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. Since 2026-10-30, a search field at the top of the sheet ("Search a connection (name, host, user, database)") narrows the list as you type, like on the desktop; folded folders open while you search so no match stays hidden, and an empty result says "No matching connection".

Limits

  • Engines: MySQL / MariaDB, PostgreSQL, SQL Server, MongoDB, SQLite, Google BigQuery. Oracle and others are not supported, ask on the public backlog.
  • BigQuery: sign-in through Application Default Credentials only (no service-account key field). Every query is billed by Google on the bytes it reads, and LIMIT does not reduce that. No Export, Import or copy (BigQuery exports to Cloud Storage itself). Rows in the grid are read-only, in storage order, with no search or sort. One statement per call: BigQuery scripts are refused. A BigQuery connection does not appear on a computer still running an older version of the app until that computer is updated.
  • SQL Server: SQL logins only (user and password); Windows / Active Directory and Microsoft Entra sign-in are not offered. No Export, Import or copy. T-SQL needs no semicolon between statements, so a read that contains a write word anywhere (EXEC, SET, INTO, DECLARE, BEGIN...) is treated as a write: it asks for confirmation, or is refused on a read-only connection. Every read runs inside a transaction that is rolled back. A connection saved with SQL Server does not appear on a computer still running an older version of the app until that computer is updated.
  • SQLite: an existing file on this computer, never created for you (an empty file is fine). No Export, Import or copy, since the database already is a file you can copy. ATTACH and VACUUM INTO are refused, so a connection only touches its own file. No SSH or Cloud SQL route, so a SQLite file on another machine is not reachable: run the agent or the app there. A statement that runs longer than 5 minutes is stopped and rolled back. Encrypted files (SQLCipher) are not readable.
  • 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, and so does the order of the list (Live settings sync and Machines). The password stays in the keychain of the machine where you typed it (the card then shows "Password needed: no password is stored on this computer for this connection") unless you turn on Synced Passwords (Settings > Account > Synced passwords, since 2026-10-02), which carries it end-to-end encrypted; the checkbox Sync this password to my other computers under the password field keeps one password local.
  • 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 (and the Cloud SQL Auth Proxy port) is bound to the local loopback only.
  • Google Cloud SQL needs cloud-sql-proxy (v2) and, for List my instances, the gcloud CLI on the computer. Not offered for MongoDB.
  • 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 a dashboard read my database without copying data into a file? Yes: turn on Live data for HTML views in Project settings > Capabilities & permissions and switch on the connection there. An HTML file of the project then calls window.agentsroom.query, read-only. See Live Data for HTML Views.

  • "The server's TLS certificate could not be verified": what do I do? (since 2026-11-09) A direct PostgreSQL or SQL Server connection with Require TLS now refuses a certificate it cannot verify (self-signed, expired, or issued for another host name), to protect your password. If the server is yours and uses a self-signed certificate you trust, open the connection's form and tick Trust the server certificate under Require TLS. Managed services (Azure SQL, Amazon RDS, a public Cloud SQL address) have a valid certificate and connect as they are. Connections saved before that date keep the box ticked and are not affected.
  • Can my agent write to my database? Only if you allow it, per connection: turn off Read-only connection and turn on Allow agents to write in its form (since 2026-10-05). Its writes then run immediately through db_query, one statement per call, without the confirmation you get in the console. With either switch in its default state, the agent can only read.
  • 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.
  • An agent updated a connection and it lost its engine, its tunnel or its production flag. Fixed on 2026-10-19: an agent's update now only changes the fields it sends, keeps the scope, and never touches Allow agents to write. A field an older version already reset has to be set again in the connection's form.
  • 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.
  • How do I reach a Google Cloud SQL instance? (since 2026-10-15) In Reach through, pick Google Cloud SQL, then type the Instance connection name (project:region:instance) or click List my instances (read with your gcloud login). AgentsRoom starts the Cloud SQL Auth Proxy (cloud-sql-proxy, to install with gcloud components install cloud-sql-proxy) on a loopback port when the connection opens, with your Application Default Credentials: no key is stored. Private IP connects to the instance's private address (this computer must reach its VPC). IAM database authentication signs in with your Google account, so the password field disappears; the user is your IAM database user. If the login has expired, the error tells you to run gcloud auth application-default login. Host, port and TLS are not used on this route. Agents set it with cloudSqlInstance, cloudSqlPrivateIp and cloudSqlIamAuth in db_connection_new / db_connection_save.
  • My PostgreSQL connection lists every database of a shared server, and opening one says no pg_hba.conf entry. PostgreSQL shows all the databases of a server to any user, and refuses the ones you may not use when you open them. Fixed on 2026-11-05: the tab opens on your default database and scrolls to it, a database you cannot open says so under its own row (with Back to your database), and databases whose access was revoked with REVOKE CONNECT are no longer listed. Refusals set in the server's pg_hba.conf cannot be read from a connection, so to hide the rest, open the connection's settings and turn on Only show this database.
  • No table opens on my old PostgreSQL server (9.6), but queries work. Fixed on 2026-11-05: the Data mode and db_schema read the columns of PostgreSQL 9.6 again. When a table cannot be read, the grid shows the error instead of "This table is empty".
  • Does "Only show this database" stop my agents from reaching another database? No. It only shortens what is listed. An agent, or a statement, can still name another database; the server decides. To restrict access, use the database user's own rights.
  • My connection has no default database, can my agent still read each database? Yes (since 2026-10-08): it passes the database name to db_query, so one server-level connection serves every project database.
  • My MongoDB Atlas connection fails with getaddrinfo ENOTFOUND. Fixed on 2026-10-26: an Atlas host name (cluster0.abc12.mongodb.net, the host of a mongodb+srv:// string) has no address of its own, only SRV and TXT records. AgentsRoom now detects it and resolves those records itself, so the cluster members, authSource and replicaSet come from Atlas and the Port is ignored. Nothing to change on a saved connection. A shard host typed by hand as a workaround keeps working. Through an SSH or SSM tunnel, use one member host instead: a tunnel forwards a single host and port.
  • Can I connect to SQL Server or Azure SQL? Yes, since 2026-11-08, on macOS, Windows and Linux, with nothing to install. In New connection, pick SQL Server, then host, port (1433), user and password, directly or through one of your SSH / AWS SSM connections in Reach through. The password stays in the OS keychain. Tables outside dbo show as schema.table. Agents use it through db_list, db_schema and db_query with the same guardrails: read-only by default, agent writes off, production flag.
  • Can I connect to Google BigQuery? Will it cost me money? Yes, since 2026-11-09, on macOS, Windows and Linux. Run gcloud auth application-default login once, then in New connection pick BigQuery and type the Project ID; no key or password is stored. Queries are billed to that project by Google, so every connection has Max billed per query (GiB), 1 GiB by default: a query that would bill more is refused instead of charged. Opening a table in the grid is free. The bytes a query read are shown next to its result, and agents see them as bytesProcessed.
  • Can I open a SQLite database? Yes, since 2026-11-02, on macOS, Windows and Linux, with nothing to install. In New connection, pick SQLite and choose the file. Its tables show in the tree under main, you run SQL in the console (Cmd/Ctrl+Enter), and agents use it through db_list, db_schema and db_query like any other connection. It starts read-only like every connection: the file itself is then opened read-only. To write, turn off Read-only connection; for agents, also turn on Allow agents to write. A file under your home folder is saved as ~/..., so the connection also works on your other computers if the file sits at the same place there; otherwise the app says "SQLite file not found on this computer" and you pick that machine's file.
  • Why is my SQLite file "not a SQLite database, or it is encrypted"? The app checks the first bytes of the file. A SQLCipher file, or a file that only has a .db extension, is refused before anything runs against it.
  • Do my agents see the password? Never: they name a connection, the app runs the statement.
  • My search shows folders that hold nothing. Fixed on 2026-10-29: while you type in Search a connection (name, host, user, database), a folder without a matching connection is hidden, and nothing matching at all shows the no-result message instead of a list of empty folders. Same change in the Servers, Commands, Secrets and Kubernetes lists; a scope filter alone still keeps your empty folders visible.
  • 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.
  • A database an agent just saved did not appear in my detached window. Fixed on 2026-10-28: every window re-reads the saved connections as soon as one is written, whoever wrote it, so a detached window no longer has to be reattached to see it.