Provision
—— XP

Практика: Postgres в Compose

практика~25 минут+450 XP

В этой практике ты поднимешь Postgres так же, как поднимал стенд в разделе про Compose: один каталог, один файл описания, одна команда. Потом заведёшь две таблицы магазина — покупателей и заказы. На них пройдёт весь раздел: запросы, изменения, индекс, резервная копия.

Начнём с базы из семи строк описания, которая уже работает, и будем смотреть, чего ей не хватает: Compose не знает, готова ли она, порт открыт всему миру, данные пропадают. Каждую находку закроем парой строк.

Шаг 1. Каталог и пароль

У стенда базы будет свой каталог, отдельный от остальных. Флаг -p у mkdir создаёт недостающие родительские каталоги и молчит, если каталог уже есть.

ubuntu@stand:~$
mkdir -p ~/infra/db
ubuntu@stand:~$
cd ~/infra/db

Пароль придумывать не будем — попросим случайный. Команда openssl rand -hex 16 печатает 16 случайных байт в шестнадцатеричном виде, то есть 32 символа из цифр и букв a–f.

ubuntu@stand:~$
openssl rand -hex 16
ubuntu@stand:~$
3f9c1e7a52b04d8e9a61c0f2b7d34e15

У тебя строка будет другой. Скопируй её и открой файл .env:

ubuntu@stand:~$
nano .env

Впиши одну строку со своим значением и сохрани (Ctrl+O, Enter, Ctrl+X):

~/infra/db/.env
POSTGRES_PASSWORD=3f9c1e7a52b04d8e9a61c0f2b7d34e15

Пароль лежит отдельно от описания по той же причине, что в разделе про Compose: файл описания уйдёт в Git, а .env — нет. Выбери его сейчас окончательно: позже увидишь, что база запоминает пароль при первом запуске и правка .env её уже не переубедит.

Шаг 2. Самая простая база

Файл описания начнём с минимума: какой образ взять и как назвать базу и пользователя.

nano ~/infra/db/compose.yaml
services:
  db:
    image: postgres:17-alpine
    environment:
      POSTGRES_DB: shop
      POSTGRES_USER: shop
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}

Официальный образ при первом запуске сам создаёт базу и пользователя по трём переменным. POSTGRES_DB — имя базы, POSTGRES_USER — имя пользователя, POSTGRES_PASSWORD — его пароль, Compose подставит его из .env. Строки name: в начале, как в разделе 08, здесь нет: имя проекта Compose возьмёт по имени каталога, db, — отсюда имена db-db-1 и db_default, на которые опираются следующие разделы.

Шаг 3. Поднять и подключиться

Запускаем в фоне, как любой стек.

ubuntu@stand:~$
docker compose up -d
ubuntu@stand:~$
 ✔ Network db_default    Created
 ✔ Container db-db-1     Started

Compose создал сеть и контейнер. Имя db-db-1 сложено из имени проекта, имени службы и номера.

psql — консольный клиент Postgres, которым пользуются все, от разработчиков до администраторов. Он уже есть внутри контейнера, ставить ничего не нужно. Флаг -U — имя пользователя, -d — имя базы.

ubuntu@stand:~$
docker compose exec db psql -U shop -d shop
ubuntu@stand:~$
psql (17.10)
Type "help" for help.

shop=#

Приглашение shop=# означает, что ты внутри базы shop. Дальше набираешь не команды Linux, а команды psql и запросы SQL. Команды самого psql начинаются с обратной косой черты и не требуют точки с запятой. Первая — где я:

ubuntu@stand:~$
shop=# \conninfo
You are connected to database "shop" as user "shop" via socket in "/var/run/postgresql" at port "5432".

Один сервер Postgres держит несколько баз. Команда \l их перечисляет (вывод сокращён до первых столбцов):

ubuntu@stand:~$
shop=# \l
   Name    | Owner | Encoding
-----------+-------+----------
 postgres  | shop  | UTF8
 shop      | shop  | UTF8
 template0 | shop  | UTF8
 template1 | shop  | UTF8

Наша — shop. База postgres служебная, туда подключаются утилиты, когда своей базы у них нет. template0 и template1 — образцы, из которых создаются новые базы; их не трогают. Выход из psql — \q.

База из семи строк работает. Дальше — чего ей не хватает.

Шаг 4. Готова ли база

Посмотри на состояние службы.

ubuntu@stand:~$
docker compose ps
ubuntu@stand:~$
NAME      SERVICE   STATUS         PORTS
db-db-1   db        Up 4 seconds   5432/tcp

