Git и база данных: инструменты и ошибки новичков

За 20–30 минут вы создадите SQL-миграцию для PostgreSQL 16, сохраните её в Git и примените к локальной базе. Важный нюанс: Git хранит файлы, а не состояние вашей базы. Поэтому рабочая схема — версионировать изменения SQL, а не надеяться, что расширение редактора синхронизирует базу с репозиторием.

Что подготовить

Инструкция рассчитана на PostgreSQL 16 и командную строку psql версии 16. Понадобятся установленный Git, уже созданная локальная база и пользователь, которому разрешено создавать таблицы. Команды показаны для Linux, macOS или WSL; в PowerShell кавычки и создание папок могут отличаться.

• Проверьте версии командами psql --version и git --version. Для сервера PostgreSQL 16 используйте клиент psql 16.
• Уточните у администратора или в настройках проекта имя базы и пользователя. Пароль вводите по запросу клиента, не помещайте его в команду или файл репозитория.
• Откройте каталог проекта, который уже связан с Git, или создайте для него отдельный каталог.

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

Настройте простой процесс

1. В корне проекта создайте каталог для миграций и проверьте, что Git видит его содержимое после добавления файла.

   mkdir -p migrations

   Проверка: каталог migrations появился рядом с файлами проекта.

2. Создайте файл migrations/001_create_customers.sql. В нём будет описано одно изменение схемы: создание таблицы клиентов.

   CREATE TABLE public.customers (
       id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
       email text NOT NULL UNIQUE,
       created_at timestamptz NOT NULL DEFAULT now()
   );

   Проверка: в файле есть SQL-команда целиком, файл сохранён именно с расширением .sql. Это и есть миграция — отдельный файл с последовательным изменением структуры базы.

3. Примените миграцию к локальной базе. Замените заглушки именем пользователя и базы; psql запросит пароль, если он требуется.

   psql -h localhost -U YOUR_DB_USER -d YOUR_DB_NAME -v ON_ERROR_STOP=1 -f migrations/001_create_customers.sql

   Проверка: psql завершился без ошибки и сообщил о создании таблицы. Параметр -v ON_ERROR_STOP=1 заставляет клиента остановиться при SQL-ошибке, а не продолжать выполнение файла.

4. Убедитесь, что таблица появилась. Запрос вернёт строку customers, если таблица существует в схеме public.

   psql -h localhost -U YOUR_DB_USER -d YOUR_DB_NAME -c 'SELECT table_name FROM information_schema.tables WHERE table_schema = ''public'' AND table_name = ''customers'';'

   Проверка: в выводе есть customers. Если строк нет, проверьте, что подключились к нужной базе.

5. Добавьте миграцию в Git и зафиксируйте её. В репозитории должна оказаться инструкция по изменению базы, а не сама база или файл с паролем.

   git add migrations/001_create_customers.sql
   git commit -m "Add customers table"

   Проверка: команда git status --short не показывает эту миграцию как незакоммиченное изменение.

Не запускайте файл 001_create_customers.sql повторно: он создаёт таблицу, которая уже существует, и завершится ошибкой. Для следующего изменения создайте новый файл, например 002_add_customer_name.sql, вместо того чтобы переписывать уже применённую миграцию.

Git может показать, кто изменил SQL-файл и когда. Но только отдельные миграции объясняют, как привести пустую или отставшую базу к нужной версии.

Что новички чаще всего делают не так

• Коммитят дамп базы целиком. Он может содержать данные, быть большим и давать шумные различия между версиями. Для истории изменений схемы удобнее миграции. Дамп нужен для резервного копирования и переноса; у pg_dump есть режим, который сохраняет только определения объектов, но это не заменяет историю последовательных изменений.
• Правят старую миграцию после её применения. У коллеги она уже могла выполниться. Тогда его база и ваша получат разные схемы при одинаковом номере миграции. Опубликованные или применённые миграции обычно оставляют неизменными: исправление оформляют новым файлом.
• Добавляют пароль в команду, SQL-файл или настройки проекта. Секрет может попасть в историю Git и остаться там даже после удаления файла. Не коммитьте пароли и локальные конфигурации с секретами; если секрет уже попал в репозиторий, считайте его раскрытым и смените.
• Считают, что успешный commit изменил базу. Коммит фиксирует файл в репозитории, но не запускает SQL. Миграцию нужно применить отдельно к каждой базе, которой требуется это изменение.
• Запускают миграцию не на той базе. В командах подключения легко перепутать тестовую и рабочую среду. До выполнения проверьте имя базы и адрес сервера, особенно если в терминале открыто несколько проектов.

Расширения для Git в редакторе могут подсветить изменения и историю файлов, а SQL-клиент — помочь подключиться к PostgreSQL. Но они не заменяют SQL-миграции и не делают автоматически одинаковыми локальную, тестовую и рабочую базы. Начать можно с Git и psql; добавлять GUI-инструменты имеет смысл, если они решают конкретную задачу команды.

Сноска. Миграция базы данных — файл с изменениями схемы или данных, который применяют в определённом порядке. Сам Git не знает, какие миграции уже выполнялись в конкретной базе.

Если не получилось

• psql: command not found. Клиент psql не установлен или система не находит его в путях команд. Установите клиент PostgreSQL 16 или запустите его из каталога установки.
• connection refused. Сервер не запущен, либо адрес и порт подключения неверны. Проверьте, работает ли локальный PostgreSQL и слушает ли он указанный адрес.
• password authentication failed. Сервер отклонил пароль для указанного пользователя. Проверьте имя пользователя и пароль у администратора базы; не публикуйте их в переписке или Git.
• relation "customers" already exists. Миграция уже применялась или таблицу создали вручную. Не удаляйте таблицу вслепую: проверьте её содержимое и историю изменений, затем решите, нужно ли оформить следующее изменение отдельной миграцией.

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

Этот ручной способ подходит для знакомства с миграциями и небольшого локального проекта, но не отслеживает автоматически, какие файлы уже применены. Перед командной разработкой или развёртыванием выберите систему управления миграциями для своего стека и настройте её таблицу учёта. Затем проверьте процесс на копии базы: примените миграции с нуля, повторно разверните приложение и убедитесь, что рабочие данные не теряются. Отдельно настройте резервное копирование — Git не является бэкапом базы.