Skip to content

Commit 5be2633

Browse files
vankovapvankovap
authored
zerops suffix (#205)
1 parent ad12213 commit 5be2633

File tree

6 files changed

+257
-219
lines changed

6 files changed

+257
-219
lines changed

‎apps/docs/content/postgresql/how-to/connect.mdx

Lines changed: 49 additions & 96 deletions
Original file line numberDiff line numberDiff line change
@@ -1,134 +1,87 @@
11
---
22
title: Connect to PostgreSQL in Zerops
3-
description: Connecting to PostgreSQL in Zerops with GUI and zCLI.
3+
description: Learn how to connect to your PostgreSQL database in Zerops from various environments.
44
---
55

6-
## Default PostgreSQL database and user
6+
This guide covers how to connect to your PostgreSQL database in Zerops, both from services within the same project and from your local workstation.
77

8-
Zerops creates a default database and a default user automatically when a new PostgreSQL service is [created](/postgresql/how-to/create).
8+
## Connection Options Overview
99

10-
#### Database
10+
Zerops provides two primary ways to connect to PostgreSQL:
1111

12-
The default database name is identical to the service hostname. The default encoding is set to `utf8mb4`.
12+
1. **Internal connections** - Between services in the same Zerops project (via private network)
13+
2. **Remote connections** - From your local machine (via Zerops VPN)
1314

14-
#### DB user
15-
16-
Default user name is identical to the service hostname. Default user password is generated randomly. You will find the password in [Zerops GUI](#copy-access-details-from-zerops-gui) or you can use the [environment variable](#use-postgresql-environment-variables).
17-
18-
:::info
19-
Zerops creates a second DB user: `zps` for maintenance reasons with full privileges. Do not delete, change the password or remove privileges from this user, it will disrupt Zerops ability to maintain the database cluster.
15+
:::caution
16+
For security reasons, Zerops doesn't allow exposing PostgreSQL services directly to the internet.
2017
:::
2118

22-
## Copy access details from Zerops GUI
19+
## Connection Details
2320

24-
You will find the PostgreSQL access details under the **Access details** button in the project dashboard page.
21+
You'll find PostgreSQL connection details in two places in the Zerops GUI:
2522

26-
{/*TODO screenshot (Access detail popover)*/}
23+
1. Under the **Access details** button in the project dashboard
24+
2. In the service detail page under the **Peek access details** button
2725

28-
The same information is available in the service detail page in the left menu under the **Peek access details** button.
26+
### Connection Parameters
2927

30-
### PostgreSQL access parameters:
28+
| Parameter | Description |
29+
| --------------------- | --------------------------------------------------------------------- |
30+
| **Hostname** | Identical to the service hostname |
31+
| **Port** | **5432** (fixed for all PostgreSQL services) |
32+
| **User** | Identical to the service hostname |
33+
| **Password** | Randomly generated during service creation |
34+
| **Connection string** | `postgresql://${user}:${password}@{hostname}:5432` |
3135

32-
| Parameter | Description |
33-
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
34-
| **Hostname** | The service hostname specified when the PostgreSQL service was created. |
35-
| **Port** | **5432**<br/>This port is fixed for all PostgreSQL services and cannot be customized. |
36-
| **User** | Zerops creates a database user automatically when the service is created. The user name is always identical to the service hostname. |
37-
| **Password** | Zerops sets a random password when the service is created. |
38-
| **Connection string** | The connection string for PostgreSQL service is:<br/>`postgresql://${user}:${password}@{hostname}:5432` |
36+
:::warning
37+
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.
38+
:::
3939

40-
## Connect to PostgreSQL from runtime services of the same project
40+
:::info
41+
For more information about default PostgreSQL setup, users, and databases, see [Manage PostgreSQL Users and Databases](/postgresql/how-to/manage).
42+
:::
4143

42-
Projects in Zerops represent a group of one or more services. Services can be of different types (runtime services, databases, message brokers, object storage, etc.). All services of the same project share a **dedicated private network**. To connect to a service within the same project, just use the service hostname and its internal port.
44+
## Connect from Services in the Same Project
4345

44-
{/*TODO image (project example diagram)*/}
46+
All services within a Zerops project share a dedicated private network. There are two ways to implement connections between services in the same project:
4547

46-
#### Example
48+
### Method 1: Direct Connection Parameters
4749

48-
To connect to PostgreSQL `database1` service, set
50+
You can directly use the connection parameters from Access Details:
4951

5052
```
5153
host = database1
54+
port = 5432
5255
user = database1
53-
password = **********
56+
password = ********** (find under Access Details)
5457
```
5558

56-
You will find the password under the [**Access details**](#copy-access-details-from-zerops-gui) button in Zerops GUI.
57-
58-
:::caution
59-
Do not use SSL/TLS protocols when connecting to PostgreSQL from other runtime services in the same project. Zerops PostgreSQL is not configured to support these protocols. The security is assured by the project private network. Due to security reasons Zerops doesn't allow exposing PostgreSQL service to the internet.
60-
:::
61-
62-
## Use PostgreSQL environment variables
63-
64-
Zerops creates default environment variables for each PostgreSQL service to help you with connection from runtime services in the same project. To avoid the need to copy database access parameters manually, use environment variables in your [runtime service].
65-
66-
### Prefix the environment variable key
67-
68-
All services of the same project can reference environment variables from other services. To use an environment variable from one service in another service in the same project, you must prefix the environment variable key with the service hostname and underscore.
69-
70-
#### Example
71-
72-
To access the `connectionString` env variable of the `postgresql1` service, use `postgresql1_connectionString` as the env variable key.
73-
To access the `password` env variable of the `postgresql2` service, use `postgresql2_password` as the env variable key.
74-
75-
### PostgreSQL environment variables
59+
### Method 2: Environment Variables (Recommended)
7660

77-
List of service environment variables is available in Zerops GUI. Go to a PostgreSQL service detail and choose **Environment variables** in the left menu.
61+
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**.
7862

79-
{/*TODO screenshot (Service env variables table page in the PostgreSQL detail)*/}
63+
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`.
8064

81-
Zerops creates following environment variables when the PostgreSQL service is created:
65+
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.
8266

83-
| Variable | Description |
84-
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
85-
| **Hostname** | The service hostname specified when the PostgreSQL service was created. |
86-
| **Port** | **5432**<br/>This port is fixed for all PostgreSQL services and cannot be customized. |
87-
| **projectId** | ID of the project. Generated by Zerops. |
88-
| **serviceId** | ID of the PostgreSQL service. Generated by Zerops. |
89-
| **Connection string** | The connection string for PostgreSQL service is:<br/>`postgresql://${user}:${password}@{hostname}:5432`<br/><br/>Connection string contains [references](/postgresql/how-to/connect#postgresql-access-parameters) to `user` and `password` variables. Each time the `user` or `password` variable is updated, the `connectionString` variable is automatically updated as well. |
90-
| **User** | Zerops creates a database user automatically when the service is created. The user name is always identical to the service hostname. |
91-
| **Password** | Zerops sets a random password when the service is created. |
92-
93-
:::caution
94-
When you change the value of the password env variable, only the env variable is updated, not the actual password of the PostgreSQL user. You have to update the password of the database user manually.
95-
96-
When you change the password of the default PostgreSQL user in the database, the new password is not synchronised to the password env variable. You have to update the `password` env variable manually.
97-
:::
98-
:::caution
99-
The official PostgreSQL documentation states that both `postgresql://` and `postgres://` URIs are valid. In Zerops, we chose to generate the connection string with the widely used `postgresql://` schema.
100-
Some softwares however require the connection string to start with the shorter `postgres://` version only, which might cause errors. To fix that, create your own environment variable with the correct URI, e.g. when your PostgreSQL service is called `db` - `postgres://${db_user}:${db_password}@${db_hostname}:${db_port}`.
67+
:::caution Important notes
68+
- When changing passwords, update both the database user password and the environment variable separately - they don't automatically synchronize.
69+
- 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.
70+
- Do not use SSL/TLS protocols for internal connections. Security is assured by the project's private network.
10171
:::
10272

103-
You can create own custom [environment variables](/features/env-variables) for the PostgreSQL service in Zerops GUI and use them in the same way as the default variables.
104-
105-
## Connect to PostgreSQL in Zerops remotely
106-
107-
:::caution
108-
Due to security reasons Zerops doesn't allow exposing PostgreSQL service directly to the internet.
109-
:::
73+
## Connect Remotely
11074

111-
### Start VPN connection
75+
You can securely connect to PostgreSQL from your local workstation via Zerops VPN:
11276

113-
You can securely connect to PostgreSQL from your local workspace via Zerops VPN. Zerops VPN client is included into zCLI, the Zerops command-line tool. To start a VPN connection to the selected Zerops project, follow these steps:
114-
115-
1. [Install & setup zCLI](/references/cli)
77+
1. [Install & set up zCLI](/references/cli)
11678
2. [Start the Zerops VPN](/references/vpn#start-vpn)
79+
3. Use the connection details from Access Details in the PostgreSQL service detail in Zerops GUI
80+
4. When finished, [stop the Zerops VPN](/references/vpn#stop-vpn)
11781

118-
### Access PostgreSQL through VPN
119-
120-
Once the VPN session is established, you have the secured connection to the project's private network in Zerops. You can access all project services locally by using their hostname. The only difference is that no [environment variables](#use-postgresql-environment-variables) are available when connected through VPN. To connect to PostgreSQL in Zerops you have to copy the [access details](#copy-access-details-from-zerops-gui) manually from Zerops GUI.
121-
122-
:::caution
123-
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.
82+
:::warning Important notes
83+
* 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/vpn/troubleshooting).
84+
* Do not use SSL/TLS protocols when connecting over VPN. Security is provided by the VPN tunnel.
12485
:::
12586

126-
### Stop VPN connection
127-
128-
[Stop the Zerops VPN](/references/vpn#stop-vpn) in zCLI.
129-
130-
### Connect to PostgreSQL from another Zerops project
131-
132-
All services of the same project share a **dedicated private network**. You can use the service hostname to connect from one service to another within the same project.
133-
134-
Different Zerops projects have no special connection. They can communicate with each other only via the internet. If you need to connect to a PostgreSQL service in a Zerops project from a runtime service in another project, you need to use the [Zerops VPN](#access-postgresql-through-vpn). Due to security reasons Zerops doesn't allow exposing PostgreSQL service directly to the internet.
87+
For database management tools and how to manage users and databases, see [Manage PostgreSQL Users and Databases](/postgresql/how-to/manage).

0 commit comments

Comments
 (0)