Up значит только «процесс жив». Готова ли база принимать подключения, Compose не знает — а именно этого ждут приложения, как ты видел в разделе про Compose. Добавь службе проверку здоровья, сразу под блоком environment.

в compose.yaml, у службы db
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "shop", "-d", "shop"]
      interval: 5s

pg_isready — маленькая программа из комплекта Postgres, которая отвечает на один вопрос: принимает ли сервер подключения. Флаг -U задаёт имя пользователя, -d — имя базы. Применяем и сразу смотрим.

ubuntu@stand:~$
docker compose up -d
ubuntu@stand:~$
 ✔ Container db-db-1     Started
ubuntu@stand:~$
docker compose ps
ubuntu@stand:~$
NAME      SERVICE   STATUS                                   PORTS
db-db-1   db        Up Less than a second (health: starting)   5432/tcp

Первая проверка ещё не прошла. Через несколько секунд:

ubuntu@stand:~$
NAME      SERVICE   STATUS                   PORTS
db-db-1   db        Up 6 seconds (healthy)   5432/tcp

Если видишь unhealthy или контейнер перезапускается — смотри журнал, о нём ниже. Ту же программу можно спросить и руками: ей не нужен пароль, поэтому она первая команда при любой поломке.

ubuntu@stand:~$
docker compose exec db pg_isready -U shop
ubuntu@stand:~$
/var/run/postgresql:5432 - accepting connections

accepting connections — база работает. Другие ответы: rejecting connections — база запускается или останавливается, no response — сервер не отвечает вовсе. А почему не поднялась, объяснит журнал. Флаг --tail 3 показывает только три последние строки.

ubuntu@stand:~$
docker compose logs db --tail 3
ubuntu@stand:~$
db-1  | LOG:  listening on Unix socket "/var/run/postgresql/.s.PGSQL.5432"
db-1  | LOG:  database system was shut down at 2026-10-23 11:01:50 UTC
db-1  | LOG:  database system is ready to accept connections

Последняя строка — то, что ты хочешь видеть. Слова FATAL и PANIC в журнале означают, что база не поднялась, а текст рядом с ними обычно прямо называет причину.

Шаг 5. Порт для клиентов снаружи контейнера

Пока до базы можно достучаться только изнутри контейнера. Чтобы подключались программы на самой машине — например, графический клиент или экспортёр метрик, — порт публикуют. Добавь под environment:

в compose.yaml, у службы db
    ports:
      - "5432:5432"
ubuntu@stand:~$
docker compose up -d
ubuntu@stand:~$
 ✔ Container db-db-1     Started

Посмотрим, кто теперь слушает порт. Команда ss -tln перечисляет открытые порты TCP.

ubuntu@stand:~$
ss -tln | grep 5432
ubuntu@stand:~$
LISTEN 0  4096     0.0.0.0:5432    0.0.0.0:*
LISTEN 0  4096        [::]:5432       [::]:*

0.0.0.0 — все адреса машины. К базе теперь может подключиться любой, кто видит сервер по сети, и единственная защита — пароль. Помни урок про порты: опубликованный порт Docker открывает в обход ufw, закрыть его там не получится. Базе наружу незачем. Допиши адрес петли перед номером порта.

в compose.yaml, у службы db
    ports:
      - "127.0.0.1:5432:5432"
ubuntu@stand:~$
docker compose up -d
ubuntu@stand:~$
 ✔ Container db-db-1     Started
ubuntu@stand:~$
ss -tln | grep 5432
ubuntu@stand:~$
LISTEN 0  4096   127.0.0.1:5432    0.0.0.0:*

Теперь база доступна только с самой машины. Если однажды понадобится подключиться с ноутбука, для этого есть туннель SSH, а не открытый порт.

Шаг 6. Где живут данные

Проверим, переживут ли данные пересоздание стека. Подключись к базе той же командой psql, что в шаге 3, и заведи крошечную таблицу. Это SQL, поэтому в конце точка с запятой.

ubuntu@stand:~$
shop=# CREATE TABLE notes (t text);
CREATE TABLE

Выйди из psql командой \q.

Теперь снимем стек и поднимем заново — так делают при любом обновлении.

ubuntu@stand:~$
docker compose down
ubuntu@stand:~$
 ✔ Container db-db-1   Removed
 ✔ Network db_default  Removed
ubuntu@stand:~$
docker compose up -d
ubuntu@stand:~$
 ✔ Network db_default    Created
 ✔ Container db-db-1     Started

Подожди, пока база станет healthy, снова подключись и спроси таблицу.

