update sqlalchemy documentation links
use explicit code-block markup
This commit is contained in:
Jan Dittberner
parent
3dc1cf28b0
commit
05e76a1430
@ -7,19 +7,18 @@ Database schema migrations
|
||||
|
||||
.. currentmodule:: migrate.changeset.schema
|
||||
|
||||
Importing :mod:`migrate.changeset` adds some new methods to existing
|
||||
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
|
||||
an object is available (for example, adding a column to a table in the
|
||||
database without having to load that table into Python).
|
||||
Importing :mod:`migrate.changeset` adds some new methods to existing 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 an object is available (for example, adding a
|
||||
column to a table in the database without having to load that table into
|
||||
Python).
|
||||
|
||||
Changeset operations can be used independently of SQLAlchemy Migrate's
|
||||
:ref:`versioning <versioning-system>`.
|
||||
|
||||
For more information, see the API documentation for
|
||||
:mod:`migrate.changeset`.
|
||||
For more information, see the API documentation for :mod:`migrate.changeset`.
|
||||
|
||||
.. _summary-changeset-api:
|
||||
|
||||
@ -43,69 +42,76 @@ Here are some direct links to the relevent sections of the API documentations:
|
||||
|
||||
.. note::
|
||||
|
||||
Many of the schema modification methods above take an
|
||||
``alter_metadata`` keyword parameter. This parameter defaults to
|
||||
``True``.
|
||||
Many of the schema modification methods above take an ``alter_metadata``
|
||||
keyword parameter. This parameter defaults to `True`.
|
||||
|
||||
The following sections give examples of how to make various kinds of
|
||||
schema changes.
|
||||
The following sections give examples of how to make various kinds of schema
|
||||
changes.
|
||||
|
||||
Column
|
||||
======
|
||||
|
||||
Given a standard SQLAlchemy table::
|
||||
Given a standard SQLAlchemy table:
|
||||
|
||||
table = Table('mytable', meta,
|
||||
Column('id', Integer, primary_key=True),
|
||||
)
|
||||
table.create()
|
||||
.. code-block:: python
|
||||
|
||||
table = Table('mytable', meta,
|
||||
Column('id', Integer, primary_key=True),
|
||||
)
|
||||
table.create()
|
||||
|
||||
.. _column-create:
|
||||
|
||||
You can create a column with :meth:`~ChangesetColumn.create`::
|
||||
You can create a column with :meth:`~ChangesetColumn.create`:
|
||||
|
||||
col = Column('col1', String, default='foobar')
|
||||
col.create(table, populate_default=True)
|
||||
.. code-block:: python
|
||||
|
||||
# Column is added to table based on its name
|
||||
assert col is table.c.col1
|
||||
col = Column('col1', String, default='foobar')
|
||||
col.create(table, populate_default=True)
|
||||
|
||||
# col1 is populated with 'foobar' because of `populate_default`
|
||||
# Column is added to table based on its name
|
||||
assert col is table.c.col1
|
||||
|
||||
# col1 is populated with 'foobar' because of `populate_default`
|
||||
|
||||
.. _column-drop:
|
||||
|
||||
.. note::
|
||||
|
||||
You can pass `primary_key_name`, `index_name`
|
||||
and `unique_name` to the :meth:`~ChangesetColumn.create` method to issue ``ALTER TABLE ADD
|
||||
You can pass `primary_key_name`, `index_name` and `unique_name` to the
|
||||
:meth:`~ChangesetColumn.create` method to issue ``ALTER TABLE ADD
|
||||
CONSTRAINT`` after changing the column.
|
||||
|
||||
For multi columns constraints and other advanced configuration,
|
||||
check the :ref:`constraint tutorial <constraint-tutorial>`.
|
||||
For multi columns constraints and other advanced configuration, check the
|
||||
:ref:`constraint tutorial <constraint-tutorial>`.
|
||||
|
||||
.. versionadded:: 0.6.0
|
||||
|
||||
You can drop a column with :meth:`~ChangesetColumn.drop`::
|
||||
You can drop a column with :meth:`~ChangesetColumn.drop`:
|
||||
|
||||
col.drop()
|
||||
.. code-block:: python
|
||||
|
||||
col.drop()
|
||||
|
||||
|
||||
.. _column-alter:
|
||||
|
||||
You can alter a column with :meth:`~ChangesetColumn.alter`::
|
||||
You can alter a column with :meth:`~ChangesetColumn.alter`:
|
||||
|
||||
col.alter(name='col2')
|
||||
.. code-block:: python
|
||||
|
||||
# Renaming a column affects how it's accessed by the table object
|
||||
assert col is table.c.col2
|
||||
col.alter(name='col2')
|
||||
|
||||
# Other properties can be modified as well
|
||||
col.alter(type=String(42), default="life, the universe, and everything", nullable=False)
|
||||
# Renaming a column affects how it's accessed by the table object
|
||||
assert col is table.c.col2
|
||||
|
||||
# Given another column object, col1.alter(col2), col1 will be changed to match col2
|
||||
col.alter(Column('col3', String(77), nullable=True))
|
||||
assert col.nullable
|
||||
assert table.c.col3 is col
|
||||
# Other properties can be modified as well
|
||||
col.alter(type=String(42), default="life, the universe, and everything", nullable=False)
|
||||
|
||||
# Given another column object, col1.alter(col2), col1 will be changed to match col2
|
||||
col.alter(Column('col3', String(77), nullable=True))
|
||||
assert col.nullable
|
||||
assert table.c.col3 is col
|
||||
|
||||
.. deprecated:: 0.6.0
|
||||
Passing a :class:`~sqlalchemy.schema.Column` to
|
||||
@ -121,11 +127,13 @@ Table
|
||||
|
||||
SQLAlchemy includes support for `creating and dropping`__ tables..
|
||||
|
||||
Tables can be renamed with :meth:`~ChangesetTable.rename`::
|
||||
Tables can be renamed with :meth:`~ChangesetTable.rename`:
|
||||
|
||||
table.rename('newtablename')
|
||||
.. code-block:: python
|
||||
|
||||
.. __: http://www.sqlalchemy.org/docs/05/metadata.html#creating-and-dropping-database-tables
|
||||
table.rename('newtablename')
|
||||
|
||||
.. __: http://www.sqlalchemy.org/docs/core/schema.html#creating-and-dropping-database-tables
|
||||
.. currentmodule:: migrate.changeset.constraint
|
||||
|
||||
|
||||
@ -136,11 +144,14 @@ Index
|
||||
|
||||
SQLAlchemy supports `creating and dropping`__ indexes.
|
||||
|
||||
Indexes can be renamed using :meth:`~migrate.changeset.schema.ChangesetIndex.rename`::
|
||||
Indexes can be renamed using
|
||||
:meth:`~migrate.changeset.schema.ChangesetIndex.rename`:
|
||||
|
||||
index.rename('newindexname')
|
||||
.. code-block:: python
|
||||
|
||||
.. __: http://www.sqlalchemy.org/docs/05/metadata.html#indexes
|
||||
index.rename('newindexname')
|
||||
|
||||
.. __: http://www.sqlalchemy.org/docs/core/schema.html#indexes
|
||||
|
||||
|
||||
.. _constraint-tutorial:
|
||||
@ -150,29 +161,33 @@ Constraint
|
||||
|
||||
.. currentmodule:: migrate.changeset.constraint
|
||||
|
||||
SQLAlchemy supports creating or dropping constraints at the same time
|
||||
a table is created or dropped. SQLAlchemy Migrate adds support for
|
||||
creating and dropping
|
||||
:class:`~sqlalchemy.schema.PrimaryKeyConstraint`,
|
||||
SQLAlchemy supports creating or dropping constraints at the same time a table
|
||||
is created or dropped. SQLAlchemy Migrate adds support for creating and
|
||||
dropping :class:`~sqlalchemy.schema.PrimaryKeyConstraint`,
|
||||
:class:`~sqlalchemy.schema.ForeignKeyConstraint`,
|
||||
:class:`~sqlalchemy.schema.CheckConstraint` and
|
||||
:class:`~sqlalchemy.schema.UniqueConstraint` constraints independently
|
||||
using ``ALTER TABLE`` statements.
|
||||
:class:`~sqlalchemy.schema.UniqueConstraint` constraints independently using
|
||||
``ALTER TABLE`` statements.
|
||||
|
||||
The following rundowns are true for all constraints classes:
|
||||
|
||||
1. Make sure you import the relevent constrain class Migrate and not
|
||||
from SQLAlchemy, for example::
|
||||
#. Make sure you import the relevant constraint class from :mod:`migrate` and
|
||||
not from :mod:`sqlalchemy`, for example:
|
||||
|
||||
from migrate.changeset.constraint import ForeignKeyConstraint
|
||||
.. code-block:: python
|
||||
|
||||
from migrate.changeset.constraint import ForeignKeyConstraint
|
||||
|
||||
The classes in that module have the extra
|
||||
:meth:`~ConstraintChangeset.create` and
|
||||
:meth:`~ConstraintChangeset.drop` methods.
|
||||
:meth:`~ConstraintChangeset.create` and :meth:`~ConstraintChangeset.drop`
|
||||
methods.
|
||||
|
||||
2. You can also use Constraints as in SQLAlchemy. In this case passing table argument explicitly is required::
|
||||
#. You can also use constraints as in SQLAlchemy. In this case passing table
|
||||
argument explicitly is required:
|
||||
|
||||
cons = PrimaryKeyConstraint('id', 'num', table=self.table)
|
||||
.. code-block:: python
|
||||
|
||||
cons = PrimaryKeyConstraint('id', 'num', table=self.table)
|
||||
|
||||
# Create the constraint
|
||||
cons.create()
|
||||
@ -180,11 +195,16 @@ The following rundowns are true for all constraints classes:
|
||||
# Drop the constraint
|
||||
cons.drop()
|
||||
|
||||
You can also pass in :class:`~sqlalchemy.schema.Column` objects (and table argument can be left out)::
|
||||
You can also pass in :class:`~sqlalchemy.schema.Column` objects (and table
|
||||
argument can be left out):
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
cons = PrimaryKeyConstraint(col1, col2)
|
||||
|
||||
3. Some dialects support ``CASCADE`` option when dropping constraints::
|
||||
#. Some dialects support ``CASCADE`` option when dropping constraints:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
cons = PrimaryKeyConstraint(col1, col2)
|
||||
|
||||
@ -194,62 +214,69 @@ The following rundowns are true for all constraints classes:
|
||||
# Drop the constraint
|
||||
cons.drop(cascade=True)
|
||||
|
||||
|
||||
.. note::
|
||||
SQLAlchemy Migrate will try to guess the name of the
|
||||
constraints for databases, but if it's something other than
|
||||
the default, you'll need to give its name. Best practice is
|
||||
to always name your constraints. Note that Oracle requires
|
||||
that you state the name of the constraint to be created or dropped.
|
||||
SQLAlchemy Migrate will try to guess the name of the constraints for
|
||||
databases, but if it's something other than the default, you'll need to
|
||||
give its name. Best practice is to always name your constraints. Note that
|
||||
Oracle requires that you state the name of the constraint to be created or
|
||||
dropped.
|
||||
|
||||
|
||||
Examples
|
||||
---------
|
||||
|
||||
Primary key constraints::
|
||||
Primary key constraints:
|
||||
|
||||
from migrate.changeset.constraint import PrimaryKeyConstraint
|
||||
.. code-block:: python
|
||||
|
||||
cons = PrimaryKeyConstraint(col1, col2)
|
||||
from migrate.changeset.constraint import PrimaryKeyConstraint
|
||||
|
||||
# Create the constraint
|
||||
cons.create()
|
||||
cons = PrimaryKeyConstraint(col1, col2)
|
||||
|
||||
# Drop the constraint
|
||||
cons.drop()
|
||||
# Create the constraint
|
||||
cons.create()
|
||||
|
||||
Foreign key constraints::
|
||||
# Drop the constraint
|
||||
cons.drop()
|
||||
|
||||
from migrate.changeset.constraint import ForeignKeyConstraint
|
||||
Foreign key constraints:
|
||||
|
||||
cons = ForeignKeyConstraint([table.c.fkey], [othertable.c.id])
|
||||
.. code-block:: python
|
||||
|
||||
# Create the constraint
|
||||
cons.create()
|
||||
from migrate.changeset.constraint import ForeignKeyConstraint
|
||||
|
||||
cons = ForeignKeyConstraint([table.c.fkey], [othertable.c.id])
|
||||
|
||||
# Create the constraint
|
||||
cons.create()
|
||||
|
||||
# Drop the constraint
|
||||
cons.drop()
|
||||
|
||||
# Drop the constraint
|
||||
cons.drop()
|
||||
Check constraints:
|
||||
|
||||
Check constraints::
|
||||
.. code-block:: python
|
||||
|
||||
from migrate.changeset.constraint import CheckConstraint
|
||||
from migrate.changeset.constraint import CheckConstraint
|
||||
|
||||
cons = CheckConstraint('id > 3', columns=[table.c.id])
|
||||
|
||||
# Create the constraint
|
||||
cons.create()
|
||||
|
||||
cons = CheckConstraint('id > 3', columns=[table.c.id])
|
||||
# Drop the constraint
|
||||
cons.drop()
|
||||
|
||||
# Create the constraint
|
||||
cons.create()
|
||||
Unique constraints:
|
||||
|
||||
# Drop the constraint
|
||||
cons.drop()
|
||||
.. code-block:: python
|
||||
|
||||
Unique constraints::
|
||||
from migrate.changeset.constraint import UniqueConstraint
|
||||
|
||||
cons = UniqueConstraint('id', 'age', table=self.table)
|
||||
|
||||
from migrate.changeset.constraint import UniqueConstraint
|
||||
# Create the constraint
|
||||
cons.create()
|
||||
|
||||
cons = UniqueConstraint('id', 'age', table=self.table)
|
||||
|
||||
# Create the constraint
|
||||
cons.create()
|
||||
|
||||
# Drop the constraint
|
||||
cons.drop()
|
||||
# Drop the constraint
|
||||
cons.drop()
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user