В этой практике ты поднимешь Postgres так же, как поднимал стенд в разделе про Compose: один каталог, один файл описания, одна команда. Потом заведёшь две таблицы магазина — покупателей и заказы. На них пройдёт весь раздел: запросы, изменения, индекс, резервная копия.
Начнём с базы из семи строк описания, которая уже работает, и будем смотреть, чего ей не хватает: Compose не знает, готова ли она, порт открыт всему миру, данные пропадают. Каждую находку закроем парой строк.
Шаг 1. Каталог и пароль
У стенда базы будет свой каталог, отдельный от остальных. Флаг -p у mkdir создаёт недостающие родительские каталоги и молчит, если каталог уже есть.
mkdir -p ~/infra/dbcd ~/infra/dbПароль придумывать не будем — попросим случайный. Команда openssl rand -hex 16 печатает 16 случайных байт в шестнадцатеричном виде, то есть 32 символа из цифр и букв a–f.
openssl rand -hex 163f9c1e7a52b04d8e9a61c0f2b7d34e15У тебя строка будет другой. Скопируй её и открой файл .env:
nano .envВпиши одну строку со своим значением и сохрани (Ctrl+O, Enter, Ctrl+X):
POSTGRES_PASSWORD=3f9c1e7a52b04d8e9a61c0f2b7d34e15Пароль лежит отдельно от описания по той же причине, что в разделе про Compose: файл описания уйдёт в Git, а .env — нет. Выбери его сейчас окончательно: позже увидишь, что база запоминает пароль при первом запуске и правка .env её уже не переубедит.
Шаг 2. Самая простая база
Файл описания начнём с минимума: какой образ взять и как назвать базу и пользователя.
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. Поднять и подключиться
Запускаем в фоне, как любой стек.
docker compose up -d✔ Network db_default Created ✔ Container db-db-1 Started
Compose создал сеть и контейнер. Имя db-db-1 сложено из имени проекта, имени службы и номера.
psql — консольный клиент Postgres, которым пользуются все, от разработчиков до администраторов. Он уже есть внутри контейнера, ставить ничего не нужно. Флаг -U — имя пользователя, -d — имя базы.
docker compose exec db psql -U shop -d shoppsql (17.10) Type "help" for help. shop=#
Приглашение shop=# означает, что ты внутри базы shop. Дальше набираешь не команды Linux, а команды psql и запросы SQL. Команды самого psql начинаются с обратной косой черты и не требуют точки с запятой. Первая — где я:
shop=# \conninfo You are connected to database "shop" as user "shop" via socket in "/var/run/postgresql" at port "5432".
Один сервер Postgres держит несколько баз. Команда \l их перечисляет (вывод сокращён до первых столбцов):
shop=# \l Name | Owner | Encoding -----------+-------+---------- postgres | shop | UTF8 shop | shop | UTF8 template0 | shop | UTF8 template1 | shop | UTF8
Наша — shop. База postgres служебная, туда подключаются утилиты, когда своей базы у них нет. template0 и template1 — образцы, из которых создаются новые базы; их не трогают. Выход из psql — \q.
База из семи строк работает. Дальше — чего ей не хватает.
Шаг 4. Готова ли база
Посмотри на состояние службы.
docker compose psNAME SERVICE STATUS PORTS db-db-1 db Up 4 seconds 5432/tcp
Up значит только «процесс жив». Готова ли база принимать подключения, Compose не знает — а именно этого ждут приложения, как ты видел в разделе про Compose. Добавь службе проверку здоровья, сразу под блоком environment.
healthcheck: test: ["CMD", "pg_isready", "-U", "shop", "-d", "shop"] interval: 5s
pg_isready — маленькая программа из комплекта Postgres, которая отвечает на один вопрос: принимает ли сервер подключения. Флаг -U задаёт имя пользователя, -d — имя базы. Применяем и сразу смотрим.
docker compose up -d ✔ Container db-db-1 Starteddocker compose psNAME SERVICE STATUS PORTS db-db-1 db Up Less than a second (health: starting) 5432/tcp
Первая проверка ещё не прошла. Через несколько секунд:
NAME SERVICE STATUS PORTS db-db-1 db Up 6 seconds (healthy) 5432/tcp
Если видишь unhealthy или контейнер перезапускается — смотри журнал, о нём ниже. Ту же программу можно спросить и руками: ей не нужен пароль, поэтому она первая команда при любой поломке.
docker compose exec db pg_isready -U shop/var/run/postgresql:5432 - accepting connectionsaccepting connections — база работает. Другие ответы: rejecting connections — база запускается или останавливается, no response — сервер не отвечает вовсе. А почему не поднялась, объяснит журнал. Флаг --tail 3 показывает только три последние строки.
docker compose logs db --tail 3db-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:
ports: - "5432:5432"
docker compose up -d ✔ Container db-db-1 StartedПосмотрим, кто теперь слушает порт. Команда ss -tln перечисляет открытые порты TCP.
ss -tln | grep 5432LISTEN 0 4096 0.0.0.0:5432 0.0.0.0:* LISTEN 0 4096 [::]:5432 [::]:*
0.0.0.0 — все адреса машины. К базе теперь может подключиться любой, кто видит сервер по сети, и единственная защита — пароль. Помни урок про порты: опубликованный порт Docker открывает в обход ufw, закрыть его там не получится. Базе наружу незачем. Допиши адрес петли перед номером порта.
ports: - "127.0.0.1:5432:5432"
docker compose up -d ✔ Container db-db-1 Startedss -tln | grep 5432LISTEN 0 4096 127.0.0.1:5432 0.0.0.0:*Теперь база доступна только с самой машины. Если однажды понадобится подключиться с ноутбука, для этого есть туннель SSH, а не открытый порт.
Шаг 6. Где живут данные
Проверим, переживут ли данные пересоздание стека. Подключись к базе той же командой psql, что в шаге 3, и заведи крошечную таблицу. Это SQL, поэтому в конце точка с запятой.
shop=# CREATE TABLE notes (t text); CREATE TABLE
Выйди из psql командой \q.
Теперь снимем стек и поднимем заново — так делают при любом обновлении.
docker compose down✔ Container db-db-1 Removed ✔ Network db_default Removed
docker compose up -d✔ Network db_default Created ✔ Container db-db-1 Started
Подожди, пока база станет healthy, снова подключись и спроси таблицу.
shop=# SELECT * FROM notes; ERROR: relation "notes" does not exist
Таблицы нет. Образ Postgres объявляет каталог данных /var/lib/postgresql/data томом, и Docker сам создал для него безымянный том. Новый контейнер получил новый, пустой безымянный том, а старый остался лежать на диске под длинным случайным именем, никому не нужный. При простом пересоздании контейнера Compose старый безымянный том подхватывает — поэтому потеря замечается не сразу, а в первый же down.
Лекарство — именованный том. Допиши службе монтирование, а в самый низ файла — раздел volumes.
volumes: - db-data:/var/lib/postgresql/data
volumes: db-data:
docker compose up -d✔ Volume db_db-data Created ✔ Container db-db-1 Started
Повтори опыт: создай таблицу notes, сделай down и up и снова спроси таблицу в psql.
shop=# SELECT * FROM notes; t --- (0 rows)
Таблица на месте: имя db_db-data Compose находит при каждом подъёме. Удалит его только docker compose down -v — запомни этот флаг как опасный. Учебная таблица больше не нужна, удали её и выйди из psql.
shop=# DROP TABLE notes; DROP TABLE
Шаг 7. Если пароля нет
Представим, что .env забыли скопировать на новую машину. Переименуем его на время.
mv .env .env.bakdocker compose up -dlevel=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 останавливается сам. Замени строку пароля:
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?задай пароль в .env}docker compose up -derror while interpolating services.db.environment.POSTGRES_PASSWORD: required variable POSTGRES_PASSWORD is missing a value: задай пароль в .envЗапуск прервался сразу и твоими словами. Возвращаем файл и поднимаем базу.
mv .env.bak .envdocker compose up -d ✔ Container db-db-1 StartedЕщё одна вещь, которую стоит знать про этот образ: тег 17 в имени закрепляет мажорную версию Postgres. Сменить её правкой тега нельзя: формат файлов данных у разных версий несовместим, и база на новом образе просто не стартует. Переход на новую мажорную версию — отдельная процедура с переносом данных.
Шаг 8. Что получилось
Сверь файл: служба, проверка, петля, именованный том, раздел volumes в самом низу.
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-#.
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, подробно разберём через урок.
shop=# INSERT INTO customers (name, city) VALUES ('Анна', 'Москва'), ('Борис', 'Казань'), ('Вера', 'Москва'), ('Глеб', 'Пермь'), ('Дина', 'Казань'); INSERT 0 5
INSERT 0 5 — вставлено пять строк. Ноль посередине — историческое поле, на него не смотрят.
Шаг 10. Таблица заказов на двести тысяч строк
Заказов нужно много: на пяти строках не увидеть ни разницы в скорости, ни пользы индекса. Сначала сама таблица. REFERENCES customers (id) говорит базе, что в заказе может стоять только номер существующего покупателя.
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, статус по кругу из трёх.
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 имя показывает устройство одной из них.
shop=# \dt Schema | Name | Type | Owner --------+-----------+-------+------- public | customers | table | shop public | orders | table | shop
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 на пальцах.