ubuntu@stand:~$
shop=# SELECT * FROM notes;
ERROR:  relation "notes" does not exist

Таблицы нет. Образ Postgres объявляет каталог данных /var/lib/postgresql/data томом, и Docker сам создал для него безымянный том. Новый контейнер получил новый, пустой безымянный том, а старый остался лежать на диске под длинным случайным именем, никому не нужный. При простом пересоздании контейнера Compose старый безымянный том подхватывает — поэтому потеря замечается не сразу, а в первый же down.

Лекарство — именованный том. Допиши службе монтирование, а в самый низ файла — раздел volumes.

в compose.yaml, у службы db
    volumes:
      - db-data:/var/lib/postgresql/data
в compose.yaml, в самый низ, без отступа
volumes:
  db-data:
ubuntu@stand:~$
docker compose up -d
ubuntu@stand:~$
 ✔ Volume db_db-data     Created
 ✔ Container db-db-1     Started

Повтори опыт: создай таблицу notes, сделай down и up и снова спроси таблицу в psql.

ubuntu@stand:~$
shop=# SELECT * FROM notes;
 t
---
(0 rows)

Таблица на месте: имя db_db-data Compose находит при каждом подъёме. Удалит его только docker compose down -v — запомни этот флаг как опасный. Учебная таблица больше не нужна, удали её и выйди из psql.

ubuntu@stand:~$
shop=# DROP TABLE notes;
DROP TABLE

Шаг 7. Если пароля нет

Представим, что .env забыли скопировать на новую машину. Переименуем его на время.

ubuntu@stand:~$
mv .env .env.bak
ubuntu@stand:~$
docker compose up -d
ubuntu@stand:~$
level=warning msg="The \"POSTGRES_PASSWORD\" variable is not set. Defaulting to a blank string."
 ✔ Container db-db-1     Recreated

Только предупреждение — и база запущена с пустым паролем в переменной. На уже созданном томе это сойдёт с рук: пароль записан внутри тома при первом запуске. А на пустом томе образ откажется стартовать с сообщением Database is uninitialized and superuser password is not specified — и узнаешь ты об этом из журнала, а не от Compose. Пусть Compose останавливается сам. Замени строку пароля:

в compose.yaml, у службы db
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?задай пароль в .env}
ubuntu@stand:~$
docker compose up -d
ubuntu@stand:~$
error while interpolating services.db.environment.POSTGRES_PASSWORD: required variable POSTGRES_PASSWORD is missing a value: задай пароль в .env

Запуск прервался сразу и твоими словами. Возвращаем файл и поднимаем базу.

ubuntu@stand:~$
mv .env.bak .env
ubuntu@stand:~$
docker compose up -d
ubuntu@stand:~$
 ✔ Container db-db-1     Started

Ещё одна вещь, которую стоит знать про этот образ: тег 17 в имени закрепляет мажорную версию Postgres. Сменить её правкой тега нельзя: формат файлов данных у разных версий несовместим, и база на новом образе просто не стартует. Переход на новую мажорную версию — отдельная процедура с переносом данных.

Шаг 8. Что получилось

Сверь файл: служба, проверка, петля, именованный том, раздел volumes в самом низу.

~/infra/db/compose.yaml
services:
  db:
    image: postgres:17-alpine
    environment:
      POSTGRES_DB: shop
      POSTGRES_USER: shop
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?задай пароль в .env}
    volumes:
      - db-data:/var/lib/postgresql/data
    ports:
      - "127.0.0.1:5432:5432"
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "shop", "-d", "shop"]
      interval: 5s

volumes:
  db-data:

Порядок ключей внутри службы Compose не важен, важны отступы.

Шаг 9. Таблица покупателей

Теперь учебные данные. Подключись к базе снова: docker compose exec db psql -U shop -d shop. Это SQL, поэтому в конце обязательна точка с запятой; без неё psql решит, что ты ещё не закончил, и сменит приглашение на shop-#.

ubuntu@stand:~$
shop=# CREATE TABLE customers (
  id   serial PRIMARY KEY,
  name text NOT NULL,
  city text NOT NULL
);
CREATE TABLE

serial — номер, который база проставляет сама: 1, 2, 3. PRIMARY KEY делает его первичным ключом. text NOT NULL — строка, которую нельзя оставить пустой. Теперь пять покупателей; как устроен INSERT, подробно разберём через урок.

ubuntu@stand:~$
shop=# INSERT INTO customers (name, city) VALUES
  ('Анна', 'Москва'), ('Борис', 'Казань'), ('Вера', 'Москва'),
  ('Глеб', 'Пермь'), ('Дина', 'Казань');
