x/sqlalchemy-migrate
Code Issues Proposed changes

update documentation

Browse Source
This commit is contained in:
iElectric 2009-06-12 15:41:59 +00:00
parent 03eb309b67
commit 431d22be61
6 changed files with 124 additions and 97 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
docs/changeset.rst
View File

@ -1,8 +1,8 @@
.. _changeset-system: .. _changeset-system:
********************** ******************
Database changeset API Database changeset
********************** ******************
.. currentmodule:: migrate.changeset .. currentmodule:: migrate.changeset

6
docs/download.rst
View File

@ -1,9 +1,6 @@
Download Download
-------- --------
SQLAlchemy-Migrate builds on SQLAlchemy_, so you should install that
first.
You can get the latest version of SQLAlchemy Migrate from the You can get the latest version of SQLAlchemy Migrate from the
`project's download page`_, the `cheese shop`_, or via easy_install_:: `project's download page`_, the `cheese shop`_, or via easy_install_::
@ -38,5 +35,8 @@ To get the latest trunk::
Patches should be submitted to the `issue tracker`_. Patches should be submitted to the `issue tracker`_.
We use `buildbot`_ to help us run tests on all databases that migrate supports.
.. _subversion: http://subversion.tigris.org/ .. _subversion: http://subversion.tigris.org/
.. _issue tracker: http://code.google.com/p/sqlalchemy-migrate/issues/list .. _issue tracker: http://code.google.com/p/sqlalchemy-migrate/issues/list
.. _buildbot: http://buildbot.fubar.si

7
docs/index.rst
View File

@ -24,9 +24,12 @@
project`_. During the hosting change the project was renamed to project`_. During the hosting change the project was renamed to
SQLAlchemy Migrate. SQLAlchemy Migrate.
Currently, sqlalchemy-migrate supports Python versions from 2.4 to 2.6.
SQLAlchemy >=0.5 is supported only.
.. warning:: .. warning::
**0.5.5** release breaks backward compatability, please read :ref:`changelog <backwards-055>` for more info. Version **0.5.5** breaks backward compatability, please read :ref:`changelog <backwards-055>` for more info.
Download and Development of SQLAlchemy Migrate Download and Development of SQLAlchemy Migrate
---------------------------------------------- ----------------------------------------------
@ -41,7 +44,7 @@ Documentation
SQLAlchemy is split into two parts, database schema versioning and SQLAlchemy is split into two parts, database schema versioning and
database changeset management. This is represented by two python database changeset management. This is represented by two python
packages :mod:`migrate.versioning` and :mod:`migrate.changeset`. The packages :mod:`migrate.versioning` and :mod:`migrate.changeset`. The
versioning API is available as the :command:`migrate` command. versioning API is available as the :ref:`migrate <command-line-usage>` command.
.. toctree:: .. toctree::

4
docs/tools.rst
View File

@ -1,9 +1,7 @@
SQLAlchemy migrate tools SQLAlchemy migrate tools
======================== ========================
The most commonly used tool is the :command:`migrate` script that is The most commonly used tool is the :ref:`migrate <command-line-usage>`.
discussed in depth in the :ref:`Database schema versioning
<versioning-system>` part of the documentation.
.. index:: repository migration .. index:: repository migration

193
docs/versioning.rst
View File

