Connect Your Application to a Managed Database

Databases on Vertra Cloud require TLS and a client certificate: a password alone never connects. This guide takes an application from “no database” to a verified connection, with the secrets kept out of your code.

Before you start

A plan that fits an application and a database: Starter 1’s 1,024 MB is enough for a database alone, but an application plus PostgreSQL, MongoDB or MySQL needs Starter 2 or above. With Redis, Starter 1 is enough.

Enough free RAM: 1,024 MB for PostgreSQL, MongoDB and MySQL; 512 MB for Redis. The application’s memory comes out of the same plan total.

Step by step

Create the database

In the dashboard, click New Project, choose Database and pick the engine. It’s ready when its status turns Online.

Collect host, port and password

All three are on the database page. The port is unique per database: never assume 5432, 27017, 6379 or 3306.

Download the certificates

In the Certificates tab, download these three files and rename them to something stable:

Downloaded	Rename to	Role
`certificate-<id>.ca.pem`	`certs/db.ca.pem`	CA file: verifies the database’s server certificate
`certificate-<id>.crt`	`certs/db.crt`	client certificate (not the CA)
`certificate-<id>.key`	`certs/db.key`	client key

The .pem and .p12 are for MongoDB and Prisma 6; see what each file is. If your database has no .ca.pem, download the .pem and use it as the CA file.

Ship the certificates with the application

Put the certs/ folder in the project you upload. If you deploy from GitHub, add certs/ to .gitignore and upload the folder through the application’s Files tab instead: the key authenticates as you and must never live in a repository.Deploying a template with a database skips this: the certificates and variables are wired into the application for you.

Store the credentials as environment variables

In the application’s Settings → Environment variables tab, add:

DB_HOST=<host>
DB_PORT=<port>
DB_PASSWORD=<password>

Restart the application so the process sees them.

Connect

Read everything from the environment. PostgreSQL with Node.js:

const fs = require('fs');
const { Pool } = require('pg');

const pool = new Pool({
  host: process.env.DB_HOST,
  port: Number(process.env.DB_PORT),
  user: 'vertracloud', // older databases: the user shown on the database page
  database: 'vertracloud',
  password: process.env.DB_PASSWORD,
  ssl: {
    ca: fs.readFileSync('certs/db.ca.pem'),
    cert: fs.readFileSync('certs/db.crt'),
    key: fs.readFileSync('certs/db.key'),
    rejectUnauthorized: true,
  },
});

pool.query('select 1').then(() => console.log('database ok'));

The same pattern for Python, MongoDB, Redis and MySQL is on the Databases page.

Test from your machine first

The connection works the same from your computer, which is the fastest way to tell a code problem from a credential problem:

psql "host=<host> port=<port> dbname=vertracloud user=vertracloud password=<password> sslmode=verify-full sslrootcert=certs/db.ca.pem sslcert=certs/db.crt sslkey=certs/db.key"

Use Drizzle Kit and Drizzle Studio

Drizzle Kit connects with the same three files, but drizzle.config.ts only accepts the ssl object together with host/port credentials, not with url. Keep the connection URL in DATABASE_URL, point three variables to the certificate files, and split the URL in the config:

.env

DATABASE_URL=postgresql://vertracloud:<password>@<host>:<port>/vertracloud
DATABASE_SSL_CA=./certs/db.ca.pem
DATABASE_SSL_CERT=./certs/db.crt
DATABASE_SSL_KEY=./certs/db.key

drizzle.config.ts

import "dotenv/config";
import { readFileSync } from "node:fs";
import { defineConfig } from "drizzle-kit";

const url = process.env.DATABASE_URL;
if (!url) throw new Error("drizzle.config: set DATABASE_URL");

function readCert(name: string): string {
  const path = process.env[name];
  if (!path) throw new Error(`drizzle.config: set ${name}`);
  return readFileSync(path, "utf8");
}

const parsed = new URL(url);

export default defineConfig({
  out: "./drizzle",
  schema: "./src/db/schema/index.ts",
  dialect: "postgresql",
  dbCredentials: {
    host: parsed.hostname,
    port: Number(parsed.port),
    user: decodeURIComponent(parsed.username),
    password: decodeURIComponent(parsed.password),
    database: parsed.pathname.slice(1),
    ssl: {
      rejectUnauthorized: true,
      ca: readCert("DATABASE_SSL_CA"), // certificate-<id>.ca.pem
      cert: readCert("DATABASE_SSL_CERT"), // certificate-<id>.crt
      key: readCert("DATABASE_SSL_KEY"), // certificate-<id>.key
    },
  },
});

Install drizzle-kit, drizzle-orm, pg and dotenv (Drizzle Kit does not load .env on its own, hence the import "dotenv/config"), then open Drizzle Studio:

npx drizzle-kit studio

It prints https://local.drizzle.studio; open it in the browser. The same config serves drizzle-kit migrate, push and pull.

Drizzle Studio connects as the database owner and can edit and delete rows. Point it at a copy, or browse without saving, when the database serves a live application.

What can go wrong with Drizzle:

The page stays on “Connecting to the Drizzle Kit on localhost:4983”, or shows sample tables you never created. The browser is blocking the page from reaching your machine. Safari and Brave do this by default: use another browser, or turn off Brave Shields for the page. In Chrome, allow local network access when asked. The database is not involved.
self-signed certificate in certificate chain. The ca is not the .ca.pem (often the .crt in its place), or a variable is empty and the config fell back to a URL without the files. The config above throws instead of falling back.
key values mismatch. The cert and key are not a pair: check that cert is the .crt and that both come from the same download.
The ssl object seems ignored. A url was passed instead of host/port, or the URL has ?sslmode=..., which overrides the object.

Troubleshooting

Connection refused or timeout

Check the port on the database page and that the database is Online.

self-signed certificate in certificate chain

The CA is missing or is the wrong file. Pass certs/db.ca.pem as the CA: the .crt is your client certificate, not the CA. If the connection string also has ?sslmode=require, it overrides the ssl object in Node.js pg; drop it from the URL.

key values mismatch

The client certificate and key are not a pair. Use the .crt as the certificate (not the .ca.pem) and take both from the same download: after Reset Certificates, the old files stop working, so download all of them again and redeploy them.

connection requires a valid client certificate

TLS is on but the .crt and .key were not sent. Pass both, besides the CA.

Authentication failed

Copy the password again; after Reset Password, update DB_PASSWORD and restart the app. An error mentioning user "postgres" means the wrong user: databases created from v26.4.8 on use vertracloud. MongoDB also needs authSource=admin in the URI. On Redis, send the user too (vertracloud): a password alone is rejected on databases created from v26.4.8 on. Check the user in the database’s username.

Hostname/IP does not match certificate's altnames

The certificate is issued for the database host. Connect by the host on the database page, not by an IP address.

ENOENT: no such file certs/db.ca.pem

The path is relative to the process’s working directory, the project root. Check the folder exists in the Files tab.

Every message, with its cause and fix, is in Why does my database connection fail?.

Overview

Bots

Node.js

Python

Other Languages

Guides

Connect Your Application to a Managed Database

Before you start

Step by step

Test from your machine first

Use Drizzle Kit and Drizzle Studio

Troubleshooting

​Before you start

​Step by step

​Test from your machine first

​Use Drizzle Kit and Drizzle Studio

​Troubleshooting

Before you start

Step by step

Test from your machine first

Use Drizzle Kit and Drizzle Studio

Troubleshooting