From vmkteam-developer
Manages incremental PostgreSQL SQL migrations with pgmigrator CLI. Applies SQL files in YYYY-MM-DD format, supports transactional/NONTR/MANUAL modes, with plan/run/dryrun/verify commands.
npx claudepluginhub vmkteam/claude-plugins --plugin vmkteam-developerThis skill uses the workspace's default tool permissions.
pgmigrator (https://github.com/vmkteam/pgmigrator) — CLI для инкрементальных миграций PostgreSQL. Отслеживает выполненные миграции в таблице `public.pgMigrations`.
Mandates invoking relevant skills via tools before any response in coding sessions. Covers access, priorities, and adaptations for Claude Code, Copilot CLI, Gemini CLI.
Share bugs, ideas, or general feedback.
pgmigrator (https://github.com/vmkteam/pgmigrator) — CLI для инкрементальных миграций PostgreSQL. Отслеживает выполненные миграции в таблице public.pgMigrations.
brew tap vmkteam/tap
brew install pgmigrator
# или
make tools # в проектах vmkteam
Docker: vmkteam/pgmigrator на Docker Hub.
Обычно лежит рядом с миграциями, например docs/patches/pgmigrator.toml:
[App]
Table = "public.pgMigrations"
StatementTimeout = "5s"
FileMask = "\\d{4}-\\d{2}-\\d{2}-\\S+.sql"
[Database]
Addr = "localhost:5432"
User = "postgres"
Database = "dbname"
Password = "postgres"
PoolSize = 1
ApplicationName = "pgmigrator"
Типичная структура — docs/patches/:
docs/patches/
├── pgmigrator.toml
├── 2024/ # старые, по годам
├── 2025/
│ ├── 2025-01-14-dummy.sql
│ └── 2025-02-10-IX_orders-MANUAL.sql
├── 2026-01-29-rfmUsers.sql # транзакционная
├── 2026-02-01-add-index-NONTR.sql # нетранзакционная
└── 2026-02-03-add-partitions-MANUAL.sql # ручная
Имя: YYYY-MM-DD-<description>.sql. Применяются в алфавитном порядке.
| Суффикс | Поведение |
|---|---|
.sql | Транзакционная (BEGIN/COMMIT автоматически) |
-NONTR.sql | Без транзакции (для CREATE INDEX CONCURRENTLY) |
-MANUAL.sql | Игнорируется pgmigrator (ручное применение DBA) |
MANUAL — для операций которые нельзя автоматизировать: партиции, тяжёлые индексы на больших таблицах, миграции с downtime.
| Команда | Описание |
|---|---|
pgmigrator plan | Показать миграции к применению |
pgmigrator run | Применить все новые |
pgmigrator run 1 | Применить N миграций |
pgmigrator dryrun | Тест с откатом |
pgmigrator skip | Пометить выполненными без запуска |
pgmigrator last | Последние применённые |
pgmigrator verify | Проверить целостность (MD5) |
pgmigrator redo | Перезапустить последнюю |
pgmigrator init | Создать пример конфига |
Флаги: -c, --config (путь к конфигу), -d, --dir (директория миграций).
db-migrate:
@pgmigrator --config docs/patches/pgmigrator.toml run
-- 2026-01-29-rfmUsers.sql
CREATE TABLE "rfmUsers" (
"siteUserId" int4 NOT NULL,
"rfmSegmentApp" varchar(20) NOT NULL,
"updatedAt" timestamp with time zone NOT NULL DEFAULT now(),
PRIMARY KEY("siteUserId")
);
ALTER TABLE "rfmUsers" ADD CONSTRAINT "Ref_rfmUsers_to_siteUsers"
FOREIGN KEY ("siteUserId") REFERENCES "siteUsers"("siteUserId")
MATCH SIMPLE ON DELETE NO ACTION ON UPDATE NO ACTION NOT DEFERRABLE;
-- 2025-02-10-IX_orders_isActive-NONTR.sql
create index concurrently "IX_orders_isActive" on orders ("siteUserId")
where "statusId" IN (7, 4, 9, 10)
and "params"->>'isCompletedByUser' is distinct from 'true';
-- 2026-02-03-add-orders-210kk_220kk-partitions-MANUAL.sql
create table orders_210kk_220kk (like orders including all);
alter table orders attach partition orders_210kk_220kk
for values from (210000000) to (220000000);
analyse orders_210kk_220kk;
| Операция | Безопасно? | Комментарий |
|---|---|---|
| CREATE TABLE | Да | Не блокирует |
| ADD COLUMN (nullable) | Да | Быстро |
| ADD COLUMN (NOT NULL + DEFAULT) | PG11+ Да | На уровне каталога |
| DROP COLUMN | Да | Пометка в каталоге |
| CREATE INDEX | Нет | Блокирует → используй NONTR |
| CREATE INDEX CONCURRENTLY | Да | -NONTR.sql |
| ADD CONSTRAINT ... NOT VALID | Да | Не проверяет существующие |
| VALIDATE CONSTRAINT | Да | ShareUpdateExclusiveLock |
| Партиции (ATTACH/DETACH) | Зависит | -MANUAL.sql |
docs/{name}.sql всегда актуальный, make db пересоздаёт с нуля.docs/patches/, потому что нельзя пересоздать БД на devel.При этом docs/{name}.sql всегда держится в актуальном состоянии (и миграция, и основной файл обновляются).
.sql в docs/patches/-NONTR.sqlpgmigrator dryrun на devpgmigrator runmake mfd-xml → make mfd-model → make mfd-repo NS=<ns> (/mfd)pgmigrator dryrun на staging-NONTR.sql, партиции → -MANUAL.sqlpgmigrator verify — MD5 целостность