Gcore Managed PostgreSQL provisions a fully managed PostgreSQL cluster with automatic backups, optional High Availability replication, and configurable storage. Before creating a cluster, verify that sufficient quota is available in the target region.
## Create a server
If the target region doesn't have sufficient quota, request additional quota first:
Navigate to **Cloud Management** > **Quotas Viewer** and select the region.
On the **Database Service** tab, select the required number of PostgreSQL clusters and specify the reason in the field on the right.
Requests are typically processed within fifteen minutes. If the quota is not increased after that time, contact [support](mailto:support@gcore.com).
### Configure the server
The creation form configures the region, PostgreSQL version, compute, storage, network, authentication, and database settings.
In the Cloud menu, navigate to **Managed PostgreSQL** and click **Create PostgreSQL server**.
Select the region where the PostgreSQL server will be hosted.
Select the appropriate [PostgreSQL version](/cloud/managed-database-postgresql#supported-versions).
In **Compute**, select the server flavor. Optionally, set custom DBMS settings via text mode in the window that opens.
In **Storage**, select the volume type and size.
Switch on the **Enable high availability** toggle in **PG configuration** to deploy three replicas with the same configuration, ensuring the database remains accessible if the primary server fails. When enabled, select the replication mode:
1. **Asynchronous**: the primary database sends changes to replicas without waiting for confirmation. Suitable when some data delay is acceptable but high performance is critical.
2. **Synchronous**: the primary database waits for confirmation that changes have been applied to all replicas. Provides full protection against data loss at the cost of some performance.
This feature can be enabled or disabled later.
In **Network settings**, configure the network interface. Select **Public** and configure the **Access control list** to limit server access to specific IP addresses.
Adding `0.0.0.0/0` allows unrestricted access from all IP addresses on the internet. Use this setting only temporarily and exclusively on test servers that do not contain sensitive data.
In **Authentication**, enter a username for the initial database user.
In **Databases**, enter the database name and select the owner. In **Server details**, specify the server name.
The database size limit is 100 GB during beta. For a larger database size, contact [support](mailto:support@gcore.com).
Click **Create PostgreSQL server** in the panel on the right.
The server will be created in a few minutes.
## Get credentials
Password generation is a one-time operation — the password cannot be recovered after closing the dialog.
Navigate to **Managed PostgreSQL** and select the server.
Click **...** next to the user, then click **Generate password**.
Copy and save the password immediately — it cannot be recovered after the window is closed.
If the password is lost, it can only be reset. A new password will be generated and the previous one deactivated.
## Upgrade the PostgreSQL version
To upgrade to a newer PostgreSQL version:
Navigate to **Managed PostgreSQL** and select the server.
On the **Overview** tab, click **Update** in the General info section.
If the latest version is already installed, the **Update** button is not displayed.
Select the required version from the drop-down list and click **Update**.
## Delete a server
Deleting a server permanently removes all data and associated resources.
Navigate to **Managed PostgreSQL** and select the server to delete.
In the confirmation window, type *Delete* and click **Delete server**.
## Connect to a PostgreSQL server
Before connecting, collect the server's connection details and verify that the client IP address is included in the access control list.
On the **Overview** tab of the server, find the connection details:
1. **Endpoint**: available in the **Connection details** section
2. **Port**: `5432` (fixed for all Managed PostgreSQL clusters)
3. **Username**: set during server creation — `dbuser` is used in these examples
4. **Password**: generated separately. If the password was lost, [reset it](/cloud/managed-database-postgresql/manage-postgresql-servers#get-credentials).
Verify that the client computer's external IP address is included in the access control list (ACL) of the PostgreSQL server.
1. **psql** — command-line PostgreSQL client.
2. **pgAdmin** — graphical PostgreSQL administration tool.
### Connect using the psql client
Run the following commands in a terminal after installing the PostgreSQL client.
[Download](https://www.postgresql.org/download/) and install the PostgreSQL client for the target operating system.
Run the following command in a terminal:
```sh theme={null}
psql -h hostname -p port -d dbname -U username
```
Replace `hostname`, `port`, `dbname`, and `username` with the actual connection values.
Enter the password and press **Enter**.
The [PostgreSQL documentation](https://www.postgresql.org/docs/) covers additional psql commands and options.
### Connect using pgAdmin
pgAdmin provides a graphical interface for managing and querying PostgreSQL servers.
[Download](https://www.pgadmin.org/) and install pgAdmin on the client computer.
On the **Dashboard** tab, select **Add New Server**.
In the **Create - Server** dialog, type the server name in the **General** tab.
Select the **Connection** tab and enter the endpoint as the host, port (`5432`), username, and password.
Locate the server in the left-side menu and click it to connect. The [pgAdmin documentation](https://www.pgadmin.org/docs/) covers advanced configuration options.
Gcore Managed PostgreSQL provisions a fully managed database cluster with automatic backups and optional High Availability replication. The workflow below creates a cluster, waits for provisioning to complete, retrieves its connection details and credentials, and connects to it with psql.
An [API token](/developer-tools/rest-api/authentication) is required, along with a [project ID](/api-reference/cloud/projects/list-projects) and a [region ID](/api-reference/cloud/regions/list-regions).
Open a bash terminal and set these as environment variables before running the examples:
```bash theme={null}
export GCORE_API_KEY="{YOUR_API_KEY}"
export GCORE_CLOUD_PROJECT_ID="{YOUR_PROJECT_ID}"
export GCORE_CLOUD_REGION_ID="{YOUR_REGION_ID}"
```
## Step 1. Activate the PostgreSQL service
The Managed PostgreSQL service requires a one-time activation per project and region before any clusters can be created.
```bash theme={null}
curl -s -X PUT "https://api.gcore.com/cloud/v1/dbaas/status/$GCORE_CLOUD_PROJECT_ID/$GCORE_CLOUD_REGION_ID" \
-H "Authorization: APIKey $GCORE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"is_initialized": true}'
```
The API returns:
```json theme={null}
{
"is_initialized": true
}
```
To check whether activation is already done, call `GET /cloud/v1/dbaas/status/{project_id}/{region_id}` — if `is_initialized` is already `true`, skip this step.
## Step 2. Create the cluster
A single create call provisions the database server, configures network access, creates an initial user, and creates the first database.
| Parameter | Required | Description |
| --------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `cluster_name` | Yes | Cluster identifier. Pattern `^[a-z0-9]([-a-z0-9]*[a-z0-9])?$`, max 50 characters |
| `pg_server_configuration.version` | Yes | PostgreSQL major version. Supported values: `"15"`, `"14"`, `"13"` |
| `pg_server_configuration.pg_conf` | Yes | Custom `postgresql.conf` settings as a string. Pass `""` to use defaults |
| `flavor.cpu` | Yes | Number of vCPUs allocated to the instance |
| `flavor.memory_gib` | Yes | RAM in GiB |
| `storage.type` | Yes | Block storage type. Use `ssd-hiiops` for best performance |
| `storage.size_gib` | Yes | Storage size in GiB. Maximum 100 GiB |
| `network.acl` | Yes | Allowed source IP addresses in CIDR notation. Use the connecting machine's public IP |
| `high_availability` | Yes | Set to `null` for a single-node cluster, or `{"replication_mode": "sync"}` or `{"replication_mode": "async"}` for three-node HA |
| `users[].name` | No | Initial database user. Lowercase letters only |
| `users[].role_attributes` | No | PostgreSQL role attributes. Include `"CREATEDB"` to allow creating databases from psql |
| `databases[].name` | No | Initial database name. Lowercase letters only. Must reference a user in `users[]` as `owner` |
```python theme={null}
import os
from gcore import Gcore
client = Gcore()
task_id_list = client.cloud.databases.postgres.clusters.create(
cluster_name="my-postgres",
pg_server_configuration={"version": "15", "pg_conf": ""},
flavor={"cpu": 2, "memory_gib": 4},
storage={"type": "ssd-hiiops", "size_gib": 10},
network={
"network_type": "public",
"acl": ["{YOUR_IP_ADDRESS}/32"],
},
high_availability=None,
users=[{"name": "dbuser", "role_attributes": ["INHERIT", "LOGIN", "CREATEDB"]}],
databases=[{"name": "mydb", "owner": "dbuser"}],
)
print(task_id_list.tasks[0])
```
```bash theme={null}
curl -s -X POST "https://api.gcore.com/cloud/v1/dbaas/postgres/clusters/$GCORE_CLOUD_PROJECT_ID/$GCORE_CLOUD_REGION_ID" \
-H "Authorization: APIKey $GCORE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"cluster_name": "my-postgres",
"pg_server_configuration": {
"version": "15",
"pg_conf": ""
},
"flavor": {
"cpu": 2,
"memory_gib": 4
},
"storage": {
"type": "ssd-hiiops",
"size_gib": 10
},
"network": {
"network_type": "public",
"acl": ["{YOUR_IP_ADDRESS}/32"]
},
"high_availability": null,
"users": [
{"name": "dbuser", "role_attributes": ["INHERIT", "LOGIN", "CREATEDB"]}
],
"databases": [
{"name": "mydb", "owner": "dbuser"}
]
}'
```
Response:
```json theme={null}
{
"tasks": ["bce1a2e8-d40b-4aca-bbad-fa2c3580cf20"]
}
```
```bash theme={null}
export TASK_ID="{TASK_ID}"
```
## Step 3. Poll the task
Cluster creation takes 3-5 minutes. Poll every 5 seconds until `state` is `FINISHED`.
```python theme={null}
task = client.cloud.tasks.poll(
task_id_list.tasks[0],
polling_interval_seconds=5,
polling_timeout_seconds=600,
)
print("Cluster ready:", task.created_resources.postgresql_clusters[0])
```
```bash theme={null}
curl -s "https://api.gcore.com/cloud/v1/tasks/$TASK_ID" \
-H "Authorization: APIKey $GCORE_API_KEY"
```
When complete:
```json theme={null}
{
"id": "bce1a2e8-d40b-4aca-bbad-fa2c3580cf20",
"state": "FINISHED",
"created_resources": {
"postgresql_clusters": ["my-postgres"]
}
}
```
## Step 4. Get the connection string
The cluster detail response includes the host, network configuration, and a connection string template in `network.connection_string`. The password field is masked — retrieve it in Step 5.
```python theme={null}
cluster = client.cloud.databases.postgres.clusters.get(
cluster_name="my-postgres",
)
print("Status:", cluster.status)
print("Host:", cluster.network.host)
print("Connection string:", cluster.network.connection_string)
```
```bash theme={null}
CLUSTER_NAME="my-postgres"
curl -s "https://api.gcore.com/cloud/v1/dbaas/postgres/clusters/$GCORE_CLOUD_PROJECT_ID/$GCORE_CLOUD_REGION_ID/$CLUSTER_NAME" \
-H "Authorization: APIKey $GCORE_API_KEY"
```
Response:
```json theme={null}
{
"cluster_name": "my-postgres",
"status": "READY",
"network": {
"network_type": "public",
"acl": ["{YOUR_IP_ADDRESS}/32"],
"host": "my-postgres-67d2e3927a98d77e71c4804f40c4ce1dd68f010d27b11a.pg.k1.frankfurt-2.cloud.gcore.dev",
"connection_string": "postgres://dbuser:*****@my-postgres-67d2e3927a98d77e71c4804f40c4ce1dd68f010d27b11a.pg.k1.frankfurt-2.cloud.gcore.dev:5432/mydb"
},
"flavor": {"cpu": 2, "memory_gib": 4},
"storage": {"size_gib": 10, "type": "ssd-hiiops"},
"pg_server_configuration": {"version": "15"},
"users": [{"name": "dbuser", "is_secret_revealed": false}],
"databases": [{"name": "mydb", "owner": "dbuser"}]
}
```
```bash theme={null}
export CLUSTER_NAME="my-postgres"
export PG_HOST="my-postgres-67d2e3927a98d77e71c4804f40c4ce1dd68f010d27b11a.pg.k1.frankfurt-2.cloud.gcore.dev"
```
## Step 5. Retrieve credentials
The credentials endpoint reveals the user password. It can only be called once per user — the password is not stored by Gcore afterward. The second call returns an error.
```python theme={null}
creds = client.cloud.databases.postgres.clusters.user_credentials.get(
username="dbuser",
cluster_name="my-postgres",
)
print(creds.username)
print(creds.password) # save immediately - second call raises an error
```
```bash theme={null}
USERNAME="dbuser"
curl -s "https://api.gcore.com/cloud/v1/dbaas/postgres/clusters/$GCORE_CLOUD_PROJECT_ID/$GCORE_CLOUD_REGION_ID/$CLUSTER_NAME/users/$USERNAME/credentials" \
-H "Authorization: APIKey $GCORE_API_KEY"
```
Response:
```json theme={null}
{
"username": "dbuser",
"password": "8T8WieWrkMSvrHlLlnAVtJDV4Vhyxz7..."
}
```
Calling this endpoint a second time returns: `"Requested credentials already revealed. You must regenerate credentials"`. To reset the password, call `POST /cloud/v1/dbaas/postgres/clusters/{project_id}/{region_id}/{cluster_name}/users/{username}/credentials`.
## Step 6. Connect with psql
With the host and password from the previous steps, open a psql session. Set the password via the `PGPASSWORD` environment variable to avoid an interactive prompt.
```bash theme={null}
export PGPASSWORD="{PASSWORD}"
psql -h $PG_HOST -p 5432 -U dbuser -d mydb
```
```
psql (15.x)
SSL connection (protocol: TLSv1.3, ...)
Type "help" for help.
mydb=#
```
Verify the connection and create a table:
```sql theme={null}
CREATE TABLE users (
id SERIAL PRIMARY KEY,
name TEXT NOT NULL,
created_at TIMESTAMPTZ DEFAULT NOW()
);
\dt
```
```
List of relations
Schema | Name | Type | Owner
--------+-------+-------+--------
public | users | table | dbuser
(1 row)
```
## Upgrade the PostgreSQL version
To upgrade to a newer major version, send a PATCH request with the target version. The cluster restarts during the upgrade.
```python theme={null}
task_id_list = client.cloud.databases.postgres.clusters.patch(
cluster_name="my-postgres",
pg_server_configuration={"version": "16"},
)
task = client.cloud.tasks.poll(
task_id_list.tasks[0],
polling_interval_seconds=5,
polling_timeout_seconds=600,
)
print("Cluster upgraded:", task.state)
```
```bash theme={null}
curl -s -X PATCH "https://api.gcore.com/cloud/v1/dbaas/postgres/clusters/$GCORE_CLOUD_PROJECT_ID/$GCORE_CLOUD_REGION_ID/$CLUSTER_NAME" \
-H "Authorization: APIKey $GCORE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"pg_server_configuration": {"version": "16"}}'
```
Response:
```json theme={null}
{
"tasks": ["bce1a2e8-d40b-4aca-bbad-fa2c3580cf20"]
}
```
Poll the task using the same method as Step 3.
## Delete a cluster
Deleting a cluster removes it and all associated data permanently.
```python theme={null}
task_id_list = client.cloud.databases.postgres.clusters.delete(
cluster_name="my-postgres",
)
task = client.cloud.tasks.poll(
task_id_list.tasks[0],
polling_interval_seconds=5,
polling_timeout_seconds=300,
)
print("Cluster deleted:", task.state)
```
```bash theme={null}
curl -s -X DELETE "https://api.gcore.com/cloud/v1/dbaas/postgres/clusters/$GCORE_CLOUD_PROJECT_ID/$GCORE_CLOUD_REGION_ID/$CLUSTER_NAME" \
-H "Authorization: APIKey $GCORE_API_KEY"
```
Response:
```json theme={null}
{
"tasks": ["bce1a2e8-d40b-4aca-bbad-fa2c3580cf20"]
}
```
Poll the task using the same method as Step 3.