| 1 |
================ |
| 2 |
``SchemaEditor`` |
| 3 |
================ |
| 4 |
|
| 5 |
.. module:: django.db.backends.base.schema |
| 6 |
|
| 7 |
.. class:: BaseDatabaseSchemaEditor |
| 8 |
|
| 9 |
Django's migration system is split into two parts; the logic for calculating |
| 10 |
and storing what operations should be run (``django.db.migrations``), and the |
| 11 |
database abstraction layer that turns things like "create a model" or |
| 12 |
"delete a field" into SQL - which is the job of the ``SchemaEditor``. |
| 13 |
|
| 14 |
It's unlikely that you will want to interact directly with ``SchemaEditor`` as |
| 15 |
a normal developer using Django, but if you want to write your own migration |
| 16 |
system, or have more advanced needs, it's a lot nicer than writing SQL. |
| 17 |
|
| 18 |
Each database backend in Django supplies its own version of ``SchemaEditor``, |
| 19 |
and it's always accessible via the ``connection.schema_editor()`` context |
| 20 |
manager:: |
| 21 |
|
| 22 |
with connection.schema_editor() as schema_editor: |
| 23 |
schema_editor.delete_model(MyModel) |
| 24 |
|
| 25 |
It must be used via the context manager as this allows it to manage things |
| 26 |
like transactions and deferred SQL (like creating ``ForeignKey`` constraints). |
| 27 |
|
| 28 |
It exposes all possible operations as methods, that should be called in |
| 29 |
the order you wish changes to be applied. Some possible operations or types |
| 30 |
of change are not possible on all databases - for example, MyISAM does not |
| 31 |
support foreign key constraints. |
| 32 |
|
| 33 |
If you are writing or maintaining a third-party database backend for Django, |
| 34 |
you will need to provide a ``SchemaEditor`` implementation in order to work with |
| 35 |
Django's migration functionality - however, as long as your database is |
| 36 |
relatively standard in its use of SQL and relational design, you should be able |
| 37 |
to subclass one of the built-in Django ``SchemaEditor`` classes and tweak the |
| 38 |
syntax a little. |
| 39 |
|
| 40 |
Methods |
| 41 |
======= |
| 42 |
|
| 43 |
``execute()`` |
| 44 |
------------- |
| 45 |
|
| 46 |
.. method:: BaseDatabaseSchemaEditor.execute(sql, params=()) |
| 47 |
|
| 48 |
Executes the SQL statement passed in, with parameters if supplied. This |
| 49 |
is a wrapper around the normal database cursors that allows capture of the SQL |
| 50 |
to a ``.sql`` file if the user wishes. |
| 51 |
|
| 52 |
``create_model()`` |
| 53 |
------------------ |
| 54 |
|
| 55 |
.. method:: BaseDatabaseSchemaEditor.create_model(model) |
| 56 |
|
| 57 |
Creates a new table in the database for the provided model, along with any |
| 58 |
unique constraints or indexes it requires. |
| 59 |
|
| 60 |
``delete_model()`` |
| 61 |
------------------ |
| 62 |
|
| 63 |
.. method:: BaseDatabaseSchemaEditor.delete_model(model) |
| 64 |
|
| 65 |
Drops the model's table in the database along with any unique constraints |
| 66 |
or indexes it has. |
| 67 |
|
| 68 |
``add_index()`` |
| 69 |
--------------- |
| 70 |
|
| 71 |
.. method:: BaseDatabaseSchemaEditor.add_index(model, index) |
| 72 |
|
| 73 |
Adds ``index`` to ``model``’s table. |
| 74 |
|
| 75 |
``remove_index()`` |
| 76 |
------------------ |
| 77 |
|
| 78 |
.. method:: BaseDatabaseSchemaEditor.remove_index(model, index) |
| 79 |
|
| 80 |
Removes ``index`` from ``model``’s table. |
| 81 |
|
| 82 |
``rename_index()`` |
| 83 |
------------------ |
| 84 |
|
| 85 |
.. method:: BaseDatabaseSchemaEditor.rename_index(model, old_index, new_index) |
| 86 |
|
| 87 |
Renames ``old_index`` from ``model``’s table to ``new_index``. |
| 88 |
|
| 89 |
``add_constraint()`` |
| 90 |
-------------------- |
| 91 |
|
| 92 |
.. method:: BaseDatabaseSchemaEditor.add_constraint(model, constraint) |
| 93 |
|
| 94 |
Adds ``constraint`` to ``model``'s table. |
| 95 |
|
| 96 |
``remove_constraint()`` |
| 97 |
----------------------- |
| 98 |
|
| 99 |
.. method:: BaseDatabaseSchemaEditor.remove_constraint(model, constraint) |
| 100 |
|
| 101 |
Removes ``constraint`` from ``model``'s table. |
| 102 |
|
| 103 |
``alter_unique_together()`` |
| 104 |
--------------------------- |
| 105 |
|
| 106 |
.. method:: BaseDatabaseSchemaEditor.alter_unique_together(model, old_unique_together, new_unique_together) |
| 107 |
|
| 108 |
Changes a model's :attr:`~django.db.models.Options.unique_together` value; this |
| 109 |
will add or remove unique constraints from the model's table until they match |
| 110 |
the new value. |
| 111 |
|
| 112 |
``alter_index_together()`` |
| 113 |
-------------------------- |
| 114 |
|
| 115 |
.. method:: BaseDatabaseSchemaEditor.alter_index_together(model, old_index_together, new_index_together) |
| 116 |
|
| 117 |
Changes a model's ``index_together`` value; this will add or remove indexes |
| 118 |
from the model's table until they match the new value. |
| 119 |
|
| 120 |
``alter_db_table()`` |
| 121 |
-------------------- |
| 122 |
|
| 123 |
.. method:: BaseDatabaseSchemaEditor.alter_db_table(model, old_db_table, new_db_table) |
| 124 |
|
| 125 |
Renames the model's table from ``old_db_table`` to ``new_db_table``. |
| 126 |
|
| 127 |
``alter_db_table_comment()`` |
| 128 |
---------------------------- |
| 129 |
|
| 130 |
.. method:: BaseDatabaseSchemaEditor.alter_db_table_comment(model, old_db_table_comment, new_db_table_comment) |
| 131 |
|
| 132 |
Change the ``model``’s table comment to ``new_db_table_comment``. |
| 133 |
|
| 134 |
``alter_db_tablespace()`` |
| 135 |
------------------------- |
| 136 |
|
| 137 |
.. method:: BaseDatabaseSchemaEditor.alter_db_tablespace(model, old_db_tablespace, new_db_tablespace) |
| 138 |
|
| 139 |
Moves the model's table from one tablespace to another. |
| 140 |
|
| 141 |
``add_field()`` |
| 142 |
--------------- |
| 143 |
|
| 144 |
.. method:: BaseDatabaseSchemaEditor.add_field(model, field) |
| 145 |
|
| 146 |
Adds a column (or sometimes multiple) to the model's table to represent the |
| 147 |
field. This will also add indexes or a unique constraint |
| 148 |
if the field has ``db_index=True`` or ``unique=True``. |
| 149 |
|
| 150 |
If the field is a ``ManyToManyField`` without a value for ``through``, instead |
| 151 |
of creating a column, it will make a table to represent the relationship. If |
| 152 |
``through`` is provided, it is a no-op. |
| 153 |
|
| 154 |
If the field is a ``ForeignKey``, this will also add the foreign key |
| 155 |
constraint to the column. |
| 156 |
|
| 157 |
``remove_field()`` |
| 158 |
------------------ |
| 159 |
|
| 160 |
.. method:: BaseDatabaseSchemaEditor.remove_field(model, field) |
| 161 |
|
| 162 |
Removes the column(s) representing the field from the model's table, along |
| 163 |
with any unique constraints, foreign key constraints, or indexes caused by |
| 164 |
that field. |
| 165 |
|
| 166 |
If the field is a ManyToManyField without a value for ``through``, it will |
| 167 |
remove the table created to track the relationship. If |
| 168 |
``through`` is provided, it is a no-op. |
| 169 |
|
| 170 |
``alter_field()`` |
| 171 |
----------------- |
| 172 |
|
| 173 |
.. method:: BaseDatabaseSchemaEditor.alter_field(model, old_field, new_field, strict=False) |
| 174 |
|
| 175 |
This transforms the field on the model from the old field to the new one. This |
| 176 |
includes changing the name of the column (the |
| 177 |
:attr:`~django.db.models.Field.db_column` attribute), changing the type of the |
| 178 |
field (if the field class changes), changing the ``NULL`` status of the field, |
| 179 |
adding or removing field-only unique constraints and indexes, changing primary |
| 180 |
key, and changing the destination of ``ForeignKey`` constraints. |
| 181 |
|
| 182 |
The most common transformation this cannot do is transforming a |
| 183 |
``ManyToManyField`` into a normal Field or vice-versa; Django cannot do this |
| 184 |
without losing data, and so it will refuse to do it. Instead, |
| 185 |
:meth:`.remove_field` and :meth:`.add_field` should be called separately. |
| 186 |
|
| 187 |
If the database has the ``supports_combined_alters``, Django will try and |
| 188 |
do as many of these in a single database call as possible; otherwise, it will |
| 189 |
issue a separate ALTER statement for each change, but will not issue ALTERs |
| 190 |
where no change is required. |
| 191 |
|
| 192 |
Attributes |
| 193 |
========== |
| 194 |
|
| 195 |
All attributes should be considered read-only unless stated otherwise. |
| 196 |
|
| 197 |
``connection`` |
| 198 |
-------------- |
| 199 |
|
| 200 |
.. attribute:: SchemaEditor.connection |
| 201 |
|
| 202 |
A connection object to the database. A useful attribute of the connection is |
| 203 |
``alias`` which can be used to determine the name of the database being |
| 204 |
accessed. |
| 205 |
|
| 206 |
This is useful when doing data migrations for :ref:`migrations with multiple |
| 207 |
databases <data-migrations-and-multiple-databases>`. |