API Documentation

Database Manager

class DatabaseManager(database, table_name=None, directory='migrations')

A DatabaseManager is a class responsible for managing and running all migrations against a specific database with a set of migration files.

Parameters:
  • database – Connection string, dict, or peewee.Database instance to use.
  • table_name – Table name to hold migrations (default migration_history).
  • directory – Directory to store migrations (default migrations).
create(modelstr)

Create a new migration file for an existing model. Model could actually also be a module, in which case all Peewee models are extracted from the model and created.

Parameters:modelstr – Python class, module, or string pointing to a class or module.
Returns:True if migration file was created, otherwise False.
Type:bool
db_migrations

List all the migrations applied to the database.

Returns:List of migration names.
Return type:tuple
delete(migration)

Delete the migration from filesystem and database. As if it never happened.

Parameters:migration – Name of migration to find (not including extension).
Returns:True if delete was successful, otherwise False.
Return type:bool
diff

List all the migrations that have not been applied to the database.

Returns:List of migration names.
Return type:tuple
downgrade(target=None, fake=False)

Run all the migrations (down to target if specified). If no target, run one downgrade.

Parameters:
  • target – Migration target to limit downgrades.
  • fake – Should the migration actually run?.
Returns:

True if downgrade was successful, otherwise False.
Return type:

bool
find_migration(value)

Try to find a migration by name or start of name.

Raises:ValueError if no matching migration is found.
Returns:Name of matching migration.
Return type:str
get_filename(migration)

Return the full path and filename for the given migration.

Parameters:migration – Name of migration to find (not including extension).
Returns:Path and filename to migration.
Return type:str
get_ident()

Return a unique identifier for a revision. This defaults to the current next incremental identifier. Override this method to change functionality. Make sure the IDs will be sortable (like timestamps or incremental numbers).

Returns:Name of new migration.
Return type:str
info()

Show the current database. Don’t include any sensitive information like passwords.

Returns:String representation.
Return type:str
load_database(database)

Load the given database, whatever it might be.

A connection string: sqlite:///database.sqlite

A dictionary: {'engine': 'SqliteDatabase', 'name': 'database.sqlite'}

A peewee.Database instance: peewee.SqliteDatabase('database.sqlite')

Parameters:database – Connection string, dict, or peewee.Database instance to use.
Raises:peewee.DatabaseError if database connection cannot be established.
Returns:Database connection.
Return type:peewee.Database instance.
migration_files

List all the migrations sitting on the filesystem.

Returns:List of migration names.
Return type:tuple
next_migration(name)

Get the name of the next migration that should be created.

Parameters:name – Name to use for migration (not including identifier).
Returns:Name of new migration.
Return type:str
open_migration(migration, mode='r')

Open a migration file with the given mode and return it.

Parameters:
  • migration – Name of migration to find (not including extension).
  • mode – Mode to pass to open(). Most likely ‘r’ or ‘w’.
Raises:

IOError if the file cannot be opened.
Returns:

File instance.
Return type:

io.FileIO
revision(name=None)

Create a single blank migration file with given name or default of ‘auto migration’.

Parameters:name – Name of migration to create (default auto migration).
Returns:True if migration file was created, otherwise False.
Type:bool
run_migration(migration, direction='upgrade', fake=False)

Run a single migration. Does not check to see if migration has already been applied.

Parameters:migration – Migration to run.
Param:Direction to run (either ‘upgrade’ or ‘downgrade’) (default upgrade).
Returns:True if migration was run successfully, otherwise False.
Type:bool
status()

Show all the migrations and a status for each.

Returns:True if listing was successful, otherwise None.
Return type:bool
upgrade(target=None, fake=False)

Run all the migrations (up to target if specified). If no target, run all upgrades.

Parameters:
  • target – Migration target to limit upgrades.
  • fake – Should the migration actually run?.
Returns:

True if upgrade was successful, otherwise False.
Return type:

bool
write_migration(migration, name, upgrade='pass', downgrade='pass')

Open a migration file and write the given attributes to it.

Parameters:migration – Name of migration to find (not including extension).
Name:Name to write in file header.
Upgrade:Text for upgrade operations.
Downgrade:Text for downgrade operations.
Raises:IOError if the file cannot be opened.
Returns:None.
class MigrationHistory(*args, **kwargs)

Base model to manage migration history in a database. You can use this manually to query the database if you want, but normally it’s handled by the DatabaseManager class.

DoesNotExist

alias of MigrationHistoryDoesNotExist

date_applied = <DateTimeField: MigrationHistory.date_applied>
id = <AutoField: MigrationHistory.id>
name = <CharField: MigrationHistory.name>

Migrator

class Migrator(database)

A migrator is a class that runs migrations for a specific upgrade or downgrade operation.

An instance of this class is automatically created and passed as the only argument to upgrade(migrator) and downgrade(migrator) methods in migration files.

Parameters:database – Connection string, dict, or peewee.Database instance to use.
add_column(table, name, coltype, **kwargs)

Add the given column to the given table.

Parameters:
  • table – Table name to add column to.
  • name – Name of the column field to add.
  • coltype – Column type (from FIELD_TO_PEEWEE).
  • kwargs – Arguments for the given column type.
Returns:

None
add_index(table, columns, unique=False)

Add an index to a table based on columns.

Parameters:
  • table – Table name.
  • columns – Columns (list or tuple).
  • unique – True or False whether index should be unique (default False).
Returns:

None
add_not_null(table, column)

Add a NOT NULL constraint to a column.

Parameters:
  • table – Table name.
  • column – Column name.
Returns:

None
create_table(**kwds)

Context manager to create the given table. Yield a TableCreator instance on which you can perform operations and add columns.

Parameters:
  • name – Name of table to created
  • safe – If True, will be created with “IF NOT EXISTS” (default False).
Returns:

generator
Return type:

TableCreator
drop_column(table, name, cascade=True)

Drop the column from the given table.

Parameters:
  • table – Table name to drop column from.
  • name – Name of the column field to drop.
  • cascade – If True, drop will be cascaded.
Returns:

None
drop_index(table, index_name)

Remove an index from a table.

Parameters:
  • table – Table name.
  • index_name – Index name.
Returns:

None
drop_not_null(table, column)

Remove a NOT NULL constraint to a column.

Parameters:
  • table – Table name.
  • column – Column name.
Returns:

None
drop_table(name, safe=False, cascade=False)

Drop the given table.

Parameters:
  • name – Table name to drop.
  • safe – If True, exception will be raised if table does not exist.
  • cascade – If True, drop will be cascaded.
Returns:

None
execute_sql(sql, params=None)

Run the given sql and return a cursor.

Parameters:
  • sql – SQL string.
  • params – Parameters for the given SQL (default None).
Returns:

SQL cursor
Return type:

cursor
rename_column(table, old_name, new_name)

Rename a column leaving everything else in tact.

Parameters:
  • table – Table name to rename column from.
  • old_name – Old column name.
  • new_name – New column name.
Returns:

None
rename_table(old_name, new_name)

Rename a table leaving everything else in tact.

Parameters:
  • old_name – Old table name.
  • new_name – New table name.
Returns:

None
class TableCreator(name)

A class used for creating a table in a migration file.

Parameters:name – Name of database table.
add_constraint(value)

Add a constraint to the model.

Parameters:name – String value of constraint.
Returns:None
add_index(columns, unique=False)

Add an index to the model.

Parameters:
  • columns – Columns (list or tuple).
  • unique – True or False whether index should be unique (default False).
bare(name, **kwargs)

Create a bare column. Alias for table.column('bare')

biginteger(name, **kwargs)

Create a biginteger column. Alias for table.column('biginteger')

bin_uuid(name, **kwargs)

Create a binary uuid column. Alias for table.column('bin_uuid')

binary(name, **kwargs)

Create a binary column. Alias for table.column('binary')

blob(name, **kwargs)

Create a blob column. Alias for table.column('blob')

bool(name, **kwargs)

Create a bool column. Alias for table.column('bool')

build_fake_model(name)

Build a fake model with some defaults and the given table name. We need this so we can perform operations that actually require a model class.

Parameters:name – Name of database table.
Returns:A new model class.
Return type:peewee.Model
char(name, **kwargs)

Create a char column. Alias for table.column('char')

column(coltype, name, **kwargs)

Generic method to add a column of any type.

Parameters:
  • coltype – Column type (from FIELD_TO_PEEWEE).
  • name – Name of column.
  • kwargs – Arguments for the given column type.
date(name, **kwargs)

Create a date column. Alias for table.column('date')

datetime(name, **kwargs)

Create a datetime column. Alias for table.column('datetime')

decimal(name, **kwargs)

Create a decimal column. Alias for table.column('decimal')

double(name, **kwargs)

Create a double column. Alias for table.column('double')

fixed(name, **kwargs)

Create a fixed column. Alias for table.column('fixed')

float(name, **kwargs)

Create a float column. Alias for table.column('float')

foreign_key(coltype, name, references, **kwargs)

Add a foreign key to the model. This has some special cases, which is why it’s not handled like all the other column types.

Parameters:
  • name – Name of the foreign key.
  • references – Table name in the format of “table.column” or just “table” (and id will be default column).
  • kwargs – Additional kwargs to pass to the column instance. You can also provide “on_delete” and “on_update” to add constraints.
Returns:

None
int(name, **kwargs)

Create a int column. Alias for table.column('int')

integer(name, **kwargs)

Create a integer column. Alias for table.column('integer')

primary_key(name)

Add a primary key to the model. This has some special cases, which is why it’s not handled like all the other column types.

Parameters:name – Name of column.
Returns:None
smallint(name, **kwargs)

Create a smallint column. Alias for table.column('smallint')

smallinteger(name, **kwargs)

Create a smallinteger column. Alias for table.column('smallinteger')

text(name, **kwargs)

Create a text column. Alias for table.column('text')

time(name, **kwargs)

Create a time column. Alias for table.column('time')

uuid(name, **kwargs)

Create a uuid column. Alias for table.column('uuid')

CLI Functions

cli_command(*args, **kwargs)

Run database migration commands.

cli_info(*args, **kwargs)

Show information about the current database.

cli_status(*args, **kwargs)

Show information about migration status.

cli_create(*args, **kwargs)

Create a migration based on an existing model.

cli_revision(*args, **kwargs)

Create a blank migration file.

cli_upgrade(*args, **kwargs)

Run database upgrades.

cli_downgrade(*args, **kwargs)

Run database downgrades.

cli_delete(*args, **kwargs)

Delete the target migration from the filesystem and database.