Connect to PostgreSQL in Zerops

This guide covers how to connect to your PostgreSQL database in Zerops, both from services within the same project and from your local workstation.

Connection Options Overview

Zerops provides two primary ways to connect to PostgreSQL:

1. Internal connections - Between services in the same Zerops project (via private network)
2. Remote connections - From your local machine (via Zerops VPN)

Caution

For security reasons, Zerops doesn't allow exposing PostgreSQL services directly to the internet.

Connection Details

You'll find PostgreSQL connection details in two places in the Zerops GUI:

1. Under the Access details button in the project dashboard
2. In the service detail page under the Peek access details button

Connection Parameters

Parameter	Description
Hostname	Identical to the service hostname
Port	5432 (fixed for all PostgreSQL services)
User	Identical to the service hostname
Password	Randomly generated during service creation
Connection string	postgresql://${user}:${password}@{hostname}:5432

Warning

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.

Info

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 Access Details:

host = database1
port = 5432
user = database1
password = ********** (find under Access Details)

Method 2: Environment Variables (Recommended)

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 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

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

1. Install & set up zCLI
2. Start the Zerops VPN
3. Use the connection details from Access Details in the PostgreSQL service detail in Zerops GUI
4. When finished, stop the Zerops VPN

Important notes

• 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.
• Do not use SSL/TLS protocols when connecting over VPN. Security is provided by the VPN tunnel.

For database management tools and how to manage users and databases, see Manage PostgreSQL Users and Databases.