update documenatation
This commit is contained in:
parent
cef2abb30f
commit
1f702ac6e0
4
TODO
4
TODO
|
@ -19,3 +19,7 @@ make_update_script_for_model:
|
||||||
|
|
||||||
- port to unittest2
|
- port to unittest2
|
||||||
- write documentation how to test all databases
|
- write documentation how to test all databases
|
||||||
|
- glossary
|
||||||
|
- managing output - logging
|
||||||
|
- required_dbs tests
|
||||||
|
- add story to changeset tutorial
|
||||||
|
|
|
@ -105,6 +105,8 @@ Module :mod:`migrate.versioning`
|
||||||
:members:
|
:members:
|
||||||
:synopsis: Database version and repository management
|
:synopsis: Database version and repository management
|
||||||
|
|
||||||
|
.. _versioning-api:
|
||||||
|
|
||||||
Module :mod:`api <migrate.versioning.api>`
|
Module :mod:`api <migrate.versioning.api>`
|
||||||
------------------------------------------
|
------------------------------------------
|
||||||
|
|
||||||
|
|
|
@ -23,11 +23,11 @@
|
||||||
|
|
||||||
.. _backwards-06:
|
.. _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.
|
- :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):``)
|
- 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.
|
- :meth:`Column.alter <migrate.changeset.schema.ChangesetColumn.alter>` does not accept `current_name` anymore, it extracts name from the old column.
|
||||||
|
|
||||||
0.5.4
|
0.5.4
|
||||||
-----
|
-----
|
||||||
|
|
|
@ -1,14 +1,14 @@
|
||||||
.. _changeset-system:
|
.. _changeset-system:
|
||||||
.. highlight:: python
|
.. highlight:: python
|
||||||
|
|
||||||
******************
|
**************************
|
||||||
Database changeset
|
Database schema migrations
|
||||||
******************
|
**************************
|
||||||
|
|
||||||
.. currentmodule:: migrate.changeset.schema
|
.. currentmodule:: migrate.changeset.schema
|
||||||
|
|
||||||
Importing :mod:`migrate.changeset` adds some new methods to existing
|
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
|
can be done either by a method or a function. Methods match
|
||||||
SQLAlchemy's existing API and are more intuitive when the object is
|
SQLAlchemy's existing API and are more intuitive when the object is
|
||||||
available; functions allow one to make changes when only the name of
|
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
|
assert table.c.col3 is col
|
||||||
|
|
||||||
.. warning::
|
.. 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::
|
.. note::
|
||||||
|
|
||||||
|
|
|
@ -47,16 +47,16 @@ master_doc = 'index'
|
||||||
|
|
||||||
# General information about the project.
|
# General information about the project.
|
||||||
project = u'SQLAlchemy Migrate'
|
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
|
# The version info for the project you're documenting, acts as replacement for
|
||||||
# |version| and |release|, also used in various other places throughout the
|
# |version| and |release|, also used in various other places throughout the
|
||||||
# built documents.
|
# built documents.
|
||||||
#
|
#
|
||||||
# The short X.Y version.
|
# The short X.Y version.
|
||||||
version = '0.5.4'
|
version = '0.6.0'
|
||||||
# The full version, including alpha/beta/rc tags.
|
# 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
|
# The language for content autogenerated by Sphinx. Refer to documentation
|
||||||
# for a list of supported languages.
|
# for a list of supported languages.
|
||||||
|
|
|
@ -2,9 +2,13 @@ Download
|
||||||
--------
|
--------
|
||||||
|
|
||||||
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`_, 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
|
You should now be able to use the *migrate* command from the command
|
||||||
line::
|
line::
|
||||||
|
@ -17,6 +21,7 @@ display more information about each command.
|
||||||
If you'd like to be notified when new versions of SQLAlchemy Migrate
|
If you'd like to be notified when new versions of SQLAlchemy Migrate
|
||||||
are released, subscribe to `migrate-announce`_.
|
are released, subscribe to `migrate-announce`_.
|
||||||
|
|
||||||
|
.. _pip: http://addmenow.si
|
||||||
.. _easy_install: http://peak.telecommunity.com/DevCenter/EasyInstall#installing-easy-install
|
.. _easy_install: http://peak.telecommunity.com/DevCenter/EasyInstall#installing-easy-install
|
||||||
.. _sqlalchemy: http://www.sqlalchemy.org/download.html
|
.. _sqlalchemy: http://www.sqlalchemy.org/download.html
|
||||||
.. _`project's download page`: http://code.google.com/p/sqlalchemy-migrate/downloads/list
|
.. _`project's download page`: http://code.google.com/p/sqlalchemy-migrate/downloads/list
|
||||||
|
@ -26,17 +31,17 @@ are released, subscribe to `migrate-announce`_.
|
||||||
Development
|
Development
|
||||||
-----------
|
-----------
|
||||||
|
|
||||||
Migrate's Subversion_ repository is at
|
Migrate's Mercurial_ repository is located at `Google Code`_.
|
||||||
http://sqlalchemy-migrate.googlecode.com/svn/
|
|
||||||
|
|
||||||
To get the latest trunk::
|
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`_.
|
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
|
.. _issue tracker: http://code.google.com/p/sqlalchemy-migrate/issues/list
|
||||||
.. _buildbot: http://buildbot.fubar.si
|
.. _hudson: http://hudson.fubar.si
|
||||||
|
|
|
@ -25,7 +25,7 @@
|
||||||
SQLAlchemy Migrate.
|
SQLAlchemy Migrate.
|
||||||
|
|
||||||
Currently, sqlalchemy-migrate supports Python versions from 2.4 to 2.6.
|
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::
|
.. warning::
|
||||||
|
|
||||||
|
@ -44,34 +44,34 @@ Download and Development
|
||||||
Dialect support
|
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 |
|
| 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 TABLE <table-rename>` | yes | yes | yes | yes | no | not supported |
|
||||||
| | | | | | | |
|
| | | | | | | |
|
||||||
+---------------------------------------------------------+--------------------------+------------------------------+------------------------+---------------------------+-------------------------------+-------+
|
+---------------------------------------------------------+--------------------------+------------------------------+------------------------+---------------------------+-------------------------------+--------------------+
|
||||||
| :ref:`ALTER TABLE RENAME COLUMN <column-alter>` | yes | yes | yes | yes | yes | |
|
| :ref:`ALTER TABLE RENAME COLUMN <column-alter>` | yes | yes | yes | yes | yes | not supported |
|
||||||
| | (workaround) [#1]_ | | | | | |
|
| | (workaround) [#1]_ | | | | | |
|
||||||
+---------------------------------------------------------+--------------------------+------------------------------+------------------------+---------------------------+-------------------------------+-------+
|
+---------------------------------------------------------+--------------------------+------------------------------+------------------------+---------------------------+-------------------------------+--------------------+
|
||||||
| :ref:`ALTER TABLE ADD COLUMN <column-create>` | yes | yes | yes | yes | yes | |
|
| :ref:`ALTER TABLE ADD COLUMN <column-create>` | yes | yes | yes | yes | yes | not supported |
|
||||||
| | (with limitations) [#2]_ | | | | | |
|
| | (with limitations) [#2]_ | | | | | |
|
||||||
+---------------------------------------------------------+--------------------------+------------------------------+------------------------+---------------------------+-------------------------------+-------+
|
+---------------------------------------------------------+--------------------------+------------------------------+------------------------+---------------------------+-------------------------------+--------------------+
|
||||||
| :ref:`ALTER TABLE DROP COLUMN <column-drop>` | yes | yes | yes | yes | yes | |
|
| :ref:`ALTER TABLE DROP COLUMN <column-drop>` | yes | yes | yes | yes | yes | not supported |
|
||||||
| | (workaround) [#1]_ | | | | | |
|
| | (workaround) [#1]_ | | | | | |
|
||||||
+---------------------------------------------------------+--------------------------+------------------------------+------------------------+---------------------------+-------------------------------+-------+
|
+---------------------------------------------------------+--------------------------+------------------------------+------------------------+---------------------------+-------------------------------+--------------------+
|
||||||
| :ref:`ALTER TABLE ALTER COLUMN <column-alter>` | yes | yes | yes | yes | yes [#4]_ | |
|
| :ref:`ALTER TABLE ALTER COLUMN <column-alter>` | yes | yes | yes | yes | yes [#4]_ | not supported |
|
||||||
| | (workaround) [#1]_ | | | (with limitations) [#3]_ | | |
|
| | (workaround) [#1]_ | | | (with limitations) [#3]_ | | |
|
||||||
+---------------------------------------------------------+--------------------------+------------------------------+------------------------+---------------------------+-------------------------------+-------+
|
+---------------------------------------------------------+--------------------------+------------------------------+------------------------+---------------------------+-------------------------------+--------------------+
|
||||||
| :ref:`ALTER TABLE ADD CONSTRAINT <constraint-tutorial>` | no | yes | yes | yes | yes | |
|
| :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 | |
|
| :ref:`ALTER TABLE DROP CONSTRAINT <constraint-tutorial>`| no | yes | yes | yes | yes | not supported |
|
||||||
| | | | | | | |
|
| | | | | | | |
|
||||||
+---------------------------------------------------------+--------------------------+------------------------------+------------------------+---------------------------+-------------------------------+-------+
|
+---------------------------------------------------------+--------------------------+------------------------------+------------------------+---------------------------+-------------------------------+--------------------+
|
||||||
| :ref:`RENAME INDEX <index-rename>` | no | yes | no | yes | yes | |
|
| :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.
|
.. [#1] Table is renamed to temporary table, new table is created followed by INSERT statements.
|
||||||
|
@ -82,10 +82,9 @@ Dialect support
|
||||||
Documentation
|
Documentation
|
||||||
-------------
|
-------------
|
||||||
|
|
||||||
SQLAlchemy is split into two parts, database schema versioning and
|
SQLAlchemy Migrate is split into two parts, database schema versioning (:mod:`migrate.versioning`) and
|
||||||
database changeset management. This is represented by two python
|
database migration management (:mod:`migrate.changeset`).
|
||||||
packages :mod:`migrate.versioning` and :mod:`migrate.changeset`. The
|
The versioning API is available as the :ref:`migrate <command-line-usage>` command.
|
||||||
versioning API is available as the :ref:`migrate <command-line-usage>` command.
|
|
||||||
|
|
||||||
.. toctree::
|
.. toctree::
|
||||||
|
|
||||||
|
|
|
@ -1,6 +1,6 @@
|
||||||
.. _versioning-system:
|
.. _versioning-system:
|
||||||
.. currentmodule:: migrate.versioning
|
.. currentmodule:: migrate.versioning
|
||||||
.. highlight:: bash
|
.. highlight:: console
|
||||||
|
|
||||||
***********************************
|
***********************************
|
||||||
Database schema versioning workflow
|
Database schema versioning workflow
|
||||||
|
@ -22,36 +22,39 @@ Create a change repository
|
||||||
--------------------------
|
--------------------------
|
||||||
|
|
||||||
To begin, we'll need to create a *repository* for our
|
To begin, we'll need to create a *repository* for our
|
||||||
project. Repositories are associated with a single database schema,
|
project.
|
||||||
and store collections of change scripts to manage that schema. The
|
|
||||||
scripts in a repository may be applied to any number of databases.
|
|
||||||
|
|
||||||
Repositories each have a name. This name is used to identify the
|
All work with repositories is done using the :ref:`migrate <command-line-usage>` command. Let's
|
||||||
repository we're working with.
|
|
||||||
|
|
||||||
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 relative to 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`.
|
||||||
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.
|
|
||||||
|
|
||||||
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
|
Next we need to declare database to be under version control.
|
||||||
control. Information on a database's version is stored in the database
|
Information on a database's version is stored in the database
|
||||||
itself; declaring a database to be under version control creates a
|
itself; declaring a database to be under version control creates a
|
||||||
table, named 'migrate_version' by default, and associates it with your
|
table named **migrate_version** and associates it with your repository.
|
||||||
repository.
|
|
||||||
|
|
||||||
The database is specified as a `SQLAlchemy database url`_.
|
The database is specified as a `SQLAlchemy database url`_.
|
||||||
|
|
||||||
|
@ -102,12 +105,17 @@ and use it to perform commands::
|
||||||
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
|
||||||
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
|
repository and database connection entered above. The difference
|
||||||
between the script :file:`manage.py` in the current directory and the
|
between the script :file:`manage.py` in the current directory and the
|
||||||
script inside the repository is, that the one in the current directory
|
script inside the repository is, that the one in the current directory
|
||||||
has the database URL preconfigured.
|
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
|
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
|
:file:`my_repository/versions/001_Add_account_table.py`. Next, we'll
|
||||||
edit this script to create our table.
|
edit this script to create our table.
|
||||||
|
|
||||||
|
|
||||||
Edit the change script
|
Edit the change script
|
||||||
----------------------
|
----------------------
|
||||||
|
|
||||||
Our change script defines two functions, currently empty:
|
Our change script predefines two functions, currently empty:
|
||||||
:func:`upgrade`` and :func:`downgrade`. We'll fill those in
|
:func:`upgrade` and :func:`downgrade`. We'll fill those in
|
||||||
|
|
||||||
.. code-block:: python
|
.. code-block:: python
|
||||||
|
|
||||||
from sqlalchemy import *
|
from sqlalchemy import *
|
||||||
from migrate 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()
|
def upgrade(migrate_engine):
|
||||||
account = Table('account', meta,
|
meta.bind = migrate_engine
|
||||||
Column('id', Integer, primary_key=True),
|
account.create()
|
||||||
Column('login', String(40)),
|
|
||||||
Column('passwd', String(40)),
|
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
|
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 :ref:`schema changes<changeset-system>` we want to perform
|
||||||
here, we're creating a table. :func:`downgrade` should reverse changes made
|
(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
|
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.)
|
||||||
|
|
||||||
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
|
.. note::
|
||||||
application, as your change scripts might break when your application
|
|
||||||
changes. More about `writing scripts with consistent behavior`_.
|
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
|
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
|
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 :func:`upgrade` and :func:`downgrade` run.
|
||||||
|
|
||||||
To test the script::
|
To test the script::
|
||||||
|
|
||||||
|
@ -201,14 +219,14 @@ To test the script::
|
||||||
Our script runs on our database (``sqlite:///project.db``, as
|
Our script runs on our database (``sqlite:///project.db``, as
|
||||||
specified in manage.py) without any errors.
|
specified in manage.py) without any errors.
|
||||||
|
|
||||||
Our repository's version now is::
|
Our repository's version is::
|
||||||
|
|
||||||
$ python manage.py version
|
$ python manage.py version
|
||||||
1
|
1
|
||||||
|
|
||||||
.. warning::
|
.. 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
|
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
|
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
|
.. warning::
|
||||||
do)**:
|
|
||||||
|
|
||||||
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
|
.. code-block:: python
|
||||||
|
|
||||||
|
@ -284,10 +303,13 @@ Your application defines a table in the model.py file:
|
||||||
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 in :file:`model.py`?
|
||||||
|
|
||||||
.. code-block:: python
|
.. code-block:: python
|
||||||
|
|
||||||
|
from sqlalchemy import *
|
||||||
|
|
||||||
|
meta = MetaData()
|
||||||
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)),
|
||||||
|
@ -309,6 +331,7 @@ We'll create a new column with a matching change script
|
||||||
model.meta.bind = migrate_engine
|
model.meta.bind = migrate_engine
|
||||||
model.table.drop()
|
model.table.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
|
||||||
first script's behavior changed! Running all our change scripts on a
|
first script's behavior changed! Running all our change scripts on a
|
||||||
new database will result in an error - the first script creates the
|
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
|
definition into each change script rather than importing parts of your
|
||||||
application.
|
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
|
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,
|
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::
|
||||||
|
|
||||||
.. code-block:: python
|
|
||||||
|
|
||||||
$ python manage.py version
|
$ python manage.py version
|
||||||
1
|
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::
|
you have first two slots filed, and command line usage would look like::
|
||||||
|
|
||||||
# preview Python script
|
# preview Python script
|
||||||
migrate downgrade 2 --preview_py
|
$ migrate downgrade 2 --preview_py
|
||||||
|
|
||||||
# downgrade to version 2
|
# downgrade to version 2
|
||||||
migrate downgrade 2
|
$ migrate downgrade 2
|
||||||
|
|
||||||
.. versionchanged:: 0.5.4
|
.. versionchanged:: 0.5.4
|
||||||
Command line parsing refactored: positional parameters usage
|
Command line parsing refactored: positional parameters usage
|
||||||
|
@ -442,6 +466,7 @@ For example, the following commands are similar:
|
||||||
|
|
||||||
.. _repository_configuration:
|
.. _repository_configuration:
|
||||||
|
|
||||||
|
|
||||||
Experimental commands
|
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
|
the necessary arguments to the commands from the output of ``migrate
|
||||||
help <command>``.
|
help <command>``.
|
||||||
|
|
||||||
|
|
||||||
Repository configuration
|
Repository configuration
|
||||||
========================
|
========================
|
||||||
|
|
||||||
|
|
|
@ -5,5 +5,9 @@
|
||||||
using Python.
|
using Python.
|
||||||
"""
|
"""
|
||||||
|
|
||||||
|
from migrate.versioning import *
|
||||||
|
from migrate.changeset import *
|
||||||
|
|
||||||
|
|
||||||
class MigrateDeprecationWarning(DeprecationWarning):
|
class MigrateDeprecationWarning(DeprecationWarning):
|
||||||
"""Warning for deprecated features in Migrate"""
|
"""Warning for deprecated features in Migrate"""
|
||||||
|
|
Loading…
Reference in New Issue