Database API

South comes with a simplistic database abstraction layer that sits above ​DBAPI, which provides a common connection cursor and sql-slinging interface, and below ​Django's database API, which deals with high-level data.

south.db (as this layer is known) allows you to create, modify and delete tables, columns and other database items (like indexes) in a database-agnostic way, so you can just reuse your migrations if you switch database rather than having to rewrite all the SQL.

All operations are methods on the south.db.db object; the usual import to have is

from south.db import db

This line will have automatically been added to your migrations if you created them using startmigration.

Methods

Please note that we're still adding new methods to the database API. If one you want is still missing and does not have a ticket, please add one.

add_column(table_name, name, field, keep_default=True)

Adds the column with name 'name' to the table 'table_name'. Uses the 'field' instance to determine the type and other options for the column.

If keep_default is True, then the field's default value will be applied to the database using SET DEFAULT. If it's False, then the default will only be used to populate existing rows, and will not be stored on the column for future INSERTs.

(keep_default is new in 0.4)

rename_column(table_name, old, new)

Renames column 'old' on 'table_name' to the name 'new'.

alter_column(table_name, name, field, explicit_name=True)

Alters the given column name so it will match the given field. Note that conversion between the two by the database must be possible. (Will not automatically add _id by default if the field is a ForeignKey?; to have this behavour, pass explicit_name=False).

(alter_column is new in 0.4)

delete_column(table_name, name)

Deletes the column 'name' on table 'table_name'.

create_table(table_name, fields)

Creates the table 'table_name' with the given list of columns 'fields'.

'fields' is a list of 2-part tuples, where the first part is the field name, and the second part is a valid django.db.models.fields.Field instance.

rename_table(old_table_name, table_name)

Renames 'old_table_name' to 'table_name'.

delete_table(table_name)

Deletes the table 'table_name'.

create_index(table_name, column_names, unique=False, db_tablespace='')

Creates an index on the table spanning over each column defined in the column_names sequence. If unique is True, the index will be created as unique. If db_tablespace is specified, the index will be created in the specified tablespace.

(create_index is new in 0.4)

delete_index(self, table_name, column_names, db_tablespace='')

Deletes the index spanning the given columns on the table. Note that the index must have previously been generated by South, as a hashing algorithm is used to convert the column names into an index name. (This also means you have to pass the column names in using the same order as when the column was created).

(delete_index is new in 0.4)

execute(sql, params=[])

Executes the given raw SQL, optionally using the given parameters. You should try to avoid using this, as it defeats the point of database abstraction; if you find yourself using it a lot, consider adding a method to this API (see contributing for more info).

send_create_signal(app_label, model_names)

Sends the post_syncdb signal for the given list of model names in the given app. Note that the signal will only be sent after all migrations have finished running.