x/sqlalchemy-migrate
Code Issues Proposed changes

update documenatation

Browse Source
This commit is contained in:
iElectric 2010-04-30 22:28:05 +02:00
parent cef2abb30f
commit 1f702ac6e0
9 changed files with 153 additions and 113 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
TODO
View File

@ -19,3 +19,7 @@ make_update_script_for_model:
- port to unittest2
- write documentation how to test all databases
- glossary
- managing output - logging
- required_dbs tests
- add story to changeset tutorial

2
docs/api.rst
View File

@ -105,6 +105,8 @@ Module :mod:`migrate.versioning`
:members:
:synopsis: Database version and repository management
.. _versioning-api:
Module :mod:`api <migrate.versioning.api>`
------------------------------------------

8
docs/changelog.rst
View File

@ -23,11 +23,11 @@
.. _backwards-06:
**Backward incompatible changes**:
.. warning:: **Backward incompatible changes**:
- :func:`api.test` and schema comparison functions now all accept `url` as first parameter and `repository` as second.
- python upgrade/downgrade scripts do not import `migrate_engine` magically, but recieve engine as the only parameter to function (eg. ``def upgrade(migrate_engine):``)
- :meth:`Column.alter <migrate.changeset.schema.ChangesetColumn.alter>` does not accept `current_name` anymore, it extracts name from the old column.
- :func:`api.test` and schema comparison functions now all accept `url` as first parameter and `repository` as second.
- python upgrade/downgrade scripts do not import `migrate_engine` magically, but recieve engine as the only parameter to function (eg. ``def upgrade(migrate_engine):``)
- :meth:`Column.alter <migrate.changeset.schema.ChangesetColumn.alter>` does not accept `current_name` anymore, it extracts name from the old column.
0.5.4
-----

10
docs/changeset.rst
View File

@ -1,14 +1,14 @@
.. _changeset-system:
.. highlight:: python
******************
Database changeset
******************
**************************
Database schema migrations
**************************
.. currentmodule:: migrate.changeset.schema
Importing :mod:`migrate.changeset` adds some new methods to existing
SA objects, as well as creating functions of its own. Most operations
SQLAlchemy objects, as well as creating functions of its own. Most operations
can be done either by a method or a function. Methods match
SQLAlchemy's existing API and are more intuitive when the object is
available; functions allow one to make changes when only the name of
@ -70,7 +70,7 @@ Given a standard SQLAlchemy table::
assert table.c.col3 is col
.. warning::
Since version ``0.6.0`` passing column into alter is deprecated. Pass in explicit parameters instead.
Since version ``0.6.0`` passing column into :meth:`ChangesetColumn.alter` is deprecated. Pass in explicit parameters instead.
.. note::

6
docs/conf.py
View File

@ -47,16 +47,16 @@ master_doc = 'index'
# General information about the project.
project = u'SQLAlchemy Migrate'
copyright = u'2009, Evan Rosson, Jan Dittberner'
copyright = u'2009, Evan Rosson, Jan Dittberner, Domen Kožar'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = '0.5.4'
version = '0.6.0'
# The full version, including alpha/beta/rc tags.
release = '0.5.4'
release = '0.6.0'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.

21
docs/download.rst
View File

@ -2,9 +2,13 @@ Download
--------
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`_, pip_ or via easy_install_::
easy_install sqlalchemy-migrate
easy_install sqlalchemy-migrate
or::
pip install sqlalchemy-migrate
You should now be able to use the *migrate* command from the command
line::
@ -17,6 +21,7 @@ display more information about each command.
If you'd like to be notified when new versions of SQLAlchemy Migrate
are released, subscribe to `migrate-announce`_.
.. _pip: http://addmenow.si
.. _easy_install: http://peak.telecommunity.com/DevCenter/EasyInstall#installing-easy-install
.. _sqlalchemy: http://www.sqlalchemy.org/download.html
.. _`project's download page`: http://code.google.com/p/sqlalchemy-migrate/downloads/list
@ -26,17 +31,17 @@ are released, subscribe to `migrate-announce`_.
Development
-----------
Migrate's Subversion_ repository is at
http://sqlalchemy-migrate.googlecode.com/svn/
Migrate's Mercurial_ repository is located at `Google Code`_.
To get the latest trunk::
svn co http://sqlalchemy-migrate.googlecode.com/svn/trunk
hg clone http://sqlalchemy-migrate.googlecode.com/hg/
Patches should be submitted to the `issue tracker`_.
We use `buildbot`_ to help us run tests on all databases that migrate supports.
We use `hudson`_ Continuous Integration tool to help us run tests on all databases that migrate supports.
.. _subversion: http://subversion.tigris.org/
.. _Mercurial: http://www.mercurial-scm.org/
.. _Google Code: http://sqlalchemy-migrate.googlecode.com/hg/
.. _issue tracker: http://code.google.com/p/sqlalchemy-migrate/issues/list
.. _buildbot: http://buildbot.fubar.si
.. _hudson: http://hudson.fubar.si

