> For the complete documentation index, see [llms.txt](https://docs.iexexchanger.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.iexexchanger.com/server-i-dannye/rabota-s-postgresql/podklyuchenie-postgresql.md).

# Подключение PostgreSQL

Эта инструкция описывает установку PostgreSQL 18 на сервер с Debian 12, подключение сервера базы данных к FASTPANEL, включение поддержки PostgreSQL в PHP 8.4 и создание отдельных баз для iEXExchanger.

Инструкция подходит для двух сценариев:

* первоначальная установка iEXExchanger на новый сервер;
* подготовка PostgreSQL перед переносом существующего проекта.

В обоих случаях PostgreSQL устанавливается и подключается одинаково. Первоначальная установка системы и перенос данных выполняются по отдельным инструкциям.

{% prompt description="Промпт для выполнения настройки" icon="bolt" %}

```markdown
Подготовь и подключи PostgreSQL 18 к iEXExchanger на сервере с Debian 12, FASTPANEL и PHP 8.4.

Твоя задача ограничивается установкой PostgreSQL, его подключением к FASTPANEL, включением PHP-драйверов, созданием баз и проверкой соединения.

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

Перед началом

1. Изучи текущее состояние сервера.
2. Найди Backend-проект iEXExchanger и его корневую директорию с файлом artisan.
3. Определи пользователя Backend-сайта в FASTPANEL.
4. Проверь наличие установщика:

scripts/install-postgresql18-fastpanel.sh

5. Проверь версию Debian, PHP и уже установленные кластеры PostgreSQL.
6. Если на сервере уже работает PostgreSQL, не изменяй и не удаляй существующие кластеры без отдельного разрешения.
7. Не выводи пароли и токены в итоговом отчёте.

Путь к Backend обычно выглядит так:

/var/www/ВЛАДЕЛЕЦ_САЙТА/data/www/app.ВАШ_ДОМЕН

Требования к установке

- PostgreSQL 18 необходимо установить через скрипт:

bash scripts/install-postgresql18-fastpanel.sh

- Запускай скрипт из корневой директории Backend.
- PostgreSQL должен принимать подключения только через:

127.0.0.1
::1

- Не открывай порт 5432 в публичном firewall.
- Используй фактический порт, который определит установщик.
- Не устанавливай PostgreSQL 17 через раздел «Приложения» FASTPANEL.
- Не назначай PostgreSQL сервером баз данных по умолчанию.
- Не используй Linux-пароль root как пароль PostgreSQL.

После установки проверь:

psql --version
pg_dump --version
pg_lsclusters
systemctl is-active postgresql@18-main
pg_isready -h 127.0.0.1 -p 5432

Проверь прослушиваемые адреса:

ss -ltnp | grep -E ':(5432|5433|5434|5435)\b'

Нормально, если PostgreSQL слушает только:

127.0.0.1
::1

Если PostgreSQL слушает 0.0.0.0 или публичный IP, остановись и исправь конфигурацию до продолжения.

FASTPANEL

Установщик создаёт административную роль fastuser и сохраняет реквизиты в файле:

/root/postgresql18-installer/fastpanel-postgresql18.credentials

Используй эту роль только для подключения PostgreSQL к FASTPANEL.

Параметры сервера:

Имя: PostgreSQL 18 local
Использовать сервер по умолчанию: Нет
Тип сервера: PostgreSQL
Тип подключения: Локальное
Имя пользователя: fastuser
Пароль: из защищённого файла установщика
Хост: автоматически
Порт: автоматически

Не используй fastuser в конфигурации iEXExchanger.

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

PHP 8.4

Проверь и включи для PHP 8.4 модули:

pdo_pgsql
pgsql

Проверь:

/opt/php84/bin/php --ri pdo_pgsql
/opt/php84/bin/php --ri pgsql
/opt/php84/sbin/php-fpm -t
systemctl is-active fp2-php84-fpm

Убедись, что Backend-сайт использует PHP 8.4.

Основная база

Создай через FASTPANEL отдельную PostgreSQL-базу для Backend.

Имя базы и пользователя сформируй из домена.

Пример для app.example.com:

Database: app_example_com_pg
Username: app_example_com_pg
Encoding: utf8
Server: PostgreSQL 18 local
Owner: владелец Backend-сайта в FASTPANEL
Password: отдельный случайный пароль

Используй в имени только:

- строчные латинские буквы;
- цифры;
- символ подчёркивания.

Не используй дефисы, пробелы, кириллицу и специальные символы.

Laravel Pulse

Если проект использует Laravel Pulse, создай отдельную базу:

Database: pulse_pg
Username: pulse_pg
Encoding: utf8
Server: PostgreSQL 18 local
Owner: тот же владелец Backend-сайта
Password: отдельный случайный пароль

Пароль pulse_pg не должен совпадать с паролем основной базы.

Проверка подключения

Проверь подключение к основной базе через psql:

psql \
  --host=127.0.0.1 \
  --port=5432 \
  --username=ИМЯ_ПОЛЬЗОВАТЕЛЯ \
  --dbname=ИМЯ_БАЗЫ

Выполни:

SELECT
    current_database(),
    current_user,
    current_setting('server_version'),
    current_setting('server_encoding');

Если используется Pulse, выполни такую же проверку для pulse_pg.

Сразу после создания проверь отсутствие таблиц командой:

\dt

Для новой базы ожидается:

Did not find any relations.

Запрещённые действия

Не выполняй:

php artisan migrate
php artisan product-updates:run

Не выполняй также:

- миграцию из MySQL;
- импорт SQL;
- ручное создание таблиц;
- перенос данных;
- удаление существующих баз;
- изменение рабочего DB_CONNECTION;
- переключение рабочего .env;
- подключение сторонних приложений к новым базам;
- открытие PostgreSQL в интернет.

Эта задача заканчивается после создания баз и успешной проверки соединения.

Для нового проекта параметры будут использованы на следующем этапе первоначальной установки iEXExchanger.

Для существующего проекта параметры будут использованы в отдельной инструкции по миграции.

Итоговый отчёт

После завершения сообщи:

1. установленную версию PostgreSQL;
2. имя и статус кластера;
3. фактический порт;
4. адреса, на которых PostgreSQL принимает соединения;
5. состояние pdo_pgsql и pgsql;
6. статус PostgreSQL в FASTPANEL;
7. имя основной базы и пользователя;
8. создана ли база pulse_pg;
9. успешно ли выполнено подключение через psql;
10. отсутствуют ли таблицы в новых базах;
11. какие действия должен выполнить владелец вручную.

Не показывай пароли в отчёте. Вместо них укажи:

Пароль создан и сохранён в защищённом месте.
```

{% endprompt %}

### Что будет настроено

После выполнения инструкции:

* PostgreSQL 18 будет установлен на сервер;
* будет создан локальный кластер `18/main`;
* PostgreSQL будет принимать только локальные подключения;
* FASTPANEL получит административную роль `fastuser`;
* PostgreSQL появится в списке серверов баз данных FASTPANEL;
* в PHP 8.4 будут включены модули `pdo_pgsql` и `pgsql`;
* для Backend будет создана отдельная база;
* для Laravel Pulse при необходимости будет создана база `pulse_pg`;
* для каждой базы будет создан отдельный пользователь;
* подключение будет проверено через `psql`.

PostgreSQL поддерживает Debian 12 Bookworm через официальный PGDG-репозиторий, из которого можно установить пакет `postgresql-18`. [Официальная инструкция PostgreSQL для Debian](https://www.postgresql.org/download/linux/debian/)

На момент подготовки документа в разделе приложений FASTPANEL доступны версии PostgreSQL до 17. Поэтому PostgreSQL 18 устанавливается отдельным скриптом, после чего подключается к панели как локальный сервер баз данных. [Список приложений FASTPANEL](https://kb.fastpanel.direct/applications/)

## Перед началом

Убедитесь, что выполнены следующие условия:

* используется Debian 12 Bookworm;
* FASTPANEL установлена и работает;
* PHP 8.4 установлен через FASTPANEL;
* Backend iEXExchanger загружен на сервер;
* у вас есть доступ к серверу по SSH;
* доступен пользователь `root`;
* сервер может подключаться к `apt.postgresql.org`;
* в папке `scripts` Backend-проекта находится установщик PostgreSQL.

Файл установщика:

```
scripts/install-postgresql18-fastpanel.sh
```

### Важные ограничения

При настройке соблюдайте следующие правила:

* не устанавливайте PostgreSQL 17 через раздел «Приложения»;
* не открывайте порт PostgreSQL в публичном firewall;
* не используйте пароль Linux-пользователя `root` в настройках PostgreSQL;
* не используйте административную роль `fastuser` в iEXExchanger;
* не назначайте PostgreSQL сервером баз данных по умолчанию в FASTPANEL;
* используйте отдельного пользователя для каждой базы;
* храните пароли баз данных в защищённом месте.

***

## Подключение к серверу

Подключитесь к серверу от имени пользователя `root`:

{% content-ref url="/spaces/uyjsNtEAtO6Sby8CHWyD/pages/cCEoFDjTDIufy3NUEakd" %}
[Подключение к серверу по SSH](/help-center/upravlenie-serverom/podklyuchenie-k-serveru-po-ssh.md)
{% endcontent-ref %}

```bash
ssh root@SERVER_IP
```

Вместо `SERVER_IP` укажите IP-адрес сервера.

## Переход в Backend-проект

Перейдите в корневую директорию Backend, где находится файл `artisan`.

{% content-ref url="/spaces/uyjsNtEAtO6Sby8CHWyD/pages/MDuqJRjp8L1cHG9i4sRB" %}
[Файлы сайта в FastPanel](/help-center/upravlenie-serverom/panel-fastpanel/faily-saita-v-fastpanel.md)
{% endcontent-ref %}

Пример:

```bash
cd /var/www/ВЛАДЕЛЕЦ_САЙТА/data/www/app.ВАШ_ДОМЕН
```

Например:

```bash
cd /var/www/example_com_usr/data/www/app.example.com
```

Проверьте наличие установщика:

```bash
ls -la scripts/install-postgresql18-fastpanel.sh
```

Если файл отображается, можно продолжать установку.

При необходимости установите право на выполнение:

```bash
chmod 0755 scripts/install-postgresql18-fastpanel.sh
```

## Установка PostgreSQL 18

Находясь в корневой директории Backend, запустите:

```bash
bash scripts/install-postgresql18-fastpanel.sh
```

Скрипт автоматически:

* проверит версию операционной системы;
* проверит запуск от `root`;
* проверит состояние `apt` и `dpkg`;
* подключит официальный PGDG-репозиторий;
* установит `postgresql-18`;
* установит `postgresql-client-18`;
* создаст или обнаружит кластер `18/main`;
* настроит кодировку `UTF8`;
* включит контрольные суммы данных;
* настроит SCRAM-аутентификацию;
* ограничит подключения адресами `127.0.0.1` и `::1`;
* создаст административную роль `fastuser`;
* сгенерирует пароль для `fastuser`;
* проверит основные возможности PostgreSQL;
* удалит созданную для проверки тестовую базу;
* сохранит реквизиты в защищённый файл;
* выведет параметры подключения для FASTPANEL.

При стандартной установке PostgreSQL будет работать со следующими параметрами:

```
Host: 127.0.0.1
Port: 5432
Database: postgres
```

Если на сервере уже работает другой кластер PostgreSQL, порт может отличаться. Используйте значение, которое покажет установщик.

## Результат выполнения установщика

После успешного завершения появится блок примерно следующего вида:

```
============================================================
POSTGRESQL 18 ГОТОВ
============================================================
Версия:              18.x
Кластер:             18/main
Host:                127.0.0.1
Port:                5432
Database:            postgres
Username:            fastuser
Password:            СГЕНЕРИРОВАННЫЙ_ПАРОЛЬ
Файл реквизитов:     /root/postgresql18-installer/fastpanel-postgresql18.credentials
============================================================

Поля FASTPANEL:
  Имя:               PostgreSQL 18 local
  По умолчанию:      не включать
  Тип сервера:       PostgreSQL
  Подключение:       Локальное
  Имя пользователя:  fastuser
  Пароль:            СГЕНЕРИРОВАННЫЙ_ПАРОЛЬ
  Хост/порт в форме: оставить автоматическими
```

Реквизиты сохраняются в файле:

```
/root/postgresql18-installer/fastpanel-postgresql18.credentials
```

Посмотреть содержимое можно только от пользователя `root`:

```bash
cat /root/postgresql18-installer/fastpanel-postgresql18.credentials
```

Ожидаемый формат:

```
name=PostgreSQL 18 local
type=PostgreSQL
connection=Local
host=127.0.0.1
port=5432
database=postgres
username=fastuser
password=СГЕНЕРИРОВАННЫЙ_ПАРОЛЬ
```

Файл защищён следующими правами:

```
Владелец: root
Группа: root
Права: 0600
```

Не копируйте его:

* в директорию сайта;
* в публичную папку;
* в Git-репозиторий;
* в общедоступное облачное хранилище;
* в переписку с сотрудниками.

## Проверка PostgreSQL

Проверьте установленную версию:

```bash
psql --version
```

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

```bash
pg_dump --version
```

Проверьте состояние кластеров:

```bash
pg_lsclusters
```

Проверьте системную службу:

```bash
systemctl is-active postgresql@18-main
```

Проверьте готовность принимать подключения:

```bash
pg_isready -h 127.0.0.1 -p 5432
```

Ожидаемый результат:

```
18/main    5432    online
127.0.0.1:5432 - accepting connections
```

Если установщик показал другой порт, используйте его вместо `5432`.

## Проверка сетевой доступности

PostgreSQL должен принимать подключения только внутри сервера.

Выполните:

```bash
ss -ltnp | grep -E ':(5432|5433|5434|5435)\b'
```

Нормальный результат содержит локальные адреса:

```
127.0.0.1:5432
[::1]:5432
```

Если отображается:

```
0.0.0.0:5432
```

или публичный IP сервера, не продолжайте настройку. Сначала закройте внешний доступ.

**Важно.** Для локального размещения iEXExchanger порт PostgreSQL не нужно открывать в интернете.

## Повторная проверка установщиком

Для проверки текущей конфигурации без изменения настроек выполните из корневой директории Backend:

```bash
bash scripts/install-postgresql18-fastpanel.sh --check
```

Команда проверяет:

* версию PostgreSQL;
* кластер;
* локальное подключение;
* административную роль;
* доступность необходимых компонентов;
* PHP-модули, если они уже включены.

Обычная проверка не меняет пароль `fastuser`.

## Смена пароля fastuser

Для принудительной смены пароля выполните:

```bash
bash scripts/install-postgresql18-fastpanel.sh --rotate-password
```

После смены обязательно обновите пароль в настройках сервера баз данных FASTPANEL.

Если в FASTPANEL останется старый пароль, сервер получит статус «Недоступен».

***

## Включение PostgreSQL в PHP 8.4

Для подключения iEXExchanger к PostgreSQL необходимо включить соответствующие PHP-модули.

FASTPANEL позволяет управлять модулями отдельно для каждой установленной версии PHP. [Настройка PHP и модулей в FASTPANEL](https://kb.fastpanel.direct/php/settings/)

{% stepper %}
{% step %}

### Где находятся модули

В FASTPANEL откройте: **«Управление» — «PHP»**

<figure><img src="/files/iQWREwxblmLimuxNpkXP" alt=""><figcaption></figcaption></figure>

Затем:

1. выберите PHP 8.4;
2. откройте управление модулями;
3. найдите `pdo_pgsql`;
4. найдите `pgsql`;
5. включите оба модуля;
6. сохраните изменения.

Убедитесь, что Backend-сайт также использует PHP 8.4.
{% endstep %}

{% step %}

### Для чего нужны модули

<table><thead><tr><th width="192.640625">Модуль</th><th>Для чего используется</th></tr></thead><tbody><tr><td><code>pdo_pgsql</code></td><td>Подключение Laravel к PostgreSQL через PDO</td></tr><tr><td><code>pgsql</code></td><td>Нативные функции PostgreSQL в PHP</td></tr></tbody></table>

Для Laravel основным является `pdo_pgsql`, но рекомендуется включить оба модуля.
{% endstep %}

{% step %}

###

### Проверка PHP-модулей

Выполните:

```bash
/opt/php84/bin/php -r 'echo json_encode([
    "pdo_pgsql" => extension_loaded("pdo_pgsql"),
    "pgsql" => extension_loaded("pgsql"),
    "pdo_drivers" => PDO::getAvailableDrivers(),
]), PHP_EOL;'
```

Ожидаемый результат:

```json
{"pdo_pgsql":true,"pgsql":true,"pdo_drivers":["sqlite","mysql","pgsql"]}
```

Порядок драйверов может отличаться. В списке обязательно должен присутствовать:

```
pgsql
```

Дополнительная проверка:

```bash
/opt/php84/bin/php --ri pdo_pgsql
```

```bash
/opt/php84/bin/php --ri pgsql
```

```bash
/opt/php84/sbin/php-fpm -t
```

```bash
systemctl is-active fp2-php84-fpm
```

Ожидаемый статус:

```
active
```

Если установщик сообщил:

```
В PHP 8.4 не включены pdo_pgsql и/или pgsql
```

PostgreSQL мог быть установлен правильно. Включите модули через FASTPANEL и снова выполните:

```bash
bash scripts/install-postgresql18-fastpanel.sh --check
```

{% endstep %}
{% endstepper %}

***

## Добавление PostgreSQL 18 в FASTPANEL

FASTPANEL умеет управлять локальными и внешними серверами баз данных. После подключения PostgreSQL можно выбирать при создании новых баз. [Управление серверами баз данных FASTPANEL](https://kb.fastpanel.direct/databases/database-servers-management/)

### Где находится раздел

В FASTPANEL откройте: **«Управление» — «Базы данных»**

Затем откройте: **«Серверы баз данных»**

<figure><img src="/files/8j1jzVwZtBjAfkXQrnuo" alt=""><figcaption></figcaption></figure>

Нажмите: **«Добавить сервер»**

<figure><img src="/files/aNp2vi3OaEVb3807GnAc" alt=""><figcaption></figcaption></figure>

Страница может иметь следующий адрес:

```
https://SERVER_IP:8888/databases/servers
```

### Заполнение формы

Укажите:

| Поле                             | Значение                        |
| -------------------------------- | ------------------------------- |
| Имя                              | `PostgreSQL 18 local`           |
| Использовать сервер по умолчанию | Нет                             |
| Тип сервера                      | `PostgreSQL`                    |
| Тип подключения                  | `Локальное`                     |
| Имя пользователя                 | `fastuser`                      |
| Пароль                           | Пароль из файла реквизитов      |
| Хост                             | Оставить автоматическим         |
| Порт                             | Оставить `0` или автоматическим |

Нажмите **«Сохранить»**.

{% hint style="info" %}

### Почему сервер не нужно выбирать по умолчанию

PostgreSQL 18 подключается как отдельный сервер баз данных для конкретных проектов.

Используйте значение:

```
Использовать сервер по умолчанию: Нет
```

При создании базы выбирайте `PostgreSQL 18 local` вручную.
{% endhint %}

## Проверка сервера в FASTPANEL

Вернитесь в раздел: **«Управление» — «Базы данных»**

Откройте: **«Серверы баз данных»**

<figure><img src="/files/8qH8ugy7jsJqrfKpl1mn" alt=""><figcaption></figcaption></figure>

У добавленной записи должно отображаться:

```
PostgreSQL 18 local
Статус: Доступен
```

Не создавайте базы, пока сервер не получил статус «Доступен».

### Проверка через CLI

Выполните:

```bash
mogwai databases servers list
```

В списке должна присутствовать запись с признаками:

```
TYPE: postgresql
LOCAL: true
USERNAME: fastuser
AVAIL: true
```

FASTPANEL поддерживает просмотр серверов и синхронизацию списка баз через `mogwai`. [Команды управления базами FASTPANEL](https://kb.fastpanel.direct/cli/databases/)

При необходимости выполните:

```bash
mogwai databases sync
```

## Какие пользователи используются

При подключении важно не перепутать разные учётные записи.

<table><thead><tr><th width="245.86328125">Учётная запись</th><th>Назначение</th></tr></thead><tbody><tr><td><code>fastuser</code></td><td>Административная роль PostgreSQL для FASTPANEL</td></tr><tr><td><code>example_com_usr</code></td><td>Владелец Backend-сайта в FASTPANEL и Linux</td></tr><tr><td><code>app_example_com_pg</code></td><td>Пользователь основной базы iEXExchanger</td></tr><tr><td><code>pulse_pg</code></td><td>Пользователь базы Laravel Pulse</td></tr></tbody></table>

{% stepper %}
{% step %}

### fastuser

Роль используется FASTPANEL для:

* создания баз;
* создания пользователей;
* управления PostgreSQL через панель.

Не используйте `fastuser` как пользователя iEXExchanger.
{% endstep %}

{% step %}

### Владелец сайта

Поле «Владелец» в FASTPANEL относится к пользователю панели и Linux.

Пример:

```
example_com_usr
```

Это не логин PostgreSQL.
{% endstep %}

{% step %}

### Пользователь основной базы

Для основной базы создаётся отдельный пользователь.

Пример:

```
app_example_com_pg
```

{% endstep %}

{% step %}

### Пользователь Pulse

Для базы Laravel Pulse используется отдельный пользователь:

```
pulse_pg
```

{% endstep %}
{% endstepper %}

***

## Создание основной базы

FASTPANEL позволяет создать базу, назначить владельца, связать её с сайтом и выбрать сервер. [Создание базы данных в FASTPANEL](https://kb.fastpanel.direct/databases/create-database/)

### Где находится раздел

В FASTPANEL откройте: **«Сайты»**

Выберите Backend-сайт:

```
app.ваш_домен
```

Откройте раздел:**«Базы данных»**

<figure><img src="/files/zDEcLKU30d6TByS8SBFR" alt=""><figcaption></figcaption></figure>

Нажмите:**«Новая база данных»**

<figure><img src="/files/wxUn347BLBz83pUPPnkL" alt=""><figcaption></figcaption></figure>

### Заполнение формы

Пример для сайта `app.example.com`:

| Поле             | Значение                                           |
| ---------------- | -------------------------------------------------- |
| Имя              | `app_example_com_pg`                               |
| Кодировка        | `utf8`                                             |
| Владелец         | Владелец Backend-сайта, например `example_com_usr` |
| Сервер           | `PostgreSQL 18 local`                              |
| Пользователь     | Создать нового пользователя                        |
| Логин            | `app_example_com_pg`                               |
| Пароль           | Отдельный надёжный пароль                          |
| Повторите пароль | Тот же пароль                                      |

<figure><img src="/files/3a51CXTRm8AbrCepsG3H" alt="" width="563"><figcaption></figcaption></figure>

Нажмите **«Сохранить»**.

### Требования к имени

Используйте:

* строчные латинские буквы;
* цифры;
* символ `_`.

Пример:

```
app_example_com_pg
```

Не используйте:

* пробелы;
* дефисы;
* кириллицу;
* специальные символы.

### Кодировка

В FASTPANEL выберите:

```
utf8
```

В PostgreSQL она отображается как:

```
UTF8
```

MySQL-кодировка:

```
utf8mb4
```

для PostgreSQL не используется.

### Пароль пользователя

Создайте отдельный случайный пароль.

Он не должен совпадать с паролями:

* `root`;
* FASTPANEL;
* `fastuser`;
* владельца сайта;
* административной панели iEXExchanger.

Сохраните пароль в защищённом менеджере.

## Создание базы Laravel Pulse

Если проект использует Laravel Pulse, создайте отдельную базу.

В карточке Backend-сайта снова нажмите: **«Новая база данных»**

Заполните форму:

| Поле             | Значение                    |
| ---------------- | --------------------------- |
| Имя              | `pulse_pg`                  |
| Кодировка        | `utf8`                      |
| Владелец         | Владелец Backend-сайта      |
| Сервер           | `PostgreSQL 18 local`       |
| Пользователь     | Создать нового пользователя |
| Логин            | `pulse_pg`                  |
| Пароль           | Отдельный надёжный пароль   |
| Повторите пароль | Тот же пароль               |

Для основной базы и Pulse используйте разные пароли.

После создания должны существовать:

```
Основная база:
Database: app_example_com_pg
Username: app_example_com_pg
```

```
Pulse:
Database: pulse_pg
Username: pulse_pg
```

Если Laravel Pulse не используется, базу `pulse_pg` создавать не нужно.

***

## Проверка основной базы

Подключитесь через `psql`:

```bash
psql \
  --host=127.0.0.1 \
  --port=5432 \
  --username=app_example_com_pg \
  --dbname=app_example_com_pg
```

Введите пароль пользователя базы.

После подключения выполните:

```sql
SELECT
    current_database(),
    current_user,
    current_setting('server_version'),
    current_setting('server_encoding');
```

Ожидаемый результат:

```
current_database | app_example_com_pg
current_user     | app_example_com_pg
server_version   | 18.x
server_encoding  | UTF8
```

Для выхода выполните:

```
\q
```

## Проверка базы Pulse

Подключитесь:

```bash
psql \
  --host=127.0.0.1 \
  --port=5432 \
  --username=pulse_pg \
  --dbname=pulse_pg
```

После подключения выполните:

```sql
SELECT
    current_database(),
    current_user,
    current_setting('server_version'),
    current_setting('server_encoding');
```

Ожидается:

```
current_database | pulse_pg
current_user     | pulse_pg
server_version   | 18.x
server_encoding  | UTF8
```

Для выхода:

```
\q
```

## Проверка новых баз

Сразу после создания базы не содержат таблиц.

Для основной базы выполните:

```bash
psql \
  --host=127.0.0.1 \
  --port=5432 \
  --username=app_example_com_pg \
  --dbname=app_example_com_pg \
  --command="\dt"
```

Ожидаемый результат:

```
Did not find any relations.
```

Для Pulse:

```bash
psql \
  --host=127.0.0.1 \
  --port=5432 \
  --username=pulse_pg \
  --dbname=pulse_pg \
  --command="\dt"
```

Ожидается:

```
Did not find any relations.
```

Это подтверждает, что базы успешно созданы и готовы к следующему этапу установки или переноса.

## Параметры подключения основной базы

Сохраните следующие данные:

```
Driver: pgsql
Host: 127.0.0.1
Port: 5432
Database: app_example_com_pg
Username: app_example_com_pg
Password: ПАРОЛЬ_ОСНОВНОЙ_БАЗЫ
SSL mode: disable
```

Для новой установки эти данные используются при настройке Backend.

При переносе существующего проекта они потребуются на отдельном этапе миграции.

Пример параметров:

```dotenv
DB_CONNECTION=pgsql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=app_example_com_pg
DB_USERNAME=app_example_com_pg
DB_PASSWORD="ПАРОЛЬ_ОСНОВНОЙ_БАЗЫ"
DB_SSLMODE=disable
```

Не применяйте этот блок к работающему проекту до перехода на PostgreSQL.

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

```
Driver: pgsql
Host: 127.0.0.1
Port: 5432
Database: pulse_pg
Username: pulse_pg
Password: ПАРОЛЬ_БАЗЫ_PULSE
SSL mode: disable
```

Пример:

```dotenv
PULSE_DB_CONNECTION=pgsql-pulse
PULSE_DB_HOST=127.0.0.1
PULSE_DB_PORT=5432
PULSE_DB_DATABASE=pulse_pg
PULSE_DB_USERNAME=pulse_pg
PULSE_DB_PASSWORD="ПАРОЛЬ_БАЗЫ_PULSE"
PULSE_DB_SSLMODE=disable
```

Параметры применяются на соответствующем этапе установки или переноса проекта.

## Что делать дальше

После успешного подключения выберите подходящую инструкцию:

* для нового проекта — продолжите первоначальную установку iEXExchanger;
* для существующего проекта — перейдите к отдельной инструкции по переносу базы данных.

Эта статья завершается проверкой подключения. Создание структуры таблиц и перенос данных выполняются на следующем этапе.

***

## Частые ошибки

<details>

<summary>FASTPANEL не подключается к PostgreSQL</summary>

Проверьте:

1. В форме используется пользователь `fastuser`.
2. Введён пароль из файла:

```
/root/postgresql18-installer/fastpanel-postgresql18.credentials
```

3. Выбран тип сервера PostgreSQL.
4. Выбрано локальное подключение.
5. Хост и порт оставлены автоматическими.
6. PostgreSQL работает:

```bash
pg_isready -h 127.0.0.1 -p 5432
```

7. Установщик успешно проходит проверку:

```bash
bash scripts/install-postgresql18-fastpanel.sh --check
```

Если пароль `fastuser` изменён, внесите новое значение в FASTPANEL.

</details>

<details>

<summary>Сервер имеет статус «Недоступен»</summary>

Проверьте:

```bash
systemctl is-active postgresql@18-main
```

```bash
pg_isready -h 127.0.0.1 -p 5432
```

```bash
mogwai databases servers list
```

Также проверьте пароль `fastuser` и фактический порт кластера.

</details>

<details>

<summary>PHP показывает could not find driver</summary>

Причина — модуль `pdo_pgsql` не включён в PHP 8.4.

Проверьте:

```bash
/opt/php84/bin/php --ri pdo_pgsql
```

```bash
/opt/php84/bin/php --ri pgsql
```

Убедитесь, что Backend-сайт назначен на PHP 8.4.

</details>

<details>

<summary>Пользователь уже существует</summary>

Удаление базы не всегда удаляет PostgreSQL-пользователя.

Используйте другой уникальный логин или удалите старого пользователя через FASTPANEL, если уверены, что он больше нигде не используется.

Не выполняйте `DROP ROLE` вручную, пока не проверите принадлежность объектов.

</details>

<details>

<summary>Не удаётся подключиться через psql</summary>

Проверьте:

* имя базы;
* имя пользователя;
* пароль;
* порт;
* состояние PostgreSQL;
* отсутствие лишних пробелов в реквизитах.

Имя базы и имя пользователя могут совпадать, но являются разными объектами PostgreSQL.

</details>

<details>

<summary>База не отображается в FASTPANEL</summary>

Выполните синхронизацию:

```bash
mogwai databases sync
```

Затем обновите страницу панели.

### Установщик не найден

Убедитесь, что вы находитесь в корневой директории Backend:

```bash
pwd
```

Проверьте файл:

```bash
ls -la scripts/install-postgresql18-fastpanel.sh
```

Если файл отсутствует, повторно загрузите полный архив Backend или добавьте установщик в папку `scripts`.

</details>

***

## Проверка результата

После выполнения инструкции должно быть подтверждено:

1. PostgreSQL 18 установлен.
2. Кластер `18/main` работает.
3. PostgreSQL принимает локальные подключения.
4. Публичный доступ к порту отсутствует.
5. PHP 8.4 видит драйвер `pgsql`.
6. FASTPANEL показывает PostgreSQL как доступный сервер.
7. Создана основная база.
8. Для основной базы создан отдельный пользователь.
9. При необходимости создана база `pulse_pg`.
10. Для Pulse создан пользователь `pulse_pg`.
11. Подключение к базам через `psql` работает.
12. Реквизиты сохранены для следующего этапа.

## Контрольный список

* [ ] PostgreSQL 18 установлен.
* [ ] Кластер `18/main` имеет статус `online`.
* [ ] PostgreSQL доступен на `127.0.0.1`.
* [ ] Публичный порт PostgreSQL закрыт.
* [ ] Создана роль `fastuser`.
* [ ] Реквизиты `fastuser` сохранены в защищённом файле.
* [ ] В PHP 8.4 включены `pdo_pgsql` и `pgsql`.
* [ ] Backend-сайт использует PHP 8.4.
* [ ] В FASTPANEL добавлен сервер `PostgreSQL 18 local`.
* [ ] Сервер имеет статус «Доступен».
* [ ] PostgreSQL не выбран сервером по умолчанию.
* [ ] Создана отдельная основная база.
* [ ] Для основной базы создан отдельный пользователь.
* [ ] При необходимости создана база `pulse_pg`.
* [ ] Для Pulse создан пользователь `pulse_pg`.
* [ ] Использована кодировка `UTF8`.
* [ ] Подключение к основной базе проверено.
* [ ] Подключение к Pulse проверено.
* [ ] Реквизиты сохранены для установки или переноса.

## Коротко

PostgreSQL 18 устанавливается из официального PGDG-репозитория и подключается к FASTPANEL как отдельный локальный сервер баз данных.

FASTPANEL использует административную роль `fastuser`. Для iEXExchanger создаётся отдельная основная база и пользователь, а для Laravel Pulse — база и пользователь `pulse_pg`.

После проверки подключения новые проекты могут продолжить стандартную установку iEXExchanger. Для существующих проектов следующим этапом выполняется перенос базы данных по отдельной инструкции.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.iexexchanger.com/server-i-dannye/rabota-s-postgresql/podklyuchenie-postgresql.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.