INSERT 0 5

INSERT 0 5 — вставлено пять строк. Ноль посередине — историческое поле, на него не смотрят.

Шаг 10. Таблица заказов на двести тысяч строк

Заказов нужно много: на пяти строках не увидеть ни разницы в скорости, ни пользы индекса. Сначала сама таблица. REFERENCES customers (id) говорит базе, что в заказе может стоять только номер существующего покупателя.

ubuntu@stand:~$
shop=# CREATE TABLE orders (
  id          serial PRIMARY KEY,
  customer_id int  NOT NULL REFERENCES customers (id),
  amount      int  NOT NULL,
  status      text NOT NULL,
  created_at  timestamptz NOT NULL DEFAULT now()
);
CREATE TABLE

Теперь данные. Функция generate_series(1, 200000) выдаёт числа от одного до двухсот тысяч, и из каждого числа i мы собираем заказ: покупатель по кругу от 1 до 5, сумма от 100 до 5099, статус по кругу из трёх.

ubuntu@stand:~$
shop=# INSERT INTO orders (customer_id, amount, status)
SELECT 1 + i % 5, 100 + i * 37 % 5000,
       (ARRAY['new','paid','done'])[1 + i % 3]
FROM generate_series(1, 200000) AS i;
INSERT 0 200000

Знак % — остаток от деления: i % 5 пробегает 0, 1, 2, 3, 4 и снова 0. Данные получаются одинаковыми у всех, кто проходит курс, поэтому числа в следующих уроках совпадут с твоими.

Шаг 11. Посмотреть, что получилось

Команда \dt перечисляет таблицы, \d имя показывает устройство одной из них.

ubuntu@stand:~$
shop=# \dt
 Schema |   Name    | Type  | Owner
--------+-----------+-------+-------
 public | customers | table | shop
 public | orders    | table | shop
ubuntu@stand:~$
shop=# \d orders
   Column    |           Type           | Nullable | Default
-------------+--------------------------+----------+---------------
 id          | integer                  | not null | nextval(...)
 customer_id | integer                  | not null |
 amount      | integer                  | not null |
 status      | text                     | not null |
 created_at  | timestamp with time zone | not null | now()
Indexes:
    "orders_pkey" PRIMARY KEY, btree (id)
Foreign-key constraints:
    "orders_customer_id_fkey" FOREIGN KEY (customer_id) REFERENCES customers(id)

Обрати внимание на Indexes: первичный ключ сам по себе создал индекс orders_pkey. О том, что это такое и почему он ускоряет поиск, будет отдельный урок. Ниже — связь с таблицей покупателей из REFERENCES. Выход из psql — \q.

Если что-то пошло не так

Почти все поломки этой практики видны в одном из трёх мест. docker compose ps показывает, жив ли контейнер. docker compose logs db --tail 20 объясняет, почему он не поднялся. Ошибка required variable POSTGRES_PASSWORD is missing a value — не создан .env или он лежит не в ~/infra/db. Ошибка port is already allocated значит, что порт 5432 уже занят другой базой на этой машине.

Есть и неочевидная ловушка. Переменные POSTGRES_DB и POSTGRES_USER срабатывают только при первом запуске, на пустом томе. Поменял имя пользователя в описании и перезапустил — ничего не изменится, потому что база уже создана. На учебном стенде лечится удалением тома (docker compose down -v), на рабочей базе так не делают никогда.

Что дальше

База жива, данные на месте. Следующий урок — о том, как их читать: язык SQL на пальцах.

Практика 01+450 XP

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

  • База поднята и здорова
  • Учебные данные на месте
  • База не смотрит наружу
  • Пароль лежит в .env
Команда сдачи — выполни на своей машине
команда
cd ~/infra/db 2>/dev/null || echo NODB; docker compose ps --format 'SVC={{.Service}} HEALTH={{.Health}}'; echo ORDERS=$(docker compose exec -T db psql -U shop -d shop -Atc 'SELECT count(*) FROM orders'); echo LOCAL=$(grep -c '127.0.0.1:5432' compose.yaml); echo ENVPASS=$(grep -c '^POSTGRES_PASSWORD=.' .env)

Нашёл ошибку или непонятное место? Наведи на абзац — слева появится «+», нажми и напиши, что не так. Замечание увидит автор курса.Нашёл ошибку или непонятное место? Нажми «+» справа от заголовка раздела и напиши, что не так. Замечание увидит автор курса.