| 1 |
============================= |
| 2 |
Database migration operations |
| 3 |
============================= |
| 4 |
|
| 5 |
All of these :doc:`operations </ref/migration-operations>` are available from |
| 6 |
the ``django.contrib.postgres.operations`` module. |
| 7 |
|
| 8 |
.. _create-postgresql-extensions: |
| 9 |
|
| 10 |
Creating extension using migrations |
| 11 |
=================================== |
| 12 |
|
| 13 |
You can create a PostgreSQL extension in your database using a migration file. |
| 14 |
This example creates an hstore extension, but the same principles apply for |
| 15 |
other extensions. |
| 16 |
|
| 17 |
Set up the hstore extension in PostgreSQL before the first ``CreateModel`` |
| 18 |
or ``AddField`` operation that involves |
| 19 |
:class:`~django.contrib.postgres.fields.HStoreField` by adding a migration with |
| 20 |
the :class:`~django.contrib.postgres.operations.HStoreExtension` operation. |
| 21 |
For example:: |
| 22 |
|
| 23 |
from django.contrib.postgres.operations import HStoreExtension |
| 24 |
|
| 25 |
|
| 26 |
class Migration(migrations.Migration): |
| 27 |
... |
| 28 |
|
| 29 |
operations = [HStoreExtension(), ...] |
| 30 |
|
| 31 |
The operation skips adding the extension if it already exists. |
| 32 |
|
| 33 |
For most extensions, this requires a database user with superuser privileges. |
| 34 |
If the Django database user doesn't have the appropriate privileges, you'll |
| 35 |
have to create the extension outside of Django migrations with a user that has |
| 36 |
them. In that case, connect to your Django database and run the query |
| 37 |
``CREATE EXTENSION IF NOT EXISTS hstore;``. |
| 38 |
|
| 39 |
.. currentmodule:: django.contrib.postgres.operations |
| 40 |
|
| 41 |
``CreateExtension`` |
| 42 |
=================== |
| 43 |
|
| 44 |
.. class:: CreateExtension(name) |
| 45 |
|
| 46 |
An ``Operation`` subclass which installs a PostgreSQL extension. For common |
| 47 |
extensions, use one of the more specific subclasses below. |
| 48 |
|
| 49 |
.. attribute:: name |
| 50 |
|
| 51 |
This is a required argument. The name of the extension to be installed. |
| 52 |
|
| 53 |
``BloomExtension`` |
| 54 |
================== |
| 55 |
|
| 56 |
.. class:: BloomExtension() |
| 57 |
|
| 58 |
Installs the ``bloom`` extension. |
| 59 |
|
| 60 |
``BtreeGinExtension`` |
| 61 |
===================== |
| 62 |
|
| 63 |
.. class:: BtreeGinExtension() |
| 64 |
|
| 65 |
Installs the ``btree_gin`` extension. |
| 66 |
|
| 67 |
``BtreeGistExtension`` |
| 68 |
====================== |
| 69 |
|
| 70 |
.. class:: BtreeGistExtension() |
| 71 |
|
| 72 |
Installs the ``btree_gist`` extension. |
| 73 |
|
| 74 |
``CITextExtension`` |
| 75 |
=================== |
| 76 |
|
| 77 |
.. class:: CITextExtension() |
| 78 |
|
| 79 |
Installs the ``citext`` extension. |
| 80 |
|
| 81 |
``CryptoExtension`` |
| 82 |
=================== |
| 83 |
|
| 84 |
.. class:: CryptoExtension() |
| 85 |
|
| 86 |
Installs the ``pgcrypto`` extension. |
| 87 |
|
| 88 |
``HStoreExtension`` |
| 89 |
=================== |
| 90 |
|
| 91 |
.. class:: HStoreExtension() |
| 92 |
|
| 93 |
Installs the ``hstore`` extension and also sets up the connection to |
| 94 |
interpret hstore data for possible use in subsequent migrations. |
| 95 |
|
| 96 |
``TrigramExtension`` |
| 97 |
==================== |
| 98 |
|
| 99 |
.. class:: TrigramExtension() |
| 100 |
|
| 101 |
Installs the ``pg_trgm`` extension. |
| 102 |
|
| 103 |
``UnaccentExtension`` |
| 104 |
===================== |
| 105 |
|
| 106 |
.. class:: UnaccentExtension() |
| 107 |
|
| 108 |
Installs the ``unaccent`` extension. |
| 109 |
|
| 110 |
.. _manage-postgresql-collations: |
| 111 |
|
| 112 |
Managing collations using migrations |
| 113 |
==================================== |
| 114 |
|
| 115 |
If you need to filter or order a column using a particular collation that your |
| 116 |
operating system provides but PostgreSQL does not, you can manage collations in |
| 117 |
your database using a migration file. These collations can then be used with |
| 118 |
the ``db_collation`` parameter on :class:`~django.db.models.CharField`, |
| 119 |
:class:`~django.db.models.TextField`, and their subclasses. |
| 120 |
|
| 121 |
For example, to create a collation for German phone book ordering:: |
| 122 |
|
| 123 |
from django.contrib.postgres.operations import CreateCollation |
| 124 |
|
| 125 |
|
| 126 |
class Migration(migrations.Migration): |
| 127 |
... |
| 128 |
|
| 129 |
operations = [ |
| 130 |
CreateCollation( |
| 131 |
"case_insensitive", |
| 132 |
provider="icu", |
| 133 |
locale="und-u-ks-level2", |
| 134 |
deterministic=False, |
| 135 |
), |
| 136 |
..., |
| 137 |
] |
| 138 |
|
| 139 |
.. class:: CreateCollation(name, locale, *, provider='libc', deterministic=True) |
| 140 |
|
| 141 |
Creates a collation with the given ``name``, ``locale`` and ``provider``. |
| 142 |
|
| 143 |
Set the ``deterministic`` parameter to ``False`` to create a |
| 144 |
non-deterministic collation, such as for case-insensitive filtering. |
| 145 |
|
| 146 |
.. class:: RemoveCollation(name, locale, *, provider='libc', deterministic=True) |
| 147 |
|
| 148 |
Removes the collations named ``name``. |
| 149 |
|
| 150 |
When reversed this is creating a collation with the provided ``locale``, |
| 151 |
``provider``, and ``deterministic`` arguments. Therefore, ``locale`` is |
| 152 |
required to make this operation reversible. |
| 153 |
|
| 154 |
Concurrent index operations |
| 155 |
=========================== |
| 156 |
|
| 157 |
PostgreSQL supports the ``CONCURRENTLY`` option to ``CREATE INDEX`` and |
| 158 |
``DROP INDEX`` statements to add and remove indexes without locking out writes. |
| 159 |
This option is useful for adding or removing an index in a live production |
| 160 |
database. |
| 161 |
|
| 162 |
.. class:: AddIndexConcurrently(model_name, index) |
| 163 |
|
| 164 |
Like :class:`~django.db.migrations.operations.AddIndex`, but creates an |
| 165 |
index with the ``CONCURRENTLY`` option. This has a few caveats to be aware |
| 166 |
of when using this option, see `the PostgreSQL documentation of building |
| 167 |
indexes concurrently <https://www.postgresql.org/docs/current/ |
| 168 |
sql-createindex.html#SQL-CREATEINDEX-CONCURRENTLY>`_. |
| 169 |
|
| 170 |
.. class:: RemoveIndexConcurrently(model_name, name) |
| 171 |
|
| 172 |
Like :class:`~django.db.migrations.operations.RemoveIndex`, but removes the |
| 173 |
index with the ``CONCURRENTLY`` option. This has a few caveats to be aware |
| 174 |
of when using this option, see `the PostgreSQL documentation |
| 175 |
<https://www.postgresql.org/docs/current/sql-dropindex.html>`_. |
| 176 |
|
| 177 |
.. note:: |
| 178 |
|
| 179 |
The ``CONCURRENTLY`` option is not supported inside a transaction (see |
| 180 |
:ref:`non-atomic migration <non-atomic-migrations>`). |
| 181 |
|
| 182 |
Adding constraints without enforcing validation |
| 183 |
=============================================== |
| 184 |
|
| 185 |
PostgreSQL supports the ``NOT VALID`` option with the ``ADD CONSTRAINT`` |
| 186 |
statement to add check constraints without enforcing validation on existing |
| 187 |
rows. This option is useful if you want to skip the potentially lengthy scan of |
| 188 |
the table to verify that all existing rows satisfy the constraint. |
| 189 |
|
| 190 |
To validate check constraints created with the ``NOT VALID`` option at a later |
| 191 |
point of time, use the |
| 192 |
:class:`~django.contrib.postgres.operations.ValidateConstraint` operation. |
| 193 |
|
| 194 |
See `the PostgreSQL documentation <https://www.postgresql.org/docs/current/ |
| 195 |
sql-altertable.html#SQL-ALTERTABLE-NOTES>`__ for more details. |
| 196 |
|
| 197 |
.. class:: AddConstraintNotValid(model_name, constraint) |
| 198 |
|
| 199 |
Like :class:`~django.db.migrations.operations.AddConstraint`, but avoids |
| 200 |
validating the constraint on existing rows. |
| 201 |
|
| 202 |
.. class:: ValidateConstraint(model_name, name) |
| 203 |
|
| 204 |
Scans through the table and validates the given check constraint on |
| 205 |
existing rows. |
| 206 |
|
| 207 |
.. note:: |
| 208 |
|
| 209 |
``AddConstraintNotValid`` and ``ValidateConstraint`` operations should be |
| 210 |
performed in two separate migrations. Performing both operations in the |
| 211 |
same atomic migration has the same effect as |
| 212 |
:class:`~django.db.migrations.operations.AddConstraint`, whereas performing |
| 213 |
them in a single non-atomic migration, may leave your database in an |
| 214 |
inconsistent state if the ``ValidateConstraint`` operation fails. |