Skip to main content
The gateway connects to your database from wherever it runs. Midplane Cloud never does, so the database needs no public address. Using Supabase, Neon, Amazon RDS or Railway? Follow its guide instead:

Supabase

Neon

Amazon RDS

Railway

Create a role for the gateway

Recommended, not required: the gateway works with any role that can log in, and Midplane’s policy decides what agents may do either way. A role of its own is a second lock. Midplane can narrow what a role may do, never widen it, so whatever the policy allows, Postgres still refuses what the role can’t do. midplane setup warns when a connection string’s role is a superuser, or owns tables or their schema: an owner can drop them whatever its grants. This role can only read. In psql, as an admin, replace the two placeholders and run:
In a web SQL editor, which is already connected to the database, leave out the \connect line.
Repeat the USAGE and SELECT grants for each schema agents should see. The grants cover today’s tables only: for later ones, run ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO midplane_gateway; as the role your migrations use.

Letting agents write

A write needs both locks open. In the policy, set the table to Read + write and Row changes to Allow or Hold (held writes wait for a person’s approval). Then grant the role the same tables, and the sequences behind serial ids:
Without the grant, the policy lets the write through and Postgres refuses it. Schema changes (ALTER, DROP, CREATE INDEX) need the role to own the table, so most setups leave them off.

Write the connection string

On your computer, or on a server at your own URL, midplane setup asks for each database’s connection string, tests it, and saves it in the gateway’s folder: secrets/shop.dsn for the database id shop. On a server behind the relay, or on a platform, it goes in the env file the dashboard shows instead, after its MIDPLANE_DSN_<ID>=. The gateway reads it from there each time it starts, and never saves it. Either way, it’s one line:
  • Host. Use the address the gateway reaches the database at, from where it runs. In a container, localhost is the container itself.
  • Password. Percent-encode @, :, /, ?, # and % in it (@ is %40).

TLS

sslmode=verify-full encrypts the connection and checks the database’s certificate. If your provider signs certificates with its own CA, download it to where the gateway runs, and add its path. In Docker, put it in /etc/midplane/tls on the server: &sslrootcert=/etc/midplane/tls/ca.pem. The commands for My own certificate mount that folder at the same path. With Midplane URL, or an Automatic (Let’s Encrypt) certificate, add -v /etc/midplane/tls:/etc/midplane/tls:ro after each docker run. On your computer, use the file’s full path.
The gateway reads sslmode differently from psql: require, prefer and verify-ca check the certificate just like verify-full. Without sslmode, or with disable, it connects without TLS. sslmode=no-verify encrypts without checking the certificate, which lets a machine in the middle read the connection: use it only on a network you trust.

Check that it connects

Setup tests each connection string as you give it. From an env file, the gateway tests each one as it first starts, in its log. Either says ok with the database and its number of tables, or why not, such as password authentication failed (28P01): look up the code in troubleshooting. Once the gateway enforces a policy, the Gateways page lists each database as it reports it, such as shop · reachable · catalog read: 12 tables, and Test connection there shows each id with ok, such as shop ok, 3 ms.