/usr/share/doc/python-migrate/html/_sources/changeset.txt is in python-migrate 0.9.1-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 | .. _changeset-system:
.. highlight:: python
**************************
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).
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`.
.. _summary-changeset-api:
Here are some direct links to the relevent sections of the API documentations:
* :meth:`Create a column <ChangesetColumn.create>`
* :meth:`Drop a column <ChangesetColumn.drop>`
* :meth:`Alter a column <ChangesetColumn.alter>` (follow a link for list of supported changes)
* :meth:`Rename a table <ChangesetTable.rename>`
* :meth:`Rename an index <ChangesetIndex.rename>`
* :meth:`Create primary key constraint <migrate.changeset.constraint.PrimaryKeyConstraint>`
* :meth:`Drop primary key constraint <migrate.changeset.constraint.PrimaryKeyConstraint.drop>`
* :meth:`Create foreign key contraint <migrate.changeset.constraint.ForeignKeyConstraint.create>`
* :meth:`Drop foreign key constraint <migrate.changeset.constraint.ForeignKeyConstraint.drop>`
* :meth:`Create unique key contraint <migrate.changeset.constraint.UniqueConstraint.create>`
* :meth:`Drop unique key constraint <migrate.changeset.constraint.UniqueConstraint.drop>`
* :meth:`Create check key contraint <migrate.changeset.constraint.CheckConstraint.create>`
* :meth:`Drop check key constraint <migrate.changeset.constraint.CheckConstraint.drop>`
.. note::
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.
Column
======
Given a standard SQLAlchemy table:
.. 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`:
.. code-block:: python
col = Column('col1', String, default='foobar')
col.create(table, populate_default=True)
# 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
CONSTRAINT`` after changing the column.
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`:
.. code-block:: python
col.drop()
.. _column-alter:
You can alter a column with :meth:`~ChangesetColumn.alter`:
.. code-block:: python
col.alter(name='col2')
# Renaming a column affects how it's accessed by the table object
assert col is table.c.col2
# 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
:meth:`ChangesetColumn.alter` is deprecated. Pass in explicit
parameters, such as `name` for a new column name and `type` for a
new column type, instead. Do **not** include any parameters that
are not changed.
.. _table-rename:
Table
=====
SQLAlchemy includes support for `creating and dropping`__ tables..
Tables can be renamed with :meth:`~ChangesetTable.rename`:
.. code-block:: python
table.rename('newtablename')
.. __: http://www.sqlalchemy.org/docs/core/schema.html#creating-and-dropping-database-tables
.. currentmodule:: migrate.changeset.constraint
.. _index-rename:
Index
=====
SQLAlchemy supports `creating and dropping`__ indexes.
Indexes can be renamed using
:meth:`~migrate.changeset.schema.ChangesetIndex.rename`:
.. code-block:: python
index.rename('newindexname')
.. __: http://www.sqlalchemy.org/docs/core/schema.html#indexes
.. _constraint-tutorial:
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`,
:class:`~sqlalchemy.schema.ForeignKeyConstraint`,
:class:`~sqlalchemy.schema.CheckConstraint` and
:class:`~sqlalchemy.schema.UniqueConstraint` constraints independently using
``ALTER TABLE`` statements.
The following rundowns are true for all constraints classes:
#. Make sure you import the relevant constraint class from :mod:`migrate` and
not from :mod:`sqlalchemy`, for example:
.. 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.
#. You can also use constraints as in SQLAlchemy. In this case passing table
argument explicitly is required:
.. code-block:: python
cons = PrimaryKeyConstraint('id', 'num', table=self.table)
# Create the constraint
cons.create()
# Drop the constraint
cons.drop()
You can also pass in :class:`~sqlalchemy.schema.Column` objects (and table
argument can be left out):
.. code-block:: python
cons = PrimaryKeyConstraint(col1, col2)
#. Some dialects support ``CASCADE`` option when dropping constraints:
.. code-block:: python
cons = PrimaryKeyConstraint(col1, col2)
# Create the constraint
cons.create()
# 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.
Examples
---------
Primary key constraints:
.. code-block:: python
from migrate.changeset.constraint import PrimaryKeyConstraint
cons = PrimaryKeyConstraint(col1, col2)
# Create the constraint
cons.create()
# Drop the constraint
cons.drop()
Foreign key constraints:
.. code-block:: python
from migrate.changeset.constraint import ForeignKeyConstraint
cons = ForeignKeyConstraint([table.c.fkey], [othertable.c.id])
# Create the constraint
cons.create()
# Drop the constraint
cons.drop()
Check constraints:
.. code-block:: python
from migrate.changeset.constraint import CheckConstraint
cons = CheckConstraint('id > 3', columns=[table.c.id])
# Create the constraint
cons.create()
# Drop the constraint
cons.drop()
Unique constraints:
.. code-block:: python
from migrate.changeset.constraint import UniqueConstraint
cons = UniqueConstraint('id', 'age', table=self.table)
# Create the constraint
cons.create()
# Drop the constraint
cons.drop()
|