> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gcore.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage a PostgreSQL server

> Create, configure, connect to, upgrade, and delete a Gcore Managed PostgreSQL server, including credentials and psql or pgAdmin access.

## Customer Portal

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:

**1. Open the Quotas Viewer**

Navigate to **Cloud Management** > **Quotas Viewer** and select the region.

![manage postgresql quotas request](https://mintcdn.com/gcore/ZzCOwyhP2SmkqgdR/images/docs/cloud/managed-database-postgresql/manage-postgresql-servers/manage-postgresql-10.png?fit=max\&auto=format\&n=ZzCOwyhP2SmkqgdR\&q=85\&s=00ed3da09058252c33df85f11f21dd8e)

**2. Set quota requirements**

On the **Database Service** tab, select the required number of PostgreSQL clusters and specify the reason in the field on the right.

**3. Send request**

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.

**1. Navigate to Managed PostgreSQL**

In the Cloud menu, navigate to **Managed PostgreSQL** and click **Create PostgreSQL server**.

![manage postgresql create a server](https://mintcdn.com/gcore/ZzCOwyhP2SmkqgdR/images/docs/cloud/managed-database-postgresql/manage-postgresql-servers/manage-postgresql-30.png?fit=max\&auto=format\&n=ZzCOwyhP2SmkqgdR\&q=85\&s=516a0be568f43c6cf4462b0dbd3fc2b7)

**2. Select a region**

Select the region where the PostgreSQL server will be hosted.

**3. Select the PostgreSQL version**

Select the appropriate [PostgreSQL version](https://docs.gcore.com/cloud/managed-database-postgresql.md#supported-versions).

**4. Configure compute and storage**

In **Compute**, select the server flavor. Optionally, set custom DBMS settings via text mode in the window that opens.

![manage postgresql select compute and flavor](https://mintcdn.com/gcore/ZzCOwyhP2SmkqgdR/images/docs/cloud/managed-database-postgresql/manage-postgresql-servers/manage-postgresql-40.png?fit=max\&auto=format\&n=ZzCOwyhP2SmkqgdR\&q=85\&s=ecaa568f592fdcae132b0fde45441938)

In **Storage**, select the volume type and size.

![manage postgresql choose volume](https://mintcdn.com/gcore/ZzCOwyhP2SmkqgdR/images/docs/cloud/managed-database-postgresql/manage-postgresql-servers/manage-postgresql-70.png?fit=max\&auto=format\&n=ZzCOwyhP2SmkqgdR\&q=85\&s=61cd7d11059168120bcb184614db1d90)

**5. (Optional) Enable high availability**

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.

![manage postgresql manage replication mode](https://mintcdn.com/gcore/ZzCOwyhP2SmkqgdR/images/docs/cloud/managed-database-postgresql/manage-postgresql-servers/manage-postgresql-90.png?fit=max\&auto=format\&n=ZzCOwyhP2SmkqgdR\&q=85\&s=7334feaf5ffe0f292f7cce389fbc0aa6)

This feature can be enabled or disabled later.

**6. Configure network settings**

In **Network settings**, configure the network interface. Select **Public** and configure the **Access control list** to limit server access to specific IP addresses.

> [!WARNING]
>
> 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.

**7. Set authentication**

In **Authentication**, enter a username for the initial database user.

![manage postgresql manage authentication](https://mintcdn.com/gcore/ZzCOwyhP2SmkqgdR/images/docs/cloud/managed-database-postgresql/manage-postgresql-servers/manage-postgresql-110-v2.png?fit=max\&auto=format\&n=ZzCOwyhP2SmkqgdR\&q=85\&s=c16613e1917954e744fe8042a89f8e17)

**8. Configure databases and server details**

In **Databases**, enter the database name and select the owner. In **Server details**, specify the server name.

> [!NOTE]
>
> The database size limit is 100 GB during beta. For a larger database size, contact [support](mailto:support@gcore.com).

![manage postgresql specify server details](https://mintcdn.com/gcore/ZzCOwyhP2SmkqgdR/images/docs/cloud/managed-database-postgresql/manage-postgresql-servers/manage-postgresql-120.png?fit=max\&auto=format\&n=ZzCOwyhP2SmkqgdR\&q=85\&s=5680896fe5c8604a1325327eeee29901)

**9. Create the server**

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.

**1. Navigate to the server**

Navigate to **Managed PostgreSQL** and select the server.

**2. Select the Users tab**

**3. Generate the password**

Click **...** next to the user, then click **Generate password**.

![Managed PostgreSQL Users tab with Generate password option in the action menu](https://mintcdn.com/gcore/ZzCOwyhP2SmkqgdR/images/docs/cloud/managed-database-postgresql/manage-postgresql-servers/manage-postgresql-130.png?fit=max\&auto=format\&n=ZzCOwyhP2SmkqgdR\&q=85\&s=9802cc20aa428335a1c15924b69374e6)

**4. Copy the password**

Copy and save the password immediately — it cannot be recovered after the window is closed.

> [!NOTE]
>
> If the password is lost, it can only be reset. A new password will be generated and the previous one deactivated.

**5. Click OK**

## Upgrade the PostgreSQL version

To upgrade to a newer PostgreSQL version:

**1. Navigate to the server**

Navigate to **Managed PostgreSQL** and select the server.

**2. Click Update**

On the **Overview** tab, click **Update** in the General info section.

> [!NOTE]
>
> If the latest version is already installed, the **Update** button is not displayed.

**3. Select the version and confirm**

Select the required version from the drop-down list and click **Update**.

![manage postgresql update version pop up](https://mintcdn.com/gcore/yzm2PLPphFfDbIQv/images/docs/cloud/managed-database-postgresql/manage-postgresql-servers/manage-postgresql-145.png?fit=max\&auto=format\&n=yzm2PLPphFfDbIQv\&q=85\&s=546d08ffc580521c86fdf16ad6e4d871)

## Delete a server

Deleting a server permanently removes all data and associated resources.

**1. Navigate to the server**

Navigate to **Managed PostgreSQL** and select the server to delete.

**2. Select the Delete tab**

![Managed PostgreSQL Delete tab with the Delete server button](https://mintcdn.com/gcore/ZzCOwyhP2SmkqgdR/images/docs/cloud/managed-database-postgresql/manage-postgresql-servers/manage-postgresql-150.png?fit=max\&auto=format\&n=ZzCOwyhP2SmkqgdR\&q=85\&s=d0fe41a1c962892010ab09c7c04ecc6d)

**3. Click Delete server**

**4. Confirm deletion**

In the confirmation window, type *Delete* and click **Delete server**.

![Managed PostgreSQL delete server confirmation dialog](https://mintcdn.com/gcore/ZzCOwyhP2SmkqgdR/images/docs/cloud/managed-database-postgresql/manage-postgresql-servers/manage-postgresql-160-v2.png?fit=max\&auto=format\&n=ZzCOwyhP2SmkqgdR\&q=85\&s=c83ed90d8dbc42c01730025ab4d70025)

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

**1. Collect connection details**

On the **Overview** tab of the server, find the connection details:

![Managed PostgreSQL server Overview tab showing Connection details with Endpoint and Port](https://mintcdn.com/gcore/ZzCOwyhP2SmkqgdR/images/docs/cloud/managed-database-postgresql/manage-postgresql-servers/manage-postgresql-170.png?fit=max\&auto=format\&n=ZzCOwyhP2SmkqgdR\&q=85\&s=1ff098df0cdbad987938b35ea2cfd540)

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](https://docs.gcore.com/cloud/managed-database-postgresql/manage-postgresql-servers.md#get-credentials).

**2. Verify client IP in ACL**

Verify that the client computer's external IP address is included in the access control list (ACL) of the PostgreSQL server.

**3. Select a connection tool**

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.

**1. Install the PostgreSQL client**

[Download](https://www.postgresql.org/download/) and install the PostgreSQL client for the target operating system.

**2. Start psql**

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.

**3. Enter the password**

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.

**1. Install pgAdmin**

[Download](https://www.pgadmin.org/) and install pgAdmin on the client computer.

**2. Launch pgAdmin**

**3. Add a new server**

On the **Dashboard** tab, select **Add New Server**.

![pgAdmin Dashboard with Add New Server button highlighted](https://mintcdn.com/gcore/ZzCOwyhP2SmkqgdR/images/docs/cloud/managed-database-postgresql/manage-postgresql-servers/manage-postgresql-180.png?fit=max\&auto=format\&n=ZzCOwyhP2SmkqgdR\&q=85\&s=d29881bfc69c746058c72dd8c708ca39)

**4. Set the server name**

In the **Create - Server** dialog, type the server name in the **General** tab.

![pgAdmin Create Server dialog showing the General tab with a Name field](https://mintcdn.com/gcore/yzm2PLPphFfDbIQv/images/docs/cloud/managed-database-postgresql/manage-postgresql-servers/manage-postgresql-190.png?fit=max\&auto=format\&n=yzm2PLPphFfDbIQv\&q=85\&s=6d6e5475f4d98a30e7f97a3e3abaea78)

**5. Set connection details**

Select the **Connection** tab and enter the endpoint as the host, port (`5432`), username, and password.

**6. Save**

**7. Connect to the server**

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.

## REST API

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.

> [!NOTE]
>
> An [API token](https://docs.gcore.com/developer-tools/rest-api/authentication.md) is required, along with a [project ID](https://docs.gcore.com/api-reference/cloud/projects/list-projects.md) and a [region ID](https://docs.gcore.com/api-reference/cloud/regions/list-regions.md).

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

> [tab] Python SDK
>
> ```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])
> ```

> [tab] curl
>
> ```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`.

> [tab] Python SDK
>
> ```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])
> ```

> [tab] curl
>
> ```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.

> [tab] Python SDK
>
> ```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)
> ```

> [tab] curl
>
> ```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.

> [tab] Python SDK
>
> ```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
> ```

> [tab] curl
>
> ```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..."
> }
> ```

> [!WARNING]
>
> 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.

> [tab] Python SDK
>
> ```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)
> ```

> [tab] curl
>
> ```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.

> [tab] Python SDK
>
> ```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)
> ```

> [tab] curl
>
> ```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.
