Postgres replicas
A second copy of one database, on a different server, that you can read. Writes stay on one copy until you switch them, or until that server goes quiet. The two databases talk over the network this database already uses.
This is streaming replication. The replica is a hot standby. It is not a dump you download, and it is not a second bill for a cloud disk. It is a second reservation of the same size, on another server. A 10MB database with a replica reserves 20MB, and the account is charged for 20MB. Start from nothing if the first database is not up yet. Tailscale, Headscale, and OpenVPN all carry the copy. The replica joins the same network as the original.
What you get
- A database named
name-replica, beside the one you already have. It shows on the server that holds it, the same way any other database does. - Two connection lines. One takes writes. The other is for reads. Both are Postgres on port 5432, TLS, on the network this database uses.
- A button that moves writes to the other copy. You can switch back the same way.
- Automatic failover when the server that takes writes stops checking in, or Postgres on it stays down while it should be running. The page keeps a log of the time and whether the switch worked. That log is not a migration history.
- Snapshots of both copies. Asking for one requests the other too. A nightly snapshot follows both.
The tailnet does the carrying
On OpenVPN, both copies use the profile saved for this database. Each one gets its own address on that VPN. The replica dials the original there. The profile’s default route is not installed, so the machine’s other traffic stays where it was.
On a tailnet, Nandling does not open a public path between the two servers. The primary publishes Postgres on its tailnet address. The replica dials that address and pulls the write-ahead log. Your ACL is what allows it. If the ACL does not let the replica reach the primary on TCP 5432, the copy does not start.
Nandling does not open a public path between the two servers. The primary publishes Postgres on its tailnet address. The replica dials that address and pulls the write-ahead log. Your ACL is what allows it. If the ACL does not let the replica reach the primary on TCP 5432, the copy does not start.
A reader uses the same rule. The laptop, or whatever opens the replica, has to be allowed to reach the replica on TCP 5432. A rule that lets tag:nandling reach tag:nandling on 5432 covers the replica and your own machines, once both databases are tagged. The connect page is the short version. Tailscale’s ACL reference is the long one. Headscale uses its own policy file, with the same idea: the replica host may open 5432 on the primary host, and your devices may open 5432 on the replica.
Each database is its own machine on the tailnet. The replica does not borrow the original’s address. MagicDNS gives it a name when the tailnet has MagicDNS on. verify-full waits for that name. require encrypts without checking the name.
If a machine is only connected through a relay, the copy still runs. It is slower, and the replica can lag. The database page says when a connection is relayed.
The second provisioning key
A provisioning key is only the first registration. After a database has joined, the server keeps that registration. Nandling does not ask for a key that lasts forever, and it does not mint a new one when a database moves.
A second host is a new registration. The key the original already used cannot register the replica, unless that key was created to allow more than one host. On the database page, Replica asks for a key for the replica alone. Paste that key there. Leave the field blank later. Blank does not erase a key that is already saved.
- Reusable, so the replica can join, and so you can replace the key if you ever need to.
- Tagged
tag:nandling. - Not ephemeral. An ephemeral node disappears when it stops, and the address goes with it.
- Pre-approved, so the replica can come back on its own.
Tailscale’s screen is Settings, then Keys. The auth key guide covers the same choices. Headscale’s preauth keys are the same idea: one key for the original, a second key for the replica, both allowed to be the tag you already use. The Headscale page is the rest of that setup.
The replica can be read as soon as it has an address. Use the replica’s connection line, not the original’s. Writes sent to the replica are refused. Postgres is in hot standby there.
Adding the replica
- Open the database. Replica is a tab at the top.
- Confirm the tailnet ACL lets that second machine open TCP 5432 on the first, and lets you open TCP 5432 on the second.
- Create a second provisioning key, as above.
- Paste it and choose Add a replica.
The replica reserves the same size as the original. A 10MB database becomes 20MB reserved, because there are two 10MB copies. An account that cannot assign that second 10MB is told so, and nothing is created. The reserve is capacity on a server, not empty space in a cloud disk. The included 10MB, when the account has it, can cover one copy. It does not cover both.
Postgres on the original restarts once, so it can send its log. Connections drop for that restart and come back. The first copy then runs over the tailnet.
Postgres on the original restarts once, so it can send its log. Connections drop for that restart and come back. The first copy then runs over the tailnet. Until that copy finishes, the replica is not a failover target. The page says so.
Reads, writes, and the switch
One copy takes writes. The other serves reads. The Replica tab shows both connection lines, and which one is which. The user and the password are the same, because the replica is a copy of the original.
Switch writes to the other copy promotes the replica. The server that had the standby keeps those files and becomes the one that takes writes. Its name becomes the original name. The other server becomes name-replica. The addresses do not swap. Use the connection line the page shows after the switch. Clients that had the old write address need the new one.
You can switch whenever you want, including when both servers are running normally.
Automatic failover
The controller watches the server that takes writes. If that server has not checked in for a few minutes, or Postgres there is down while the database is supposed to be running, the replica takes writes. The replica has to be up, and it has to have a tailnet address.
The controller watches the server that takes writes. If that server has not checked in for a few minutes, or Postgres there is down while the database is supposed to be running, the replica takes writes. The replica has to be up, it has to have a tailnet address, and it has to have finished its copy. If it has not, nothing switches, and the log says why.
The log on the Replica tab is the time and the result. Succeeded means writes moved. Did not switch means they stayed, and the sentence says why.
After a failover, the new replica copies again from the server that now takes writes. That rebuild is how the old primary becomes a standby.
After a failover, the new replica copies again from the server that now takes writes. That rebuild is how the old primary becomes a standby. It is not written as a migration.
Snapshots
Snapshots are something you turn on for a database. On its page you ask for one, or you turn on a nightly snapshot. Five you ask for, and seven nightly ones, are kept for that database. They are encrypted, they stay on the backup server, and they cannot be downloaded. The quick start explains the keys. A snapshot does not switch writes.
Loading a snapshot can replace the database you pick, or it can open a new database and start there. The new one follows the same rules as any database you create. It does not promote a replica. Promotion is the switch, or the automatic failover.
Quick start · Headscale · ACL · Extensions