mirror of
https://github.com/django/django.git
synced 2025-01-11 10:56:28 +00:00
4a954cfd11
This patch does not remove all occurrences of the words in question. Rather, I went through all of the occurrences of the words listed below, and judged if they a) suggested the reader had some kind of knowledge/experience, and b) if they added anything of value (including tone of voice, etc). I left most of the words alone. I looked at the following words: - simply/simple - easy/easier/easiest - obvious - just - merely - straightforward - ridiculous Thanks to Carlton Gibson for guidance on how to approach this issue, and to Tim Bell for providing the idea. But the enormous lion's share of thanks go to Adam Johnson for his patient and helpful review.
201 lines
6.8 KiB
Plaintext
201 lines
6.8 KiB
Plaintext
================
|
||
``SchemaEditor``
|
||
================
|
||
|
||
.. module:: django.db.backends.base.schema
|
||
|
||
.. class:: BaseDatabaseSchemaEditor
|
||
|
||
Django's migration system is split into two parts; the logic for calculating
|
||
and storing what operations should be run (``django.db.migrations``), and the
|
||
database abstraction layer that turns things like "create a model" or
|
||
"delete a field" into SQL - which is the job of the ``SchemaEditor``.
|
||
|
||
It's unlikely that you will want to interact directly with ``SchemaEditor`` as
|
||
a normal developer using Django, but if you want to write your own migration
|
||
system, or have more advanced needs, it's a lot nicer than writing SQL.
|
||
|
||
Each database backend in Django supplies its own version of ``SchemaEditor``,
|
||
and it's always accessible via the ``connection.schema_editor()`` context
|
||
manager::
|
||
|
||
with connection.schema_editor() as schema_editor:
|
||
schema_editor.delete_model(MyModel)
|
||
|
||
It must be used via the context manager as this allows it to manage things
|
||
like transactions and deferred SQL (like creating ``ForeignKey`` constraints).
|
||
|
||
It exposes all possible operations as methods, that should be called in
|
||
the order you wish changes to be applied. Some possible operations or types
|
||
of change are not possible on all databases - for example, MyISAM does not
|
||
support foreign key constraints.
|
||
|
||
If you are writing or maintaining a third-party database backend for Django,
|
||
you will need to provide a ``SchemaEditor`` implementation in order to work with
|
||
1.7's migration functionality - however, as long as your database is relatively
|
||
standard in its use of SQL and relational design, you should be able to
|
||
subclass one of the built-in Django ``SchemaEditor`` classes and tweak the
|
||
syntax a little. Also note that there are a few new database features that
|
||
migrations will look for: ``can_rollback_ddl``
|
||
and ``supports_combined_alters`` are the most important.
|
||
|
||
Methods
|
||
=======
|
||
|
||
``execute()``
|
||
-------------
|
||
|
||
.. method:: BaseDatabaseSchemaEditor.execute(sql, params=[])
|
||
|
||
Executes the SQL statement passed in, with parameters if supplied. This
|
||
is a wrapper around the normal database cursors that allows capture of the SQL
|
||
to a ``.sql`` file if the user wishes.
|
||
|
||
``create_model()``
|
||
------------------
|
||
|
||
.. method:: BaseDatabaseSchemaEditor.create_model(model)
|
||
|
||
Creates a new table in the database for the provided model, along with any
|
||
unique constraints or indexes it requires.
|
||
|
||
``delete_model()``
|
||
------------------
|
||
|
||
.. method:: BaseDatabaseSchemaEditor.delete_model(model)
|
||
|
||
Drops the model's table in the database along with any unique constraints
|
||
or indexes it has.
|
||
|
||
``add_index()``
|
||
---------------
|
||
|
||
.. method:: BaseDatabaseSchemaEditor.add_index(model, index)
|
||
|
||
Adds ``index`` to ``model``’s table.
|
||
|
||
``remove_index()``
|
||
------------------
|
||
|
||
.. method:: BaseDatabaseSchemaEditor.remove_index(model, index)
|
||
|
||
Removes ``index`` from ``model``’s table.
|
||
|
||
``add_constraint()``
|
||
--------------------
|
||
|
||
.. method:: BaseDatabaseSchemaEditor.add_constraint(model, constraint)
|
||
|
||
.. versionadded:: 2.2
|
||
|
||
Adds ``constraint`` to ``model``'s table.
|
||
|
||
``remove_constraint()``
|
||
-----------------------
|
||
|
||
.. method:: BaseDatabaseSchemaEditor.remove_constraint(model, constraint)
|
||
|
||
.. versionadded:: 2.2
|
||
|
||
Removes ``constraint`` from ``model``'s table.
|
||
|
||
``alter_unique_together()``
|
||
---------------------------
|
||
|
||
.. method:: BaseDatabaseSchemaEditor.alter_unique_together(model, old_unique_together, new_unique_together)
|
||
|
||
Changes a model's :attr:`~django.db.models.Options.unique_together` value; this
|
||
will add or remove unique constraints from the model's table until they match
|
||
the new value.
|
||
|
||
``alter_index_together()``
|
||
--------------------------
|
||
|
||
.. method:: BaseDatabaseSchemaEditor.alter_index_together(model, old_index_together, new_index_together)
|
||
|
||
Changes a model's :attr:`~django.db.models.Options.index_together` value; this
|
||
will add or remove indexes from the model's table until they match the new
|
||
value.
|
||
|
||
``alter_db_table()``
|
||
--------------------
|
||
|
||
.. method:: BaseDatabaseSchemaEditor.alter_db_table(model, old_db_table, new_db_table)
|
||
|
||
Renames the model's table from ``old_db_table`` to ``new_db_table``.
|
||
|
||
``alter_db_tablespace()``
|
||
-------------------------
|
||
|
||
.. method:: BaseDatabaseSchemaEditor.alter_db_tablespace(model, old_db_tablespace, new_db_tablespace)
|
||
|
||
Moves the model's table from one tablespace to another.
|
||
|
||
``add_field()``
|
||
---------------
|
||
|
||
.. method:: BaseDatabaseSchemaEditor.add_field(model, field)
|
||
|
||
Adds a column (or sometimes multiple) to the model's table to represent the
|
||
field. This will also add indexes or a unique constraint
|
||
if the field has ``db_index=True`` or ``unique=True``.
|
||
|
||
If the field is a ``ManyToManyField`` without a value for ``through``, instead
|
||
of creating a column, it will make a table to represent the relationship. If
|
||
``through`` is provided, it is a no-op.
|
||
|
||
If the field is a ``ForeignKey``, this will also add the foreign key
|
||
constraint to the column.
|
||
|
||
``remove_field()``
|
||
------------------
|
||
|
||
.. method:: BaseDatabaseSchemaEditor.remove_field(model, field)
|
||
|
||
Removes the column(s) representing the field from the model's table, along
|
||
with any unique constraints, foreign key constraints, or indexes caused by
|
||
that field.
|
||
|
||
If the field is a ManyToManyField without a value for ``through``, it will
|
||
remove the table created to track the relationship. If
|
||
``through`` is provided, it is a no-op.
|
||
|
||
``alter_field()``
|
||
-----------------
|
||
|
||
.. method:: BaseDatabaseSchemaEditor.alter_field(model, old_field, new_field, strict=False)
|
||
|
||
This transforms the field on the model from the old field to the new one. This
|
||
includes changing the name of the column (the
|
||
:attr:`~django.db.models.Field.db_column` attribute), changing the type of the
|
||
field (if the field class changes), changing the ``NULL`` status of the field,
|
||
adding or removing field-only unique constraints and indexes, changing primary
|
||
key, and changing the destination of ``ForeignKey`` constraints.
|
||
|
||
The most common transformation this cannot do is transforming a
|
||
``ManyToManyField`` into a normal Field or vice-versa; Django cannot do this
|
||
without losing data, and so it will refuse to do it. Instead,
|
||
:meth:`.remove_field` and :meth:`.add_field` should be called separately.
|
||
|
||
If the database has the ``supports_combined_alters``, Django will try and
|
||
do as many of these in a single database call as possible; otherwise, it will
|
||
issue a separate ALTER statement for each change, but will not issue ALTERs
|
||
where no change is required (as South often did).
|
||
|
||
Attributes
|
||
==========
|
||
|
||
All attributes should be considered read-only unless stated otherwise.
|
||
|
||
``connection``
|
||
--------------
|
||
|
||
.. attribute:: SchemaEditor.connection
|
||
|
||
A connection object to the database. A useful attribute of the connection is
|
||
``alias`` which can be used to determine the name of the database being
|
||
accessed.
|
||
|
||
This is useful when doing data migrations for :ref:`migrations with multiple
|
||
databases <data-migrations-and-multiple-databases>`.
|