~ubuntu-branches/ubuntu/saucy/migrate/saucy-proposed

.. currentmodule:: migrate.versioning

.. highlight:: console

***********************************

Database schema versioning workflow

***********************************

also available as the :ref:`migrate <command-line-usage>` command.

 

Purpose of this package is frontend for migrations. It provides commands

to manage migrate repository and database selection aswell as script versioning.

 

 

Project setup

project.

 

All work with repositories is done using the :ref:`migrate <command-line-usage>` command. Let's

 $ migrate create my_repository "Example project"

 

This creates an initially empty repository relative to current directory at

my_repository/ named `Example project`.

 

The repository directory

contains a sub directory :file:`versions` that will store the :ref:`schema versions <changeset-system>`,

:ref:`repository configuration <repository_configuration>` and a script :ref:`manage.py <project_management_script>`

that has the same functionality as the :ref:`migrate <command-line-usage>` command but is

preconfigured with repository specific parameters.

 

.. note::

 

    Repositories are associated with a single database schema,

    and store collections of change scripts to manage that schema. The

    scripts in a repository may be applied to any number of databases.

    Each repository has an unique name. This name is used to identify the

    repository we're working with.

 

 

Version control a database

Next we need to declare database to be under version control.

Information on a database's version is stored in the database

table named **migrate_version** and associates it with your repository.

 $ python my_repository/manage.py version_control sqlite:///project.db

 $ python my_repository/manage.py db_version sqlite:///project.db

 $ python my_repository/manage.py version

 $ migrate manage manage.py --repository=my_repository --url=sqlite:///project.db

 $ python manage.py db_version

the same as those performed with the :ref:`migrate <command-line-usage>` tool, using the

.. note::

 

   Parameters specified in manage.py should be the same as in :ref:`versioning api <versioning-api>`.

   Preconfigured parameter should just be omitted from :ref:`migrate <command-line-usage>` command.

 

Our first change script will create a simple table

 

.. code-block:: python

 

         account = Table('account', meta,

                         Column('id', Integer, primary_key=True),

                         Column('login', String(40)),

                         Column('passwd', String(40)),

         )

 $ python manage.py script "Add account table"

 

Our change script predefines two functions, currently empty:

:func:`upgrade` and :func:`downgrade`. We'll fill those in

 

.. code-block:: python

 

    from sqlalchemy import *

    from migrate import *

 

    meta = MetaData()

 

    account = Table('account', meta,

        Column('id', Integer, primary_key=True),

        Column('login', String(40)),

        Column('passwd', String(40)),

    )

  

    def upgrade(migrate_engine):

        meta.bind = migrate_engine

        account.create()

 

    def downgrade(migrate_engine):

        meta.bind = migrate_engine

        account.drop()

 

As you might have guessed, :func:`upgrade` upgrades the database to the next

version. This function should contain the :ref:`schema changes<changeset-system>` we want to perform

(in our example we're creating a table).

 

:func:`downgrade` should reverse changes made

by :func:`upgrade`. You'll need to write both functions for every change

script. (Well, you don't *have* to write downgrade, but you won't be

 

.. note::

 

    As you can see, **migrate_engine** is passed to both functions.

    You should use this in your change scripts, rather

    than creating your own engine.

 

.. warning::

 

    You should be very careful about importing files from the rest of your

    application, as your change scripts might break when your application

    changes. More about `writing scripts with consistent behavior`_.

 

script will run its :func:`upgrade` and :func:`downgrade` functions on a specified

appear unchanged after :func:`upgrade` and :func:`downgrade` run.

 

To test the script::

 

 $ python manage.py test

Our repository's version is::

 $ python manage.py version

.. warning::

 

         test command executes actual script, be sure you are NOT doing this on production database.

 

 

 $ python manage.py upgrade

could also specify a version number if we wished, using the ``--version``

table has been created::

 

 $ python manage.py db_version

 $ sqlite3 project.db

.. warning:: 

 

    **Consider the following example of what NOT to do**

 

Let's say your application defines a table in the :file:`model.py` file:

 

.. code-block:: python

 

 from sqlalchemy import *

 

 meta = MetaData()

 table = Table('mytable', meta,

     Column('id', Integer, primary_key=True),

 )

 

... and uses this file to create a table in a change script:

 

.. code-block:: python

 

 from sqlalchemy import *

 from migrate import *

 import model

 

 def upgrade(migrate_engine):

     model.meta.bind = migrate_engine

 

 def downgrade(migrate_engine):

     model.meta.bind = migrate_engine 

     model.table.drop()

 

This runs successfully the first time. But what happens if we change

the table definition in :file:`model.py`?

 

.. code-block:: python

 

 from sqlalchemy import *

 

 meta = MetaData()

 table = Table('mytable', meta,

     Column('id', Integer, primary_key=True),

     Column('data', String(42)),

 )

 

We'll create a new column with a matching change script

 

.. code-block:: python

 

 from sqlalchemy import *

 from migrate import *

 import model

 

 def upgrade(migrate_engine):

     model.meta.bind = migrate_engine

 

 def downgrade(migrate_engine):

     model.meta.bind = migrate_engine

.. note:: Sometimes it is enough to just reflect tables with SQLAlchemy instead of copy-pasting - but remember, explicit is better than implicit!

 

 

database you're working with

 

.. code-block:: python

 $ python manage.py version

 $ python manage.py script_sql postgres

.. _command-line-usage:

 

:command:`migrate` command is used for API interface. For list of commands and help use::

 

        $ migrate --help

 

:program:`migrate` command exectues :func:`main` function.

which calls :func:`main` function with keywords arguments.

You may want to specify `url` and `repository` arguments which almost all API functions require.

        $ migrate downgrade URL REPOSITORY VERSION [--preview_sql|--preview_py]

 

and you have a project management script that looks like

 

.. code-block:: python

        # preview Python script

        $ migrate downgrade 2 --preview_py

        $ migrate downgrade 2

Options passed as kwargs to :func:`~migrate.versioning.shell.main` are now parsed correctly.

.. currentmodule:: migrate.versioning.api

your Python scripts by importing :mod:`migrate.versioning.api`. See the

:mod:`migrate.versioning.api` documentation for a list of functions;

 $ migrate help help

*From Python*

 

.. code-block:: python

 

 

  example: `['postgres', 'sqlite']`

 

 

.. _custom-templates:

 

Customize templates

===================

 

Users can pass ``templates_path`` to API functions to provide customized templates path.

Path should be a collection of templates, like ``migrate.versioning.templates`` package directory.

 

One may also want to specify custom themes. API functions accept ``templates_theme`` for this purpose (which defaults to `default`)

 

Example::

        

        /home/user/templates/manage $ ls

        default.py_tmpl

        pylons.py_tmpl

 

        /home/user/templates/manage $ migrate manage manage.py --templates_path=/home/user/templates --templates_theme=pylons

 

 

.. versionadded:: 0.6.0