Debian Codegraph @

docs/ref/contrib/postgres/operations.txt

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