wiki:db.add_column
Last modified 6 years ago Last modified on 03/12/09 16:48:57

db.add_column

db.add_column(table_name, field_name, field, keep_default=True)

(keep_default is in South 0.4 and higher)

Adds a column called field_name to the table table_name, of the type specified by the field instance field.

If keep_default is True, then any default value specified on the field will be added to the database schema for that column permanently. If not, then the default is only used when adding the column, and then dropped afterwards.

Note that the default value for fields given here is only ever used when adding the column to a non-empty table; the default used by the ORM in your application is the one specified on the field in your models.py file, as Django handles adding default values before the query hits the database.

The only case where having the default stored in the database as well would make a difference would be where you are interacting with the database from somewhere else, or Django doesn't know about the added column at all.

Also, note that the name you give for the column is the field name, not the column name - if the field you pass in is a ForeignKey?, for example, the real column name will have _id on the end.

Examples

A normal column addition (the column is nullable, so all existing rows will have it set to NULL):

db.add_column('core_profile', 'height', models.IntegerField(null=True))

Providing a default value instead, so all current rows will get this value for 'height':

db.add_column('core_profile', 'height', models.IntegerField(default=-1))

Same as above, but the default is not left in the database schema:

db.add_column('core_profile', 'height', models.IntegerField(default=-1), keep_default=False)