×

Создание инстанса PostgreSQL и первое подключение

 
ВВЕДЕНИЕ
 
PostgreSQL в DevSpace — это не одна виртуальная машина с установленной базой, а группа экземпляров, которой управляет платформа. Один экземпляр всегда primary и принимает запись, остальные — реплики: они повторяют за ним данные и могут обслуживать чтение. Если primary выйдет из строя, платформа сама переведёт одну из реплик в его роль, без вашего участия.
 
Для администратора, привыкшего к установке на сервере, меняются три вещи:
 
  • пользователей и базы вы описываете в форме создания, а не командами CREATE USER и CREATE DATABASE. Платформа приводит базу к тому состоянию, которое записано в конфигурации
  • подключаться нужно не к адресу конкретной машины, а к адресам сервисов: у инстанса их несколько, отдельно для записи и для чтения
  • переключение на нового primary происходит само, и адрес сервиса записи при этом не меняется
 
ПЕРЕД НАЧАЛОМ
 
Нужны доступ к дашборду DevSpace и права на создание сервисов в вашем пространстве. Для проверки подключения понадобится любой клиент PostgreSQL — например, консольный psql или графический DBeaver.
 
ПОШАГОВОЕ РУКОВОДСТВО
 
Шаг 1. Откройте форму создания
 
В дашборде откройте Marketplace, в категории PaaS выберите карточку PostgreSQL. То же самое делает меню в левой части консоли: выберите Postgres и нажмите Deploy. У формы две вкладки — Form с полями и YAML с той же конфигурацией текстом.
 
Шаг 2. Задайте основные параметры
 
Поле
Значение в примере
Зачем
 Name
pg01
Имя инстанса: строчные латинские буквы, цифры и дефисы. Войдёт в имена сервисов и секрета
 replicas
2
Primary и одна реплика — минимум для переключения при сбое
 resourcesPreset
t1.micro
Типовой пресет CPU и памяти каждого экземпляра (справочник пресетов)
 size
10Gi
Размер диска под данные. Увеличить можно позже, уменьшить нельзя
 storageClass
local
Класс хранилища. После создания изменить нельзя
 external
включено
Доступ к базе из интернета. Без него база доступна только из вашего пространства
 version
оставьте по умолчанию
Мажорная версия PostgreSQL. По умолчанию предлагается самая свежая из списка
 
Дальше в статье <name> — это имя, которое вы задали в поле Name: платформа подставляет его в имена сервисов, секретов и компонентов инстанса.
 
storageClass здесь выбирается по тому же правилу, что и у других сервисов: при replicas: 1 берите replicated, потому что другой копии данных нет. При двух и больше подходит local — PostgreSQL сам держит копию на реплике, а у replicated ввод-вывод медленнее из-за синхронной записи на несколько серверов.
Включайте external, только если к базе действительно нужно ходить из интернета. Сервисы одного пространства видят друг друга по внутренним адресам, и приложению, которое работает рядом, внешний доступ не нужен.
 
Шаг 3. Опишите пользователя
 
В группе users впишите имя пользователя в поле Enter key name… и нажмите + Add рядом с ним. Пользователь раскроется отдельным блоком, в нём задайте пароль.
 
Пароль можно не задавать — тогда платформа сгенерирует его сама. Увидеть его можно будет на вкладке Secrets карточки инстанса.
 
Флажок replication в этом же блоке выдаёт пользователю права на репликацию. Он нужен только для инструментов, которые читают поток изменений базы, например для Debezium. Обычному пользователю приложения его не ставьте.
 
Шаг 4. Опишите базу данных
 
В группе databases так же добавьте базу: имя в поле Enter key name…, затем + Add. В раскрывшемся блоке укажите, кто с ней работает: в списке roles.admin нажмите + add и впишите имя пользователя из шага 3.
 
Роли задают права пользователей на эту базу:
 
  • roles.admin— полный доступ к базе, включая создание и изменение таблиц
  • roles.readonly— только чтение
  • extensions— список расширений PostgreSQL, которые платформа включит в этой базе, например hstore или postgis
 
Шаг 5. Запустите развёртывание
 
Нажмите Deploy. Откроется карточка инстанса. Статус Ready в шапке означает, что платформа применила конфигурацию.
 
Шаг 6. Убедитесь, что все компоненты запущены
 
Статус Ready появляется раньше, чем поднимутся все экземпляры. Поэтому фактическое состояние смотрите на вкладке Workloads — по смыслу это аналог systemctl status на сервере.
 
