How to connect to a database on a private network

Open a client session against a PostgreSQL or MySQL/MariaDB instance that has no floating IP. The steps cover both connection paths: an application instance already on the private network, and a workstation reaching the subnet through a bastion.

Replace DB_PRIVATE_IP with the database instance's private address, JUMP_HOST with your bastion's reachable address, and YOUR_PRIVATE_KEY_PATH with the key matching the key_name on the deployment. The templates default to Ubuntu 24.04, so the SSH user is ubuntu.

Step 1: Find the private address#

List the instances in the project and read the address from the database row:

openstack server list -c Name -c Networks -c Status

The database instance shows one address on the private network and no floating IP:

+----------+-------------------------------+--------+
| Name     | Networks                      | Status |
+----------+-------------------------------+--------+
| postgres | postgres-net=192.168.40.12    | ACTIVE |
| app-01   | postgres-net=192.168.40.20    | ACTIVE |
+----------+-------------------------------+--------+

Step 2: Confirm the security group allows your source#

Find the group attached to the database instance, then list its rules:

openstack server show postgres -c security_groups
openstack security group rule list SECURITY_GROUP_NAME

The rule you need shows the engine's port with your source range in the IP Range column: 5432 for PostgreSQL, 3306 for MySQL and MariaDB. If your source address falls outside every listed range, add a rule for it with How to create security group rules. Scope the new rule to the narrowest range that covers the client, such as the application subnet or a single instance address.

Step 3: Connect from an application instance#

An instance on the same private network connects directly. SSH to the application instance, install the client package, and open a session.

For PostgreSQL:

sudo apt update && sudo apt install -y postgresql-client
PGPASSWORD='YOUR_DB_PASSWORD' psql -h DB_PRIVATE_IP -U appuser -d appdb -c "SELECT version();"

For MySQL or MariaDB:

sudo apt update && sudo apt install -y mariadb-client
mysql -h DB_PRIVATE_IP -u appuser -p'YOUR_DB_PASSWORD' appdb -e "SELECT VERSION();"

A version string in the output confirms the network path, the security group rule, and the account all work.

Step 4: Connect from your workstation through a bastion#

A workstation has no route to the private subnet, so forward a local port through the bastion and point the client at 127.0.0.1.

For PostgreSQL:

ssh -i YOUR_PRIVATE_KEY_PATH -N -L 5432:DB_PRIVATE_IP:5432 ubuntu@JUMP_HOST

For MySQL or MariaDB:

ssh -i YOUR_PRIVATE_KEY_PATH -N -L 3306:DB_PRIVATE_IP:3306 ubuntu@JUMP_HOST

Leave that session running and connect from a second terminal:

PGPASSWORD='YOUR_DB_PASSWORD' psql -h 127.0.0.1 -U appuser -d appdb
mysql -h 127.0.0.1 -u appuser -p'YOUR_DB_PASSWORD' appdb

The tunnel keeps the engine port off the public internet: the bastion terminates the SSH session, and the database still accepts connections only from inside the subnet.

Step 5: Verify from the application#

Point the application at the private address and confirm it connects with its own credentials rather than yours:

postgresql://appuser:[email protected]:5432/appdb
mysql://appuser:[email protected]:3306/appdb

Store the password with the rest of the application's secrets; see How to inject application secrets.

Troubleshoot a refused connection#

Next steps#

• Database networking and access: the addressing and access model behind these steps
• How to restore PostgreSQL from a self-managed-postgres backup: a restore drill that uses the same private-subnet access
• SSH bastion access into a private subnet: bastion setup and client configuration