sqlalchemy-migrate/doc/source/changeset.rst

Database schema migrations

migrate.changeset.schema

Importing 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 versioning <versioning-system>.

For more information, see the API documentation for migrate.changeset.

Here are some direct links to the relevent sections of the API documentations:

• Create a column <ChangesetColumn.create>
• Drop a column <ChangesetColumn.drop>
• Alter a column <ChangesetColumn.alter> (follow a link for list of supported changes)
• Rename a table <ChangesetTable.rename>
• Rename an index <ChangesetIndex.rename>
• Create primary key constraint <migrate.changeset.constraint.PrimaryKeyConstraint>
• Drop primary key constraint <migrate.changeset.constraint.PrimaryKeyConstraint.drop>
• Create foreign key contraint <migrate.changeset.constraint.ForeignKeyConstraint.create>
• Drop foreign key constraint <migrate.changeset.constraint.ForeignKeyConstraint.drop>
• Create unique key contraint <migrate.changeset.constraint.UniqueConstraint.create>
• Drop unique key constraint <migrate.changeset.constraint.UniqueConstraint.drop>
• Create check key contraint <migrate.changeset.constraint.CheckConstraint.create>
• 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:

table = Table('mytable', meta,
    Column('id', Integer, primary_key=True),
)
table.create()

You can create a column with ~ChangesetColumn.create:

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`

Note

You can pass primary_key_name, index_name and unique_name to the ~ChangesetColumn.create method to issue ALTER TABLE ADD CONSTRAINT after changing the column.

For multi columns constraints and other advanced configuration, check the constraint tutorial <constraint-tutorial>.

0.6.0

You can drop a column with ~ChangesetColumn.drop:

col.drop()

You can alter a column with ~ChangesetColumn.alter:

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

0.6.0 Passing a ~sqlalchemy.schema.Column to 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

SQLAlchemy includes support for creating and dropping tables..

Tables can be renamed with ~ChangesetTable.rename:

table.rename('newtablename')

migrate.changeset.constraint

Index

SQLAlchemy supports creating and dropping indexes.

Indexes can be renamed using ~migrate.changeset.schema.ChangesetIndex.rename:

index.rename('newindexname')

Constraint

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 ~sqlalchemy.schema.PrimaryKeyConstraint, ~sqlalchemy.schema.ForeignKeyConstraint, ~sqlalchemy.schema.CheckConstraint and ~sqlalchemy.schema.UniqueConstraint constraints independently using ALTER TABLE statements.

The following rundowns are true for all constraints classes:

1. Make sure you import the relevant constraint class from migrate and not from sqlalchemy, for example:

   from migrate.changeset.constraint import ForeignKeyConstraint

   The classes in that module have the extra ~ConstraintChangeset.create and ~ConstraintChangeset.drop methods.

2. You can also use constraints as in SQLAlchemy. In this case passing table argument explicitly is required:

   cons = PrimaryKeyConstraint('id', 'num', table=self.table)
   
   # Create the constraint
   cons.create()
   
   # Drop the constraint
   cons.drop()

   You can also pass in ~sqlalchemy.schema.Column objects (and table argument can be left out):

   cons = PrimaryKeyConstraint(col1, col2)

3. Some dialects support CASCADE option when dropping constraints:

   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:

from migrate.changeset.constraint import PrimaryKeyConstraint

cons = PrimaryKeyConstraint(col1, col2)

# Create the constraint
cons.create()

# Drop the constraint
cons.drop()

Foreign key constraints:

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:

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:

from migrate.changeset.constraint import UniqueConstraint

cons = UniqueConstraint('id', 'age', table=self.table)

# Create the constraint
cons.create()

# Drop the constraint
cons.drop()