В разделе Pods должны быть строки обоих экземпляров — postgres-<name>-1 и postgres-<name>-2 — в статусе Running со счётчиком 1/1. Рядом остаются строки разовых задач: postgres-<name>-1-initdb-… создавала базу, postgres-<name>-init-job-… заводила пользователей и базы из формы, postgres-<name>-2-join-… подключала вторую реплику. У них статус Succeeded и счётчик 0/1 — так и должно быть, задача отработала и завершилась.
Если экземпляр долго не доходит до Running или счётчик держится на 0/1, откройте вкладку Events — там видно, на чём остановился запуск. Возвращайтесь к Workloads и после изменений конфигурации: смена версии или пресета ресурсов перезапускает экземпляры по очереди.
 
 
Шаг 7. Получите адреса и учётные данные
 
На вкладке Services у инстанса четыре адреса, все на порту 5432:
 
 
  • postgres-<name>-rw— запись: всегда ведёт на текущий primary. Основной адрес для приложения
  • postgres-<name>-ro— только чтение: ведёт на реплики. Сюда отправляют отчёты и тяжёлые выборки, чтобы не мешать записи
  • postgres-<name>-r— любой экземпляр, и primary, и реплики
  • postgres-<name>-external-write— внешний адрес для записи, появляется при включённом external. В колонке External IP стоит адрес, по которому база доступна из интернета
     
    Строка подключения к нему выглядит так:
    postgresql://user01:<пароль>@<внешний-IP>:5432/db01
 
Учётные данные — на вкладке Secrets, в секрете postgres-<name>-credentials. В нём по ключу на каждого пользователя: имя ключа — имя пользователя, значение — его пароль. Значение раскрывается кнопкой с иконкой глаза, рядом есть кнопка копирования.
 
Рекомендуем передавать учётные данные приложению через хранилище секретов, а не хранить в коде.
 
ПАРАМЕТРЫ
 
Основные
 
Параметр
Что делает
Значение по умолчанию
Когда менять
 replicas
Число экземпляров PostgreSQL: один primary, остальные реплики.
2
1 — только для сред без требований к доступности: переключать будет не на что. Больше двух — когда чтение нужно размазать по репликам.
 resourcesPreset
Типовой пресет CPU и памяти каждого экземпляра (справочник пресетов).
t1.micro
Под рабочий набор данных и нагрузку.
 resources
Явные CPU и память вместо пресета.
не заданы
Когда типовых пресетов не хватает. Явные значения имеют приоритет над пресетом. Память указывайте с единицами измерения: 512Mi, 2Gi.
 size
Размер диска под данные каждого экземпляра.
10Gi
Увеличивать можно на работающем инстансе, уменьшать нельзя.
 storageClass
Класс постоянного хранилища.
local — подставляет форма
При одном экземпляре — replicated, при двух и больше обычно local. Параметр неизменяемый.
 external
Доступ к базе из интернета через отдельный адрес.
false
Когда к базе ходит приложение вне пространства или вы подключаетесь клиентом со своего компьютера.
 version
Мажорная версия PostgreSQL.
самая свежая из списка
При переносе данных с существующего сервера — его версия.
 tls.enabled
Добавлять ли внешнее имя инстанса в сертификат сервера. Само шифрование соединений платформа держит включённым в любом случае.
не задано — имя добавляется, когда включён external
Явное false, если внешнее имя в сертификате не нужно.
 
Как выбрать класс хранилища. replicated держит копии тома на нескольких серверах платформы и переживает потерю сервера, но пишет синхронно в несколько мест, поэтому ввод-вывод у него всегда медленнее, чем у local. Критерий выбора — не «тест или продуктив», а сколько экземпляров у сервиса: один экземпляр — replicated, два и больше — обычно local, потому что копия данных уже есть на реплике.
 
Сервер PostgreSQL
 
Параметр
Что делает
Значение по умолчанию
Когда менять
 postgresql.parameters
Настройки самого сервера PostgreSQL — то, что в обычной установке правят в файле postgresql.conf.
max_connections: "100"
Под требования приложения. Часть параметров применяется только после перезапуска экземпляров.
 
На пресетах, где памяти меньше 512Mi — это t1.nano, t1.micro и c1.nano — под кеш страниц PostgreSQL отводится четверть памяти экземпляра: 32 МБ у t1.nano и 64 МБ у двух остальных. Для разработки и небольших баз этого достаточно, но под нагрузкой кеша будет не хватать: выбирайте пресет от 512Mi памяти или задайте shared_buffers в postgresql.parameters явно.
 
