Alembic

Alembic basiert auf SQLAlchemy und dient als Datenbankmigrationswerkzeug mit den folgenden Funktionen:

  • ALTER-Anweisungen an eine Datenbank ausgeben um die Strukturen von Tabellen und anderen Konstrukten zu ändern

  • System zum Erstellen von Migrationsskripten. Optional kann auch die Reihenfolge der Schritte für das Downgrade angegeben werden.

  • Die Skripte werden in einer bestimmten Reihenfolge ausgeführt.

Siehe auch

Auto Generating Migrations

Migrationsumgebung erstellen

Das Migration Environment ist ein Verzeichnis, das für eine bestimmte Anwendung spezifisch ist. Sie wird mit dem ini-Befehl von Alembic erstellt und anschließend zusammen mit dem Quellcode der Anwendung verwaltet.

$ cd myrproject
$ alembic init alembic
Creating directory /path/to/myproject/alembic...done
Creating directory /path/to/myproject/alembic/versions...done
Generating /path/to/myproject/alembic.ini...done
Generating /path/to/myproject/alembic/env.py...done
Generating /path/to/myproject/alembic/README...done
Generating /path/to/myproject/alembic/script.py.mako...done
Please edit configuration/connection/logging settings in
'/path/to/myproject/alembic.ini' before proceeding.

Die Struktur eines solchen Migrationsumgebung kann später dann z.B. so aussehen:

myproject/
└── alembic
    ├── alembic.ini
    ├── env.py
    ├── README
    ├── script.py.mako
    └── versions
        ├── 2b1ae634e5cd_add_order_id.py
        ├── 3512b954651e_add_account.py
        └── 3adcc9a56557_rename_username_field.py

Vorlagen

Alembic erhält eine Reihe von Vorlagen, die mit list angezeigt werden können:

$ alembic list_templates
Available templates:

generic - Generic single-database configuration.
multidb - Rudimentary multi-database configuration.
pylons - Configuration that reads from a Pylons project environment.

Templates are used via the 'init' command, e.g.:

  alembic init --template pylons ./scripts

ini-Datei konfigurieren

Die mit der generic-Vorlage erstellte Datei sieht folgendermaßen aus:

# A generic, single database configuration.

[alembic]
# path to migration scripts
script_location = alembic

# 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 dateutil.tz.gettz()
# 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 script.py.mako
# output_encoding = utf-8

sqlalchemy.url = driver://user:pass@localhost/dbname

# Logging configuration
[loggers]
keys = root,sqlalchemy,alembic

[handlers]
keys = console

[formatters]
keys = generic

[logger_root]
level = WARN
handlers = console
qualname =

[logger_sqlalchemy]
level = WARN
handlers =
qualname = sqlalchemy.engine

[logger_alembic]
level = INFO
handlers =
qualname = alembic

[handler_console]
class = StreamHandler
args = (sys.stderr,)
level = NOTSET
formatter = generic

[formatter_generic]
format = %(levelname)-5.5s [%(name)s] %(message)s
datefmt = %H:%M:%S
%(here)s

Ersetzungsvariable zum Erstellen absoluter Pfade

file_template

Dies ist das Namensschema, das zum Generieren neuer Migrationsdateien verwendet wird. Zu den verfügbaren Variablen gehören:

%%(rev)s

Revision-ID

%%(slug)s

Verkürzte Revisionsnachricht

%%(year)d, %%(month).2d, %%(day).2d, %%(hour).2d, %%(minute).2d, %%(second).2d

Erstellungszeitpunkt

Erstellen eines Migrationsskripts

Eine neue Revision kann erstellt werden mit:

$ alembic revision -m "create account table"
Generating /path/to/yourproject/alembic/versions/1975ea83b712_create_account_table.py...done

Die Datei 1975ea83b712_create_account_table.py sieht dann folgendermaßen aus:

"""create account table

Revision ID: 1975ea83b712
Revises:
Create Date: 2018-12-08 11:40:27.089406

"""

# revision identifiers, used by Alembic.
revision = "1975ea83b712"
down_revision = None
branch_labels = None

import sqlalchemy as sa

from alembic import op


def upgrade():
    pass


def downgrade():
    pass
down_revision

Variable, die Alembic mitteilt, in welcher Reihenfolge die Migrationen ausgeführt werden sollen, z.B.:

# revision identifiers, used by Alembic.
revision = "ae1027a6acf"
down_revision = "1975ea83b712"
upgrade, downgrade

z.B.:

def upgrade():
    op.create_table(
        "account",
        sa.Column("id", sa.Integer, primary_key=True),
        sa.Column("name", sa.String(50), nullable=False),
        sa.Column("description", sa.Unicode(200)),
    )


def downgrade():
    op.drop_table("account")

create_table() und drop_table() sind Alembic-Direktiven. Einen Überblick über alle Alembic-Direktiven erhaltet ihr in der Operation Reference.

Ausführen von Migration

Erste Migration:

$ alembic upgrade head
INFO  [alembic.context] Context class PostgresqlContext.
INFO  [alembic.context] Will assume transactional DDL.
INFO  [alembic.context] Running upgrade None -> 1975ea83b712

Wir können auch direkt auf Revisionsnummern verweisen:

$ alembic upgrade ae1

Auch relative Migrationen können angestoßen werden:

$ alembic upgrade +2

oder:

$ alembic downgrade -1

oder:

$ alembic upgrade ae10+2

Informationen anzeigen

Aktuelle Version

$ alembic current
INFO  [alembic.context] Context class PostgresqlContext.
INFO  [alembic.context] Will assume transactional DDL.
Current revision for postgresql://scott:XXXXX@localhost/test: 1975ea83b712 -> ae1027a6acf (head), Add a column

Historie

$ alembic history --verbose

Rev: ae1027a6acf (head)
Parent: 1975ea83b712
Path: /path/to/yourproject/alembic/versions/ae1027a6acf_add_a_column.py

    add a column

    Revision ID: ae1027a6acf
    Revises: 1975ea83b712
    Create Date: 2014-11-20 13:02:54.849677

Rev: 1975ea83b712
Parent: <base>
Path: /path/to/yourproject/alembic/versions/1975ea83b712_add_account_table.py

    create account table

    Revision ID: 1975ea83b712
    Revises:
    Create Date: 2014-11-20 13:02:46.257104

Die Historie kann auch spezifischer angezeigt werden:

$ alembic history -r1975ea:ae1027

oder:

$ alembic history -r-3:current

oder:

$ alembic history -r1975ea: