fox/src/PaaS/PostgreSQL/connection.md

# Общая схема подключения

Подключение к кластеру **Cloud PostgreSQL** осуществляется через прокси-сервер. Клиентские подключения принимаются прокси, который маршрутизирует трафик к соответствующим узлам кластера (master или replica) в зависимости от выбранного порта.

Прокси является единой точкой входа для всех клиентских подключений и принимает входящие соединения от приложений, административных инструментов и пользователей.

В зависимости от выбранного порта прокси автоматически направляет трафик:
- **на активный primary-узел** - для операций чтения и записи
- **на реплики** - для операций только чтения

::: warning Примечание
Прямое подключение к отдельным узлам базы данных **не используется и не предоставляется**. Взаимодействие с кластером всегда выполняется **через прокси-сервер**.
::: 

## Подключение к базе данных

Для подключения к базе данных необходимо использовать IP-адрес прокси-сервера, который предоставляется после заказа услуги.

Этот IP-адрес является единой точкой входа для работы с кластером PostgreSQL. Все подключения к базе данных - как из приложений, так и из клиентских инструментов - выполняются через него.

Использование других IP-адресов или попытка прямого подключения к отдельным узлам кластера не предусмотрены.

## Доступные порты

Для разных типов нагрузки используются разные порты:

|Порт  |Назначение                               |
|------|-----------------------------------------|
|5432  |Primary (чтение и запись)                |
|15432 |Replica (только чтение)                  |
|6432  |Primary через PgBouncer (чтение и запись)|
|16432 |Replica через PgBouncer (только чтение)  |

#### Особенности работы портов

- Порты **для чтения и записи** (5432, 6432) всегда направляют трафик на активный primary-узел. При смене primary переключение происходит автоматически;
- Порты **только для чтения** (15432, 16432) направляют трафик на активные реплики. Если реплик несколько, нагрузка распределяется между ними по принципу round-robin;
- Если в кластере **отсутствуют реплики**, порты для чтения не используются - подключение по ним не устанавливается.

#### Рекомендации по выбору порта

- Для OLTP-нагрузки и большого количества соединений рекомендуется использовать **порты PgBouncer (6432 или 16432)**;
- Для операций записи используйте **master-порты (5432 или 6432)**;
- Для read-only запросов можно использовать **replica-порты (15432 или 16432)**.

## Доступ к pgAdmin

Для администрирования базы данных используется [web-интерфейс pgAdmin](./pgadmin.md).
Доступ осуществляется по DNS-имени, которое нужно прописать локально в инфраструктуре откуда будет происходить доступ к web-интерфейсу сервиса:
`10.X.X.4 <domain>.cloud-pg.dfcloud.ru`

После добавления записи pgAdmin будет доступен по адресу:
`https://<domain>.cloud-pg.dfcloud.ru`

Авторизация выполняется с использованием учётных данных, предоставленных вместе с доступом к сервису.

::: warning Примечание

- подключение к базе данных возможно только через указанный прокси-IP;
- в интерфейсе pgAdmin уже добавлен сервер базы данных, созданный для данной инсталляции. Для подключения требуется ввести пароль от учётной записи базы данных;
- pgAdmin предназначен для администрирования и не рекомендуется для выполнения тяжёлых или длительных запросов в production-среде.

:::

## Примеры подключения к PostgreSQL

Подключение к primary:
`psql -h 10.X.X.4 -p 5432 -U <username> -d <database>`

Подключение через PgBouncer:
`psql -h 10.X.X.4 -p 6432 -U <username> -d <database>`

#### Подключение через DBeaver / DataGrip

При создании подключения укажите:
- Host: 10.X.X.4;
- Port: 5432 или 6432;
- Database: `<database>`;
- User / Password: согласно выданным доступам;
- Тип подключения: PostgreSQL.

#### Пример строки подключения

Primary:
`postgresql://<username>:<password>@10.X.X.4:5432/<database>`

Через PgBouncer:
`postgresql://<username>:<password>@10.X.X.4:6432/<database>`