dbevo 0.0.1

Database schema migrations for Python. Inspired by Play Framework Evolutions.

dbevo

Database schema migrations for Python.

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

---

📋 Содержание

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

---

🚀 Установка

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

poetry install

---

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

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

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

DBEVO_DATABASE_URL=postgresql://user:password@localhost:5432/mydb
DBEVO_MIGRATIONS_PATH=migrations
DBEVO_TEMPLATE_PATH=src/dbevo/templates/migration.sql.j2

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

---

⚙️ Конфигурация

Конфигурация загружается в следующем порядке (приорет сверху вниз):

1. Переменные окружения (префикс DBEVO_)
2. Файл .env
3. Значения по умолчанию

Доступные переменные

Переменная	Описание	По умолчанию
DBEVO_DATABASE_URL	PostgreSQL DSN	-
DBEVO_MIGRATIONS_PATH	Путь к миграциям	migrations
DBEVO_TEMPLATE_PATH	Шаблон миграции	src/dbevo/templates/migration.sql.j2
DBEVO_SCHEMA_NAME	Схема БД	dbevo
DBEVO_GENERATE_OUTPUT	Выходная директория для генерации моделей	src/dbevo/models

---

🛠 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 <[e-mail]>
-- 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