Debian Codegraph @

docs/ref/schema-editor.txt

raw
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>`.