Skip to main content

Deploy PostgreSQL in 5 minutes

This guide walks you through creating your first PostgreSQL cluster from the Hikube console, up to the first connection with psql.

Objectives​

By the end of this guide, you will have:

  • A PostgreSQL cluster deployed in your Hikube project
  • An application database and a user to connect to it
  • A password generated by the platform
  • A working connection with psql

Prerequisites​

  • A Hikube account and a project with sufficient quotas (CPU, memory, storage)
  • The psql client installed on your workstation, if you want to test a connection from the Internet

Step 1: Create the cluster​

  1. Log in to the Hikube console and select your project.
  2. In the side menu, open DB & Messaging → PostgreSQL. The PostgreSQL Clusters page is displayed.
  3. Click Create a cluster. The Create a PostgreSQL cluster wizard opens.

Step 2: Configure and confirm​

The wizard has six steps: General, Configuration, Databases, Users, Summary and Finish. Move between them with Next and Previous.

General​

Enter the Cluster Name (a random name is suggested by default), for example demo-pg. It must be 3 to 16 characters long (lowercase letters, digits and hyphens), start with a letter and end with a letter or a digit.

Configuration​

FieldRecommended value for this guideNote
PostgreSQL Version18Offered versions: 15, 16, 17, 18
Instance presets1.small — 1 CPU / 2GiNo preset is preselected; capacity allocated to each node
Disk size (GB)10Storage capacity per node
Number of replicas1 (Standalone)2 or 3 for high availability
External accessEnabledRequired to connect from your workstation

PostgreSQL wizard, Configuration step

The banner at the top of the wizard shows the Estimated Cost and the impact on the project quotas.

warning

The Number of replicas cannot be changed after creation. For production, choose 2 (High Availability) or 3 (Max High Availability) from the start.

note

Only enable External access if you need it: it exposes the database on the public Internet.

Databases​

Enter a Database name, for example myapp (1 to 54 characters: lowercase letters, digits, underscores and hyphens; starts with a letter or an underscore, but not with pg_), then click Add.

Add at least one application database: the postgres database, always created, is a system database reserved for the platform, and your users cannot receive any right on it.

Users​

Add at least one user:

  1. Username: for example app_user (lowercase letters, digits and underscores only, no hyphen).
  2. Database name: select myapp. The list offers only the databases added at the Databases step. Without an application database, it shows “No application database” and the user is created without any right.
  3. Rights: Administrator (Admin) or Read-only.
  4. Click Add.

Summary​

Review the summary (Version, Instance preset, Data volume, Replicas, External exposure, Databases to create, Users to create, Estimated cost), then click Create cluster.

Step 3: Check the status​

The Finish step confirms the creation ("Creation complete!"). Click Finish to open the cluster page.

The cluster status is shown next to its name, on the cluster page as well as in the PostgreSQL Clusters list:

StatusMeaning
CreatingThe cluster is being provisioned
ReadyThe cluster is operational
ErrorThe platform could not apply the cluster's creation or its last change

Expected result: after a few minutes, the status changes to Ready. The cluster page shows the PostgreSQL Version, the Replicas, the Allocated Size and the External Access (Enabled).

Step 4: Retrieve the credentials​

Passwords are displayed only once, at the wizard's Finish step, in the User Credentials section:

  • Password of each user created;
  • Internal Connection String: the cluster address, when external access is enabled.

If the platform refuses a user, the step shows “User not created” and the reason, instead of its password.

PostgreSQL wizard, Finish step: user credentials (password masked)

warning

Copy these passwords into a password manager before leaving the screen: they will not be displayed again. If one is lost, generate a new one from the Users tab (Actions → Change Password).

The Connection and Databases card of the cluster page shows its addresses in two zones, each with a copy button:

  • Internal, From the project's resources only: the internal host, always filled in, and the port (5432). It is reachable from the VMs and Kubernetes clusters of the same project, without external access;
  • External, From the Internet: the public address, when External Access is enabled.

Step 5: Connect and test​

From your workstation, connect with psql to the address in the External zone:

psql "host=<host> port=5432 dbname=myapp user=app_user sslmode=require"

From a VM or a Kubernetes cluster of the project, use the host in the Internal zone: psql "host=<internal-host> port=5432 dbname=myapp user=app_user".

Enter the password when prompted, then check the connection:

SELECT version();
CREATE TABLE test (id serial PRIMARY KEY, message text);
INSERT INTO test (message) VALUES ('Hello Hikube');
SELECT * FROM test;

Expected result:

 id |    message
----+--------------
  1 | Hello Hikube
(1 row)

Step 6: Quick troubleshooting​

The External zone shows "Disabled" or "Waiting for allocation…"​

"Disabled": External Access is turned off. Enable it via Edit if you need to connect from the Internet; from the project, use the host in the Internal zone. "Waiting for allocation…": the public address has not been assigned yet, wait a few moments.

The internal host does not resolve from a VM​

Copy the full name from the Internal zone, without shortening it. On Debian 13, the name does not resolve without configuration: see Reaching a managed service in the project.

The Next button stays disabled​

  • At the Configuration step: the cluster exceeds the project quotas. Reduce the preset, the disk size or the number of replicas.
  • At the Users step: add at least one user.

Authentication rejected​

Check the username, the target database and the password. If the password has been lost, perform a rotation from the Users tab. See Manage users and databases.

The cluster changes to Error​

The platform could not apply the cluster's creation or its last change. Contact support, providing the project and cluster names.

Step 7: Cleanup​

  1. Open the cluster page (DB & Messaging → PostgreSQL → cluster name).
  2. Click Delete cluster.
  3. Enter the exact cluster name in the Resource name to confirm field, then click Permanently delete.
warning

This action deletes the PostgreSQL cluster and all associated data. It is irreversible.

Summary​

From the console, you have created:

  • A PostgreSQL cluster in your project
  • A database and a user with their rights
  • External access and a psql connection