Commit a8a1f74a authored by Frédéric Mangano-Tarumi's avatar Frédéric Mangano-Tarumi Committed by Lukas Fleischer
Browse files

Set up Alembic for database migrations

Signed-off-by: Lukas Fleischer's avatarLukas Fleischer <>
parent 7188743f
......@@ -47,8 +47,8 @@ read the instructions below.
4) Install Python modules and dependencies:
# pacman -S python-mysql-connector python-pygit2 python-srcinfo python-sqlalchemy
# pacman -S python-bleach python-markdown
# pacman -S python-mysql-connector python-pygit2 python-srcinfo python-sqlalchemy \
python-bleach python-markdown python-alembic
# python3 install
5) Create a new MySQL database and a user and import the aurweb SQL schema:
......@@ -11,7 +11,8 @@ INSTALL.
2) Install the necessary packages:
# pacman -S --needed php php-sqlite sqlite words fortune-mod python python-sqlalchemy
# pacman -S --needed php php-sqlite sqlite words fortune-mod \
python python-sqlalchemy python-alembic
Ensure to enable the pdo_sqlite extension in php.ini.
# A generic, single database configuration.
# path to migration scripts
script_location = migrations
# template used to generate migration files
# file_template = %%(rev)s_%%(slug)s
# timezone to use when rendering the date
# within the migration file as well as the filename.
# string value is passed to
# leave blank for localtime
# timezone =
# max length of characters to apply to the
# "slug" field
# truncate_slug_length = 40
# set to 'true' to run the environment during
# the 'revision' command, regardless of autogenerate
# revision_environment = false
# set to 'true' to allow .pyc and .pyo files without
# a source .py file to be detected as revisions in the
# versions/ directory
# sourceless = false
# version location specification; this defaults
# to alembic/versions. When using multiple version
# directories, initial revisions must be specified with --version-path
# version_locations = %(here)s/bar %(here)s/bat alembic/versions
# the output encoding used when revision files
# are written from
# output_encoding = utf-8
# the database URL is generated in
# sqlalchemy.url = driver://user:pass@localhost/dbname
# post_write_hooks defines scripts or Python functions that are run
# on newly generated revision scripts. See the documentation for further
# detail and examples
# format using "black" - use the console_scripts runner, against the "black" entrypoint
# hooks=black
# black.type=console_scripts
# black.entrypoint=black
# black.options=-l 79
# Logging configuration
keys = root,sqlalchemy,alembic
keys = console
keys = generic
level = WARN
handlers = console
qualname =
level = WARN
handlers =
qualname = sqlalchemy.engine
level = INFO
handlers =
qualname = alembic
class = StreamHandler
args = (sys.stderr,)
level = NOTSET
formatter = generic
format = %(levelname)-5.5s [%(name)s] %(message)s
datefmt = %H:%M:%S
import aurweb.db
import aurweb.schema
import alembic.command
import alembic.config
import argparse
import sqlalchemy
......@@ -31,10 +33,17 @@ def feed_initial_data(conn):
def run(args):
# Ensure Alembic is fine before we do the real work, in order not to fail at
# the last step and leave the database in an inconsistent state. The
# configuration is loaded lazily, so we query it to force its loading.
alembic_config = alembic.config.Config('alembic.ini')
engine = sqlalchemy.create_engine(aurweb.db.get_sqlalchemy_url(),
echo=(args.verbose >= 1))
alembic.command.stamp(alembic_config, 'head')
if __name__ == '__main__':
Schema of aurweb's database.
Changes here should always be accompanied by an Alembic migration, which can be
usually be automatically generated. See `migrations/README` for details.
from sqlalchemy import CHAR, Column, ForeignKey, Index, MetaData, String, TIMESTAMP, Table, Text, text
from sqlalchemy.dialects.mysql import BIGINT, DECIMAL, INTEGER, TINYINT
from sqlalchemy.ext.compiler import compiles
This directory contains Alembic's environment for managing database migrations.
From Alembic's documentation: Alembic is a lightweight database migration tool
for usage with the SQLAlchemy Database Toolkit for Python.
Upgrading to the latest version
Simply run `alembic upgrade head` from aurweb's root.
Creating new migrations
When working with Alembic and SQLAlchemy, you should never edit the database
schema manually. Please proceed like this instead:
1. Edit `aurweb/` to your liking.
2. Run `alembic revision --autogenerate -m "your message"`
3. Proofread the generated migration.
4. Run `alembic upgrade head` to apply the changes to the database.
5. Commit the new migration.
To revert a migration, you may run `alembic downgrade -1` and then manually
delete the migration file. Note that SQLite is limited and that it's sometimes
easier to recreate the database.
For anything more complicated, please read Alembic's documentation.
- `ModuleNotFoundError: No module named 'aurweb'`
You may either install the aurweb module with pip, or set PYTHONPATH to your
aurweb repository. Since alembic must be run from the aurweb root, you may
simply use: `PYTHONPATH=. alembic [...]`.
- `FAILED: No config file 'alembic.ini' found, or file has no '[alembic]' section`
You need to run Alembic from the project's root, and not from `migrations/`.
- `configparser.NoSectionError: No section: 'database'`
You need to set AUR_CONFIG, as explained in `TESTING`.
import aurweb.db
import aurweb.schema
from alembic import context
import logging.config
import sqlalchemy
# this is the Alembic Config object, which provides
# access to the values within the .ini file in use.
config = context.config
# Interpret the config file for Python logging.
# This line sets up loggers basically.
# model MetaData for autogenerating migrations
target_metadata = aurweb.schema.metadata
# other values from the config, defined by the needs of,
# can be acquired:
# my_important_option = config.get_main_option("my_important_option")
# ... etc.
def run_migrations_offline():
"""Run migrations in 'offline' mode.
This configures the context with just a URL
and not an Engine, though an Engine is acceptable
here as well. By skipping the Engine creation
we don't even need a DBAPI to be available.
Calls to context.execute() here emit the given string to the
script output.
dialect_opts={"paramstyle": "named"},
with context.begin_transaction():
def run_migrations_online():
"""Run migrations in 'online' mode.
In this scenario we need to create an Engine
and associate a connection with the context.
connectable = sqlalchemy.create_engine(
with connectable.connect() as connection:
connection=connection, target_metadata=target_metadata
with context.begin_transaction():
if context.is_offline_mode():
Revision ID: ${up_revision}
Revises: ${down_revision | comma,n}
Create Date: ${create_date}
from alembic import op
import sqlalchemy as sa
${imports if imports else ""}
# revision identifiers, used by Alembic.
revision = ${repr(up_revision)}
down_revision = ${repr(down_revision)}
branch_labels = ${repr(branch_labels)}
depends_on = ${repr(depends_on)}
def upgrade():
${upgrades if upgrades else "pass"}
def downgrade():
${downgrades if downgrades else "pass"}
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment