sqlalchemy-shifter 0.1.0__tar.gz

sqlalchemy_shifter-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sqlalchemy-shifter contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sqlalchemy_shifter-0.1.0/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.3
+Name: sqlalchemy-shifter
+Version: 0.1.0
+Summary: A lightweight DB migration tool for SQLAlchemy
+Author: Alexey Volkov
+Author-email: webwizardry@hotmail.com
+Requires-Python: >=3.10
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: sqlalchemy (>=2.0.48,<3.0.0)
+Requires-Dist: typer (>=0.24.1,<0.25.0)
+Description-Content-Type: text/markdown
+
+# SQLAlchemy Shifter
+
+**SQLAlchemy Shifter** — это легковесный, модульный инструмент для управления миграциями баз данных поверх Python и SQLAlchemy. Идеологически вдохновлен системой миграций фреймворков уровня **Yii2** и **Laravel**.
+
+В отличие от Alembic, здесь нет сложного графа версий, "магической" связки состояний или жесткой привязки к одному файлу `alembic.ini`. Инструмент использует простой линейный подход, базируясь исключительно на таймстемпах файлов, и спроектирован для использования в современных микросервисных архитектурах (когда миграции могут поставляться разными пакетами).
+
+## Ключевые особенности
+
+- **Отсутствие Alembic-зависимостей**: Работает на чистом `SQLAlchemy Core`. Встроен собственный минималистичный DDL-генератор, никаких графов версионирования.
+- **ООП-транзакционность `up` / `safeUp`**: Базовый класс предоставляет два уровня методов миграции. Если необходимо выполнение внутри транзакции — логика описывается в `safeUp()`. Движок атомарно обернет её блоком `with connection.begin()`.
+- **Изоляция через Connection Names**: Миграция сама знает, к какой физической базе она относится (через флаг `connection = "default"`). Это дает возможность управлять несколькими базами данных из одной точки старта.
+- **Синхронно описываем, Асинхронно исполняем**: DDL-миграции пишутся синхронно, а применяются через `run_sync` в случае использования `AsyncEngine`.
+
+## Установка
+
+Используя Poetry:
+```bash
+poetry add sqlalchemy-shifter
+```
+
+Либо классическим pip:
+```bash
+pip install sqlalchemy-shifter
+```
+
+## Использование
+
+### 1. Создание заготовки миграции
+Для создания болванки файла миграции предусмотрен встроенный CLI.
+
+```bash
+python -m sqlalchemy_shifter.cli create create_users_table --path src/myapp/migrations --conn default
+```
+
+Эта команда сгенерирует файл `m20260401_120421_create_users_table.py` в указанной папке:
+
+```python
+from sqlalchemy_shifter.migration import Migration
+from sqlalchemy import Column, Integer, String
+
+class m20260401_120421_create_users_table(Migration):
+    
+    connection = "default"
+
+    def safeUp(self):
+        # Хелперы в стиле Yii2:
+        self.create_table(
+            "users",
+            Column("id", Integer, primary_key=True),
+            Column("username", String(255), nullable=False)
+        )
+        self.create_index("idx_username", "users", ["username"], unique=True)
+
+    def safeDown(self):
+        self.drop_index("idx_username", "users")
+        self.drop_table("users")
+```
+
+### 2. Запуск накатки (в коде приложения)
+
+В точке старта вашего приложения инициализируйте `ShifterService`, передав ему инстансы SQLAlchemy Engines и пути к папкам с реализованными миграциями.
+
+```python
+import asyncio
+from sqlalchemy.ext.asyncio import create_async_engine
+from sqlalchemy_shifter import ShifterService
+
+async def main():
+    engine_main = create_async_engine("sqlite+aiosqlite:///app.db")
+    
+    # 1. Инициализируем сервис
+    shifter = ShifterService(
+        engines={"default": engine_main},       # Маппинг подключений
+        paths=["src/myapp/migrations"]          # Директории с миграциями
+    )
+    
+    # 2. Выполняем миграции
+    applied_count = await shifter.upgrade_all()
+    print(f"Applied {applied_count} migrations.")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+> **Совет**: `ShifterService.upgrade_all()` проверяет таблицу состояния `shifter_migrations` конкретной базы. Если файл уже в статусе 'applied', он будет проигнорирован.
+
+## Лицензия
+
+Пакет поставляется по лицензии **MIT**. См. файл `LICENSE`.
+

sqlalchemy_shifter-0.1.0/README.md

@@ -0,0 +1,89 @@
+# SQLAlchemy Shifter
+
+**SQLAlchemy Shifter** — это легковесный, модульный инструмент для управления миграциями баз данных поверх Python и SQLAlchemy. Идеологически вдохновлен системой миграций фреймворков уровня **Yii2** и **Laravel**.
+
+В отличие от Alembic, здесь нет сложного графа версий, "магической" связки состояний или жесткой привязки к одному файлу `alembic.ini`. Инструмент использует простой линейный подход, базируясь исключительно на таймстемпах файлов, и спроектирован для использования в современных микросервисных архитектурах (когда миграции могут поставляться разными пакетами).
+
+## Ключевые особенности
+
+- **Отсутствие Alembic-зависимостей**: Работает на чистом `SQLAlchemy Core`. Встроен собственный минималистичный DDL-генератор, никаких графов версионирования.
+- **ООП-транзакционность `up` / `safeUp`**: Базовый класс предоставляет два уровня методов миграции. Если необходимо выполнение внутри транзакции — логика описывается в `safeUp()`. Движок атомарно обернет её блоком `with connection.begin()`.
+- **Изоляция через Connection Names**: Миграция сама знает, к какой физической базе она относится (через флаг `connection = "default"`). Это дает возможность управлять несколькими базами данных из одной точки старта.
+- **Синхронно описываем, Асинхронно исполняем**: DDL-миграции пишутся синхронно, а применяются через `run_sync` в случае использования `AsyncEngine`.
+
+## Установка
+
+Используя Poetry:
+```bash
+poetry add sqlalchemy-shifter
+```
+
+Либо классическим pip:
+```bash
+pip install sqlalchemy-shifter
+```
+
+## Использование
+
+### 1. Создание заготовки миграции
+Для создания болванки файла миграции предусмотрен встроенный CLI.
+
+```bash
+python -m sqlalchemy_shifter.cli create create_users_table --path src/myapp/migrations --conn default
+```
+
+Эта команда сгенерирует файл `m20260401_120421_create_users_table.py` в указанной папке:
+
+```python
+from sqlalchemy_shifter.migration import Migration
+from sqlalchemy import Column, Integer, String
+
+class m20260401_120421_create_users_table(Migration):
+    
+    connection = "default"
+
+    def safeUp(self):
+        # Хелперы в стиле Yii2:
+        self.create_table(
+            "users",
+            Column("id", Integer, primary_key=True),
+            Column("username", String(255), nullable=False)
+        )
+        self.create_index("idx_username", "users", ["username"], unique=True)
+
+    def safeDown(self):
+        self.drop_index("idx_username", "users")
+        self.drop_table("users")
+```
+
+### 2. Запуск накатки (в коде приложения)
+
+В точке старта вашего приложения инициализируйте `ShifterService`, передав ему инстансы SQLAlchemy Engines и пути к папкам с реализованными миграциями.
+
+```python
+import asyncio
+from sqlalchemy.ext.asyncio import create_async_engine
+from sqlalchemy_shifter import ShifterService
+
+async def main():
+    engine_main = create_async_engine("sqlite+aiosqlite:///app.db")
+    
+    # 1. Инициализируем сервис
+    shifter = ShifterService(
+        engines={"default": engine_main},       # Маппинг подключений
+        paths=["src/myapp/migrations"]          # Директории с миграциями
+    )
+    
+    # 2. Выполняем миграции
+    applied_count = await shifter.upgrade_all()
+    print(f"Applied {applied_count} migrations.")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+> **Совет**: `ShifterService.upgrade_all()` проверяет таблицу состояния `shifter_migrations` конкретной базы. Если файл уже в статусе 'applied', он будет проигнорирован.
+
+## Лицензия
+
+Пакет поставляется по лицензии **MIT**. См. файл `LICENSE`.

sqlalchemy_shifter-0.1.0/pyproject.toml

@@ -0,0 +1,18 @@
+[project]
+name = "sqlalchemy-shifter"
+version = "0.1.0"
+description = "A lightweight DB migration tool for SQLAlchemy"
+authors = [
+    {name = "Alexey Volkov",email = "webwizardry@hotmail.com"}
+]
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "sqlalchemy (>=2.0.48,<3.0.0)",
+    "typer (>=0.24.1,<0.25.0)",
+]
+
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"

sqlalchemy_shifter-0.1.0/sqlalchemy_shifter/__init__.py

@@ -0,0 +1,5 @@
+from sqlalchemy_shifter.service import ShifterService
+from sqlalchemy_shifter.migration import Migration
+from sqlalchemy_shifter.builder import SchemaBuilder
+
+__all__ = ["ShifterService", "Migration", "SchemaBuilder"]

sqlalchemy_shifter-0.1.0/sqlalchemy_shifter/builder.py

@@ -0,0 +1,85 @@
+from typing import Any
+from sqlalchemy.engine import Connection
+from sqlalchemy.schema import Table, MetaData, CreateTable, DropTable, Index, CreateIndex, DropIndex, DDLElement, Column
+from sqlalchemy.ext.compiler import compiles
+
+
+# Custom DDL Commands for SQLAlchemy
+
+class AddColumn(DDLElement):
+    __visit_name__ = "add_column"
+    def __init__(self, table_name: str, column: Column):
+        self.table_name = table_name
+        self.column = column
+
+
+class DropColumn(DDLElement):
+    __visit_name__ = "drop_column"
+    def __init__(self, table_name: str, column_name: str):
+        self.table_name = table_name
+        self.column_name = column_name
+
+
+@compiles(AddColumn)
+def visit_add_column(element: AddColumn, compiler: Any, **kw: Any) -> str:
+    table = Table(element.table_name, MetaData())
+    column_spec = compiler.get_column_specification(element.column)
+    return "ALTER TABLE %s ADD COLUMN %s" % (
+        compiler.preparer.format_table(table),
+        column_spec
+    )
+
+
+@compiles(DropColumn)
+def visit_drop_column(element: DropColumn, compiler: Any, **kw: Any) -> str:
+    table = Table(element.table_name, MetaData())
+    column_name = compiler.preparer.quote(element.column_name)
+    return "ALTER TABLE %s DROP COLUMN %s" % (
+        compiler.preparer.format_table(table),
+        column_name
+    )
+
+
+class SchemaBuilder:
+    """
+    Легковесный DDL хелпер. 
+    Обеспечивает Yii2-style синтаксис чисто поверх SQLAlchemy Core (без Alembic).
+    """
+
+    def __init__(self, connection: Connection):
+        self._connection = connection
+
+    def execute(self, sql: Any, *args, **kwargs) -> Any:
+        from sqlalchemy import text
+        if isinstance(sql, str):
+            sql = text(sql)
+        return self._connection.execute(sql, *args, **kwargs)
+
+    def create_table(self, table_name: str, *columns: Column) -> None:
+        # Привязываем колонки к абстрактной таблице для генерации DDL
+        table = Table(table_name, MetaData(), *columns)
+        self.execute(CreateTable(table))
+
+    def drop_table(self, table_name: str) -> None:
+        table = Table(table_name, MetaData())
+        self.execute(DropTable(table))
+
+    def add_column(self, table_name: str, column: Column) -> None:
+        self.execute(AddColumn(table_name, column))
+
+    def drop_column(self, table_name: str, column_name: str) -> None:
+        self.execute(DropColumn(table_name, column_name))
+
+    def create_index(self, index_name: str, table_name: str, columns: list[str], unique: bool = False) -> None:
+        # Для индексов оборачиваем названия во временные объекты, чтобы компилятор их понял
+        table = Table(table_name, MetaData(), *(Column(c) for c in columns))
+        cols = [getattr(table.c, c) for c in columns]
+        idx = Index(index_name, *cols, unique=unique)
+        self.execute(CreateIndex(idx))
+
+    def drop_index(self, index_name: str, table_name: str) -> None:
+        table = Table(table_name, MetaData())
+        idx = Index(index_name)
+        # Указание таблицы необходимо только для генерации диалектно корректного DROP
+        idx.table = table
+        self.execute(DropIndex(idx))

sqlalchemy_shifter-0.1.0/sqlalchemy_shifter/cli.py

@@ -0,0 +1,53 @@
+import os
+import typer
+from datetime import datetime
+
+app = typer.Typer(help="SQLAlchemy Shifter CLI")
+
+
+@app.command()
+def create(
+    name: str = typer.Argument(..., help="Имя миграции, например: create_users_table"),
+    path: str = typer.Option("migrations", "--path", "-p", help="Путь до директории с миграциями"),
+    connection: str = typer.Option("default", "--conn", "-c", help="Имя соединения базы данных")
+):
+    """
+    Создает новый шаблонный файл миграции.
+    """
+    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    filename = f"m{timestamp}_{name}.py"
+    filepath = os.path.join(path, filename)
+    
+    os.makedirs(path, exist_ok=True)
+    
+    safe_name = name.replace('-', '_')
+    tpl = f'''from sqlalchemy_shifter.migration import Migration
+from sqlalchemy import text
+
+
+class m{timestamp}_{safe_name}(Migration):
+    
+    connection = "{connection}"
+
+    def safeUp(self):
+        """
+        Метод выполняется внутри транзакции (оборачивается автоматическим begin).
+        Здесь вы можете использовать DDL хелперы:
+        self.create_table('users', ...)
+        """
+        pass
+
+    def safeDown(self):
+        """
+        Откат миграции. Выполняется внутри транзакции.
+        """
+        pass
+'''
+    with open(filepath, "w", encoding="utf-8") as f:
+        f.write(tpl)
+        
+    typer.secho(f"Миграция создана: {filepath}", fg=typer.colors.GREEN)
+
+
+if __name__ == "__main__":
+    app()

sqlalchemy_shifter-0.1.0/sqlalchemy_shifter/migration.py

@@ -0,0 +1,39 @@
+from sqlalchemy.engine import Connection
+from sqlalchemy_shifter.builder import SchemaBuilder
+
+
+class Migration(SchemaBuilder):
+    """
+    Базовый класс миграций, реализующий транзакционность через методы up() и down().
+    Если логика требует транзакции - переопределяйте safeUp() / safeDown().
+    Если логика НЕ требует транзакции - переопределяйте up() / down().
+    """
+
+    connection: str = "default"  # по умолчанию привязываем к коннекту 'default'
+
+    def __init__(self, connection: Connection):
+        super().__init__(connection)
+
+    def safeUp(self) -> None:
+        """Метод для безопасного применения миграции внутри транзакции."""
+        pass
+
+    def safeDown(self) -> None:
+        """Метод для безопасного отката миграции внутри транзакции."""
+        pass
+
+    def up(self) -> None:
+        """
+        Открывает транзакцию и вызывает safeUp.
+        Вызывается движком ShifterService.
+        """
+        with self._connection.begin():
+            self.safeUp()
+
+    def down(self) -> None:
+        """
+        Открывает транзакцию и вызывает safeDown.
+        Вызывается движком ShifterService.
+        """
+        with self._connection.begin():
+            self.safeDown()

sqlalchemy_shifter-0.1.0/sqlalchemy_shifter/service.py

@@ -0,0 +1,134 @@
+import os
+import importlib.util
+import inspect
+from sqlalchemy.ext.asyncio import AsyncEngine
+from sqlalchemy.engine import Engine
+
+from sqlalchemy_shifter.state import StateManager
+from sqlalchemy_shifter.migration import Migration
+
+
+class ShifterService:
+    """
+    Движок для управления миграциями.
+    Принимает маппинг движков SQLAlchemy и список директорий.
+    """
+
+    def __init__(self, engines: dict[str, Engine | AsyncEngine], paths: list[str]):
+        self.engines = engines
+        self.paths = paths
+
+    def _load_migrations(self):
+        """
+        Обходит директории и загружает все классы миграций.
+        Возвращает список словарей: [{'version': str, 'cls': type[Migration]}]
+        """
+        migrations = []
+        for path in self.paths:
+            if not os.path.exists(path):
+                continue
+
+            for root, _, files in os.walk(path):
+                for file in files:
+                    if file.startswith("m") and file.endswith(".py"):
+                        version = file[:-3]  # отрезаем .py
+                        filepath = os.path.join(root, file)
+                        
+                        # динамически импортируем модуль
+                        spec = importlib.util.spec_from_file_location(version, filepath)
+                        if spec and spec.loader:
+                            module = importlib.util.module_from_spec(spec)
+                            spec.loader.exec_module(module)
+
+                            # ищем класс, унаследованный от Migration
+                            for name, obj in inspect.getmembers(module):
+                                if inspect.isclass(obj) and issubclass(obj, Migration) and obj is not Migration:
+                                    migrations.append({
+                                        "version": version,
+                                        "cls": obj
+                                    })
+                                    break
+        return migrations
+
+    async def upgrade_all(self):
+        """Ищет непримененные миграции и накатывает их по хронологии."""
+        migrations = self._load_migrations()
+        # сортируем файлы по имени (таймстемпу)
+        migrations.sort(key=lambda x: x["version"])
+
+        applied_count = 0
+        for mig_dict in migrations:
+            version = mig_dict["version"]
+            migration_cls = mig_dict["cls"]
+            
+            # Проверяем соединение для этой миграции
+            conn_name = getattr(migration_cls, "connection", "default")
+            engine = self.engines.get(conn_name)
+            
+            if not engine:
+                raise ValueError(f"Engine '{conn_name}' not found for migration {version}")
+
+            if await self._apply_single_migration(engine, version, migration_cls):
+                applied_count += 1
+
+        return applied_count
+
+    async def _apply_single_migration(self, engine, version: str, migration_cls) -> bool:
+        """
+        Обертка над синхронным выполнением (работает для Sync и Async).
+        """
+        def _sync_upgrade(conn):
+            state = StateManager(conn)
+            # Если миграция уже была в этой БД, пропускаем
+            if version in state.get_applied_migrations():
+                return False
+            
+            print(f"Applying migration: {version} (Connection: {migration_cls.connection})")
+            
+            # Инстанцируем и выполняем up()
+            mig_instance = migration_cls(conn)
+            mig_instance.up()
+            
+            # Сохраняем состояние
+            state.add_migration(version)
+            print(f"Success: {version}")
+            return True
+
+        if isinstance(engine, AsyncEngine):
+            # Асинхронный движок
+            async with engine.connect() as async_conn:
+                return await async_conn.run_sync(_sync_upgrade)
+        else:
+            # Синхронный движок
+            with engine.connect() as sync_conn:
+                return _sync_upgrade(sync_conn)
+
+    async def create_migration_file(self, path: str, name: str):
+        """Создает файл миграции с таймстемпом."""
+        import time
+        from datetime import datetime
+        
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+        filename = f"m{timestamp}_{name}.py"
+        filepath = os.path.join(path, filename)
+        
+        os.makedirs(path, exist_ok=True)
+        
+        tpl = f'''from sqlalchemy_shifter.migration import Migration
+from sqlalchemy import text
+
+
+class {name.capitalize()}Migration(Migration):
+    connection = "default"
+
+    def safeUp(self):
+        pass
+
+    def safeDown(self):
+        pass
+'''
+        with open(filepath, "w", encoding="utf-8") as f:
+            f.write(tpl)
+            
+        print(f"Created new migration: {filepath}")
+        return filepath

sqlalchemy_shifter-0.1.0/sqlalchemy_shifter/state.py

@@ -0,0 +1,51 @@
+import time
+from sqlalchemy import Table, Column, String, Integer, MetaData
+from sqlalchemy.engine import Connection
+
+class StateManager:
+    """
+    Управляет таблицей истории миграций.
+    Обеспечивает создание таблицы и получение/запись состояния.
+    """
+
+    TABLE_NAME = "shifter_migrations"
+
+    def __init__(self, connection: Connection):
+        self.connection = connection
+        self.metadata = MetaData()
+        self.table = Table(
+            self.TABLE_NAME,
+            self.metadata,
+            Column('version', String(255), primary_key=True),
+            Column('apply_time', Integer)
+        )
+
+    def ensure_table_exists(self):
+        """Создает таблицу, если её нет. Закрывает транзакцию."""
+        self.table.create(self.connection, checkfirst=True)
+        # В SQLAlchemy 2.0 любые операции открывают транзакцию по умолчанию.
+        # Мы коммитим её, чтобы подготовить коннект для последующего with conn.begin()
+        self.connection.commit()
+
+    def get_applied_migrations(self) -> list[str]:
+        """Возвращает список примененных версий. Закрывает read-транзакцию."""
+        self.ensure_table_exists()
+        stmt = self.table.select().order_by(self.table.c.apply_time.asc())
+        result = self.connection.execute(stmt)
+        versions = [row.version for row in result]
+        self.connection.commit()  # освобождаем коннект
+        return versions
+
+    def add_migration(self, version: str):
+        """Записывает миграцию в историю."""
+        self.ensure_table_exists()
+        stmt = self.table.insert().values(version=version, apply_time=int(time.time()))
+        self.connection.execute(stmt)
+        self.connection.commit()
+
+    def remove_migration(self, version: str):
+        """Удаляет миграцию из истории."""
+        self.ensure_table_exists()
+        stmt = self.table.delete().where(self.table.c.version == version)
+        self.connection.execute(stmt)
+        self.connection.commit()