https://github.com/vanderhoof/alembic-dddl
Alembic extension that adds support for arbitrary user-defined objects like views or functions in autogenerate command.
https://github.com/vanderhoof/alembic-dddl
alembic alembic-extension autogenerate database ddl migration sqlalchemy
Last synced: 10 months ago
JSON representation
Alembic extension that adds support for arbitrary user-defined objects like views or functions in autogenerate command.
- Host: GitHub
- URL: https://github.com/vanderhoof/alembic-dddl
- Owner: Vanderhoof
- License: mit
- Created: 2023-12-26T10:27:52.000Z (over 2 years ago)
- Default Branch: master
- Last Pushed: 2024-12-08T17:39:13.000Z (over 1 year ago)
- Last Synced: 2024-12-08T18:29:02.908Z (over 1 year ago)
- Topics: alembic, alembic-extension, autogenerate, database, ddl, migration, sqlalchemy
- Language: Python
- Homepage:
- Size: 99.6 KB
- Stars: 9
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Alembic Dumb DDL
[](https://pypi.org/project/alembic-dddl/) [](https://github.com/Vanderhoof/alembic-dddl)  [](https://codecov.io/gh/Vanderhoof/alembic-dddl) [](https://pypi.org/project/alembic-dddl/)
A plugin for [Alembic](https://alembic.sqlalchemy.org/en/latest/) DB migration tool that adds support for arbitrary user-defined objects like views, functions, triggers, etc. in autogenerate command.
Alembic DDDL _does not_ compare the objects in the code with their state in the database. Instead, it **only tracks if the source code of the script has changed**, compared to the previous revision.
## Installation
You can install Alembic Dumb DDL from pip:
```shell
pip install alembic-dddl
```
## Quick start
Step 1: save your DDL script in a file, and make sure that it overwrites the entities, not just creates them (e.g. start with `DROP ... IF EXISTS` or a similar construct for your DBMS).
```sql
-- myapp/scripts/last_month_orders.sql
DROP VIEW IF EXISTS last_month_orders;
CREATE VIEW last_month_orders AS
SELECT *
FROM orders
WHERE order_date > current_date - interval '30 days';
```
Step 2: Wrap your script in a `DDL` class:
```python
# myapp/models.py
from alembic_dddl import DDL
from pathlib import Path
SCRIPTS = Path(__file__).parent / "scripts"
def load_sql(filename: str) -> str:
"""Helper function to load the contents of a file from a `scripts` directory"""
return (SCRIPTS / filename).read_text()
my_ddl = DDL(
# will be used in revision filename
name="last_month_orders",
# DDL script SQL code, will be used in the upgrade command
sql=load_sql("last_month_orders.sql"),
# Cleanup SQL code, will be used in the first downgrade command
down_sql="DROP VIEW IF EXISTS last_month_orders;",
)
```
Step 3: Register your script in alembic's `env.py`:
```python
# migrations/env.py
from myapp.models import my_ddl
from alembic_dddl import register_ddl
register_ddl(my_ddl) # also supports a list
# ...
# the rest of the env.py file
```
From now on the alembic autogenerate command will keep track of `last_month_orders.sql`, and if it changes — automatically add update code to your migration scripts to update your entities.
Run the migration:
```shell
$ alembic revision --autogenerate -m "last_month_orders"
...
INFO [alembic_dddl.dddl] Detected new DDL "last_month_orders"
Generating myapp/migrations/versions/2024_01_08_0955-0c897e9399a9_last_month_orders.py ... done
```
The generated revision script:
```python
# migrations/versions/2024_01_08_0955-0c897e9399a9_last_month_orders.py
...
def upgrade() -> None:
# ### commands auto generated by Alembic - please adjust! ###
op.run_ddl_script("2024_01_08_0955_last_month_orders_0c897e9399a9.sql")
# ### end Alembic commands ###
def downgrade() -> None:
# ### commands auto generated by Alembic - please adjust! ###
op.execute("DROP VIEW IF EXISTS last_month_orders;")
# ### end Alembic commands ###
```
For more info see [tutorial](docs/tutorial.md) or take a look at the [Example Project](https://github.com/Vanderhoof/alembic-dddl/tree/master/example/).
## Why do it this way?
Managing your custom entities with Alembic DDDL has several benefits:
1. The DDL scripts are defined in one place in the source code, any change to them is reflected in git history through direct diffs.
2. Any kind of SQL script and any DBMS is supported because the plugin does not interact with the database.
3. The migrations for your DDL scripts are fully autogenerated, they are also clean and concise.
# Further reading
* [Tutorial](docs/tutorial.md)
* [How it Works](docs/how_it_works.md)
* [Configuration](docs/configuration.md)
* [Setting up Logging](docs/logging.md)
# Maintainers
* [@Vanderhoof](https://github.com/Vanderhoof)
* [@Bopio](https://github.com/bopio)