From b0b333d579b6281c68bd945b63c33c93abb8e5ac Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Michal=20Salo=C5=88?= Date: Thu, 11 Jun 2026 19:39:48 +0200 Subject: [PATCH 1/2] Add PostgreSQL scaling profiles and fix errors --- apps/docs/content/postgresql/faq.mdx | 4 +- .../docs/content/postgresql/how-to/backup.mdx | 8 +- .../content/postgresql/how-to/connect.mdx | 54 +++++- .../docs/content/postgresql/how-to/create.mdx | 98 ++++++---- .../postgresql/how-to/export-import-data.mdx | 31 ++- .../docs/content/postgresql/how-to/manage.mdx | 59 ++---- apps/docs/content/postgresql/how-to/scale.mdx | 179 +++++++++++++++++- apps/docs/content/postgresql/overview.mdx | 2 +- 8 files changed, 333 insertions(+), 102 deletions(-) diff --git a/apps/docs/content/postgresql/faq.mdx b/apps/docs/content/postgresql/faq.mdx index c306b0dc..d920acb9 100644 --- a/apps/docs/content/postgresql/faq.mdx +++ b/apps/docs/content/postgresql/faq.mdx @@ -1,6 +1,6 @@ --- title: Frequently Asked Questions -description: Get quick answers to your related questions about PostgreSql from frequently asked questions by people at Zerops. +description: Get quick answers to your related questions about PostgreSQL from frequently asked questions by people at Zerops. --- import { FAQ, FAQItem } from '/src/components/Faq'; @@ -12,7 +12,7 @@ import { FAQ, FAQItem } from '/src/components/Faq'; - Use port `5432` for all write operations (INSERT, UPDATE, DELETE) — this always routes to the primary node - Use port `5433` for read operations (SELECT) — this distributes queries across all replicas, improving performance - The read replica port (`5433`) is only available in HA mode. If you're running PostgreSQL in single container (NON_HA) mode, only port `5432` is available. + The read replica port (`5433`) is only available in HA mode. If you're running PostgreSQL in single container mode, only port `5432` is available. See [Connection Parameters](/postgresql/how-to/connect#connection-parameters) for all available ports and environment variables. diff --git a/apps/docs/content/postgresql/how-to/backup.mdx b/apps/docs/content/postgresql/how-to/backup.mdx index 4f80ca49..d23e647b 100644 --- a/apps/docs/content/postgresql/how-to/backup.mdx +++ b/apps/docs/content/postgresql/how-to/backup.mdx @@ -29,7 +29,13 @@ To restore a PostgreSQL backup: 1. **Download** the backup file (`.zip`) from the Zerops UI 2. **Extract** the zip file to access the individual schema dump files 3. **Prepare** your target environment (clean existing data or use a new instance) -4. **Restore** using PostgreSQL native tools. Follow the [official PostgreSQL backup documentation](https://www.postgresql.org/docs/current/backup-dump.html) for detailed restore procedures, or use web-based management tools like phpMyAdmin or Adminer as described in [PostgreSQL Management](/postgresql/how-to/manage). +4. **Restore** each schema with `pg_restore`. The dumps are in PostgreSQL's custom format (`-Fc`), so `pg_restore` is required — plain `psql` can't read them: + + ```sh + pg_restore -d [database_name] schemaName.dump + ``` + + See the [official PostgreSQL backup documentation](https://www.postgresql.org/docs/current/backup-dump.html) for detailed restore options. If you'd rather use a web UI like [Adminer](/postgresql/how-to/manage), first convert a dump to plain SQL with `pg_restore -f schema.sql schemaName.dump` and import that SQL file. For assistance with the restoration process, contact Zerops support. diff --git a/apps/docs/content/postgresql/how-to/connect.mdx b/apps/docs/content/postgresql/how-to/connect.mdx index ef49f549..f9b10079 100644 --- a/apps/docs/content/postgresql/how-to/connect.mdx +++ b/apps/docs/content/postgresql/how-to/connect.mdx @@ -28,7 +28,7 @@ The full list of connection-related environment variables is available in the se Parameter Internal - External (TLS) + Public IP (TLS) Env Variable @@ -97,6 +97,50 @@ Zerops creates a system user named `zps` with full privileges for maintenance pu For more information about default PostgreSQL setup, users, and databases, see [Manage PostgreSQL Users and Databases](/postgresql/how-to/manage). ::: +## Connection ports and TLS + +PostgreSQL on Zerops exposes three ports, each for a different purpose: + + + + + + + + + + + + + + + + + + + + + + + + + + +
PortPurposeTLS
5432Primary node — read and writeNot supported (plaintext)
5433Read-only replicas — distributes reads (HA mode only)Not supported (plaintext)
6432pgBouncer connection poolerRequired
+ +- **Ports `5432` and `5433` do not support TLS.** Connect with `sslmode=disable`. Inside a project these ports are reachable only on the private network, and over the [VPN](#method-1-connect-via-zerops-vpn) the tunnel already encrypts the traffic — requesting TLS on them fails the handshake. Every "do not use SSL/TLS" note elsewhere in these docs refers to `5432`/`5433`. +- **Port `6432` (pgBouncer) requires TLS.** Connect with at least `sslmode=require`; the connection is always encrypted. pgBouncer presents a certificate signed by the [Zerops CA](/references/networking/zerops-ca) but does not force the client to validate it, so `sslmode=require` is enough. If you want to verify the server's identity, use `sslmode=verify-full` together with the Zerops CA. This holds whether you reach `6432` from inside the project or over a public IP. + +## Connection pooling with pgBouncer + +Port `6432` puts [pgBouncer](https://www.pgbouncer.org/) in front of PostgreSQL and multiplexes many client connections onto a small pool of server connections. This is valuable for applications that open many short-lived connections — serverless functions, PHP-FPM, or anything with high connection churn — and **we recommend connecting through `6432` rather than `5432` for these workloads, including for internal service-to-service connections.** + +A few things to know: + +- **Transaction pooling.** A server connection is returned to the pool after each transaction, not when the client disconnects. Prepared statements are supported (cached per server connection), but session-scoped features that span transactions — session-level `SET`, advisory locks held across statements, `LISTEN`/`NOTIFY` — won't behave as expected. Use a direct `5432` connection for those. +- **TLS is required** on `6432` (see [above](#connection-ports-and-tls)), even for internal connections. +- **HA mode.** pgBouncer pools connections to the primary (writes). Read routing across replicas on port `5433` is separate and is not pooled. + ## Connect from Services in the Same Project All services within a Zerops project share a dedicated private network. There are two ways to implement connections between services in the same project: @@ -127,7 +171,7 @@ For more details on how to use environment variables, and instructions for addin :::caution Important notes - When changing passwords, update both the database user password and the environment variable separately - they don't automatically synchronize. - While both `postgresql://` and `postgres://` URI formats are valid, Zerops uses the `postgresql://` format. If your software requires `postgres://`, create a custom environment variable with this format. -- Do not use SSL/TLS protocols for internal connections. Security is assured by the project's private network. +- Internal connections on ports `5432`/`5433` don't use SSL/TLS — security is provided by the project's private network. For TLS-encrypted [connection pooling](#connection-pooling-with-pgbouncer), connect to pgBouncer on port `6432` instead. ::: ## Connect Remotely @@ -144,15 +188,13 @@ You can securely connect to PostgreSQL from your local workstation via Zerops VP 4. When finished, [stop the Zerops VPN](/references/networking/vpn#stop-vpn) :::warning Important notes -* Do not use SSL/TLS protocols when connecting over VPN. Security is provided by the VPN tunnel. +* Connect to ports `5432`/`5433` without SSL/TLS when using the VPN — the tunnel already encrypts the traffic. * If your connection over VPN doesn't work, try adding `.zerops` suffix to the service hostname (e.g., `database1.zerops`). For additional help, check the [VPN troubleshooting page](/references/networking/vpn#troubleshooting). ::: ### Method 2: Connect via Direct IP Access -Direct IP Access uses [pgBouncer](https://www.pgbouncer.org/) for connection pooling and TLS termination. - -Internally, port `5432` is available without SSL (and port `5433` for reads in HA mode). Externally, connections are secured with TLS through pgBouncer (port `6432`) before being routed to your PostgreSQL service. The read replica port is not available for external connections. +Public access always goes through [pgBouncer](https://www.pgbouncer.org/) on port `6432` over TLS (see [Connection ports and TLS](#connection-ports-and-tls)), which also pools your connections before routing them to PostgreSQL. The read-only replica port (`5433`) is not exposed for public access — route reads through your application logic instead. :::tip Trusting the TLS certificate The TLS certificate served on port `6432` is signed by the Zerops Certificate Authority. To verify it from outside Zerops, download and trust the [Zerops CA](/references/networking/zerops-ca) — e.g. `psql "... sslmode=verify-full sslrootcert=./zerops-ca.pem"`. diff --git a/apps/docs/content/postgresql/how-to/create.mdx b/apps/docs/content/postgresql/how-to/create.mdx index d84970c1..6afbbe29 100644 --- a/apps/docs/content/postgresql/how-to/create.mdx +++ b/apps/docs/content/postgresql/how-to/create.mdx @@ -42,6 +42,8 @@ The hostname is fixed after the service is created and cannot be changed later. Zerops automatically scales PostgreSQL services based on actual database usage. Configure the scaling parameters to match your database needs and control costs. +**Profile**: Choose a [scaling profile](/postgresql/how-to/scale#scaling-profiles) matched to your workload (OLTP, OLAP, or write-heavy). The profile sets sensible autoscaling defaults and tunes the PostgreSQL configuration for that workload; you can override individual values afterwards. + **CPU Mode**: Choose between shared (cost-effective) or dedicated (consistent performance). **Resource Limits**: Set minimum and maximum resources for CPU, RAM, and disk to control costs and ensure performance. @@ -75,7 +77,7 @@ Zerops uses a YAML format file to describe the project infrastructure. #### Basic example -Create a directory `my-project`. Create a `description.yaml` file inside the directory with the following content: +Create a directory `my-project`. Create a `zerops-import.yaml` file inside the directory with the following content: ```yaml # Basic project data @@ -86,17 +88,17 @@ project: services: - # service name hostname: postgresql1 - # service type and version number in postgresql@{version} format - type: postgresql@12 - # mode of operation "HA"/"NON_HA" - mode: NON_HA + # service type, mode and version number in postgresql:{mode}@{version} format + type: postgresql:single@18 + # autoscaling profile for the service. If not set, a default profile will be used. + profile: oltp-staging ``` The YAML file describes your future project infrastructure. The project will contain one PostgreSQL service in the single container mode with default [auto scaling](/postgresql/how-to/scale) configuration. The hostname will be set to `postgresql1`. #### Full example -Create a directory `my-project`. Create a `description.yaml` file inside the directory with the following content: +Create a directory `my-project`. Create a `zerops-import.yaml` file inside the directory with the following content: ```yaml # Basic project data @@ -113,11 +115,11 @@ project: services: - # first service hostname hostname: postgresql1 - # service type and version number in postgresql@{version} format - type: postgresql@12 - # mode of operation "HA"/"NON_HA" - mode: HA - # optional: vertical auto-scaling customization + # service type, mode and version number in postgresql:{mode}@{version} format + type: postgresql:ha@18 + # autoscaling profile for the service. If not set, a default profile will be used. + profile: oltp-staging + # optional: vertical auto-scaling customization (overrides values from profile) verticalAutoscaling: cpuMode: DEDICATED minCpu: 2 @@ -131,10 +133,10 @@ services: minFreeRamPercent: 20 - # second service hostname hostname: postgresql2 - # service type and version number in postgresql@{version} format - type: postgresql@12 - # mode of operation "HA"/"non_HA" - mode: NON_HA + # service type, mode and version number in postgresql:{mode}@{version} format + type: postgresql:single@18 + # autoscaling profile for the service. If not set, a default profile will be used. + profile: oltp-hobby ``` The YAML file describes your future project infrastructure. The project will contain two PostgreSQL services. @@ -143,14 +145,14 @@ The hostname of the first service will be set to `postgresql1`. The [high availa The hostname of the second service will be set to `postgresql2`. The [single container](/features/scaling#single-container-mode) mode will be chosen and the default [auto scaling configuration](/postgresql/how-to/scale) will be set. -#### Description of description.yaml parameters +#### Description of zerops-import.yaml parameters The `project:` section is required. Only one project can be defined. - + @@ -180,7 +182,7 @@ At least one service in the `services:` section is required. You can create a pr
ParameterParameter Description Limitations
- + @@ -215,10 +217,10 @@ At least one service in the `services:` section is required. You can create a pr + + + + + + + +
ParameterParameter Description
- mode + type — HA / single - Defines the operation mode of the PostgreSQL service. + The HA vs. single-container mode is selected through the :ha or :single part of the service type. The standalone mode field is deprecated.

HA @@ -238,18 +240,34 @@ At least one service in the `services:` section is required. You can create a pr In HA mode, a dedicated read replica port (5433) is available, allowing you to route read queries to replicas for better performance. See Connection Parameters for details.

- NON_HA + Single
Zerops will create a PostgreSQL database installed in a single container. Useful for non-essential data or dev environments.

Your data is stored only in a single container. If the container or the - the underlying physical machine fails, your data since the last backup are + underlying physical machine fails, your data since the last backup is lost. Zerops doesn't provide any automatic repairs of a single node PostgreSQL services.
+ profile + + Optional. The autoscaling profile for the service. Sets the autoscaling envelope (min/max resources and headroom) and tunes the PostgreSQL configuration for your workload type. If omitted, a default is used (oltp-staging for single, oltp-production for HA). Can be changed at any time. +
+ profileOverrides + + Optional. Only valid when profile: custom. Overrides individual PostgreSQL configuration values on top of the custom profile. See the custom profile reference for the full list of overridable keys. +
verticalAutoscaling @@ -262,7 +280,7 @@ At least one service in the `services:` section is required. You can create a pr
- - cpuMode + cpuMode Optional. Accepts `SHARED`, `DEDICATED` values. Default is `SHARED` @@ -270,7 +288,7 @@ At least one service in the `services:` section is required. You can create a pr
- - minCpu/maxCpu + minCpu/maxCpu Optional. Set the minCpu or maxCpu in CPU cores (integer). @@ -278,7 +296,7 @@ At least one service in the `services:` section is required. You can create a pr
- - minRam/maxRam + minRam/maxRam Optional. Set the minRam or maxRam in GB (float). @@ -286,7 +304,7 @@ At least one service in the `services:` section is required. You can create a pr
- - minDisk/maxDisk + minDisk/maxDisk Optional. Set the minDisk or maxDisk in GB (float). @@ -296,12 +314,12 @@ At least one service in the `services:` section is required. You can create a pr
:::caution -The PostgreSQL service **hostname** and **mode** are fixed after the service is created. They can't be changed later. +The PostgreSQL service **hostname** and **mode** (the `:ha` / `:single` part of the service `type`) are fixed after the service is created and can't be changed later. The autoscaling **profile**, by contrast, can be changed at any time. ::: -### Create a project based on the description.yaml +### Create a project based on the zerops-import.yaml -When you have your `description.yaml` ready, use the `zcli project project-import` command to create a new project and the service infrastructure. +When you have your `zerops-import.yaml` ready, use the `zcli project project-import zerops-import.yaml` command to create a new project and the service infrastructure. ```sh Usage: @@ -314,11 +332,11 @@ Flags: --working-dir string Sets a custom working directory. The default working directory is the current directory. (default "./") ``` -Zerops will create a project and one or more services based on the `description.yaml` content. +Zerops will create a project and one or more services based on the `zerops-import.yaml` content. -The maximum size of the `description.yaml` file is 100 kB. +The maximum size of the `zerops-import.yaml` file is 100 kB. -You don't specify the project name in the `zcli project project-import` command, because the project name is defined in the `description.yaml`. +You don't specify the project name in the `zcli project project-import` command, because the project name is defined in the `zerops-import.yaml`. If you have access to more than one client, you must specify the client ID for which the project is to be created. The `clientID` is located in the Zerops GUI under the client name on the project dashboard page. @@ -335,7 +353,7 @@ If you have access to more than one client, you must specify the client ID for w #### Example -Create a directory `my-project` if it doesn't exist. Create an `import.yaml` file inside the `my-project` directory with following content: +Create a directory `my-project` if it doesn't exist. Create a `zerops-import.yaml` file inside the `my-project` directory with following content: ```bash # array of project services @@ -343,17 +361,15 @@ services: - # service name hostname: postgresql1 - # service type and version number in postgresql@{version} format - type: postgresql@12 - # mode of operation "HA"/"NON_HA" - mode: NON_HA + # service type, mode and version number in postgresql:{mode}@{version} format + type: postgresql:single@18 ``` The YAML file describes the list of one or more services that you want to add to your existing project. In the example above, one PostgreSQL service in the [single container](/features/scaling#single-container-mode) with default [auto scaling](/postgresql/how-to/scale) configuration will be added to your project. The hostname of the new service will be set to `postgresql1`. -The content of the `services:` section of `import.yaml` is identical to the [project description file](#create-a-project-description-file). The `import.yaml` never contains the `project:` section because the project already exists. +The content of the `services:` section of `zerops-import.yaml` is identical to the [project description file](#create-a-project-description-file). The `zerops-import.yaml` doesn't contain the `project:` section because the project already exists. -When your `import.yaml` is ready, use the `zcli project service-import` command to add one or more services to your existing Zerops project. +When your `zerops-import.yaml` is ready, use the `zcli project service-import zerops-import.yaml` command to add one or more services to your existing Zerops project. ```sh Usage: @@ -365,6 +381,6 @@ Flags: command will be executed. ``` -zCLI commands are interactive, when you press enter after `zcli project service-import importYamlPath`, you will be given a list of your projects to choose from. +zCLI commands are interactive, when you press enter after `zcli project service-import zerops-import.yaml`, you will be given a list of your projects to choose from. -The maximum size of the `import.yaml` file is 100 kB. \ No newline at end of file +The maximum size of the `zerops-import.yaml` file is 100 kB. \ No newline at end of file diff --git a/apps/docs/content/postgresql/how-to/export-import-data.mdx b/apps/docs/content/postgresql/how-to/export-import-data.mdx index 6338db15..515d4b53 100644 --- a/apps/docs/content/postgresql/how-to/export-import-data.mdx +++ b/apps/docs/content/postgresql/how-to/export-import-data.mdx @@ -3,12 +3,11 @@ title: Export or import PostgreSQL data description: Learn how to export or import postgresql data in Zerops. --- -## Use Adminer or phpMyAdmin to export or import data -* [Adminer ↗](https://www.adminer.org) - an open source full-featured database management tool written in PHP -* [phpMyAdmin ↗](https://www.phpmyadmin.net) - a free software tool written in PHP, intended to handle the administration of PostgreSQL over the Web +## Use Adminer to export or import data +* [Adminer ↗](https://www.adminer.org) - an open source, full-featured database management tool written in PHP that supports PostgreSQL -1. [Install the tools to Zerops](/postgresql/how-to/manage#installing-management-tools) -2. Use their standard export or import functions +1. [Install Adminer to Zerops](/postgresql/how-to/manage#installing-adminer) +2. Use its standard export or import functions ## Use a database management tool on your workstation to export or import data @@ -16,7 +15,7 @@ Do you already use a database management tool that supports PostgreSQL on your w Zerops VPN client is included into zCLI, the Zerops command-line tool. To start the VPN connection, read [how to connect to PostgreSQL remotely](/postgresql/how-to/connect#connect-remotely). :::caution -Do not use SSL/TLS protocols when connecting to PostgreSQL over VPN. Zerops PostgreSQL is not configured to support these protocols. The security is assured by the VPN. +Connect to ports `5432`/`5433` without SSL/TLS — the VPN tunnel already encrypts the connection. (TLS is only used on the pgBouncer pooling port `6432`; see [Connection ports and TLS](/postgresql/how-to/connect#connection-ports-and-tls).) ::: Once the connection to PostgreSQL is established, use the standard export or import functions of your favourite management tool. @@ -32,11 +31,17 @@ Once the VPN session is established, you have the secured connection to the proj Use [psql ↗](https://www.postgresql.org/docs/current/app-psql.html) command to connect to PostgreSQL in Zerops: ```sh -psql -h [hostname] -U [user] -p [password] -d [database_name] +psql -h [hostname] -U [user] -d [database_name] +``` + +`psql` has no password flag — it will prompt you, or you can supply the password non-interactively via the `PGPASSWORD` environment variable: + +```sh +PGPASSWORD=[password] psql -h [hostname] -U [user] -d [database_name] ``` :::caution -Do not use SSL/TLS protocols when connecting to PostgreSQL over VPN. Zerops PostgreSQL is not configured to support these protocols. The security is assured by the VPN. +Connect to ports `5432`/`5433` without SSL/TLS — the VPN tunnel already encrypts the connection. (TLS is only used on the pgBouncer pooling port `6432`; see [Connection ports and TLS](/postgresql/how-to/connect#connection-ports-and-tls).) ::: To export your database data and structure, use the [pg_dump ↗](https://www.postgresql.org/docs/current/backup-dump.html) command. @@ -45,8 +50,14 @@ To export your database data and structure, use the [pg_dump ↗](https://www.po pg_dump [database_name] > dumpfilename.sql ``` -To import your database data and structure, use the `mysql` command. +To import your database data and structure from a plain SQL dump, use the `psql` command. + +```sh +psql [database_name] < dumpfilename.sql +``` + +For a custom-format dump (created with `pg_dump -Fc`, the format used by [Zerops backups](/postgresql/how-to/backup)), use [pg_restore ↗](https://www.postgresql.org/docs/current/app-pgrestore.html) instead: ```sh -mysql [database_name] < dumpfilename.sql +pg_restore -d [database_name] dumpfilename.dump ``` diff --git a/apps/docs/content/postgresql/how-to/manage.mdx b/apps/docs/content/postgresql/how-to/manage.mdx index 48dac79c..06e192cf 100644 --- a/apps/docs/content/postgresql/how-to/manage.mdx +++ b/apps/docs/content/postgresql/how-to/manage.mdx @@ -4,7 +4,6 @@ description: Learn how to manage PostgreSQL users, databases, plugins, and use d --- import { Dropdown, DropdownItem } from '/src/components/Dropdown'; -import TabbedCodeBlocks from '/src/components/TabbedCodeBlock'; This guide covers how to manage your PostgreSQL databases in Zerops, including default setup, database management tools, plugins, and best practices. @@ -14,12 +13,12 @@ Zerops creates a default database and user automatically when a new PostgreSQL s ### Database -- **Name**: Identical to the service hostname -- **Encoding**: `utf8mb4` +- **Name**: `db` +- **Encoding**: `C.UTF-8` ### DB User -- **Username**: Identical to the service hostname +- **Username**: `db` - **Password**: Generated randomly :::info @@ -29,58 +28,38 @@ For connection methods and environment variables, see the [Connect to PostgreSQL :::caution Important notes - When changing passwords, update both the database user password and the environment variable separately - they don't automatically synchronize. - While both `postgresql://` and `postgres://` URI formats are valid, Zerops uses the `postgresql://` format. If your software requires `postgres://`, create a custom environment variable with this format. -- Do not use SSL/TLS protocols for internal connections. Security is assured by the project's private network. +- Internal connections on ports `5432`/`5433` don't use SSL/TLS — security is provided by the project's private network. For TLS-encrypted connection pooling, connect to pgBouncer on port `6432` instead. See [Connection ports and TLS](/postgresql/how-to/connect#connection-ports-and-tls). ::: ## Database Management Tools -You can use any PostgreSQL management tool of your choice to administer your databases in Zerops. For convenience, Zerops provides ready-to-use recipes for two popular web-based database management tools: +You can use any PostgreSQL management tool of your choice to administer your databases in Zerops. For convenience, Zerops provides a ready-to-use recipe for [Adminer](https://www.adminer.org) — a lightweight, full-featured web-based database management tool that supports PostgreSQL. -* [Adminer](https://www.adminer.org) - a lightweight database management tool by Jakub Vrána -* [phpMyAdmin](https://www.phpmyadmin.net) - a popular free database administration tool that works with both MySQL and PostgreSQL databases +### Installing Adminer -### Installing Management Tools - -You can install these tools with a simple one-click import in Zerops: +You can install Adminer with a simple one-click import in Zerops: 1. In Zerops GUI, open your project and select **Import services** from the left menu -2. Copy and paste one of the following YAML configurations: - - + enableSubdomainAccess: true + buildFromGit: https://github.com/zeropsio/recipe-adminer +``` -### Accessing Management Tools +### Accessing Adminer -After installation, you can access these tools via VPN: +After installation, you can access Adminer via VPN: 1. [Start the Zerops VPN](/references/networking/vpn) -2. Type `http://adminer` or `http://phpmyadmin` in your browser +2. Type `http://adminer` in your browser :::tip -Try `http://adminer.zerops` or `http://phpmyadmin.zerops` if you encounter any connection issues. +Try `http://adminer.zerops` if you encounter any connection issues. ::: :::caution @@ -95,7 +74,7 @@ You can use various database management tools from your local workstation to con 2. **Obtain the [connection details](/postgresql/how-to/connect#connection-details)** from Zerops GUI - Environment variables are not available through VPN connections 3. Connect with your **preferred database tool** - - Do not use SSL/TLS (security is provided by the VPN) + - Do not use SSL/TLS on ports `5432`/`5433` — the VPN tunnel already encrypts the connection - **Desktop Database Tools** - popular GUI tools like pgAdmin, DBeaver, DataGrip, or any other PostgreSQL-compatible client will work with Zerops - **Command Line with psql** - connect using the standard PostgreSQL command-line client with the credential obtained above: ```sh diff --git a/apps/docs/content/postgresql/how-to/scale.mdx b/apps/docs/content/postgresql/how-to/scale.mdx index 468f2e2b..b83c1057 100644 --- a/apps/docs/content/postgresql/how-to/scale.mdx +++ b/apps/docs/content/postgresql/how-to/scale.mdx @@ -5,6 +5,7 @@ description: Get to know how Zerops scales your PostgreSQL service. import Image from '/src/components/Image'; import ResourceTable from '/src/components/ResourceTable'; +import { Dropdown, DropdownItem } from '/src/components/Dropdown'; Zerops automatically scales your PostgreSQL service based on actual database usage. When your database needs more power, resources increase. When demand drops, resources scale down to reduce costs. @@ -16,6 +17,182 @@ For complete scaling details across all services, see [Automatic Scaling and Hig PostgreSQL services use **vertical scaling** to adjust CPU, RAM, and disk resources within containers based on usage patterns. Unlike runtime services, PostgreSQL does not use horizontal scaling (adding/removing containers). Instead, PostgreSQL services use deployment modes for high availability. +## Scaling profiles + +A **scaling profile** is the starting point for a PostgreSQL service. Each profile sets two things at once: + +1. **The autoscaling envelope** — the default minimum/maximum CPU, RAM, and disk, and the free-resource headroom that controls how eagerly the autoscaler reacts. +2. **The PostgreSQL configuration** — memory, WAL, planner, autovacuum, and replication settings tuned for a specific workload shape. + +A profile name combines a **workload type** with a **tier**, e.g. `oltp-production`. + +### Workload types + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeTuned forNotes
OLTPTransactional workloads — web apps, APIs, order processing, auth. Short transactions and point lookups.The default and most general-purpose type. Synchronous replication in HA.
OLAPAnalytical workloads — reporting, dashboards, large aggregations.Larger sort/hash memory, aggressive query parallelism, higher-resolution planner statistics. Asynchronous replication in HA (synchronous commits would throttle bulk loads).
WriteHeavyHigh-volume ingestion — IoT telemetry, event logging, metrics.Commit batching, WAL compression, and aggressive autovacuum to keep up with write volume. Synchronous replication in HA.
+ +### Tiers + +The tier sets the size of the autoscaling envelope (and, in HA, the replication topology). Available tiers depend on the deployment mode: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ProfileModeUse it for
oltp-hobbySingleSide projects, prototypes, learning. Runs hot with minimal headroom to keep costs low.
oltp-stagingSingle / HAStaging, internal tools, early-stage apps. Moderate headroom. Default for single.
oltp-productionSingle / HABusiness-critical transactional workloads. Generous headroom for traffic spikes. Default for HA.
oltp-enterpriseHA onlyHigh-throughput OLTP at scale. Highest connection limits and the most aggressive headroom.
olap-productionSingle / HAAnalytical / warehouse workloads.
writeheavy-productionSingle / HAIngestion pipelines and write-heavy workloads.
customSingle / HAOLTP-based profile that lets you override individual PostgreSQL settings — see Custom profile.
+ +:::note +In **HA** mode the OLTP and WriteHeavy profiles run with two synchronous standbys, so an acknowledged `COMMIT` survives a node failure. OLAP runs with asynchronous standbys, trading a small potential window of recent writes for ingest speed. +::: + +### Setting a profile + +Set the profile when you create the service in the GUI, or with the `profile` field in your [import YAML](/postgresql/how-to/create#create-a-project-description-file): + +```yaml +services: + - hostname: db + type: postgresql:ha@18 + profile: oltp-production +``` + +If you don't set one, the default is used (`oltp-staging` for single, `oltp-production` for HA). **The profile can be changed at any time**, from both the GUI and a re-import. + +### Overriding the autoscaling envelope + +The resource limits a profile sets are defaults. You can override any of them — CPU mode, min/max CPU/RAM/disk, and the free-resource thresholds — **without switching to the custom profile**, using the [`verticalAutoscaling`](/postgresql/how-to/create#full-example) block in your import YAML or the **Automatic scaling configuration** in the GUI. These overrides apply on top of any profile. + +### Custom profile + +The `custom` profile uses the **OLTP** tuning as its base and additionally lets you override individual PostgreSQL configuration values through `profileOverrides`: + +```yaml +services: + - hostname: db + type: postgresql:single@18 + profile: custom + profileOverrides: + random_page_cost: 1.1 + default_statistics_target: 200 + autovacuum_max_workers: 5 + max_parallel_workers_per_gather: 4 +``` + +Settings that Zerops derives from the container's resources or that are required for the managed cluster to operate — `shared_buffers`, `max_connections`, JIT on/off, the pooler limits, and the replication/Patroni settings — are managed automatically and **cannot** be overridden. Refer to the [PostgreSQL configuration documentation](https://www.postgresql.org/docs/current/runtime-config.html) for the meaning, valid range, and units of each parameter. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyTypeDescription
work_memintegerMemory per sort/hash operation before spilling to disk
hash_mem_multiplierintegerMultiplier applied to work_mem for hash-based operations
maintenance_work_memintegerMemory for maintenance operations (VACUUM, CREATE INDEX, REINDEX)
autovacuum_work_memintegerMemory used by each autovacuum worker
temp_buffersintegerPer-session memory for accessing temporary tables
temp_file_limitintegerMaximum total disk space a session may use for temporary files
effective_cache_sizeintegerPlanner's assumption of total cache available (shared_buffers + OS cache)
effective_io_concurrencyintegerEstimated number of concurrent disk I/O operations the storage can handle
maintenance_io_concurrencyintegerConcurrent disk I/O operations for maintenance (VACUUM, prefetch)
random_page_costnumberPlanner's estimated cost of a non-sequential page fetch
default_statistics_targetintegerDefault number of samples used by ANALYZE for column statistics
jit_above_costnumberQuery plan cost above which JIT compilation is considered
max_worker_processesintegerMaximum number of background worker processes
max_parallel_workersintegerMaximum parallel workers that can be active at one time cluster-wide
max_parallel_workers_per_gatherintegerMaximum parallel workers a single Gather node can start
max_parallel_maintenance_workersintegerMaximum parallel workers for maintenance (CREATE INDEX, VACUUM)
wal_compressionstringCompression algorithm for full-page WAL images (off/pglz/lz4/zstd)
wal_buffersintegerShared memory used to buffer WAL data not yet written to disk
wal_writer_delayintegerInterval at which the WAL writer flushes WAL to disk
wal_writer_flush_afterintegerWAL bytes written before the WAL writer triggers a flush
commit_delayintegerArtificial delay before a WAL flush during commit to batch concurrent commits
commit_siblingsintegerMinimum number of concurrent open transactions required for commit_delay to apply
max_wal_sizeintegerSoft upper limit on WAL size that triggers a checkpoint
min_wal_sizeintegerMinimum WAL size kept for future reuse before recycling segments
autovacuum_max_workersintegerMaximum autovacuum worker processes running concurrently
autovacuum_naptimeintegerDelay between autovacuum runs on any given database
autovacuum_vacuum_scale_factornumberFraction of table size added to the autovacuum threshold
autovacuum_analyze_scale_factornumberFraction of table size added to the auto-analyze threshold
autovacuum_vacuum_cost_delayintegerCost-based delay inserted by autovacuum between I/O operations
autovacuum_vacuum_cost_limitintegerAccumulated vacuum cost at which an autovacuum worker sleeps
vacuum_cost_delayintegerCost-based delay inserted by manual VACUUM between I/O operations (milliseconds, 0 disables)
idle_in_transaction_session_timeoutintegerTerminate sessions that stay idle in a transaction longer than this
+ + + ## Configure scaling You can configure scaling settings: @@ -97,7 +274,7 @@ Navigate to your PostgreSQL service and select **Service containers & Overview** ## Technical details -Zerops monitors database usage and automatically adjusts resources based on predefined thresholds and timing parameters. The scaling behavior follows the same principles as other services in the platform. +Zerops monitors database usage and automatically adjusts resources based on predefined thresholds and timing parameters. The scaling behavior follows the same principles as other services on the platform. For complete technical specifications including: - Resource monitoring intervals and thresholds diff --git a/apps/docs/content/postgresql/overview.mdx b/apps/docs/content/postgresql/overview.mdx index 7f6730b6..4848a1c6 100644 --- a/apps/docs/content/postgresql/overview.mdx +++ b/apps/docs/content/postgresql/overview.mdx @@ -1,6 +1,6 @@ --- title: PostgreSQL overview -description: Learn about working with PostgresSql with ease in Zerops. +description: Learn about working with PostgreSQL with ease in Zerops. --- import DocCardList from '@theme/DocCardList'; From 3d9e8eae49e349c3a2274f58fda47a8e1b4f05c5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Michal=20Salo=C5=88?= Date: Thu, 11 Jun 2026 20:14:57 +0200 Subject: [PATCH 2/2] Refactor PostgreSQL section --- apps/docs/content/features/backup.mdx | 2 +- apps/docs/content/postgresql/faq.mdx | 31 -- .../docs/content/postgresql/how-to/backup.mdx | 57 --- .../content/postgresql/how-to/connect.mdx | 174 ++++---- .../docs/content/postgresql/how-to/create.mdx | 370 +++++------------- .../postgresql/how-to/export-import-data.mdx | 63 --- .../docs/content/postgresql/how-to/manage.mdx | 182 ++++----- apps/docs/content/postgresql/how-to/scale.mdx | 94 ++--- apps/docs/content/postgresql/overview.mdx | 177 ++++----- .../references/networking/zerops-ca.mdx | 2 +- apps/docs/sidebars.js | 33 +- apps/docs/src/components/Dropdown/index.tsx | 9 +- apps/docs/static/data.json | 10 +- 13 files changed, 444 insertions(+), 760 deletions(-) delete mode 100644 apps/docs/content/postgresql/faq.mdx delete mode 100644 apps/docs/content/postgresql/how-to/backup.mdx delete mode 100644 apps/docs/content/postgresql/how-to/export-import-data.mdx diff --git a/apps/docs/content/features/backup.mdx b/apps/docs/content/features/backup.mdx index 645bde3b..e8abbe8d 100644 --- a/apps/docs/content/features/backup.mdx +++ b/apps/docs/content/features/backup.mdx @@ -7,7 +7,7 @@ Zerops provides an automated, secure backup system for supported services. This ## Supported Services -Zerops provides automated backup functionality for the following services. For specific backup format details and restore instructions, visit each service's documentation: [MariaDB](/mariadb/how-to/backup), [PostgreSQL](/postgresql/how-to/backup), [Qdrant](/qdrant/overview), [Elasticsearch](/elasticsearch/overview), [NATS](/nats/overview), [Meilisearch](/meilisearch/overview), and [Shared Storage](/shared-storage/how-to/backup). +Zerops provides automated backup functionality for the following services. For specific backup format details and restore instructions, visit each service's documentation: [MariaDB](/mariadb/how-to/backup), [PostgreSQL](/postgresql/how-to/manage#backups), [Qdrant](/qdrant/overview), [Elasticsearch](/elasticsearch/overview), [NATS](/nats/overview), [Meilisearch](/meilisearch/overview), and [Shared Storage](/shared-storage/how-to/backup). ## Managing Backups in the UI diff --git a/apps/docs/content/postgresql/faq.mdx b/apps/docs/content/postgresql/faq.mdx deleted file mode 100644 index d920acb9..00000000 --- a/apps/docs/content/postgresql/faq.mdx +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: Frequently Asked Questions -description: Get quick answers to your related questions about PostgreSQL from frequently asked questions by people at Zerops. ---- - -import { FAQ, FAQItem } from '/src/components/Faq'; - - - - In High Availability (HA) mode, PostgreSQL runs on multiple containers with a primary node and replicas. To get the most out of this setup: - - - Use port `5432` for all write operations (INSERT, UPDATE, DELETE) — this always routes to the primary node - - Use port `5433` for read operations (SELECT) — this distributes queries across all replicas, improving performance - - The read replica port (`5433`) is only available in HA mode. If you're running PostgreSQL in single container mode, only port `5432` is available. - - See [Connection Parameters](/postgresql/how-to/connect#connection-parameters) for all available ports and environment variables. - - - *One possible cause:*
- The connection string in Zerops always starts with `postgresql://`. While the official PostgreSQL documentation - states that both `postgresql://` and `postgres://` URIs are valid, some software requires the shorter `postgres://` - version. - - To resolve this, create your own environment variable with the correct URI. For example, if your PostgreSQL service is named `db`, use the following format: - - ``` - postgres://${db_user}:${db_password}@${db_hostname}:${db_port} - ``` - - \ No newline at end of file diff --git a/apps/docs/content/postgresql/how-to/backup.mdx b/apps/docs/content/postgresql/how-to/backup.mdx deleted file mode 100644 index d23e647b..00000000 --- a/apps/docs/content/postgresql/how-to/backup.mdx +++ /dev/null @@ -1,57 +0,0 @@ ---- -title: Backup in PostgreSQL -description: Learn how you can work with backups in PostgreSQL service in Zerops. ---- - -Zerops provides automated data backup for PostgreSQL services with full encryption and flexible management options. - -For general backup information including configuration, scheduling, and management options, see the [Zerops Backups](/features/backup) documentation, which covers: -- Backup scheduling and retention policies -- Tagging system and storage quotas -- Manual backup creation and CLI tools -- Security and encryption details - -This page focuses on PostgreSQL-specific backup details. - -## PostgreSQL Backup Format - -PostgreSQL backups are created using `pg_dump` and stored in `.zip` format: - -- **Format**: `.zip` (containing per-schema `.dump` files) -- **Tooling**: `pg_dump` -- **Compression**: Custom format (`-Fc`), schema files named `schemaName.dump` -- **Storage**: Encrypted and stored in isolated object storage - -## Restoring PostgreSQL Backups - -To restore a PostgreSQL backup: - -1. **Download** the backup file (`.zip`) from the Zerops UI -2. **Extract** the zip file to access the individual schema dump files -3. **Prepare** your target environment (clean existing data or use a new instance) -4. **Restore** each schema with `pg_restore`. The dumps are in PostgreSQL's custom format (`-Fc`), so `pg_restore` is required — plain `psql` can't read them: - - ```sh - pg_restore -d [database_name] schemaName.dump - ``` - - See the [official PostgreSQL backup documentation](https://www.postgresql.org/docs/current/backup-dump.html) for detailed restore options. If you'd rather use a web UI like [Adminer](/postgresql/how-to/manage), first convert a dump to plain SQL with `pg_restore -f schema.sql schemaName.dump` and import that SQL file. - -For assistance with the restoration process, contact Zerops support. - -## High Availability - -For PostgreSQL services running in High Availability mode: -- Backups are created on a randomly selected healthy node -- Other nodes remain operational during the backup process -- Manual backups typically run on the primary node - -## Best Practices - -- Always create a manual backup with a protected tag before database migrations or major schema changes -- Test your restore process periodically in a non-production environment -- Monitor your backup storage usage in the Project Overview -- Use descriptive tags like `pre-migration-v2` for important snapshots -- Consider the order of schema restoration if you have dependencies between schemas - -For additional best practices and troubleshooting, refer to the [main backup documentation](/features/backup). \ No newline at end of file diff --git a/apps/docs/content/postgresql/how-to/connect.mdx b/apps/docs/content/postgresql/how-to/connect.mdx index f9b10079..2fbda2e6 100644 --- a/apps/docs/content/postgresql/how-to/connect.mdx +++ b/apps/docs/content/postgresql/how-to/connect.mdx @@ -1,26 +1,20 @@ --- -title: Connect to PostgreSQL in Zerops -description: Learn how to connect to your PostgreSQL database in Zerops from various environments. +title: Connect to PostgreSQL +description: Connect to your PostgreSQL database in Zerops, covering ports, TLS, connection pooling, environment variables, VPN, public access, and management tools. --- -This guide covers how to connect to your PostgreSQL database in Zerops, both from services within the same project and from outside the Zerops environment. +This guide covers everything about reaching your PostgreSQL database in Zerops: connection details, ports and TLS, connection pooling, connecting from other services or from your workstation, and the database tools you can use. -## Connection Options Overview +## Connection options at a glance -Zerops provides several ways to connect to PostgreSQL: +- **Internal**: between services in the same project, over the private network. +- **Remote**: from outside Zerops, either through the [VPN](#connect-via-zerops-vpn) (your machine joins the private network) or through [public IP access](#connect-via-public-ip) (TLS through pgBouncer). -1. **Internal connections** - Between services in the same Zerops project (via private network) -2. **Remote connections**: - - **VPN access** - From your local machine via Zerops VPN - - **Direct IP access** - Enables external applications to connect using TLS encryption by opening public ports on IPv6 (available by default) or IPv4 (requires add-on activation if not already enabled) +## Connection details -## Connection Details +Find your connection details in the service detail page under **Peek access details** (hostname, port, user, password, connection string). The full list of connection-related environment variables lives under **Environment variables** in the same service detail. -You'll find PostgreSQL connection details in the service detail page under the **Peek access details** button (shows hostname, port, user, password, and connection string). - -The full list of connection-related environment variables is available in the service detail under **Environment variables**. - -### Connection Parameters +### Connection parameters @@ -53,7 +47,7 @@ The full list of connection-related environment variables is available in the se - + @@ -77,7 +71,7 @@ The full list of connection-related environment variables is available in the se - + @@ -85,16 +79,8 @@ The full list of connection-related environment variables is available in the se
UserIdentical to hostname`db` (default) Same as internal `user`
Database namedb`db` (default) Same as internal `dbName`
-:::tip -If you're running PostgreSQL in High Availability (HA) mode, configure your application to route read queries to port **5433**. This distributes the load across all replicas, reducing pressure on the primary node and improving overall throughput. -::: - :::warning -Zerops creates a system user named `zps` with full privileges for maintenance purposes. Do not delete, change the password, or remove privileges from this user, as it will disrupt Zerops' ability to maintain the database cluster. -::: - -:::info -For more information about default PostgreSQL setup, users, and databases, see [Manage PostgreSQL Users and Databases](/postgresql/how-to/manage). +Zerops creates a system user named `zps` with full privileges for maintenance. Do not delete it, change its password, or remove its privileges, as doing so disrupts Zerops' ability to maintain the database cluster. ::: ## Connection ports and TLS @@ -112,12 +98,12 @@ PostgreSQL on Zerops exposes three ports, each for a different purpose: 5432 - Primary node — read and write + Primary node (read and write) Not supported (plaintext) 5433 - Read-only replicas — distributes reads (HA mode only) + Read-only replicas, distributing reads (HA mode only) Not supported (plaintext) @@ -128,89 +114,131 @@ PostgreSQL on Zerops exposes three ports, each for a different purpose: -- **Ports `5432` and `5433` do not support TLS.** Connect with `sslmode=disable`. Inside a project these ports are reachable only on the private network, and over the [VPN](#method-1-connect-via-zerops-vpn) the tunnel already encrypts the traffic — requesting TLS on them fails the handshake. Every "do not use SSL/TLS" note elsewhere in these docs refers to `5432`/`5433`. +- **Ports `5432` and `5433` do not support TLS.** Connect with `sslmode=disable`. Inside a project these ports are reachable only on the private network, and over the [VPN](#connect-via-zerops-vpn) the tunnel already encrypts the traffic, so requesting TLS on them fails the handshake. - **Port `6432` (pgBouncer) requires TLS.** Connect with at least `sslmode=require`; the connection is always encrypted. pgBouncer presents a certificate signed by the [Zerops CA](/references/networking/zerops-ca) but does not force the client to validate it, so `sslmode=require` is enough. If you want to verify the server's identity, use `sslmode=verify-full` together with the Zerops CA. This holds whether you reach `6432` from inside the project or over a public IP. ## Connection pooling with pgBouncer -Port `6432` puts [pgBouncer](https://www.pgbouncer.org/) in front of PostgreSQL and multiplexes many client connections onto a small pool of server connections. This is valuable for applications that open many short-lived connections — serverless functions, PHP-FPM, or anything with high connection churn — and **we recommend connecting through `6432` rather than `5432` for these workloads, including for internal service-to-service connections.** +Port `6432` puts [pgBouncer](https://www.pgbouncer.org/) in front of PostgreSQL and multiplexes many client connections onto a small pool of server connections. This is valuable for applications that open many short-lived connections (serverless functions, PHP-FPM, or anything with high connection churn), and **we recommend connecting through `6432` rather than `5432` for these workloads, including for internal service-to-service connections.** A few things to know: -- **Transaction pooling.** A server connection is returned to the pool after each transaction, not when the client disconnects. Prepared statements are supported (cached per server connection), but session-scoped features that span transactions — session-level `SET`, advisory locks held across statements, `LISTEN`/`NOTIFY` — won't behave as expected. Use a direct `5432` connection for those. +- **Transaction pooling.** A server connection is returned to the pool after each transaction, not when the client disconnects. Prepared statements are supported (cached per server connection), but session-scoped features that span transactions (session-level `SET`, advisory locks held across statements, `LISTEN`/`NOTIFY`) won't behave as expected. Use a direct `5432` connection for those. - **TLS is required** on `6432` (see [above](#connection-ports-and-tls)), even for internal connections. - **HA mode.** pgBouncer pools connections to the primary (writes). Read routing across replicas on port `5433` is separate and is not pooled. -## Connect from Services in the Same Project +## Connect from services in the same project -All services within a Zerops project share a dedicated private network. There are two ways to implement connections between services in the same project: +All services in a project share a private network, so other services reach PostgreSQL directly by its hostname. There are two ways to wire it up. -### Method 1: Direct Connection Parameters +### Direct connection parameters -You can directly use the connection parameters from Peek Access Details: +Use the parameters from **Peek access details**: -``` -host = database1 -port = 5432 -user = database1 -password = ********** (find under Peek Access Details) +```ini +host = db # your PostgreSQL service hostname +port = 5432 # 5433 for read-only replicas in HA mode +user = db # default user +password = ********** ``` -For read operations in HA mode, use port `5433` instead of `5432` with the same credentials. +### Environment variables (recommended) -### Method 2: Environment Variables (Recommended) +Zerops generates connection environment variables for every PostgreSQL service. To use one service's variables from another, prefix the variable name with the service hostname and an underscore. For example, to read the `connectionString` of service `db`, reference `db_connectionString`. -For better maintainability, Zerops creates environment variables for each PostgreSQL service that you can use in your application configuration. List of service environment variables is available in Zerops GUI. Go to a PostgreSQL service detail and choose **Environment variables**. +For read-only connections (HA mode only), use `connectionStringReplicas` instead. -To use variables from one service in another, prefix the variable name with the service hostname and underscore - to access the `connectionString` variable of `postgresql1`, use `postgresql1_connectionString`. - -For read-only connections (HA mode only), use the `connectionStringReplicas` variable instead. - -For more details on how to use environment variables, and instructions for adding your own custom variables, see the [Environment Variables](/features/env-variables) documentation. +See the [Environment Variables](/features/env-variables) documentation for details and for adding your own variables. :::caution Important notes -- When changing passwords, update both the database user password and the environment variable separately - they don't automatically synchronize. -- While both `postgresql://` and `postgres://` URI formats are valid, Zerops uses the `postgresql://` format. If your software requires `postgres://`, create a custom environment variable with this format. -- Internal connections on ports `5432`/`5433` don't use SSL/TLS — security is provided by the project's private network. For TLS-encrypted [connection pooling](#connection-pooling-with-pgbouncer), connect to pgBouncer on port `6432` instead. +- When changing a password, update both the database user and the environment variable, since they don't synchronize automatically. +- Zerops uses the `postgresql://` URI scheme. If your software requires the shorter `postgres://`, create a custom environment variable with that format. +- Internal connections on `5432`/`5433` don't use SSL/TLS. Security comes from the private network. For TLS-encrypted [connection pooling](#connection-pooling-with-pgbouncer), connect to pgBouncer on `6432`. ::: -## Connect Remotely +## Connect remotely -Zerops offers two methods for connecting to your PostgreSQL database from outside the Zerops environment: +There are two ways to reach PostgreSQL from outside Zerops: the VPN (recommended for development) and public IP access (for external applications). -### Method 1: Connect via Zerops VPN +### Connect via Zerops VPN -You can securely connect to PostgreSQL from your local workstation via Zerops VPN: +The VPN puts your workstation on the project's private network, so you connect exactly as an internal service would. 1. [Install & set up zCLI](/references/cli) 2. [Start the Zerops VPN](/references/networking/vpn#start-vpn) -3. Use the connection details from Access Details in the PostgreSQL service detail in Zerops GUI +3. Use the connection details from **Peek access details** in the service detail 4. When finished, [stop the Zerops VPN](/references/networking/vpn#stop-vpn) :::warning Important notes -* Connect to ports `5432`/`5433` without SSL/TLS when using the VPN — the tunnel already encrypts the traffic. -* If your connection over VPN doesn't work, try adding `.zerops` suffix to the service hostname (e.g., `database1.zerops`). For additional help, check the [VPN troubleshooting page](/references/networking/vpn#troubleshooting). +* Connect to `5432`/`5433` without SSL/TLS over the VPN, since the tunnel already encrypts the traffic. +* Environment variables are **not** available over the VPN; copy the access details from the GUI. +* If a connection doesn't work, try the `.zerops` suffix on the hostname (e.g. `db.zerops`). See the [VPN troubleshooting page](/references/networking/vpn#troubleshooting). ::: -### Method 2: Connect via Direct IP Access +### Connect via public IP -Public access always goes through [pgBouncer](https://www.pgbouncer.org/) on port `6432` over TLS (see [Connection ports and TLS](#connection-ports-and-tls)), which also pools your connections before routing them to PostgreSQL. The read-only replica port (`5433`) is not exposed for public access — route reads through your application logic instead. +Public access always goes through pgBouncer on port `6432` over TLS (see [Connection ports and TLS](#connection-ports-and-tls)), which also pools your connections. The read-only replica port (`5433`) is **not** exposed publicly. Route reads through your application logic instead. :::tip Trusting the TLS certificate -The TLS certificate served on port `6432` is signed by the Zerops Certificate Authority. To verify it from outside Zerops, download and trust the [Zerops CA](/references/networking/zerops-ca) — e.g. `psql "... sslmode=verify-full sslrootcert=./zerops-ca.pem"`. +The certificate on `6432` is signed by the Zerops Certificate Authority. To verify it from outside Zerops, download and trust the [Zerops CA](/references/networking/zerops-ca), for example `psql "... sslmode=verify-full sslrootcert=./zerops-ca.pem"`. ::: -#### Enable external access +To enable public access: + +1. Open your PostgreSQL service in the GUI and go to **Public Access through IP Addresses** +2. Choose IPv6 (available by default) or IPv4 (requires the [unique IPv4](/references/networking/public-access#ipv4-configuration) add-on) +3. Open one or more ports pointing to your service (routed through pgBouncer): + - Any port from 10–65435 (except 80 and 443) + - Each public port can map to any internal port; multiple public ports can share one internal port + - IPv4 and IPv6 can be configured independently +4. Optionally enable firewall protection +5. Click **Publish X IP access change(s)** to apply + +## Database management tools -1. Navigate to your PostgreSQL service in the Zerops GUI and choose the **Public Access through IP Addresses** section -2. Choose either IPv6 (available by default) or IPv4 (requires the [unique IPv4](/references/networking/public-access#ipv4-configuration) add-on) -3. Open one or more ports and point them to your PostgreSQL service (the system will direct them through pgBouncer) - - Choose any port from 10-65435 (except 80 and 443) - - Select destination service and internal port - - Each public port can be mapped to any internal service port - - Multiple public ports can point to the same internal port if needed - - Port configurations can be set independently for IPv4 and IPv6 -4. Optionally enable firewall protection for additional security -5. Click the **Publish X IP access change(s)** button to apply your settings +You can use any PostgreSQL-compatible tool to administer your database. For a zero-setup option, Zerops provides a ready-to-use recipe for [Adminer](https://www.adminer.org), a lightweight, full-featured web-based tool that supports PostgreSQL. + +### Install Adminer + +In the GUI, open your project, select **Import services**, and paste: + +```yaml title="zerops-import.yaml" +services: + - hostname: adminer + type: php-apache@8.5 + maxContainers: 1 + enableSubdomainAccess: true + buildFromGit: https://github.com/zeropsio/recipe-adminer +``` + +Then [start the VPN](/references/networking/vpn) and open `http://adminer` in your browser (try `http://adminer.zerops` if it doesn't resolve). + +:::caution +Do not use `https` when reaching management tools over the VPN. +::: + +### Desktop tools and psql + +Popular desktop clients (pgAdmin, DBeaver, DataGrip, or any PostgreSQL-compatible tool) work with Zerops over the VPN: + +1. [Start the Zerops VPN](/references/networking/vpn) to open an encrypted tunnel to your project +2. Copy the [connection details](#connection-details) from the GUI (environment variables aren't available over the VPN) +3. Connect without SSL/TLS on `5432`/`5433`, since the tunnel already encrypts the connection + +For the `psql` command-line client: + +```sh +psql -h [hostname] -U [user] -d [database_name] +``` + +`psql` has no password flag, so it prompts you. To pass the password non-interactively, use `PGPASSWORD`: + +```sh +PGPASSWORD=[password] psql -h [hostname] -U [user] -d [database_name] +``` + +:::tip +Try `[hostname].zerops` instead of `[hostname]` if you hit connection issues over the VPN. +::: -For database management tools and how to manage users and databases, see [Manage PostgreSQL Users and Databases](/postgresql/how-to/manage). \ No newline at end of file +To move data in and out with these tools, see [Export & import data](/postgresql/how-to/manage#export--import-data). diff --git a/apps/docs/content/postgresql/how-to/create.mdx b/apps/docs/content/postgresql/how-to/create.mdx index 6afbbe29..7c84de62 100644 --- a/apps/docs/content/postgresql/how-to/create.mdx +++ b/apps/docs/content/postgresql/how-to/create.mdx @@ -1,125 +1,96 @@ --- -title: Create a PostgreSQL service -description: Creating and scaling PostgreSQL in Zerops with GUI and zCLI +title: Create & import +description: Create a PostgreSQL service in the Zerops GUI or import it with a YAML definition, including the full parameter reference. --- -import Image from '/src/components/Image'; import data from '@site/static/data.json'; import UnorderedList from '@site/src/components/UnorderedList'; import Video from '@site/src/components/Video'; -import ResourceTable from '/src/components/ResourceTable'; -## Create PostgreSQL using Zerops GUI +Create a PostgreSQL service in the [GUI](#create-in-the-gui), or describe it in YAML and [import](#import-with-yaml) it through the GUI or zCLI. Both paths configure the same things; the YAML route is repeatable and versionable. -First, set up a project in Zerops GUI. Then go to the project dashboard page and choose **Add new service** in the left menu in the **Services** block. Then add a new PostgreSQL service: +## Create in the GUI + +Go to your project dashboard and choose **Add new service** in the **Services** block: