Skip to main content

Offline extensions for Alembic database migration framework for SQLAlchemy

Project description

alembic-offline
===============

.. image:: https://api.travis-ci.org/paylogic/alembic-offline.png
:target: https://travis-ci.org/paylogic/alembic-offline

.. image:: https://pypip.in/v/alembic-offline/badge.png
:target: https://crate.io/packages/alembic-offline/

.. image:: https://coveralls.io/repos/paylogic/alembic-offline/badge.svg?branch=master
:target: https://coveralls.io/r/paylogic/alembic-offline?branch=master

.. image:: https://readthedocs.org/projects/alembic-offline/badge/?version=latest
:alt: Documentation Status
:scale: 100%
:target: https://readthedocs.org/projects/alembic-offline/

alembic-offline is an extension for Alembic to enrich offline functionality of migrations using SQLAlchemy

.. contents::

Usage
-----

Phased migrations
^^^^^^^^^^^^^^^^^

alembic-offline introduces a helper which allows to implement phased migrations, e.g. those which steps
are divided into logical phases. For example, you can have steps to be executed before code deploy and
those after.

In your alembic config file (main section):

::

phases = before-deploy after-deploy final
default-phase = after-deploy

In your version file:

.. code-block:: python

from sqlalchemy import INTEGER, VARCHAR, NVARCHAR, TIMESTAMP, Column, func
from alembic import op

from alembic_offline import phased, execute_script

from tests.migrations.scripts import script

revision = '1'
down_revision = None


@phased
def upgrade():

op.create_table(
'account',
Column('id', INTEGER, primary_key=True),
Column('name', VARCHAR(50), nullable=False),
Column('description', NVARCHAR(200)),
Column('timestamp', TIMESTAMP, server_default=func.now())
)
yield
op.execute("update account set name='some'")
yield
execute_script(script.__file__)


def downgrade():
pass

Will give the sql output (for sqlite):

.. code-block:: sql

-- Running upgrade -> 1

-- PHASE::before-deploy::;

CREATE TABLE account (
id INTEGER NOT NULL,
name VARCHAR(50) NOT NULL,
description NVARCHAR(200),
timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
PRIMARY KEY (id)
);

-- PHASE::after-deploy::;

update account set name='some';

-- PHASE::final::;

-- SCRIPT::scripts/script.py::;

INSERT INTO alembic_version (version_num) VALUES ('1');

As you see, phases are rendered as SQL comments to divide migration steps, so those who execute migration
can see which phase's step it is.
However, if migration procedure is highly customized, you can use alembic-offline API described below.
`get_migration_data` returns migration phases in special form so you can automate their execution.

Arbitrary script as operation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

For complex migrations, it's not enough to execute sql, you might need some script to be executed instead.
For that, there's special operation:

.. code-block:: python

from alembic_offline import execute_script

def upgrade():
execute_script('scripts/script.py')

If you'll get migration sql, it will be rendered as SQL comment:

.. code-block:: sql

-- SCRIPT::scripts/script.py::;

For those who execute migrations it will be visible and they can execute the script manually.
However, if migration procedure is highly customized, you can use alembic-offline API described below.
`get_migration_data` returns script migration steps in special form so you can automate their execution.
For online mode, the script will be executed as subprocess via python `subprocess` module.

Get migration data
^^^^^^^^^^^^^^^^^^

alembic-offline provides specialized API to get certain migration data as dictionary:

.. code-block:: python

from alembic_offline import get_migration_data

from alembic.config import Config

config = Config('path to alembic.ini')

data = get_migration_data(config, 'your-revision')

assert data == {
'revision': 'your-revision',
'phases': {
'after-deploy': [
{
'type': 'mysql',
'script': 'alter table account add column name VARCHAR(255)'
},
{
'type': 'python',
'script': 'from app.models import Session, Account; Session.add(Account()); Session.commit()',
'path': 'scripts/my_script.py'
},
]
}
}

`get_migration_data` requires both `phases` and `default-phase` configuration options to be set.
`default-phase` is needed to be able to get migration data even for simple migrations without phases.

Get migration data in batch
^^^^^^^^^^^^^^^^^^^^^^^^^^^

alembic-offline provides an API call to get migration data for all revisions:

.. code-block:: python

from alembic_offline import get_migrations_data

from alembic.config import Config

config = Config('path to alembic.ini')

data = get_migrations_data(config)

assert data == [
{
'revision': 'your-revision',
'phases': {
'after-deploy': [
{
'type': 'mysql',
'script': 'alter table account add column name VARCHAR(255)'
},
{
'type': 'python',
'script': 'from app.models import Session, Account; Session.add(Account()); Session.commit()',
'path': 'scripts/my_script.py'
},
]
}
}
]

Contact
-------

If you have questions, bug reports, suggestions, etc. please create an issue on
the `GitHub project page <http://github.com/paylogic/alembic-offline>`_.

License
-------

This software is licensed under the `MIT license <http://en.wikipedia.org/wiki/MIT_License>`_

© 2015 Anatoly Bubenkov, Paylogic International and others.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

alembic_offline-2.0.0.tar.gz (10.0 kB view details)

Uploaded Source

Built Distribution

alembic_offline-2.0.0-py3-none-any.whl (6.7 kB view details)

Uploaded Python 3

File details

Details for the file alembic_offline-2.0.0.tar.gz.

File metadata

  • Download URL: alembic_offline-2.0.0.tar.gz
  • Upload date:
  • Size: 10.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.10.14

File hashes

Hashes for alembic_offline-2.0.0.tar.gz
Algorithm Hash digest
SHA256 d0474a20b052709602107850322874f0a9a82c316c389711d475f8906f4cfd14
MD5 d6c435a365c9704238008ebd0d1b832a
BLAKE2b-256 ee80c972b6c3ae03371623bb773cc6852b36b40e20ba9f9b87a2d4b1db0eff1b

See more details on using hashes here.

File details

Details for the file alembic_offline-2.0.0-py3-none-any.whl.

File metadata

File hashes

Hashes for alembic_offline-2.0.0-py3-none-any.whl
Algorithm Hash digest
SHA256 5e04a61a7e57de3ae71d9b7874352f6cd9781d8b92bf4e3f349e09360f26b121
MD5 ed20d3e0ed251d02f469be39bb0fe4b7
BLAKE2b-256 bb278511841b8da07cffb8877f3b0e5725afb901ab15feb401f0d3c813d9687d

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page