Параметры, через которые можно выполнить произвольный код, платформа запрещает: archive_command, restore_command, shared_preload_libraries и другие подобные. Не задавайте и параметры репликации — archive_mode, wal_level, primary_conninfo, max_replication_slots: ими управляет сама платформа.
 
Синхронная репликация
 
Параметр
Что делает
Значение по умолчанию
Когда менять
 quorum.minSyncReplicas
Сколько реплик должны подтвердить запись, прежде чем транзакция считается зафиксированной.
0 — асинхронная репликация
Когда недопустима потеря даже последних транзакций при отказе primary. Платите задержкой на запись.
 quorum.maxSyncReplicas
Верхняя граница числа синхронных реплик. Должна быть меньше общего числа экземпляров.
0
Вместе с minSyncReplicas.
 
Пользователи и базы
 
Параметр
Что делает
Значение по умолчанию
Когда менять
 users.<name>.password
Пароль пользователя.
пусто — платформа сгенерирует сама
Когда пароль задаёт ваша система управления секретами.
 users.<name>.replication
Права на чтение потока изменений базы.
false
Для инструментов захвата изменений, например Debezium.
 databases.<name>.roles.admin
Пользователи с полным доступом к базе.
пусто
При заведении новой базы.
 databases.<name>.roles.readonly
Пользователи с доступом только на чтение.
пусто
Для отчётов и аналитики.
 databases.<name>.extensions
Расширения PostgreSQL, включаемые в этой базе.
пусто
Когда приложению нужно расширение, например hstore или postgis.
 
Пользователей и базы можно добавлять и удалять после создания инстанса — платформа применит изменения к работающей базе.
 
Резервное копирование
 
Параметр
Что делает
Значение по умолчанию
Когда менять
 backup.enabled
Включает регулярные копии в S3-совместимое хранилище.
false
Для любых важных данных.
 backup.schedule
Расписание копий.
пусто
Под требования к точке восстановления.
 backup.retentionPolicy
Срок хранения копий.
30d
Под требования к глубине хранения.
 backup.destinationPath
Адрес бакета и путь, куда складываются копии.
заполнитель
Вместе с backup.enabled.
 backup.endpointURL
Адрес S3-совместимого хранилища.
заполнитель
Вместе с backup.enabled.
 backup.s3AccessKey / backup.s3SecretKey
Ключи доступа к хранилищу.
пусто
Вместе с backup.enabled.
 
Как задать расписание. Расписание пишется строкой из шести значений через пробел: секунда, минута, час, день месяца, месяц, день недели. Первое поле — именно секунды, этим формат отличается от привычного по cron, где полей пять. Звёздочка на месте значения означает «любое». Считать ничего не нужно — чаще всего подходит один из вариантов ниже.
 
Строка
Когда снимается копия
 0 0 2 * * *
каждый день в 2 часа ночи
 0 0 */6 * * *
каждые шесть часов
 0 30 3 * * 0
раз в неделю, в воскресенье в 3:30
 0 0 1 1 * *
раз в месяц, первого числа в час ночи
 
Чем чаще копии, тем меньше данных потеряется при сбое, но тем больше места они занимают в хранилище. Ночное время берут, чтобы копирование не накладывалось на дневную нагрузку.
 
Восстановление из копии
 
Параметр
Что делает
Значение по умолчанию
Когда менять
 bootstrap.enabled
Создать инстанс не пустым, а из резервной копии.
false
При восстановлении после сбоя или при проверке копии.
 bootstrap.oldName
Имя инстанса, копии которого разворачиваются.
пусто
Вместе с bootstrap.enabled.
 bootstrap.recoveryTime
Момент времени, на который восстанавливаться.
пусто — последнее состояние
Когда нужно откатиться на точку до ошибки.
 
ПРИМЕР КОНФИГУРАЦИИ
 
apiVersion: apps.cozystack.io/v1alpha1
kind: Postgres
metadata:
  name: pg01
spec:
  # Два экземпляра: primary и реплика.
  replicas: 2
  resourcesPreset: t1.micro
  resources: {}
 
  # Диск под данные каждого экземпляра.
  size: 10Gi
 
  # Неизменяемый параметр. В примере local: копия данных есть на реплике.
  storageClass: local
 
  # Доступ из интернета через отдельный адрес.
  external: true
 
  # Мажорная версия PostgreSQL.
  version: v18
 
  # Настройки сервера.
  postgresql:
    parameters:
      max_connections: "100"
 
  # Асинхронная репликация.
  quorum:
    minSyncReplicas: 0
    maxSyncReplicas: 0
 
  # Пользователь приложения.
  users:
    user01:
      password: "<пароль>"
 
  # База и права: user01 — администратор базы db01.
  databases:
    db01:
      roles:
        admin:
          - user01
 
Производные ресурсы получают префикс postgres-: сервисы postgres-<name>-rw, postgres-<name>-ro, postgres-<name>-r и postgres-<name>-external-write, секрет postgres-<name>-credentials.
 
ПРОВЕРКА
 
Понадобится клиент PostgreSQL. Консольный psql входит в комплект сервера и в отдельный пакет клиента: в дистрибутивах Linux это обычно postgresql-client, в Windows — установщик PostgreSQL, в macOS — пакет из Homebrew. Подойдёт и графический клиент, например DBeaver или pgAdmin. Проверить, что клиент на месте:
psql --version
 
Из того же пространства
 
Приложению внутри пространства доступен внутренний адрес сервиса записи. Полное имя — postgres-<name>-rw.tenant-<идентификатор-пространства>.svc.cozy.local, порт 5432:
psql "postgresql://user01:<пароль>@postgres-<name>-rw:5432/db01"
 
Снаружи
 
Возьмите адрес из колонки External IP у сервиса postgres-<name>-external-write:
psql "postgresql://user01:<пароль>@<внешний-IP>:5432/db01" -c "SELECT version();"
 
Ответ показывает версию сервера, который развернула платформа:
 PostgreSQL 18.1 (Debian 18.1-1.pgdg11+2) on x86_64-pc-linux-gnu, ...
 
Проверьте запись и чтение:
psql "postgresql://user01:<пароль>@<внешний-IP>:5432/db01" \
  -c "CREATE TABLE IF NOT EXISTS test (greeting text);" \
  -c "INSERT INTO test VALUES ('hello');" \
  -c "SELECT * FROM test;"
 
 
Ожидаемый ответ — подтверждения команд и вставленная строка:
CREATE TABLE
INSERT 0 1
 greeting
----------
 hello
 
Соединение шифруется: платформа включает TLS на стороне сервера, и отдельно настраивать его не нужно. Убедиться можно прямо в сессии:
psql "postgresql://user01:<пароль>@<внешний-IP>:5432/db01" \
  -c "SELECT ssl, version, cipher FROM pg_stat_ssl WHERE pid = pg_backend_pid();"
 ssl | version |         cipher
-----+---------+------------------------
 t   | TLSv1.3 | TLS_AES_256_GCM_SHA384
 
Если что-то не так
 
Ошибка
Причина
Что делать
 FATAL: password authentication failed for user "user01"
Неверный пароль или имя пользователя
Возьмите пароль заново на вкладке Secrets кнопкой копирования. Имя пользователя — то, что вы задали на шаге 3
 FATAL: database "..." does not exist
В адресе указана база, которой нет
Имя базы — то, что вы задали на шаге 4. Список баз виден в конфигурации инстанса на вкладке Overview
 Клиент долго ждёт и обрывается по таймауту
Внешний адрес не выдан или external не включён
Проверьте на вкладке Services, что у postgres-<name>-external-write есть адрес в колонке External IP
 could not translate host name
Внутреннее имя сервиса используется снаружи пространства
Изнутри пространства — короткое имя сервиса, снаружи — только внешний адрес
 
ЧТО ДАЛЬШЕ
 
  • Подключение из приложения — передайте драйверу адрес сервиса записи. Например, на Python:
    import psycopg
     
    conn = psycopg.connect(
        "postgresql://user01:<пароль>@postgres-<name>-rw:5432/db01"
    )
    with conn.cursor() as cur:
        cur.execute("SELECT 1")
        print(cur.fetchone())
     
    Для отчётов и аналитики используйте адрес postgres-<name>-ro — так тяжёлые выборки не мешают записи
     
  • Расширения — добавьте нужное в databases.<name>.extensions, платформа включит его в базе
  • Масштабирование — replicas и пресет ресурсов меняются в той же форме, диск можно только увеличивать, storageClass неизменяем
  • Резервное копирование — включите backup.* и регулярно проверяйте восстановление: разверните копию отдельным инстансом через bootstrap.* и сверьте данные. Копия, которую ни разу не восстанавливали, не считается рабочей
  • Удаление — удаление инстанса удаляет и его данные. Снимите копию заранее, если они ещё нужны.