Skip to content

Databases Updated 2026-05-29

Database connection strings

Connection-string patterns for connecting an application to a database on Stack Harbor PaaS — Java JDBC, PHP, ProxySQL endpoints for clustered topologies, and UTF-8 encoding.

Stack Harbor PaaS runs applications and databases as separate containers inside the same environment. To open a connection, the application must reference the database by hostname — localhost does not work, because the application is not on the same container as the database.

This page covers the connection-string patterns for the three options available — node CNAME, private IP, public IP — and engine-specific code for Java JDBC and PHP.

Three host options

From any application container inside the environment, the database is reachable via:

  • CNAME of the database node — node{node_id}-{environment_name}.{domain} (the canonical form).
  • Private IP — useful for fixed-topology setups; the IP stays stable for the lifetime of the environment.
  • Public IP — only available when a public endpoint is attached to the database node.

For a clustered MySQL/MariaDB/Percona topology, applications connect to a ProxySQL endpoint (proxy.{environment_name}.{domain}) rather than to a specific node. ProxySQL handles routing, so a node failover does not require an application restart.

Java connection (JDBC)

EngineJDBC URL
MySQL / MariaDBjdbc:mysql://node{node_id}-{environment_name}.{domain}/{dbname}
MySQL auto-clusterjdbc:mysql://proxy.{environment_name}.{domain}:3306/{dbname}
MariaDB auto-clusterjdbc:mariadb://proxy.{environment_name}.{domain}:3306/{dbname}?usePipelineAuth=false
PostgreSQLjdbc:postgresql://node{node_id}-{environment_name}.{domain}/{dbname}

Open the connection with DriverManager.getConnection(URL, user, password) against any of these URLs. The clustered URLs go through the ProxySQL load balancers — the cluster can fail over without an application restart.

For UTF-8 encoding, append the standard encoding parameters:

jdbc:{dbtype}://{host}/{dbname}?useUnicode=yes&characterEncoding=UTF-8

PHP connection

For MySQL and MariaDB, the standard MySQLi or PDO patterns apply:

$conn = mysqli_connect('node{node_id}-{environment_name}.{domain}', 'user', 'password', 'dbname');

For PostgreSQL, use the libpq connection string:

$conn = pg_connect("host=node{node_id}-{environment_name}.{domain} port=5432 dbname=postgres user=webadmin password=password");

The host string must not include http:// — the database is not an HTTP endpoint. Credentials are emailed by the platform when the database container is created.

Python and Node.js

Python (psycopg, mysqlclient, pymongo) and Node.js (mysql2, pg, mongodb) follow the same hostname pattern. Pass the CNAME (or private IP) of the database node as the host. For a clustered MySQL topology, point at the ProxySQL endpoint instead.

What you cannot use

  • localhost — application and database are on separate containers, so the loopback is not the database.
  • A bare service name without the environment suffix — the CNAME includes the environment name, not just the node id.
  • A public IP without a public endpoint attached — the database container does not have one by default.

See also