Skip to content

Commit 8236de4

Browse files
vgvolegvgvoleg
committed
Alembic usage example guide
1 parent d55414b commit 8236de4

12 files changed

+476
-4
lines changed

‎README.md

+2
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,8 @@ with engine.connect() as conn:
3232

3333
```
3434

35+
To setup `alembic` to work with `YDB` please check [this example](https://github.com/ydb-platform/ydb-sqlalchemy/tree/main/examples/alembic).
36+
3537
## Development
3638

3739
### Run Tests:

‎examples/alembic/README.md

+88
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
# Alembic support
2+
3+
In this example we'll see how to use `alembic` with ydb.
4+
5+
## Installation
6+
7+
To make `alembic` work with `YDB` tables please follow these steps:
8+
9+
* Install `ydb-sqlalchemy` package from PyPi:
10+
11+
```bash
12+
pip install ydb-sqlalchemy`
13+
```
14+
15+
* Install `alembic` package from PyPi:
16+
17+
```bash
18+
pip install alembic
19+
```
20+
21+
## Preparation
22+
23+
We have to setup `alembic` correctly.
24+
First of all, we should register `YDB` dialect in `env.py`:
25+
26+
```python3
27+
from alembic.ddl.impl import DefaultImpl
28+
29+
30+
class YDBImpl(DefaultImpl):
31+
__dialect__ = "yql"
32+
```
33+
34+
Secondly, since `YDB` do not support updating primary key columns, we have to update alembic table structure.
35+
For this purpose we should update `run_migrations_online` method in `env.py`:
36+
37+
```python3
38+
def run_migrations_online() -> None:
39+
"""Run migrations in 'online' mode.
40+
41+
In this scenario we need to create an Engine
42+
and associate a connection with the context.
43+
44+
"""
45+
connectable = engine_from_config(
46+
config.get_section(config.config_ini_section, {}),
47+
prefix="sqlalchemy.",
48+
poolclass=pool.NullPool,
49+
)
50+
51+
with connectable.connect() as connection:
52+
context.configure(
53+
connection=connection, target_metadata=target_metadata
54+
)
55+
56+
ctx = context.get_context()
57+
ctx._version = sa.Table( # noqa: SLF001
58+
ctx.version_table,
59+
sa.MetaData(),
60+
sa.Column("version_num", sa.String(32), nullable=False),
61+
sa.Column("id", sa.Integer(), nullable=True, primary_key=True),
62+
)
63+
64+
with context.begin_transaction():
65+
context.run_migrations()
66+
```
67+
68+
## Example
69+
70+
To run this example:
71+
1. Install all dependencies described in `Installation` section.
72+
1. Update `sqlalchemy.url` field in `alembic.ini` config file.
73+
1. Run `alembic upgrade head` to apply all migrations:
74+
75+
```bash
76+
alembic upgrade head
77+
78+
INFO [alembic.runtime.migration] Context impl YDBImpl.
79+
INFO [alembic.runtime.migration] Will assume non-transactional DDL.
80+
INFO [alembic.runtime.migration] Running upgrade -> d91d9200b65c, create series table
81+
INFO [alembic.runtime.migration] Running upgrade d91d9200b65c -> 820b994ffa7c, create seasons table
82+
INFO [alembic.runtime.migration] Running upgrade 820b994ffa7c -> 9085c679f5dc, create episodes table
83+
```
84+
85+
To create new migration just add a few changes in `models.py` and run:
86+
```bash
87+
alembic revision --autogenerate -m "name of your migration"
88+
```

‎examples/alembic/__init__.py

Whitespace-only changes.

‎examples/alembic/alembic.ini

+117
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
# A generic, single database configuration.
2+
3+
[alembic]
4+
# path to migration scripts
5+
# Use forward slashes (/) also on windows to provide an os agnostic path
6+
script_location = migrations
7+
8+
# template used to generate migration file names; The default value is %%(rev)s_%%(slug)s
9+
# Uncomment the line below if you want the files to be prepended with date and time
10+
# see https://alembic.sqlalchemy.org/en/latest/tutorial.html#editing-the-ini-file
11+
# for all available tokens
12+
# file_template = %%(year)d_%%(month).2d_%%(day).2d_%%(hour).2d%%(minute).2d-%%(rev)s_%%(slug)s
13+
14+
# sys.path path, will be prepended to sys.path if present.
15+
# defaults to the current working directory.
16+
prepend_sys_path = .
17+
18+
# timezone to use when rendering the date within the migration file
19+
# as well as the filename.
20+
# If specified, requires the python>=3.9 or backports.zoneinfo library.
21+
# Any required deps can installed by adding `alembic[tz]` to the pip requirements
22+
# string value is passed to ZoneInfo()
23+
# leave blank for localtime
24+
# timezone =
25+
26+
# max length of characters to apply to the "slug" field
27+
# truncate_slug_length = 40
28+
29+
# set to 'true' to run the environment during
30+
# the 'revision' command, regardless of autogenerate
31+
# revision_environment = false
32+
33+
# set to 'true' to allow .pyc and .pyo files without
34+
# a source .py file to be detected as revisions in the
35+
# versions/ directory
36+
# sourceless = false
37+
38+
# version location specification; This defaults
39+
# to ./versions. When using multiple version
40+
# directories, initial revisions must be specified with --version-path.
41+
# The path separator used here should be the separator specified by "version_path_separator" below.
42+
# version_locations = %(here)s/bar:%(here)s/bat:./versions
43+
44+
# version path separator; As mentioned above, this is the character used to split
45+
# version_locations. The default within new alembic.ini files is "os", which uses os.pathsep.
46+
# If this key is omitted entirely, it falls back to the legacy behavior of splitting on spaces and/or commas.
47+
# Valid values for version_path_separator are:
48+
#
49+
# version_path_separator = :
50+
# version_path_separator = ;
51+
# version_path_separator = space
52+
# version_path_separator = newline
53+
version_path_separator = os # Use os.pathsep. Default configuration used for new projects.
54+
55+
# set to 'true' to search source files recursively
56+
# in each "version_locations" directory
57+
# new in Alembic version 1.10
58+
# recursive_version_locations = false
59+
60+
# the output encoding used when revision files
61+
# are written from script.py.mako
62+
# output_encoding = utf-8
63+
64+
sqlalchemy.url = yql+ydb://localhost:2136/local
65+
66+
67+
[post_write_hooks]
68+
# post_write_hooks defines scripts or Python functions that are run
69+
# on newly generated revision scripts. See the documentation for further
70+
# detail and examples
71+
72+
# format using "black" - use the console_scripts runner, against the "black" entrypoint
73+
# hooks = black
74+
# black.type = console_scripts
75+
# black.entrypoint = black
76+
# black.options = -l 79 REVISION_SCRIPT_FILENAME
77+
78+
# lint with attempts to fix using "ruff" - use the exec runner, execute a binary
79+
# hooks = ruff
80+
# ruff.type = exec
81+
# ruff.executable = %(here)s/.venv/bin/ruff
82+
# ruff.options = --fix REVISION_SCRIPT_FILENAME
83+
84+
# Logging configuration
85+
[loggers]
86+
keys = root,sqlalchemy,alembic
87+
88+
[handlers]
89+
keys = console
90+
91+
[formatters]
92+
keys = generic
93+
94+
[logger_root]
95+
level = WARNING
96+
handlers = console
97+
qualname =
98+
99+
[logger_sqlalchemy]
100+
level = WARNING
101+
handlers =
102+
qualname = sqlalchemy.engine
103+
104+
[logger_alembic]
105+
level = INFO
106+
handlers =
107+
qualname = alembic
108+
109+
[handler_console]
110+
class = StreamHandler
111+
args = (sys.stderr,)
112+
level = NOTSET
113+
formatter = generic
114+
115+
[formatter_generic]
116+
format = %(levelname)-5.5s [%(name)s] %(message)s
117+
datefmt = %H:%M:%S

‎examples/alembic/migrations/README

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Generic single-database configuration.

‎examples/alembic/migrations/env.py

+95
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
from logging.config import fileConfig
2+
3+
import sqlalchemy as sa
4+
from sqlalchemy import engine_from_config
5+
from sqlalchemy import pool
6+
7+
from alembic import context
8+
from alembic.ddl.impl import DefaultImpl
9+
10+
11+
# this is the Alembic Config object, which provides
12+
# access to the values within the .ini file in use.
13+
config = context.config
14+
15+
# Interpret the config file for Python logging.
16+
# This line sets up loggers basically.
17+
if config.config_file_name is not None:
18+
fileConfig(config.config_file_name)
19+
20+
# add your model's MetaData object here
21+
# for 'autogenerate' support
22+
# from myapp import mymodel
23+
# target_metadata = mymodel.Base.metadata
24+
25+
from models import *
26+
target_metadata = Base.metadata
27+
28+
# other values from the config, defined by the needs of env.py,
29+
# can be acquired:
30+
# my_important_option = config.get_main_option("my_important_option")
31+
# ... etc.
32+
33+
34+
class YDBImpl(DefaultImpl):
35+
__dialect__ = "yql"
36+
37+
38+
def run_migrations_offline() -> None:
39+
"""Run migrations in 'offline' mode.
40+
41+
This configures the context with just a URL
42+
and not an Engine, though an Engine is acceptable
43+
here as well. By skipping the Engine creation
44+
we don't even need a DBAPI to be available.
45+
46+
Calls to context.execute() here emit the given string to the
47+
script output.
48+
49+
"""
50+
url = config.get_main_option("sqlalchemy.url")
51+
context.configure(
52+
url=url,
53+
target_metadata=target_metadata,
54+
literal_binds=True,
55+
dialect_opts={"paramstyle": "named"},
56+
)
57+
58+
with context.begin_transaction():
59+
context.run_migrations()
60+
61+
62+
def run_migrations_online() -> None:
63+
"""Run migrations in 'online' mode.
64+
65+
In this scenario we need to create an Engine
66+
and associate a connection with the context.
67+
68+
"""
69+
connectable = engine_from_config(
70+
config.get_section(config.config_ini_section, {}),
71+
prefix="sqlalchemy.",
72+
poolclass=pool.NullPool,
73+
)
74+
75+
with connectable.connect() as connection:
76+
context.configure(
77+
connection=connection, target_metadata=target_metadata
78+
)
79+
80+
ctx = context.get_context()
81+
ctx._version = sa.Table( # noqa: SLF001
82+
ctx.version_table,
83+
sa.MetaData(),
84+
sa.Column("version_num", sa.String(32), nullable=False),
85+
sa.Column("id", sa.Integer(), nullable=True, primary_key=True),
86+
)
87+
88+
with context.begin_transaction():
89+
context.run_migrations()
90+
91+
92+
if context.is_offline_mode():
93+
run_migrations_offline()
94+
else:
95+
run_migrations_online()

‎examples/alembic/migrations/script.py.mako

+26
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
"""${message}
2+
3+
Revision ID: ${up_revision}
4+
Revises: ${down_revision | comma,n}
5+
Create Date: ${create_date}
6+
7+
"""
8+
from typing import Sequence, Union
9+
10+
from alembic import op
11+
import sqlalchemy as sa
12+
${imports if imports else ""}
13+
14+
# revision identifiers, used by Alembic.
15+
revision: str = ${repr(up_revision)}
16+
down_revision: Union[str, None] = ${repr(down_revision)}
17+
branch_labels: Union[str, Sequence[str], None] = ${repr(branch_labels)}
18+
depends_on: Union[str, Sequence[str], None] = ${repr(depends_on)}
19+
20+
21+
def upgrade() -> None:
22+
${upgrades if upgrades else "pass"}
23+
24+
25+
def downgrade() -> None:
26+
${downgrades if downgrades else "pass"}

‎examples/alembic/migrations/versions/820b994ffa7c_create_seasons_table.py

+37
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
"""create seasons table
2+
3+
Revision ID: 820b994ffa7c
4+
Revises: d91d9200b65c
5+
Create Date: 2024-12-10 14:50:44.633728
6+
7+
"""
8+
from typing import Sequence, Union
9+
10+
from alembic import op
11+
import sqlalchemy as sa
12+
13+
14+
# revision identifiers, used by Alembic.
15+
revision: str = '820b994ffa7c'
16+
down_revision: Union[str, None] = 'd91d9200b65c'
17+
branch_labels: Union[str, Sequence[str], None] = None
18+
depends_on: Union[str, Sequence[str], None] = None
19+
20+
21+
def upgrade() -> None:
22+
# ### commands auto generated by Alembic - please adjust! ###
23+
op.create_table('seasons',
24+
sa.Column('series_id', sa.Integer(), nullable=False),
25+
sa.Column('season_id', sa.Integer(), nullable=False),
26+
sa.Column('title', sa.Unicode(), nullable=True),
27+
sa.Column('first_aired', sa.Integer(), nullable=True),
28+
sa.Column('last_aired', sa.Integer(), nullable=True),
29+
sa.PrimaryKeyConstraint('series_id', 'season_id')
30+
)
31+
# ### end Alembic commands ###
32+
33+
34+
def downgrade() -> None:
35+
# ### commands auto generated by Alembic - please adjust! ###
36+
op.drop_table('seasons')
37+
# ### end Alembic commands ###

0 commit comments

Comments
 (0)