experimentum.Storage.Migrations package¶

Submodules¶

experimentum.Storage.Migrations.Blueprint module¶

The Blueprint class lets you create, delete, or alter columns of a table.

Columns¶

Adding Columns¶

To update an existing table, you can use the Schema.table() method. The method accepts a table name as its argument and returns a Blueprint instance that can be used to add columns to the table:

with self.schema.table('users') as table:
    table.string('email')
    table.string('address').nullable()
    table.integer('age').nullable().unsigned()

The table builder contains a plethora of column types that you can use when building your tables:

Command	Description
`table.array('ratings', 'integer', 2)`	ARRAY column type. Only supported in postgresql!
`table.big_increments('id')`	Auto-incrementing ID using a “big integer” (primary key) equivalent column.
`table.big_integer('votes)`	BIGINT equivalent column.
`table.binary('data')`	BLOB equivalent column.
`table.boolean('confirmed')`	BOOLEAN equivalent column.
`table.char('name', 4)`	CHAR equivalent column with a length.
`table.date('created_on')`	DATE equivalent column.
`table.datetime('created_at')`	DATETIME equivalent column.
`table.decimal('amount', 5, 2)`	DECIMAL equivalent column with a precision (total digits) and a scale (decimal digits).
`table.double('column', 15, 8)`	DOUBLE equivalent column with a precision (total digits) and a scale (decimal digits).
`table.enum('choices', ['foo', 'bar'])`	ENUM equivalent column.
`table.float('amount')`	FLOAT equivalent column.
`table.increments('id')`	Auto-incrementing ID using a “integer” (primary key) equivalent column.
`table.integer('votes')`	INTEGER equivalent column.
`table.json('options')`	JSON equivalent column.
`table.long_text('description')`	LONGTEXT equivalent column.
`table.medium_integer('votes')`	MEDIUMINT equivalent column.
`table.medium_text('description')`	MEDIUMTEXT equivalent column.
`table.small_integer('votes')`	SMALLINT equivalent column.
`table.string('email')`	VARCHAR equivalent column.
`table.string('votes', 100)`	VARCHAR equivalent column with a length.
`table.text('description')`	TEXT equivalent column.
`table.time('sunrise')`	TIME equivalent column.
`table.timestamp('added_at')`	TIMESTAMP equivalent column.

Column Modifiers¶

Each of the column methods above returns a Column instance, which lets you add several column “modifier” while adding a column to a table. For example, to make a column “nullable” you can use the nullable() method:

with self.schema.table('users') as table:
    table.string('email').nullable()

The column modifiers are the following (does not include index modifiers):

Modifier	Description
`.default('default_value')`	Specify a default value for the column.
`.nullable()`	Designate that the column allows NULL values.
`.unsigned()`	Set INTEGER column as UNSINGED (MySQL).

Dropping Columns¶

To drop a column from a table, you can use the drop_column() method.

Dropping a column from a database table:

with self.schema.table('users') as table:
    table.drop_column('votes')

Dropping multiple columns from a database table:

with self.schema.table('users') as table:
    table.drop_column('votes', 'avatar', 'location')

Indexes¶

The schema builder supports several types of indexes which you can add to and/or drop from columns. You can create the index after defining the column. For example:

table.string('email')
table.unique('email')

Available Index Types¶

Each index method accepts an optional second argument to specify the name of the index. If omitted, the name will be derived from the names of the table and column(s). Below is a list of all available index types:

Command	Description
`table.primary('id')`	Addys a primary key.
`table.primary(['id', 'parent_id'])`	Adds composite keys.
`table.unique('email)`	Adds a unique index.
`table.index('state')`	Adds a basic index.

Note

In MySQL/MariaDB and PostgreSQL the length of indexes are limited. experimentum generates index names based on table and column names, therefore if your column names are too long you can pass the name keyword argument to specify your own index name:

table.index(
    ['some_field_with_a_really_long_name', 'another_really_long_field'],
    name='my_idx_name'
)

Dropping Indexes¶

To drop an index you must specify the index’s columns. experimentum assigns a reasonable name to the indexes by default. If you have specified a custom index name, you have to add it as the optional second argument.

Command	Description
`table.drop_primary('id')`	Drop a primary key from the “id” column.
`table.drop_unique('email)`	Drop a unique index from the “email” column.
`table.drop_index('state')`	Drop a basic index from the “state” column.
`table.drop_foreign('user_id')`	Drop a foreign key from the “user_id” column.

Foreign Key Contraints¶

experimentum also provides support for adding foreign key constraints to your tables:

with self.schema.table('posts') as table:
    table.increments('user_id')
    table.foreign('user_id')\
        .references('id').on('users')\
        .on_delete('cascade')\
        .on_update('cascade')

In this example, we are stating that the user_id column references the id column on the users table and set the “on update” and “on delete” actions to cascade. Make sure to create the foreign key column first!

To drop a foreign key, you can use the drop_foreign() method. It works just like dropping an index.

class experimentum.Storage.Migrations.Blueprint.Blueprint(table)¶

Bases: object

Lets you create, delete, or alter columns of a table.

Inspired by the Lavavel Schema Blueprint (https://laravel.com/docs/5.6/migrations#columns).

table¶

Name of the table.

Type:	str

columns¶

Defaults to []. List of columns for the table.

Type:	list

dropped¶

Defaults to {‘columns’: [], ‘indexes’: []}. Object with list of dropped columns and indexes of the table.

Type:	object

indexes¶

Defaults to []. List of indices for the table.

Type:	list

fkeys¶

Defaults to []. List of foreign keys for the table.

Type:	list

action¶

Defaults to ‘alter’. Action (i.e. create or alter).

Type:	str

add_column(col_type, name, **kwargs)¶

Add a new column to the blueprint.

Parameters:	col_type (str) – Column Type name (str) – Name of the Column.
Returns:	Column data structure to add column modifiers.
Return type:	Column

array(column, arr_type, dimensions=None)¶

ARRAY column type.

Only supported in postgresql, for other systems it defaults back to arr_type!

Parameters:	column (str) – Name of the column. arr_type (str) – Type of array dimensions (int, optional) – Defaults to None. Array Dimension.
Returns:	Column data structure to add column modifiers.
Return type:	Column

big_increments(column)¶

Auto-incrementing ID using a “big integer” (primary key) equivalent column.

Parameters:	column (str) – Name of the column.
Returns:	Column data structure to add column modifiers.
Return type:	Column

big_integer(column)¶

BIGINT equivalent column.

Parameters:	column (str) – Name of the column.
Returns:	Column data structure to add column modifiers.
Return type:	Column

binary(column)¶

BLOB equivalent column.

Parameters:	column (str) – Name of the column.
Returns:	Column data structure to add column modifiers.
Return type:	Column

boolean(column)¶

BOOLEAN equivalent column.

Parameters:	column (str) – Name of the column.
Returns:	Column data structure to add column modifiers.
Return type:	Column

char(column, length)¶

CHAR equivalent column with a length.

Parameters:	column (str) – Name of the column. length (int) – Length of the column
Returns:	Column data structure to add column modifiers.
Return type:	Column

create()¶: Set the create action.

date(column)¶

DATE equivalent column.

Parameters:	column (str) – Name of the column.
Returns:	Column data structure to add column modifiers.
Return type:	Column

datetime(column)¶

DATETIME equivalent column.

Parameters:	column (str) – Name of the column.
Returns:	Column data structure to add column modifiers.
Return type:	Column

decimal(column, precision, scale=2)¶

DECIMAL equivalent column with a precision (total digits) and a scale (decimal digits).

Parameters:	column (str) – Name of the column. precision (int) – Total Digits scale (int, optional) – Defaults to 2. Number of decimal gigits
Returns:	Column data structure to add column modifiers.
Return type:	Column

double(column, precision, scale=2)¶

DOUBLE equivalent column with a precision (total digits) and a scale (decimal digits).

Parameters:	column (str) – Name of the column. precision (int) – Total Digits scale (int) – Default to 2. Number of decimal digits.
Returns:	Column data structure to add column modifiers.
Return type:	Column

drop_column(*args)¶

Drop one or multiple columns.

Parameters:	args (str*) – Column names

drop_foreign(column, name=None)¶

Drop a foreign key from the column.

Parameters:	column (str) – foreign Key column name (str, optional) – Default to None. Name of the foreign key.

drop_index(column, name=None)¶

Drop a index key from the column.

Parameters:	column (str) – index Key column name (str, optional) – Default to None. Name of the index key.

drop_primary(column, name=None)¶

Drop a primary key from the column.

Parameters:	column (str) – Primary Key column name (str, optional) – Default to None. Name of the primary key.

drop_unique(column, name=None)¶

Drop a unique key from the column.

Parameters:	column (str) – unique Key column name (str, optional) – Default to None. Name of the unique key.

enum(column, fields)¶

ENUM equivalent column.

Parameters:	column (str) – Name of the column. fields (list) – Field Names for the enum
Returns:	Column data structure to add column modifiers.
Return type:	Column

float(column)¶

FLOAT equivalent column.

Parameters:	column (str) – Name of the column.
Returns:	Column data structure to add column modifiers.
Return type:	Column

foreign(column, name=None)¶

Add a foreign key to the column.

Parameters:	column (str) – Foreign Key column name (str, optional) – Default to None. Name of the foreign key.
Returns:	ForeignKey data structure to configure foreign key.
Return type:	ForeignKey

increments(column)¶

Auto-incrementing ID using a “integer” (primary key) equivalent column.

Parameters:	column (str) – Name of the column.
Returns:	Column data structure to add column modifiers.
Return type:	Column

index(column, name=None)¶

Add a basic index to the column.

Parameters:	column (str) – Indexed column name (str, optional) – Default to None. Name of the unique key.
Returns:	self instance for method chaining.
Return type:	Blueprint

integer(column)¶

INTEGER equivalent column.

Parameters:	column (str) – Name of the column.
Returns:	Column data structure to add column modifiers.
Return type:	Column

json(column)¶

JSON equivalent column.

Parameters:	column (str) – Name of the column.
Returns:	Column data structure to add column modifiers.
Return type:	Column

long_text(column)¶

LONGTEXT equivalent column.

Parameters:	column (str) – Name of the column.
Returns:	Column data structure to add column modifiers.
Return type:	Column

medium_integer(column)¶

MEDIUMINT equivalent column.

Parameters:	column (str) – Name of the column.
Returns:	Column data structure to add column modifiers.
Return type:	Column

medium_text(column)¶

MEDIUMTEXT equivalent column.

Parameters:	column (str) – Name of the column.
Returns:	Column data structure to add column modifiers.
Return type:	Column

primary(column, name=None)¶

Add a primary key to the column.

Parameters:	column (str) – Primary Key column name (str, optional) – Default to None. Name of the primary key.
Returns:	self instance for method chaining.
Return type:	Blueprint

small_integer(column)¶

SMALLINT equivalent column.

Parameters:	column (str) – Name of the column.
Returns:	Column data structure to add column modifiers.
Return type:	Column

string(column, length=None)¶

VARCHAR equivalent column with an optional length.

Parameters:	column (str) – Name of the column. length (int, optional) – Defaults to None. Length of the string.
Returns:	Column data structure to add column modifiers.
Return type:	Column

text(column)¶

TEXT equivalent column.

Parameters:	column (str) – Name of the column.
Returns:	Column data structure to add column modifiers.
Return type:	Column

time(column)¶

TIME equivalent column.

Parameters:	column (str) – Name of the column.
Returns:	Column data structure to add column modifiers.
Return type:	Column

timestamp(column)¶

TIMESTAMP equivalent column.

Parameters:	column (str) – Name of the column.
Returns:	Column data structure to add column modifiers.
Return type:	Column

unique(column, name=None)¶

Add a unique key to the column.

Parameters:	column (str) – Unique Key column name (str, optional) – Default to None. Name of the unique key.
Returns:	self instance for method chaining.
Return type:	Blueprint

experimentum.Storage.Migrations.Column module¶

Column Data Structure to add column modifiers.

Add column modifiers like nullable, default, unsigned to a column. They support method chaining, so the following is possible:

table.integer('foo').unsigned().nullable()

class experimentum.Storage.Migrations.Column.Column(col_typ, name, parameters)¶

Bases: object

Stores attributes the the column.

default(value)¶

Specify a default value for the column.

Parameters:	value (object) – The default value
Returns:	self instance for method chaining.
Return type:	Column

get(attribute, default=None)¶

Get the value of an attribute, with a default if it does not exist.

Parameters:	attribute (str) – Attribute you want to get. default (object, optional) – Defaults to None. Default value if attribute is not found.
Returns:	object

nullable()¶

Designate that the column allows NULL values.

Returns:	self instance for method chaining.
Return type:	Column

unsigned()¶

Set INTEGER column as UNSINGED (MySQL).

Returns:	self instance for method chaining.
Return type:	Column

experimentum.Storage.Migrations.ForeignKey module¶

ForeignKey data structure to configure foreign key attributes.

Supports method chaining to easily configure foreign keys, like:

table.foreign('user_id').references('id').on('users')\
    .on_delete('cascade')\
    .on_update('cascade')

class experimentum.Storage.Migrations.ForeignKey.ForeignKey(column, name=None)¶

Bases: object

Stores attributes for a Foreign Key.

get(attribute, default=None)¶

Get the value of an attribute, with a default if it does not exist.

Parameters:	attribute (str) – Attribute you want to get default (object, optional) – Defaults to None. Default value.
Returns:	object

on(ref_table)¶

Set the table the foreign key references.

Parameters:	ref_table (str) – Name of the referenced table
Returns:	self instance for method chaining.
Return type:	ForeignKey

on_delete(action)¶

Set the action which will be executed on delete.

Parameters:	action (str) – Action to execute
Returns:	self instance for method chaining.
Return type:	ForeignKey

on_update(action)¶

Set the action which will be executed on update.

Parameters:	action (str) – Action to execute
Returns:	self instance for method chaining.
Return type:	ForeignKey

references(ref_column)¶

Set the column the foreign key references.

Parameters:	ref_column (str) – Name of referenced column
Returns:	self instance for method chaining.
Return type:	ForeignKey

experimentum.Storage.Migrations.Migration module¶

Handles database migrations.

class experimentum.Storage.Migrations.Migration.Migration(app)¶

Bases: object

Base Migration Class.

down()¶: Revert the migrations.

revision = None¶

up()¶: Revert the migrations.

experimentum.Storage.Migrations.Migrator module¶

Management of all migrations.

Handles actions like upgrade, downgrading, keeping track of which migrations did run and which not. Used by MigrationCommand.

class experimentum.Storage.Migrations.Migrator.Migrator(path, app)¶

Bases: object

Management of all migrations.

path¶

Path to the migrations folder.

Type:	str

down(migration=None)¶

Downgrade to an old migration revision.

Parameters:	migration (Migration, optional) – Defaults to None. The Migration Class to upgrade to.
Raises:	TypeError – if migration is not a valid migration

static get_migration_files(path)¶

Get all of the migration files in a given path.

Parameters:	path (str) – Path to migrations folder
Returns:	list of migration files
Return type:	list

make(name)¶

Make a new migration file.

Parameters:	name (str) – Name for the migration.

refresh()¶: Rerun all migrations.

status(printing=True)¶

Print the current status of which migrations did run and which not.

Parameters:	printing (bool, optional) – Defaults to True. Whether or not the status table is printed.
Returns:	migration status list
Return type:	list

up(migration=None)¶

Upgrade to a new migration revision.

Parameters:	migration (Migration, optional) – Defaults to None. The Migration Class to upgrade to.
Raises:	TypeError – if migration is not a valid migration

experimentum.Storage.Migrations.Schema module¶

The Schema class provides a database agnostic way of manipulating tables.

Tables¶

Creating Tables¶

To create a new database table, the create() method is used. The create() method accepts a table name as its argument and returns a Blueprint instance that can be used to define the new table. When creating the table, you may use any of the Blueprint column methods to define the table’s columns:

with self.schema.create('users') as table:
    table.increments('id')

Checking Existence¶

To check if a table or column exist you can use the has_table() or has_column() methods respectively:

if self.schema.has_table('users'):
    # ...

if self.schema.has_column('users', 'email'):
    # ...

Renaming / Dropping Tables¶

To rename an existing database table, use the rename() method:

self.schema.rename('from', 'to')

To drop a table, you can use the drop() or drop_if_exists() methods:

self.schema.drop('users')
self.schema.drop_if_exists('users')

class experimentum.Storage.Migrations.Schema.Schema(app)¶

Bases: object

Database agnostic way of manipulating tables.

The Schema class was inspired by the Laravel Schema Builder (https://laravel.com/docs/5.6/migrations#tables).

app¶

Main App Class.

Type:	App

store¶

Data Store.

Type:	AbstractStore

create(**kwds)¶

Create a new table blueprint.

Parameters:	name (str) – Name of the table.
Yields:	Blueprint – New Instance of a table blueprint

drop(name)¶

Drop a table.

Parameters:	name (str) – Name of the table

drop_if_exists(name)¶

Drop a table if it exists.

Parameters:	name (str) – Name of the table

has_column(table, column)¶

Check if table has a specific column.

Parameters:	table (str) – Table to check column (str) – Column to check

has_table(table)¶

Check if database has a specific table.

Parameters:	table (str) – Table to check existance of

rename(old, new)¶

Rename a table.

Parameters:	old (str) – Old table name new (str) – New table name

table(**kwds)¶

Create a blueprint for an existing table.

Parameters:	name (str) – Name of the table
Yields:	Blueprint – New Instance of a table blueprint

Module contents¶

Handle all migration related stuff, and provides the following classes/modules.

Schema: The Schema Builder lets you create, delete, or alter tables.
Blueprint Module: The Blueprint class lets you create, delete, or alter columns of a table.
Migration Module: The Migration class handles database migrations.
Migrator Module: The Migrator class handles the management of all migrations.
Column Module: Datastructure for columns.
ForeignKey Module: Datastructure for foreign keys.