Version 3 (modified by amccurdy, 7 years ago) (diff)


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 added to your migrations if you created them using startmigration.


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)

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.

rename_column(table_name, old, new)

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

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'.


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.

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).