65
docs/index.rst
View File

@ -25,7 +25,7 @@
SQLAlchemy Migrate.
Currently, sqlalchemy-migrate supports Python versions from 2.4 to 2.6.
SQLAlchemy >=0.5 is supported only.
SQLAlchemy Migrate 0.6.0 supports SQLAlchemy both 0.5.x and 0.6.x branches.
.. warning::
@ -44,34 +44,34 @@ Download and Development
Dialect support
---------------
+---------------------------------------------------------+--------------------------+------------------------------+------------------------+---------------------------+-------------------------------+-------+
| Operation / Dialect | :ref:`sqlite <sqlite-d>` | :ref:`postgres <postgres-d>` | :ref:`mysql <mysql-d>` | :ref:`oracle <oracle-d>` | :ref:`firebird <firebird-d>` | mssql |
| | | | | | | |
+=========================================================+==========================+==============================+========================+===========================+===============================+=======+
| :ref:`ALTER TABLE RENAME TABLE <table-rename>` | yes | yes | yes | yes | no | |
| | | | | | | |
+---------------------------------------------------------+--------------------------+------------------------------+------------------------+---------------------------+-------------------------------+-------+
| :ref:`ALTER TABLE RENAME COLUMN <column-alter>` | yes | yes | yes | yes | yes | |
| | (workaround) [#1]_ | | | | | |
+---------------------------------------------------------+--------------------------+------------------------------+------------------------+---------------------------+-------------------------------+-------+
| :ref:`ALTER TABLE ADD COLUMN <column-create>` | yes | yes | yes | yes | yes | |
| | (with limitations) [#2]_ | | | | | |
+---------------------------------------------------------+--------------------------+------------------------------+------------------------+---------------------------+-------------------------------+-------+
| :ref:`ALTER TABLE DROP COLUMN <column-drop>` | yes | yes | yes | yes | yes | |
| | (workaround) [#1]_ | | | | | |
+---------------------------------------------------------+--------------------------+------------------------------+------------------------+---------------------------+-------------------------------+-------+
| :ref:`ALTER TABLE ALTER COLUMN <column-alter>` | yes | yes | yes | yes | yes [#4]_ | |
| | (workaround) [#1]_ | | | (with limitations) [#3]_ | | |
+---------------------------------------------------------+--------------------------+------------------------------+------------------------+---------------------------+-------------------------------+-------+
| :ref:`ALTER TABLE ADD CONSTRAINT <constraint-tutorial>` | no | yes | yes | yes | yes | |
| | | | | | | |
+---------------------------------------------------------+--------------------------+------------------------------+------------------------+---------------------------+-------------------------------+-------+
| :ref:`ALTER TABLE DROP CONSTRAINT <constraint-tutorial>`| no | yes | yes | yes | yes | |
| | | | | | | |
+---------------------------------------------------------+--------------------------+------------------------------+------------------------+---------------------------+-------------------------------+-------+
| :ref:`RENAME INDEX <index-rename>` | no | yes | no | yes | yes | |
| | | | | | | |
+---------------------------------------------------------+--------------------------+------------------------------+------------------------+---------------------------+-------------------------------+-------+
+---------------------------------------------------------+--------------------------+------------------------------+------------------------+---------------------------+-------------------------------+--------------------+
| Operation / Dialect | :ref:`sqlite <sqlite-d>` | :ref:`postgres <postgres-d>` | :ref:`mysql <mysql-d>` | :ref:`oracle <oracle-d>` | :ref:`firebird <firebird-d>` | mssql |
| | | | | | | |
+=========================================================+==========================+==============================+========================+===========================+===============================+====================+
| :ref:`ALTER TABLE RENAME TABLE <table-rename>` | yes | yes | yes | yes | no | not supported |
| | | | | | | |
+---------------------------------------------------------+--------------------------+------------------------------+------------------------+---------------------------+-------------------------------+--------------------+
| :ref:`ALTER TABLE RENAME COLUMN <column-alter>` | yes | yes | yes | yes | yes | not supported |
| | (workaround) [#1]_ | | | | | |
+---------------------------------------------------------+--------------------------+------------------------------+------------------------+---------------------------+-------------------------------+--------------------+
| :ref:`ALTER TABLE ADD COLUMN <column-create>` | yes | yes | yes | yes | yes | not supported |
| | (with limitations) [#2]_ | | | | | |
+---------------------------------------------------------+--------------------------+------------------------------+------------------------+---------------------------+-------------------------------+--------------------+
| :ref:`ALTER TABLE DROP COLUMN <column-drop>` | yes | yes | yes | yes | yes | not supported |
| | (workaround) [#1]_ | | | | | |
+---------------------------------------------------------+--------------------------+------------------------------+------------------------+---------------------------+-------------------------------+--------------------+
| :ref:`ALTER TABLE ALTER COLUMN <column-alter>` | yes | yes | yes | yes | yes [#4]_ | not supported |
| | (workaround) [#1]_ | | | (with limitations) [#3]_ | | |
+---------------------------------------------------------+--------------------------+------------------------------+------------------------+---------------------------+-------------------------------+--------------------+
| :ref:`ALTER TABLE ADD CONSTRAINT <constraint-tutorial>` | no | yes | yes | yes | yes | not supported |
| | | | | | | |
+---------------------------------------------------------+--------------------------+------------------------------+------------------------+---------------------------+-------------------------------+--------------------+
| :ref:`ALTER TABLE DROP CONSTRAINT <constraint-tutorial>`| no | yes | yes | yes | yes | not supported |
| | | | | | | |
+---------------------------------------------------------+--------------------------+------------------------------+------------------------+---------------------------+-------------------------------+--------------------+
| :ref:`RENAME INDEX <index-rename>` | no | yes | no | yes | yes | not supported |
| | | | | | | |
+---------------------------------------------------------+--------------------------+------------------------------+------------------------+---------------------------+-------------------------------+--------------------+
.. [#1] Table is renamed to temporary table, new table is created followed by INSERT statements.
@ -82,10 +82,9 @@ Dialect support
Documentation
-------------
SQLAlchemy is split into two parts, database schema versioning and
database changeset management. This is represented by two python
packages :mod:`migrate.versioning` and :mod:`migrate.changeset`. The
versioning API is available as the :ref:`migrate <command-line-usage>` command.
SQLAlchemy Migrate is split into two parts, database schema versioning (:mod:`migrate.versioning`) and
database migration management (:mod:`migrate.changeset`).
The versioning API is available as the :ref:`migrate <command-line-usage>` command.
.. toctree::

146
docs/versioning.rst
View File

@ -1,6 +1,6 @@
.. _versioning-system:
.. currentmodule:: migrate.versioning
.. highlight:: bash
.. highlight:: console
***********************************
Database schema versioning workflow
@ -22,36 +22,39 @@ Create a change repository
--------------------------
To begin, we'll need to create a *repository* for our
project. 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.
project.
Repositories each have a name. This name is used to identify the
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 :ref:`migrate <command-line-usage>` command. Let's
create our project's repository::
$ 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 versions that will store the schema versions,
a configuration file :file:`migrate.cfg` that contains
:ref:`repository configuration <repository_configuration>`, a
:file:`README` file containing information that the directory is an
sqlalchemy-migrate repository 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 the repository.
my_repository/ named `Example project`.
Version-control a database
The repository directory
contains a sub directory :file:`versions` that will store the :ref:`schema versions <changeset-system>`,
a configuration file :file:`migrate.cfg` that contains
: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 create a database and declare it to be under version
control. Information on a database's version is stored in the database
Next we need to declare database to be under version control.
Information on a database's version is stored in the database
itself; declaring a database to be under version control creates a
table, named 'migrate_version' by default, and associates it with your
repository.
table named **migrate_version** and associates it with your repository.
The database is specified as a `SQLAlchemy database url`_.
@ -102,12 +105,17 @@ and use it to perform commands::
0
The script manage.py was created. All commands we perform with it are
the same as those performed with the 'migrate' tool, using the
the same as those performed with the :ref:`migrate <command-line-usage>` tool, using the
repository and database connection entered above. The difference
between the script :file:`manage.py` in the current directory and the
script inside the repository is, that the one in the current directory
has the database URL preconfigured.
.. 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.
Making schema changes
=====================
@ -139,47 +147,57 @@ This creates an empty change script at
:file:`my_repository/versions/001_Add_account_table.py`. Next, we'll
edit this script to create our table.
Edit the change script
----------------------
Our change script defines two functions, currently empty:
:func:`upgrade`` and :func:`downgrade`. We'll fill those in
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 *
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)),
)
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()
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 changes we want to perform;
here, we're creating a table. :func:`downgrade` should reverse changes made
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
able to revert to an older version of the database or test your
scripts without it.)
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.
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`_.
.. 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`_.
Test the change script
------------------------
@ -189,7 +207,7 @@ script will run its :func:`upgrade` and :func:`downgrade` functions on a specifi
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
to correct it by hand. If the test is successful, the database should
appear unchanged after upgrade() and downgrade() run.
appear unchanged after :func:`upgrade` and :func:`downgrade` run.
To test the script::
@ -201,14 +219,14 @@ To test the script::
Our script runs on our database (``sqlite:///project.db``, as
specified in manage.py) without any errors.
Our repository's version now is::
Our repository's version is::
$ python manage.py version
1
.. warning::
test command exectues actual script, be sure you are NOT doing this on production database.
test command executes actual script, be sure you are NOT doing this on production database.
Upgrade the database
@ -254,10 +272,11 @@ every time, despite any changes to your app's source code. You don't
want your change scripts' behavior changing when your source code
does.
**Consider the following example of what can go wrong (i.e. what NOT to
do)**:
.. warning::
Your application defines a table in the model.py file:
**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
@ -284,10 +303,13 @@ Your application defines a table in the model.py file:
model.table.drop()
This runs successfully the first time. But what happens if we change
the table definition?
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)),
@ -309,6 +331,7 @@ We'll create a new column with a matching change script
model.meta.bind = migrate_engine
model.table.drop()
This appears to run fine when upgrading an existing database - but the
first script's behavior changed! Running all our change scripts on a
new database will result in an error - the first script creates the
@ -319,6 +342,9 @@ To avoid the above problem, you should copy-paste your table
definition into each change script rather than importing parts of your
application.
.. note:: Sometimes it is enough to just reflect tables with SQLAlchemy instead of copy-pasting - but remember, explicit is better than implicit!
Writing for a specific database
-------------------------------
@ -340,9 +366,7 @@ Writings .sql scripts
---------------------
You might prefer to write your change scripts in SQL, as .sql files,
rather than as Python scripts. SQLAlchemy-migrate can work with that
.. code-block:: python
rather than as Python scripts. SQLAlchemy-migrate can work with that::
$ python manage.py version
1
@ -389,10 +413,10 @@ and you have a project management script that looks like
you have first two slots filed, and command line usage would look like::
# preview Python script
migrate downgrade 2 --preview_py
$ migrate downgrade 2 --preview_py
# downgrade to version 2
migrate downgrade 2
$ migrate downgrade 2
.. versionchanged:: 0.5.4
Command line parsing refactored: positional parameters usage
@ -442,6 +466,7 @@ For example, the following commands are similar:
.. _repository_configuration:
Experimental commands
=====================
@ -470,6 +495,7 @@ As this sections headline says: These features are EXPERIMENTAL. Take
the necessary arguments to the commands from the output of ``migrate
help <command>``.
Repository configuration
========================

4
migrate/__init__.py
View File

@ -5,5 +5,9 @@
using Python.
"""
from migrate.versioning import *
from migrate.changeset import *
class MigrateDeprecationWarning(DeprecationWarning):
"""Warning for deprecated features in Migrate"""