dbevo

Database schema migrations for Python.

Легковесный фреймворк для управления миграциями базы данных, вдохновленный Play Framework Evolutions.

---

📋 Содержание

• Установка
• Быстрый старт
• CLI Команды
• Структура миграций
• Примеры
• Разработка
• Лицензия

---

🚀 Установка

git clone https://github.com/xDarkmanx/dbevo.git
cd dbevo

poetry install

---

⚡ Быстрый старт

1. Настройка окружения

Создайте файл .dbevo.toml в корне проекта:

[dbevo]
author = "You name <you@email>"
project = "dbevo"
auto_apply = false
dry_run = false
verbose = true

[dbevo.database]
database_uri="postgresql://user:pass@localhost:5432/database"
pool_min_size = 1
pool_max_size = 10
command_timeout = 60

[dbevo.migrations]
path = "dbevo"
table = "dbevo.migrations"
groups_table = "dbevo.migration_groups"
history_table = "dbevo.migration_history"
lock_table = "dbevo.locks"
config_table = "dbevo.config"

[dbevo.generate]
migration_template = "templates/migration.sql.j2"
sqlalchemy_template = "templates/sqlalchemy.py.j2"
pydantic_template = "templates/pydantic.py.j2"

[dbevo.generate.exclude]
columns = ["id", "create_at", "update_at"]
technical = false
sensitive = false
foreign_keys = false

2. Инициализация схемы отслеживания

dbevo init

Создаёт схему dbevo с таблицами для отслеживания применённых миграций.

3. Создание новой миграции

dbevo new add_user_table --schema core

Создаёт файл: migrations/core/000001__add_user_table.sql

4. Применение миграций

dbevo apply

5. Проверка статуса

dbevo status

---

🛠 CLI Команды

dbevo init

Инициализирует схему отслеживания миграций в базе данных.

dbevo init [--debug]

dbevo status

Показывает статус всех миграций.

dbevo status [--debug]

Пример вывода:

dbevo status

Database: postgresql://localhost:5432/mydb
Migrations path: migrations

┌────────────────────────────────────┬─────────────┬──────────┬────────────────┐
│ Migration                          │ Group       │ Status   │ Applied At     │
├────────────────────────────────────┼─────────────┼──────────┼────────────────┤
│ 000001__init_core_schema           │ core        │ applied  │ 2026-03-30 10: │
│ 000002__init_utils_schema          │ utils       │ applied  │ 2026-03-30 10: │
│ 000003__create_update_trigger_func │ utils       │ pending  │ -              │
└────────────────────────────────────┴─────────────┴──────────┴────────────────┘

Total: 1 pending, 2 applied

dbevo apply

Применяет все ожидающие миграции.

dbevo apply [--debug] [--auto-confirm] [--dry-run]

Опции:

Опция	Описание
--debug	Включить debug вывод
--auto-confirm	Пропустить подтверждение
--dry-run	Показать SQL без выполнения

dbevo revert

Откатывает миграции до указанной версии.

dbevo revert --to 000002 [--debug] [--dry-run] [--auto-confirm] [--force]

Опции:

Опция	Описание
--to	Номер миграции, к которой откатиться
--dry-run	Показать SQL без выполнения
--auto-confirm	Пропустить подтверждение
--force	Принудительно, даже если файл изменён

dbevo new

Создаёт новый файл миграции.

dbevo new <description> [--schema <schema_name>]

Примеры:

dbevo new add_user_table --schema core
dbevo new add_email_column --schema utils

dbevo generate

Генерирует Pydantic-модели из схемы базы данных.

dbevo generate models [--output <path>]

---

📁 Структура миграций

Миграции организованы по группам (схемам) и имеют глобальный номер.

migrations/
├── core/
│   ├── 000001__init_core_schema.sql
│   └── 000004__add_user_table.sql
└── utils/
    ├── 000002__init_utils_schema.sql
    ├── 000003__create_indexes.sql
    └── 000005__create_update_trigger_function.sql

Формат имени файла

<6-digit-number>__<description>.sql

• Номер: 6 цифр, глобальная нумерация
• Описание: snake_case, описывает изменения

Формат миграции

------------------------------------------------------------------------------------------------------------------------
-- Author: Semenets Pavel <p.semenets@gmail.com>
-- Project: dbevo
-- Schema: utils
-- Create: Date: 2026-03-30
-- Migration: 000002__init_utils_schema
------------------------------------------------------------------------------------------------------------------------

-- !Ups
------------------------------------------------------------------------------------------------------------------------
-- Desc: init_utils_schema
------------------------------------------------------------------------------------------------------------------------
CREATE SCHEMA IF NOT EXISTS "utils";
COMMENT ON SCHEMA "utils" IS 'core schema';


-- !Ups end

-- !Downs
------------------------------------------------------------------------------------------------------------------------
-- Desc: Rollback
------------------------------------------------------------------------------------------------------------------------
DROP SCHEMA IF EXISTS "utils";


-- !Downs end

Секции:

Секция	Описание
-- !Ups	SQL для применения миграции
-- !Downs	SQL для отката миграции

Откат до конкретной версии

# Откат всех миграций после 000002
dbevo revert --to 2

# Откат с подтверждением
dbevo revert --to 000002 --auto-confirm

Dry-run для проверки SQL

# Проверка перед применением
dbevo apply --dry-run

# Проверка перед откатом
dbevo revert --to 000002 --dry-run

---

🔧 Разработка

Зависимости

poetry install --with lint,test,security

Запуск тестов

poetry run pytest

Linting

poetry run flake8 src/
poetry run bandit -r src/

---

📄 Лицензия

MIT License. См. LICENSE для деталей.

---

🤝 Вклад

Приветствуются Pull Requests! Пожалуйста, сначала обсудите изменения в issue.

---

📚 См. также

• Play Framework Evolutions
• Alembic
• Flyway
• Liquibase