@ -1,13 +1,17 @@
.. _versioning-system: .. _versioning-system:
.. currentmodule:: migrate.versioning
.. highlight:: bash
************************** ***********************************
Database schema versioning Database schema versioning workflow
************************** ***********************************
SQLAlchemy migrate provides the :mod:`migrate.versioning` API that is SQLAlchemy migrate provides the :mod:`migrate.versioning` API that is
also available as the :command:`migrate` command. 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.
.. program:: migrate
Project Setup Project Setup
============= =============
@ -28,16 +32,16 @@ repository we're working with.
All work with repositories is done using the migrate command. Let's All work with repositories is done using the migrate command. Let's
create our project's repository:: create our project's repository::
% migrate create my_repository "Example project" $ migrate create my_repository "Example project"
This creates an initially empty repository in the current directory at This creates an initially empty repository relative to current directory at
my_repository/ named Example project. The repository directory my_repository/ named `Example project`. The repository directory
contains a sub directory versions that will store the schema versions, contains a sub directory versions that will store the schema versions,
a configuration file :file:`migrate.cfg` that contains a configuration file :file:`migrate.cfg` that contains
:ref:`repository configuration <repository_configuration>`, a :ref:`repository configuration <repository_configuration>`, a
:file:`README` file containing information that the directory is an :file:`README` file containing information that the directory is an
sqlalchemy-migrate repository and a script :file:`manage.py` that has sqlalchemy-migrate repository and a script :ref:`manage.py <project_management_script>`
the same functionality as the :command:`migrate` command but is that has the same functionality as the :ref:`migrate <command-line-usage>` command but is
preconfigured with the repository. preconfigured with the repository.
Version-control a database Version-control a database
@ -56,7 +60,7 @@ The database is specified as a `SQLAlchemy database url`_.
:: ::
% python my_repository/manage.py version_control sqlite:///project.db $ python my_repository/manage.py version_control sqlite:///project.db
We can have any number of databases under this repository's version We can have any number of databases under this repository's version
control. control.
@ -65,7 +69,7 @@ Each schema has a version that SQLAlchemy Migrate manages. Each change
script applied to the database increments this version number. You can script applied to the database increments this version number. You can
see a database's current version:: see a database's current version::
% python my_repository/manage.py db_version sqlite:///project.db $ python my_repository/manage.py db_version sqlite:///project.db
0 0
A freshly versioned database begins at version 0 by default. This A freshly versioned database begins at version 0 by default. This
@ -77,7 +81,7 @@ and applying change scripts changes the database's version number.
Similarly, we can also see the latest version available in a Similarly, we can also see the latest version available in a
repository with the command:: repository with the command::
% python my_repository/manage.py version $ python my_repository/manage.py version
0 0
We've entered no changes so far, so our repository cannot upgrade a We've entered no changes so far, so our repository cannot upgrade a
@ -93,8 +97,8 @@ path - typing them each time is tedious. We can create a script for
our project that remembers the database and repository we're using, our project that remembers the database and repository we're using,
and use it to perform commands:: and use it to perform commands::
% migrate manage manage.py --repository=my_repository --url=sqlite:///project.db $ migrate manage manage.py --repository=my_repository --url=sqlite:///project.db
% python manage.py db_version $ python manage.py db_version
0 0
The script manage.py was created. All commands we perform with it are The script manage.py was created. All commands we perform with it are
@ -117,17 +121,19 @@ helps ensure multiple databases you're working with are consistent.
Create a change script Create a change script
---------------------- ----------------------
Our first change script will create a simple table:: Our first change script will create a simple table
account = Table('account',meta, .. code-block:: python
Column('id',Integer,primary_key=True),
Column('login',String(40)), account = Table('account', meta,
Column('passwd',String(40)), Column('id', Integer, primary_key=True),
) Column('login', String(40)),
Column('passwd', String(40)),
)
This table should be created in a change script. Let's create one:: This table should be created in a change script. Let's create one::
% python manage.py script "Add account table" $ python manage.py script "Add account table"
This creates an empty change script at This creates an empty change script at
:file:`my_repository/versions/001_Add_account_table.py`. Next, we'll :file:`my_repository/versions/001_Add_account_table.py`. Next, we'll
@ -137,34 +143,38 @@ Edit the change script
---------------------- ----------------------
Our change script defines two functions, currently empty: Our change script defines two functions, currently empty:
``upgrade()`` and ``downgrade()``. We'll fill those in:: :func:`upgrade`` and :func:`downgrade`. We'll fill those in
.. code-block:: python
from sqlalchemy import * from sqlalchemy import *
from migrate import * from migrate import *
meta = MetaData(migrate_engine) meta = MetaData()
account = Table('account', meta, account = Table('account', meta,
Column('id', Integer, primary_key=True), Column('id', Integer, primary_key=True),
Column('login', String(40)), Column('login', String(40)),
Column('passwd', String(40)), Column('passwd', String(40)),
) )
def upgrade(): def upgrade(migrate_engine):
meta.bind(migrate_engine)
account.create() account.create()
def downgrade(): def downgrade(migrate_engine):
meta.bind(migrate_engine)
account.drop() account.drop()
As you might have guessed, upgrade() upgrades the database to the next As you might have guessed, :func:`upgrade` upgrades the database to the next
version. This function should contain the changes we want to perform; version. This function should contain the changes we want to perform;
here, we're creating a table. downgrade() should reverse changes made here, we're creating a table. :func:`downgrade` should reverse changes made
by upgrade(). You'll need to write both functions for every change 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 script. (Well, you don't *have* to write downgrade, but you won't be
able to revert to an older version of the database or test your able to revert to an older version of the database or test your
scripts without it.) scripts without it.)
``from migrate import *`` imports a special SQLAlchemy engine named As you can see, **migrate_engine** is passed to both functions.
'migrate_engine'. You should use this in your change scripts, rather You should use this in your change scripts, rather
than creating your own engine. than creating your own engine.
You should be very careful about importing files from the rest of your You should be very careful about importing files from the rest of your
@ -175,17 +185,15 @@ Test the change script
------------------------ ------------------------
Change scripts should be tested before they are committed. Testing a Change scripts should be tested before they are committed. Testing a
script will run its upgrade() and downgrade() functions on a specified script will run its :func:`upgrade` and :func:`downgrade` functions on a specified
database; you can ensure the script runs without error. You should be database; you can ensure the script runs without error. You should be
testing on a test database - if something goes wrong here, you'll need testing on a test database - if something goes wrong here, you'll need
to correct it by hand. If the test is successful, the database should to correct it by hand. If the test is successful, the database should
appear unchanged after upgrade() and downgrade() run. appear unchanged after upgrade() and downgrade() run.
To test the script: To test the script::
.. code-block:: none $ python manage.py test
% python manage.py test
Upgrading... done Upgrading... done
Downgrading... done Downgrading... done
Success Success
@ -195,28 +203,31 @@ specified in manage.py) without any errors.
Our repository's version now is:: Our repository's version now is::
% python manage.py version $ python manage.py version
1 1
.. warning::
test command exectues actual script, be sure you are NOT doing this on production database.
Upgrade the database Upgrade the database
-------------------- --------------------
Now, we can apply this change script to our database:: Now, we can apply this change script to our database::
% python manage.py upgrade $ python manage.py upgrade
0 -> 1... done 0 -> 1... done
This upgrades the database (``sqlite:///project.db``, as specified This upgrades the database (``sqlite:///project.db``, as specified
when we created manage.py above) to the latest available version. (We when we created manage.py above) to the latest available version. (We
could also specify a version number if we wished, using the --version could also specify a version number if we wished, using the ``--version``
option.) We can see the database's version number has changed, and our option.) We can see the database's version number has changed, and our
table has been created: table has been created::
.. code-block:: none $ python manage.py db_version
% python manage.py db_version
1 1
% sqlite3 project.db $ sqlite3 project.db
sqlite> .tables sqlite> .tables
account migrate_version account migrate_version
@ -243,54 +254,58 @@ every time, despite any changes to your app's source code. You don't
want your change scripts' behavior changing when your source code want your change scripts' behavior changing when your source code
does. does.
Consider the following example of what can go wrong (i.e. what NOT to **Consider the following example of what can go wrong (i.e. what NOT to
do): do)**:
Your application defines a table in the model.py file: Your application defines a table in the model.py file:
:: .. code-block:: python
from sqlalchemy import * from sqlalchemy import *
meta = MetaData() meta = MetaData()
table = Table('mytable',meta, table = Table('mytable', meta,
Column('id',Integer,primary_key=True), Column('id', Integer, primary_key=True),
) )
...and uses this file to create a table in a change script: ... and uses this file to create a table in a change script:
:: .. code-block:: python
from sqlalchemy import * from sqlalchemy import *
from migrate import * from migrate import *
import model import model
model.meta.connect(migrate_engine)
def upgrade(): def upgrade(migrate_engine):
model.table.create() model.meta.bind(migrate_engine)
def downgrade():
def downgrade(migrate_engine):
model.meta.bind(migrate_engine)
model.table.drop() model.table.drop()
This runs successfully the first time. But what happens if we change This runs successfully the first time. But what happens if we change
the table definition? the table definition?
:: .. code-block:: python
table = Table('mytable',meta, table = Table('mytable', meta,
Column('id',Integer,primary_key=True), Column('id', Integer, primary_key=True),
Column('data',String(42)), Column('data', String(42)),
) )
We'll create a new column with a matching change script:: We'll create a new column with a matching change script
.. code-block:: python
from sqlalchemy import * from sqlalchemy import *
from migrate import * from migrate import *
import model import model
model.meta.connect(migrate_engine)
def upgrade(): def upgrade(migrate_engine):
model.meta.bind(migrate_engine)
model.table.data.create() model.table.data.create()
def downgrade(): def downgrade(migrate_engine):
model.meta.bind(migrate_engine)
model.table.data.drop() model.table.data.drop()
This appears to run fine when upgrading an existing database - but the This appears to run fine when upgrading an existing database - but the
@ -309,7 +324,9 @@ Writing for a specific database
Sometimes you need to write code for a specific database. Migrate Sometimes you need to write code for a specific database. Migrate
scripts can run under any database, however - the engine you're given scripts can run under any database, however - the engine you're given
might belong to any database. Use engine.name to get the name of the might belong to any database. Use engine.name to get the name of the
database you're working with:: database you're working with
.. code-block:: python
>>> from sqlalchemy import * >>> from sqlalchemy import *
>>> from migrate import * >>> from migrate import *
@ -322,11 +339,13 @@ Writings .sql scripts
--------------------- ---------------------
You might prefer to write your change scripts in SQL, as .sql files, You might prefer to write your change scripts in SQL, as .sql files,
rather than as Python scripts. SQLAlchemy-migrate can work with that:: rather than as Python scripts. SQLAlchemy-migrate can work with that
% python manage.py version .. code-block:: python
$ python manage.py version
1 1
% python manage.py script_sql postgres $ python manage.py script_sql postgres
This creates two scripts This creates two scripts
:file:`my_repository/versions/002_postgresql_upgrade.sql` and :file:`my_repository/versions/002_postgresql_upgrade.sql` and
@ -338,27 +357,29 @@ database defined by SQLAlchemy may be used here - ex. sqlite,
postgres, oracle, mysql... postgres, oracle, mysql...
.. _command-line-usage:
Command line usage Command line usage
================== ==================
.. currentmodule:: migrate.versioning.shell .. currentmodule:: migrate.versioning.shell
:command:`migrate` command is used for API interface. For list of commands and help use :command:`migrate` command is used for API interface. For list of commands and help use::
:: $ migrate --help
migrate --help :program:`migrate` command exectues :func:`main` function.
:program:`migrate` command uses :func:`migrate.versioning.shell.main` function.
For ease of usage, generate your own :ref:`project management script <project_management_script>`, For ease of usage, generate your own :ref:`project management script <project_management_script>`,
which calls :func:`shell.main` function with keywords arguments. which calls :func:`main` function with keywords arguments.
You may want to specify `url` and `repository` arguments which almost all API functions require as positional arguments. You may want to specify `url` and `repository` arguments which almost all API functions require.
If api command looks like:: If api command looks like::
migrate downgrade URL REPOSITORY VERSION [--preview_sql|--preview_py] $ migrate downgrade URL REPOSITORY VERSION [--preview_sql|--preview_py]
and you have a project management script that looks like:: and you have a project management script that looks like
.. code-block:: python
from migrate.versioning.shell import main from migrate.versioning.shell import main
@ -366,7 +387,7 @@ and you have a project management script that looks like::
you have first two slots filed, and command line usage would look like:: you have first two slots filed, and command line usage would look like::
# downgrade to version 2 and preview Python file # preview Python script
migrate downgrade 2 --preview_py migrate downgrade 2 --preview_py
# downgrade to version 2 # downgrade to version 2
@ -376,7 +397,7 @@ you have first two slots filed, and command line usage would look like::
Command line parsing refactored: positional parameters usage Command line parsing refactored: positional parameters usage
Whole command line parsing was rewriten from scratch with use of OptionParser. Whole command line parsing was rewriten from scratch with use of OptionParser.
Options passed as kwargs to :func:`migrate.versioning.shell.main` are now parsed correctly. Options passed as kwargs to :func:`~migrate.versioning.shell.main` are now parsed correctly.
Options are passed to commands in the following priority (starting from highest): Options are passed to commands in the following priority (starting from highest):
- optional (given by ``--some_option`` in commandline) - optional (given by ``--some_option`` in commandline)
@ -387,11 +408,11 @@ Options are passed to commands in the following priority (starting from highest)
Python API Python API
========== ==========
.. currentmodule:: migrate.versioning .. currentmodule:: migrate.versioning.api
All commands available from the command line are also available for All commands available from the command line are also available for
your Python scripts by importing :mod:`migrate.versioning`. See the your Python scripts by importing :mod:`migrate.versioning.api`. See the
:mod:`migrate.versioning` documentation for a list of functions; :mod:`migrate.versioning.api` documentation for a list of functions;
function names match equivalent shell commands. You can use this to function names match equivalent shell commands. You can use this to
help integrate SQLAlchemy Migrate with your existing update process. help integrate SQLAlchemy Migrate with your existing update process.
@ -399,12 +420,14 @@ For example, the following commands are similar:
*From the command line*:: *From the command line*::
% migrate help help $ migrate help help
/usr/bin/migrate help COMMAND /usr/bin/migrate help COMMAND
Displays help on a given command. Displays help on a given command.
*From Python*:: *From Python*
.. code-block:: python
import migrate.versioning.api import migrate.versioning.api
migrate.versioning.api.help('help') migrate.versioning.api.help('help')
@ -469,4 +492,4 @@ currently:
successfully during a commit, or the entire commit will fail. List successfully during a commit, or the entire commit will fail. List
the databases your application will actually be using to ensure your the databases your application will actually be using to ensure your
updates to that database work properly. This must be a list; updates to that database work properly. This must be a list;
example: `['postgres','sqlite']` example: `['postgres', 'sqlite']`

5
migrate/versioning/script/py.py
View File

@ -137,7 +137,10 @@ class PythonScript(base.BaseScript):
funcname = base.operations[op] funcname = base.operations[op]
func = self._func(funcname) func = self._func(funcname)
func(engine) try:
func(engine)
except TypeError:
print "upgrade/downgrade functions must accept one parameter (migrate_engine)"
@property @property
def module(self): def module(self):