Skip to main content
This guide covers how to connect to your PostgreSQL database in Zerops, both from services within the same project and from outside the Zerops environment.

​
Connection Options Overview

Zerops provides several ways to connect to PostgreSQL:
  1. Internal connections - Between services in the same Zerops project (via private network)
  2. Remote connections:
    • VPN access - From your local machine via Zerops VPN
    • Direct IP access - Enables external applications to connect using TLS encryption by opening public ports on IPv6 (available by default) or IPv4 (requires add-on activation if not already enabled)

​
Connection Details

You’ll find PostgreSQL connection details in the service detail page under the Peek access details button (shows hostname, port, user, password, and connection string). The full list of connection-related environment variables is available in the service detail under Environment variables.

​
Connection Parameters

ParameterInternalExternal (TLS)Env Variable
HostnameService hostnamePublic IP addresshostname
Port (primary)54326432 (via pgBouncer)port / portTls
Port (replicas, HA only)5433N/AportReplicas
UserIdentical to hostnameSame as internaluser
PasswordGenerated at creationSame as internalpassword
Connection string (primary)postgresql://${user}:${password}@${hostname}:5432/${dbName}Same format with TLS portconnectionString / connectionTlsString
Connection string (replicas, HA only)postgresql://${user}:${password}@${hostname}:5433/${dbName}N/AconnectionStringReplicas
Database namedbSame as internaldbName
If you’re running PostgreSQL in High Availability (HA) mode, configure your application to route read queries to port 5433. This distributes the load across all replicas, reducing pressure on the primary node and improving overall throughput.
Zerops creates a system user named zps with full privileges for maintenance purposes. Do not delete, change the password, or remove privileges from this user, as it will disrupt Zerops’ ability to maintain the database cluster.
For more information about default PostgreSQL setup, users, and databases, see Manage PostgreSQL Users and Databases.

​
Connect from Services in the Same Project

All services within a Zerops project share a dedicated private network. There are two ways to implement connections between services in the same project:

​
Method 1: Direct Connection Parameters

You can directly use the connection parameters from Peek Access Details: 
host = database1
port = 5432
user = database1
password = ********** (find under Peek Access Details)
For read operations in HA mode, use port 5433 instead of 5432 with the same credentials. For better maintainability, Zerops creates environment variables for each PostgreSQL service that you can use in your application configuration. List of service environment variables is available in Zerops GUI. Go to a PostgreSQL service detail and choose Environment variables. To use variables from one service in another, prefix the variable name with the service hostname and underscore - to access the connectionString variable of postgresql1, use postgresql1_connectionString. For read-only connections (HA mode only), use the connectionStringReplicas variable instead. 
// Using environment variables to connect
const { Pool } = require('pg');

const pool = new Pool({
  connectionString: process.env.postgresql1_connectionString
});

// For read operations in HA mode
const readPool = new Pool({
  connectionString: process.env.postgresql1_connectionStringReplicas
});
For more details on how to use environment variables, and instructions for adding your own custom variables, see the Environment Variables documentation.
Important notes:
  • When changing passwords, update both the database user password and the environment variable separately - they don’t automatically synchronize.
  • While both postgresql:// and postgres:// URI formats are valid, Zerops uses the postgresql:// format. If your software requires postgres://, create a custom environment variable with this format.
  • Do not use SSL/TLS protocols for internal connections. Security is assured by the project’s private network.

​
Connect Remotely

Zerops offers two methods for connecting to your PostgreSQL database from outside the Zerops environment:

​
Method 1: Connect via Zerops VPN

You can securely connect to PostgreSQL from your local workstation via Zerops VPN:
1

Install & set up zCLI

Install and configure zCLI if you haven’t already.
2

Start the Zerops VPN

Start the VPN connection to your project.
3

Get connection details

Use the connection details from Access Details in the PostgreSQL service detail in Zerops GUI.
4

Connect with your tool

Connect using your preferred database client (pgAdmin, DBeaver, psql, etc.).
5

Stop the VPN when finished

Stop the Zerops VPN when you’re done.
Important notes:
  • Do not use SSL/TLS protocols when connecting over VPN. Security is provided by the VPN tunnel.
  • If your connection over VPN doesn’t work, try adding .zerops suffix to the service hostname (e.g., database1.zerops). For additional help, check the VPN troubleshooting page.

​
Method 2: Connect via Direct IP Access

Direct IP Access uses pgBouncer for connection pooling and TLS termination. Internally, port 5432 is available without SSL (and port 5433 for reads in HA mode). Externally, connections are secured with TLS through pgBouncer (port 6432) before being routed to your PostgreSQL service. The read replica port is not available for external connections.

​
Enable external access

1

Navigate to Public Access settings

Navigate to your PostgreSQL service in the Zerops GUI and choose the Public Access through IP Addresses section.
2

Choose IP version

Choose either IPv6 (available by default) or IPv4 (requires the unique IPv4 add-on).
3

Configure ports

Open one or more ports and point them to your PostgreSQL service (the system will direct them through pgBouncer):
  • Choose any port from 10-65435 (except 80 and 443)
  • Select destination service and internal port
  • Each public port can be mapped to any internal service port
  • Multiple public ports can point to the same internal port if needed
  • Port configurations can be set independently for IPv4 and IPv6
4

Enable firewall (optional)

Optionally enable firewall protection for additional security.
5

Publish changes

Click the Publish X IP access change(s) button to apply your settings.

​
Connection Examples

​
Using psql Command Line

# Connect to primary (read/write)
psql -h database1 -U database1 -d db

# Connect to replicas for read operations (HA mode only)
psql -h database1 -p 5433 -U database1 -d db

​
Using Connection String

# Primary connection
postgresql://database1:your-password@database1:5432/db

# Replica connection (HA mode only)
postgresql://database1:your-password@database1:5433/db

​
Next Steps

Manage Users & Databases

Create and manage users, databases, and plugins

Backup & Restore

Configure backups and restore your data

Build docs developers (and LLMs) love

Get started for freeTalk to us