PostgreSQL connection details and how a service uses them

What this covers

A managed PostgreSQL database is created by the platform rather than installed by you, which means it comes with a host, a port, a database name, a user and a password already set. Your service reaches it using those details, passed in as an environment variable rather than written into your code, so the same build can run against a different database without being changed.

This page is the reference for those details: what each one means, which of them you can look up again later, and where the two common connection failures come from. The steps for creating a database are in how to add a managed Redis or Postgres.

Choosing the PostgreSQL major version

The new-database page has a PostgreSQL version field. It lists the major versions Voroa runs, with the current default already selected, and the version you pick is the version your database is actually created on. If you have no reason to prefer one, leave the default: it is the newest version Voroa offers, and it accepts data imported from every older version on the list.

That last point is the one worth planning around. A PostgreSQL dump only moves upward. A database created on an older major version cannot read a dump taken from a newer one, so if you intend to import an existing database, create yours on a version at least as new as the one your data comes from.

The choice is made once, at creation. The version of an existing database cannot be changed — see upgrading your PostgreSQL major version for what to do instead. On some plans the version is chosen for you rather than offered; the page tells you when that is the case.

The five connection details

Every PostgreSQL database is reached with the same five pieces of information. A connection URL is those five joined into one string, which is why a library that wants a single DATABASE_URL and a library that wants five separate settings are asking for exactly the same thing.

Host. The address of the database inside Voroa. It is an identifier the platform assigns when the database is created, not the display name you chose. The two are different strings and only one of them is an address: a connection that uses the name from your dashboard will not resolve, and the error you get back is usually about the host not being found rather than about the name being wrong.

Port. Copy the port shown on the Connect tab rather than assuming one. Inside the database itself Voroa uses the standard PostgreSQL port and does not change it, so most clients connect correctly with their own default. The public endpoint has a port of its own instead, unique to that database, and you have to state it. Either way the exact value is on the Connect tab.

Database name. A PostgreSQL server can hold several databases. A managed database on Voroa is created with one, and this is its name. Connecting without naming it sends your client to whatever name it defaults to, which is usually your username. That is the source of a “database does not exist” error against a database that is perfectly healthy, and the fix is to name it rather than to investigate the database.

User. The login role your service authenticates as. It is created along with the database and has full rights over it.

Password. The only one of the five that is a secret, and the only one Voroa cannot show you again.

Where to find them

Open the database from your dashboard and go to the Connect tab. It lists the host, the port, the database name and the user at any time, because none of those are secret.

It also shows the connection URL in template form, with the password masked. Read that as the shape of the string your app needs, not as a credential you can use: pasting it as it stands will fail authentication, because the password is not in it and the mask is not a stand-in for one. If a deployment is failing to authenticate, this is worth checking first, because a masked template copied into an environment variable looks completely correct at a glance.

Getting the URL the first time

There are two paths, and which one you are on depends on whether the database is paid.

On a database that is created straight away, Voroa shows the full connection URL, password included, once, on the screen you land on after creating it. Copy it at that moment and keep it somewhere safe, such as a password manager.

On a paid PostgreSQL database, nothing is shown at that point. The database is created pending payment and is only built once the payment completes, so there is no password to show yet and the create screen tells you so. Wait until the database shows Running, then open it and use Reveal connection string to get your credentials. If you were expecting a URL on the create screen and did not get one, you have not missed your only chance – you are simply on this path.

Read that button as issuing rather than retrieving. Revealing does not look up the password that already exists: it sets a new one and shows it once, and the previous password stops working at that moment. The first time, that costs you nothing, because nothing is connected yet. A second time is a credential change: any service already using the database keeps the old password and will fail to connect until you give it the new one and redeploy. So copy it when it appears, and treat a later reveal as the rotation it actually is.

Either way the password is not kept in a form that can be read back, so it cannot be displayed a second time by anyone, including Voroa support.

If the password is lost

The way back is not to look it up but to replace it. On the Connect tab, under Rotate credentials, use Rotate & reveal connection URL: this issues a new password and shows the new connection URL once, in the same way. The previous password stops working as soon as the rotation completes, so update every service that uses it and redeploy, or those services will fail to connect. The section only appears for members whose workspace role allows database configuration; if you cannot see it, someone with that role has to rotate for you.

How a service uses them

Add the connection URL to your service as an environment variable rather than committing it to your repository, and name it what your framework expects – DATABASE_URL is the usual convention for PostgreSQL and most libraries read it with no further configuration. If your framework wants the parts separately, set them as separate variables instead; the values are the same five details either way. See environment variables for the full flow.

The address on the Connect tab

The Connect tab shows the address to use. It has its own port, is created with the database, and is reachable from your own Voroa service, your laptop, pgAdmin, a migration script, or an application hosted elsewhere.

It is TLS-only. Use sslmode=require, because the certificate is generated for your database rather than signed by a public authority.

If your service uses a short internal name

A connection string may name the database by a short internal name rather than the address above. That name works only from a service on the same machine as the database. It keeps working exactly as it is - you do not have to change anything or redeploy - and when you next update the connection string, copy the address from the Connect tab instead.

A database with no external endpoint still shows the short internal name, because that is genuinely the only address it has.

To limit which addresses may reach your database, see connect to your PostgreSQL database from anywhere - and read the warning there about your own services before you set a list.

Next steps

• How to add a managed Redis or Postgres on Voroa
• Connect to your PostgreSQL database from anywhere
• How to add environment variables on Voroa
• Create extra PostgreSQL users for each app or tool
• Managed PostgreSQL on Voroa - what every database includes, and what each size costs.