Debian Codegraph @

django/db/backends/base/schema.py

raw
1 import logging
2 import operator
3 from datetime import datetime
4
5 from django.conf import settings
6 from django.core.exceptions import FieldError
7 from django.db.backends.ddl_references import (
8 Columns,
9 Expressions,
10 ForeignKeyName,
11 IndexName,
12 Statement,
13 Table,
14 )
15 from django.db.backends.utils import names_digest, split_identifier, truncate_name
16 from django.db.models import Deferrable, Index
17 from django.db.models.fields.composite import CompositePrimaryKey
18 from django.db.models.sql import Query
19 from django.db.transaction import TransactionManagementError, atomic
20 from django.utils import timezone
21
22 logger = logging.getLogger("django.db.backends.schema")
23
24
25 def _is_relevant_relation(relation, altered_field):
26 """
27 When altering the given field, must constraints on its model from the given
28 relation be temporarily dropped?
29 """
30 field = relation.field
31 if field.many_to_many:
32 # M2M reverse field
33 return False
34 if altered_field.primary_key and field.to_fields == [None]:
35 # Foreign key constraint on the primary key, which is being altered.
36 return True
37 # Is the constraint targeting the field being altered?
38 return altered_field.name in field.to_fields
39
40
41 def _all_related_fields(model):
42 # Related fields must be returned in a deterministic order.
43 return sorted(
44 model._meta._get_fields(
45 forward=False,
46 reverse=True,
47 include_hidden=True,
48 include_parents=False,
49 ),
50 key=operator.attrgetter("name"),
51 )
52
53
54 def _related_non_m2m_objects(old_field, new_field):
55 # Filter out m2m objects from reverse relations.
56 # Return (old_relation, new_relation) tuples.
57 related_fields = zip(
58 (
59 obj
60 for obj in _all_related_fields(old_field.model)
61 if _is_relevant_relation(obj, old_field)
62 ),
63 (
64 obj
65 for obj in _all_related_fields(new_field.model)
66 if _is_relevant_relation(obj, new_field)
67 ),
68 )
69 for old_rel, new_rel in related_fields:
70 yield old_rel, new_rel
71 yield from _related_non_m2m_objects(
72 old_rel.remote_field,
73 new_rel.remote_field,
74 )
75
76
77 class BaseDatabaseSchemaEditor:
78 """
79 This class and its subclasses are responsible for emitting schema-changing
80 statements to the databases - model creation/removal/alteration, field
81 renaming, index fiddling, and so on.
82 """
83
84 # Overrideable SQL templates
85 sql_create_table = "CREATE TABLE %(table)s (%(definition)s)"
86 sql_rename_table = "ALTER TABLE %(old_table)s RENAME TO %(new_table)s"
87 sql_retablespace_table = "ALTER TABLE %(table)s SET TABLESPACE %(new_tablespace)s"
88 sql_delete_table = "DROP TABLE %(table)s CASCADE"
89
90 sql_create_column = "ALTER TABLE %(table)s ADD COLUMN %(column)s %(definition)s"
91 sql_alter_column = "ALTER TABLE %(table)s %(changes)s"
92 sql_alter_column_type = "ALTER COLUMN %(column)s TYPE %(type)s%(collation)s"
93 sql_alter_column_null = "ALTER COLUMN %(column)s DROP NOT NULL"
94 sql_alter_column_not_null = "ALTER COLUMN %(column)s SET NOT NULL"
95 sql_alter_column_default = "ALTER COLUMN %(column)s SET DEFAULT %(default)s"
96 sql_alter_column_no_default = "ALTER COLUMN %(column)s DROP DEFAULT"
97 sql_alter_column_no_default_null = sql_alter_column_no_default
98 sql_delete_column = "ALTER TABLE %(table)s DROP COLUMN %(column)s CASCADE"
99 sql_rename_column = (
100 "ALTER TABLE %(table)s RENAME COLUMN %(old_column)s TO %(new_column)s"
101 )
102 sql_update_with_default = (
103 "UPDATE %(table)s SET %(column)s = %(default)s WHERE %(column)s IS NULL"
104 )
105
106 sql_unique_constraint = "UNIQUE (%(columns)s)%(deferrable)s"
107 sql_check_constraint = "CHECK (%(check)s)"
108 sql_delete_constraint = "ALTER TABLE %(table)s DROP CONSTRAINT %(name)s"
109 sql_constraint = "CONSTRAINT %(name)s %(constraint)s"
110 sql_pk_constraint = "PRIMARY KEY (%(columns)s)"
111
112 sql_create_check = "ALTER TABLE %(table)s ADD CONSTRAINT %(name)s CHECK (%(check)s)"
113 sql_delete_check = sql_delete_constraint
114
115 sql_create_unique = (
116 "ALTER TABLE %(table)s ADD CONSTRAINT %(name)s "
117 "UNIQUE%(nulls_distinct)s (%(columns)s)%(deferrable)s"
118 )
119 sql_delete_unique = sql_delete_constraint
120
121 sql_create_fk = (
122 "ALTER TABLE %(table)s ADD CONSTRAINT %(name)s FOREIGN KEY (%(column)s) "
123 "REFERENCES %(to_table)s (%(to_column)s)%(deferrable)s"
124 )
125 sql_create_inline_fk = None
126 sql_create_column_inline_fk = None
127 sql_delete_fk = sql_delete_constraint
128
129 sql_create_index = (
130 "CREATE INDEX %(name)s ON %(table)s "
131 "(%(columns)s)%(include)s%(extra)s%(condition)s"
132 )
133 sql_create_unique_index = (
134 "CREATE UNIQUE INDEX %(name)s ON %(table)s "
135 "(%(columns)s)%(include)s%(nulls_distinct)s%(condition)s"
136 )
137 sql_rename_index = "ALTER INDEX %(old_name)s RENAME TO %(new_name)s"
138 sql_delete_index = "DROP INDEX %(name)s"
139
140 sql_create_pk = (
141 "ALTER TABLE %(table)s ADD CONSTRAINT %(name)s PRIMARY KEY (%(columns)s)"
142 )
143 sql_delete_pk = sql_delete_constraint
144
145 sql_delete_procedure = "DROP PROCEDURE %(procedure)s"
146
147 sql_alter_table_comment = "COMMENT ON TABLE %(table)s IS %(comment)s"
148 sql_alter_column_comment = "COMMENT ON COLUMN %(table)s.%(column)s IS %(comment)s"
149
150 def __init__(self, connection, collect_sql=False, atomic=True):
151 self.connection = connection
152 self.collect_sql = collect_sql
153 if self.collect_sql:
154 self.collected_sql = []
155 self.atomic_migration = self.connection.features.can_rollback_ddl and atomic
156
157 # State-managing methods
158
159 def __enter__(self):
160 self.deferred_sql = []
161 if self.atomic_migration:
162 self.atomic = atomic(self.connection.alias)
163 self.atomic.__enter__()
164 return self
165
166 def __exit__(self, exc_type, exc_value, traceback):
167 if exc_type is None:
168 for sql in self.deferred_sql:
169 self.execute(sql, None)
170 if self.atomic_migration:
171 self.atomic.__exit__(exc_type, exc_value, traceback)
172
173 # Core utility functions
174
175 def execute(self, sql, params=()):
176 """Execute the given SQL statement, with optional parameters."""
177 # Don't perform the transactional DDL check if SQL is being collected
178 # as it's not going to be executed anyway.
179 if (
180 not self.collect_sql
181 and self.connection.in_atomic_block
182 and not self.connection.features.can_rollback_ddl
183 ):
184 raise TransactionManagementError(
185 "Executing DDL statements while in a transaction on databases "
186 "that can't perform a rollback is prohibited."
187 )
188 # Account for non-string statement objects.
189 sql = str(sql)
190 # Log the command we're running, then run it
191 logger.debug(
192 "%s; (params %r)", sql, params, extra={"params": params, "sql": sql}
193 )
194 if self.collect_sql:
195 ending = "" if sql.rstrip().endswith(";") else ";"
196 if params is not None:
197 self.collected_sql.append(
198 (sql % tuple(map(self.quote_value, params))) + ending
199 )
200 else:
201 self.collected_sql.append(sql + ending)
202 else:
203 with self.connection.cursor() as cursor:
204 cursor.execute(sql, params)
205
206 def quote_name(self, name):
207 return self.connection.ops.quote_name(name)
208
209 def table_sql(self, model):
210 """Take a model and return its table definition."""
211 # Add any unique_togethers (always deferred, as some fields might be
212 # created afterward, like geometry fields with some backends).
213 for field_names in model._meta.unique_together:
214 fields = [model._meta.get_field(field) for field in field_names]
215 self.deferred_sql.append(self._create_unique_sql(model, fields))
216 # Create column SQL, add FK deferreds if needed.
217 column_sqls = []
218 params = []
219 for field in model._meta.local_fields:
220 # SQL.
221 definition, extra_params = self.column_sql(model, field)
222 if definition is None:
223 continue
224 # Check constraints can go on the column SQL here.
225 db_params = field.db_parameters(connection=self.connection)
226 if db_params["check"]:
227 definition += " " + self.sql_check_constraint % db_params
228 # Autoincrement SQL (for backends with inline variant).
229 col_type_suffix = field.db_type_suffix(connection=self.connection)
230 if col_type_suffix:
231 definition += " %s" % col_type_suffix
232 params.extend(extra_params)
233 # FK.
234 if field.remote_field and field.db_constraint:
235 to_table = field.remote_field.model._meta.db_table
236 to_column = field.remote_field.model._meta.get_field(
237 field.remote_field.field_name
238 ).column
239 if self.sql_create_inline_fk:
240 definition += " " + self.sql_create_inline_fk % {
241 "to_table": self.quote_name(to_table),
242 "to_column": self.quote_name(to_column),
243 }
244 elif self.connection.features.supports_foreign_keys:
245 self.deferred_sql.append(
246 self._create_fk_sql(
247 model, field, "_fk_%(to_table)s_%(to_column)s"
248 )
249 )
250 # Add the SQL to our big list.
251 column_sqls.append(
252 "%s %s"
253 % (
254 self.quote_name(field.column),
255 definition,
256 )
257 )
258 # Autoincrement SQL (for backends with post table definition
259 # variant).
260 if field.get_internal_type() in (
261 "AutoField",
262 "BigAutoField",
263 "SmallAutoField",
264 ):
265 autoinc_sql = self.connection.ops.autoinc_sql(
266 model._meta.db_table, field.column
267 )
268 if autoinc_sql:
269 self.deferred_sql.extend(autoinc_sql)
270 # The BaseConstraint DDL creation methods such as constraint_sql(),
271 # create_sql(), and delete_sql(), were not designed in a way that
272 # separate SQL from parameters which make their generated SQL unfit to
273 # be used in a context where parametrization is delegated to the
274 # backend.
275 constraint_sqls = []
276 if params:
277 # If parameters are present (e.g. a DEFAULT clause on backends that
278 # allow parametrization) defer constraint creation so they are not
279 # mixed with SQL meant to be parametrized.
280 for constraint in model._meta.constraints:
281 self.deferred_sql.append(constraint.create_sql(model, self))
282 else:
283 constraint_sqls.extend(
284 constraint.constraint_sql(model, self)
285 for constraint in model._meta.constraints
286 )
287
288 pk = model._meta.pk
289 if isinstance(pk, CompositePrimaryKey):
290 constraint_sqls.append(self._pk_constraint_sql(pk.columns))
291
292 sql = self.sql_create_table % {
293 "table": self.quote_name(model._meta.db_table),
294 "definition": ", ".join(
295 str(statement)
296 for statement in (*column_sqls, *constraint_sqls)
297 if statement
298 ),
299 }
300 if model._meta.db_tablespace:
301 tablespace_sql = self.connection.ops.tablespace_sql(
302 model._meta.db_tablespace
303 )
304 if tablespace_sql:
305 sql += " " + tablespace_sql
306 return sql, params
307
308 # Field <-> database mapping functions
309
310 def _iter_column_sql(
311 self, column_db_type, params, model, field, field_db_params, include_default
312 ):
313 yield column_db_type
314 if collation := field_db_params.get("collation"):
315 yield self._collate_sql(collation)
316 if self.connection.features.supports_comments_inline and field.db_comment:
317 yield self._comment_sql(field.db_comment)
318 # Work out nullability.
319 null = field.null
320 # Add database default.
321 if field.has_db_default():
322 default_sql, default_params = self.db_default_sql(field)
323 yield f"DEFAULT {default_sql}"
324 params.extend(default_params)
325 include_default = False
326 # Include a default value, if requested.
327 include_default = (
328 include_default
329 and not self.skip_default(field)
330 and
331 # Don't include a default value if it's a nullable field and the
332 # default cannot be dropped in the ALTER COLUMN statement (e.g.
333 # MySQL longtext and longblob).
334 not (null and self.skip_default_on_alter(field))
335 )
336 if include_default:
337 default_value = self.effective_default(field)
338 if default_value is not None:
339 column_default = "DEFAULT " + self._column_default_sql(field)
340 if self.connection.features.requires_literal_defaults:
341 # Some databases can't take defaults as a parameter
342 # (Oracle, SQLite). If this is the case, the individual
343 # schema backend should implement prepare_default().
344 yield column_default % self.prepare_default(default_value)
345 else:
346 yield column_default
347 params.append(default_value)
348 # Oracle treats the empty string ('') as null, so coerce the null
349 # option whenever '' is a possible value.
350 if (
351 field.empty_strings_allowed
352 and not field.primary_key
353 and self.connection.features.interprets_empty_strings_as_nulls
354 ):
355 null = True
356 if field.generated:
357 generated_sql, generated_params = self._column_generated_sql(field)
358 params.extend(generated_params)
359 yield generated_sql
360 elif not null:
361 yield "NOT NULL"
362 elif not self.connection.features.implied_column_null:
363 yield "NULL"
364 if field.primary_key:
365 yield "PRIMARY KEY"
366 elif field.unique:
367 yield "UNIQUE"
368 # Optionally add the tablespace if it's an implicitly indexed column.
369 tablespace = field.db_tablespace or model._meta.db_tablespace
370 if (
371 tablespace
372 and self.connection.features.supports_tablespaces
373 and field.unique
374 ):
375 yield self.connection.ops.tablespace_sql(tablespace, inline=True)
376
377 def column_sql(self, model, field, include_default=False):
378 """
379 Return the column definition for a field. The field must already have
380 had set_attributes_from_name() called.
381 """
382 # Get the column's type and use that as the basis of the SQL.
383 field_db_params = field.db_parameters(connection=self.connection)
384 column_db_type = field_db_params["type"]
385 # Check for fields that aren't actually columns (e.g. M2M).
386 if column_db_type is None:
387 return None, None
388 params = []
389 return (
390 " ".join(
391 # This appends to the params being returned.
392 self._iter_column_sql(
393 column_db_type,
394 params,
395 model,
396 field,
397 field_db_params,
398 include_default,
399 )
400 ),
401 params,
402 )
403
404 def skip_default(self, field):
405 """
406 Some backends don't accept default values for certain columns types
407 (i.e. MySQL longtext and longblob).
408 """
409 return False
410
411 def skip_default_on_alter(self, field):
412 """
413 Some backends don't accept default values for certain columns types
414 (i.e. MySQL longtext and longblob) in the ALTER COLUMN statement.
415 """
416 return False
417
418 def prepare_default(self, value):
419 """
420 Only used for backends which have requires_literal_defaults feature
421 """
422 raise NotImplementedError(
423 "subclasses of BaseDatabaseSchemaEditor for backends which have "
424 "requires_literal_defaults must provide a prepare_default() method"
425 )
426
427 def _column_default_sql(self, field):
428 """
429 Return the SQL to use in a DEFAULT clause. The resulting string should
430 contain a '%s' placeholder for a default value.
431 """
432 return "%s"
433
434 def db_default_sql(self, field):
435 """Return the sql and params for the field's database default."""
436 from django.db.models.expressions import Value
437
438 db_default = field._db_default_expression
439 sql = (
440 self._column_default_sql(field) if isinstance(db_default, Value) else "(%s)"
441 )
442 query = Query(model=field.model)
443 compiler = query.get_compiler(connection=self.connection)
444 default_sql, params = compiler.compile(db_default)
445 if self.connection.features.requires_literal_defaults:
446 # Some databases don't support parameterized defaults (Oracle,
447 # SQLite). If this is the case, the individual schema backend
448 # should implement prepare_default().
449 default_sql %= tuple(self.prepare_default(p) for p in params)
450 params = []
451 return sql % default_sql, params
452
453 def _column_generated_sql(self, field):
454 """Return the SQL to use in a GENERATED ALWAYS clause."""
455 expression_sql, params = field.generated_sql(self.connection)
456 persistency_sql = "STORED" if field.db_persist else "VIRTUAL"
457 if self.connection.features.requires_literal_defaults:
458 expression_sql = expression_sql % tuple(self.quote_value(p) for p in params)
459 params = ()
460 return f"GENERATED ALWAYS AS ({expression_sql}) {persistency_sql}", params
461
462 @staticmethod
463 def _effective_default(field):
464 # This method allows testing its logic without a connection.
465 if field.has_default():
466 default = field.get_default()
467 elif field.generated:
468 default = None
469 elif not field.null and field.blank and field.empty_strings_allowed:
470 if field.get_internal_type() == "BinaryField":
471 default = b""
472 else:
473 default = ""
474 elif getattr(field, "auto_now", False) or getattr(field, "auto_now_add", False):
475 internal_type = field.get_internal_type()
476 if internal_type == "DateTimeField":
477 default = timezone.now()
478 else:
479 default = datetime.now()
480 if internal_type == "DateField":
481 default = default.date()
482 elif internal_type == "TimeField":
483 default = default.time()
484 else:
485 default = None
486 return default
487
488 def effective_default(self, field):
489 """Return a field's effective database default value."""
490 return field.get_db_prep_save(self._effective_default(field), self.connection)
491
492 def quote_value(self, value):
493 """
494 Return a quoted version of the value so it's safe to use in an SQL
495 string. This is not safe against injection from user code; it is
496 intended only for use in making SQL scripts or preparing default values
497 for particularly tricky backends (defaults are not user-defined, though,
498 so this is safe).
499 """
500 raise NotImplementedError()
501
502 # Actions
503
504 def create_model(self, model):
505 """
506 Create a table and any accompanying indexes or unique constraints for
507 the given `model`.
508 """
509 sql, params = self.table_sql(model)
510 # Prevent using [] as params, in the case a literal '%' is used in the
511 # definition on backends that don't support parametrized DDL.
512 self.execute(sql, params or None)
513
514 if self.connection.features.supports_comments:
515 # Add table comment.
516 if model._meta.db_table_comment:
517 self.alter_db_table_comment(model, None, model._meta.db_table_comment)
518 # Add column comments.
519 if not self.connection.features.supports_comments_inline:
520 for field in model._meta.local_fields:
521 if field.db_comment:
522 field_db_params = field.db_parameters(
523 connection=self.connection
524 )
525 field_type = field_db_params["type"]
526 self.execute(
527 *self._alter_column_comment_sql(
528 model, field, field_type, field.db_comment
529 )
530 )
531 # Add any field index (deferred as SQLite _remake_table needs it).
532 self.deferred_sql.extend(self._model_indexes_sql(model))
533
534 # Make M2M tables
535 for field in model._meta.local_many_to_many:
536 if field.remote_field.through._meta.auto_created:
537 self.create_model(field.remote_field.through)
538
539 def delete_model(self, model):
540 """Delete a model from the database."""
541 # Handle auto-created intermediary models
542 for field in model._meta.local_many_to_many:
543 if field.remote_field.through._meta.auto_created:
544 self.delete_model(field.remote_field.through)
545
546 # Delete the table
547 self.execute(
548 self.sql_delete_table
549 % {
550 "table": self.quote_name(model._meta.db_table),
551 }
552 )
553 # Remove all deferred statements referencing the deleted table.
554 for sql in list(self.deferred_sql):
555 if isinstance(sql, Statement) and sql.references_table(
556 model._meta.db_table
557 ):
558 self.deferred_sql.remove(sql)
559
560 def add_index(self, model, index):
561 """Add an index on a model."""
562 if (
563 index.contains_expressions
564 and not self.connection.features.supports_expression_indexes
565 ):
566 return None
567 # Index.create_sql returns interpolated SQL which makes params=None a
568 # necessity to avoid escaping attempts on execution.
569 self.execute(index.create_sql(model, self), params=None)
570
571 def remove_index(self, model, index):
572 """Remove an index from a model."""
573 if (
574 index.contains_expressions
575 and not self.connection.features.supports_expression_indexes
576 ):
577 return None
578 self.execute(index.remove_sql(model, self))
579
580 def rename_index(self, model, old_index, new_index):
581 if self.connection.features.can_rename_index:
582 self.execute(
583 self._rename_index_sql(model, old_index.name, new_index.name),
584 params=None,
585 )
586 else:
587 self.remove_index(model, old_index)
588 self.add_index(model, new_index)
589
590 def add_constraint(self, model, constraint):
591 """Add a constraint to a model."""
592 sql = constraint.create_sql(model, self)
593 if sql:
594 # Constraint.create_sql returns interpolated SQL which makes
595 # params=None a necessity to avoid escaping attempts on execution.
596 self.execute(sql, params=None)
597
598 def remove_constraint(self, model, constraint):
599 """Remove a constraint from a model."""
600 sql = constraint.remove_sql(model, self)
601 if sql:
602 self.execute(sql)
603
604 def alter_unique_together(self, model, old_unique_together, new_unique_together):
605 """
606 Deal with a model changing its unique_together. The input
607 unique_togethers must be doubly-nested, not the single-nested
608 ["foo", "bar"] format.
609 """
610 olds = {tuple(fields) for fields in old_unique_together}
611 news = {tuple(fields) for fields in new_unique_together}
612 # Deleted uniques
613 for fields in olds.difference(news):
614 self._delete_composed_index(
615 model,
616 fields,
617 {"unique": True, "primary_key": False},
618 self.sql_delete_unique,
619 )
620 # Created uniques
621 for field_names in news.difference(olds):
622 fields = [model._meta.get_field(field) for field in field_names]
623 self.execute(self._create_unique_sql(model, fields))
624
625 def alter_index_together(self, model, old_index_together, new_index_together):
626 """
627 Deal with a model changing its index_together. The input
628 index_togethers must be doubly-nested, not the single-nested
629 ["foo", "bar"] format.
630 """
631 olds = {tuple(fields) for fields in old_index_together}
632 news = {tuple(fields) for fields in new_index_together}
633 # Deleted indexes
634 for fields in olds.difference(news):
635 self._delete_composed_index(
636 model,
637 fields,
638 {"index": True, "unique": False},
639 self.sql_delete_index,
640 )
641 # Created indexes
642 for field_names in news.difference(olds):
643 fields = [model._meta.get_field(field) for field in field_names]
644 self.execute(self._create_index_sql(model, fields=fields, suffix="_idx"))
645
646 def _delete_composed_index(self, model, fields, constraint_kwargs, sql):
647 meta_constraint_names = {
648 constraint.name for constraint in model._meta.constraints
649 }
650 meta_index_names = {constraint.name for constraint in model._meta.indexes}
651 columns = [model._meta.get_field(field).column for field in fields]
652 constraint_names = self._constraint_names(
653 model,
654 columns,
655 exclude=meta_constraint_names | meta_index_names,
656 **constraint_kwargs,
657 )
658 if (
659 constraint_kwargs.get("unique") is True
660 and constraint_names
661 and self.connection.features.allows_multiple_constraints_on_same_fields
662 ):
663 # Constraint matching the unique_together name.
664 default_name = str(
665 self._unique_constraint_name(model._meta.db_table, columns, quote=False)
666 )
667 if default_name in constraint_names:
668 constraint_names = [default_name]
669 if len(constraint_names) != 1:
670 raise ValueError(
671 "Found wrong number (%s) of constraints for %s(%s)"
672 % (
673 len(constraint_names),
674 model._meta.db_table,
675 ", ".join(columns),
676 )
677 )
678 self.execute(self._delete_constraint_sql(sql, model, constraint_names[0]))
679
680 def alter_db_table(self, model, old_db_table, new_db_table):
681 """Rename the table a model points to."""
682 if old_db_table == new_db_table or (
683 self.connection.features.ignores_table_name_case
684 and old_db_table.lower() == new_db_table.lower()
685 ):
686 return
687 self.execute(
688 self.sql_rename_table
689 % {
690 "old_table": self.quote_name(old_db_table),
691 "new_table": self.quote_name(new_db_table),
692 }
693 )
694 # Rename all references to the old table name.
695 for sql in self.deferred_sql:
696 if isinstance(sql, Statement):
697 sql.rename_table_references(old_db_table, new_db_table)
698
699 def alter_db_table_comment(self, model, old_db_table_comment, new_db_table_comment):
700 if self.sql_alter_table_comment and self.connection.features.supports_comments:
701 self.execute(
702 self.sql_alter_table_comment
703 % {
704 "table": self.quote_name(model._meta.db_table),
705 "comment": self.quote_value(new_db_table_comment or ""),
706 }
707 )
708
709 def alter_db_tablespace(self, model, old_db_tablespace, new_db_tablespace):
710 """Move a model's table between tablespaces."""
711 self.execute(
712 self.sql_retablespace_table
713 % {
714 "table": self.quote_name(model._meta.db_table),
715 "old_tablespace": self.quote_name(old_db_tablespace),
716 "new_tablespace": self.quote_name(new_db_tablespace),
717 }
718 )
719
720 def add_field(self, model, field):
721 """
722 Create a field on a model. Usually involves adding a column, but may
723 involve adding a table instead (for M2M fields).
724 """
725 # Special-case implicit M2M tables
726 if field.many_to_many and field.remote_field.through._meta.auto_created:
727 return self.create_model(field.remote_field.through)
728 # Get the column's definition
729 definition, params = self.column_sql(model, field, include_default=True)
730 # It might not actually have a column behind it
731 if definition is None:
732 return
733 if col_type_suffix := field.db_type_suffix(connection=self.connection):
734 definition += f" {col_type_suffix}"
735 # Check constraints can go on the column SQL here
736 db_params = field.db_parameters(connection=self.connection)
737 if db_params["check"]:
738 definition += " " + self.sql_check_constraint % db_params
739 if (
740 field.remote_field
741 and self.connection.features.supports_foreign_keys
742 and field.db_constraint
743 ):
744 constraint_suffix = "_fk_%(to_table)s_%(to_column)s"
745 # Add FK constraint inline, if supported.
746 if self.sql_create_column_inline_fk:
747 to_table = field.remote_field.model._meta.db_table
748 to_column = field.remote_field.model._meta.get_field(
749 field.remote_field.field_name
750 ).column
751 namespace, _ = split_identifier(model._meta.db_table)
752 definition += " " + self.sql_create_column_inline_fk % {
753 "name": self._fk_constraint_name(model, field, constraint_suffix),
754 "namespace": (
755 "%s." % self.quote_name(namespace) if namespace else ""
756 ),
757 "column": self.quote_name(field.column),
758 "to_table": self.quote_name(to_table),
759 "to_column": self.quote_name(to_column),
760 "deferrable": self.connection.ops.deferrable_sql(),
761 }
762 # Otherwise, add FK constraints later.
763 else:
764 self.deferred_sql.append(
765 self._create_fk_sql(model, field, constraint_suffix)
766 )
767 # Build the SQL and run it
768 sql = self.sql_create_column % {
769 "table": self.quote_name(model._meta.db_table),
770 "column": self.quote_name(field.column),
771 "definition": definition,
772 }
773 # Prevent using [] as params, in the case a literal '%' is used in the
774 # definition on backends that don't support parametrized DDL.
775 self.execute(sql, params or None)
776 # Drop the default if we need to
777 if (
778 not field.has_db_default()
779 and not self.skip_default_on_alter(field)
780 and self.effective_default(field) is not None
781 ):
782 changes_sql, params = self._alter_column_default_sql(
783 model, None, field, drop=True
784 )
785 sql = self.sql_alter_column % {
786 "table": self.quote_name(model._meta.db_table),
787 "changes": changes_sql,
788 }
789 self.execute(sql, params)
790 # Add field comment, if required.
791 if (
792 field.db_comment
793 and self.connection.features.supports_comments
794 and not self.connection.features.supports_comments_inline
795 ):
796 field_type = db_params["type"]
797 self.execute(
798 *self._alter_column_comment_sql(
799 model, field, field_type, field.db_comment
800 )
801 )
802 # Add an index, if required
803 self.deferred_sql.extend(self._field_indexes_sql(model, field))
804 # Reset connection if required
805 if self.connection.features.connection_persists_old_columns:
806 self.connection.close()
807
808 def remove_field(self, model, field):
809 """
810 Remove a field from a model. Usually involves deleting a column,
811 but for M2Ms may involve deleting a table.
812 """
813 # Special-case implicit M2M tables
814 if field.many_to_many and field.remote_field.through._meta.auto_created:
815 return self.delete_model(field.remote_field.through)
816 # It might not actually have a column behind it
817 if field.db_parameters(connection=self.connection)["type"] is None:
818 return
819 # Drop any FK constraints, MySQL requires explicit deletion
820 if field.remote_field:
821 fk_names = self._constraint_names(model, [field.column], foreign_key=True)
822 for fk_name in fk_names:
823 self.execute(self._delete_fk_sql(model, fk_name))
824 # Delete the column
825 sql = self.sql_delete_column % {
826 "table": self.quote_name(model._meta.db_table),
827 "column": self.quote_name(field.column),
828 }
829 self.execute(sql)
830 # Reset connection if required
831 if self.connection.features.connection_persists_old_columns:
832 self.connection.close()
833 # Remove all deferred statements referencing the deleted column.
834 for sql in list(self.deferred_sql):
835 if isinstance(sql, Statement) and sql.references_column(
836 model._meta.db_table, field.column
837 ):
838 self.deferred_sql.remove(sql)
839
840 def alter_field(self, model, old_field, new_field, strict=False):
841 """
842 Allow a field's type, uniqueness, nullability, default, column,
843 constraints, etc. to be modified.
844 `old_field` is required to compute the necessary changes.
845 If `strict` is True, raise errors if the old column does not match
846 `old_field` precisely.
847 """
848 if not self._field_should_be_altered(old_field, new_field):
849 return
850 # Ensure this field is even column-based
851 old_db_params = old_field.db_parameters(connection=self.connection)
852 old_type = old_db_params["type"]
853 new_db_params = new_field.db_parameters(connection=self.connection)
854 new_type = new_db_params["type"]
855 modifying_generated_field = False
856 if (old_type is None and old_field.remote_field is None) or (
857 new_type is None and new_field.remote_field is None
858 ):
859 raise ValueError(
860 "Cannot alter field %s into %s - they do not properly define "
861 "db_type (are you using a badly-written custom field?)"
862 % (old_field, new_field),
863 )
864 elif (
865 old_type is None
866 and new_type is None
867 and (
868 old_field.remote_field.through
869 and new_field.remote_field.through
870 and old_field.remote_field.through._meta.auto_created
871 and new_field.remote_field.through._meta.auto_created
872 )
873 ):
874 return self._alter_many_to_many(model, old_field, new_field, strict)
875 elif (
876 old_type is None
877 and new_type is None
878 and (
879 old_field.remote_field.through
880 and new_field.remote_field.through
881 and not old_field.remote_field.through._meta.auto_created
882 and not new_field.remote_field.through._meta.auto_created
883 )
884 ):
885 # Both sides have through models; this is a no-op.
886 return
887 elif old_type is None or new_type is None:
888 raise ValueError(
889 "Cannot alter field %s into %s - they are not compatible types "
890 "(you cannot alter to or from M2M fields, or add or remove "
891 "through= on M2M fields)" % (old_field, new_field)
892 )
893 elif old_field.generated != new_field.generated or (
894 new_field.generated and old_field.db_persist != new_field.db_persist
895 ):
896 modifying_generated_field = True
897 elif new_field.generated:
898 try:
899 old_field_sql = old_field.generated_sql(self.connection)
900 except FieldError:
901 # Field used in a generated field was renamed.
902 modifying_generated_field = True
903 else:
904 new_field_sql = new_field.generated_sql(self.connection)
905 modifying_generated_field = old_field_sql != new_field_sql
906 if modifying_generated_field:
907 raise ValueError(
908 f"Modifying GeneratedFields is not supported - the field {new_field} "
909 "must be removed and re-added with the new definition."
910 )
911
912 self._alter_field(
913 model,
914 old_field,
915 new_field,
916 old_type,
917 new_type,
918 old_db_params,
919 new_db_params,
920 strict,
921 )
922
923 def _field_db_check(self, field, field_db_params):
924 # Always check constraints with the same mocked column name to avoid
925 # recreating constrains when the column is renamed.
926 check_constraints = self.connection.data_type_check_constraints
927 data = field.db_type_parameters(self.connection)
928 data["column"] = "__column_name__"
929 try:
930 return check_constraints[field.get_internal_type()] % data
931 except KeyError:
932 return None
933
934 def _alter_field(
935 self,
936 model,
937 old_field,
938 new_field,
939 old_type,
940 new_type,
941 old_db_params,
942 new_db_params,
943 strict=False,
944 ):
945 """Perform a "physical" (non-ManyToMany) field update."""
946 # Drop any FK constraints, we'll remake them later
947 fks_dropped = set()
948 if (
949 self.connection.features.supports_foreign_keys
950 and old_field.remote_field
951 and old_field.db_constraint
952 and self._field_should_be_altered(
953 old_field,
954 new_field,
955 ignore={"db_comment"},
956 )
957 ):
958 fk_names = self._constraint_names(
959 model, [old_field.column], foreign_key=True
960 )
961 if strict and len(fk_names) != 1:
962 raise ValueError(
963 "Found wrong number (%s) of foreign key constraints for %s.%s"
964 % (
965 len(fk_names),
966 model._meta.db_table,
967 old_field.column,
968 )
969 )
970 for fk_name in fk_names:
971 fks_dropped.add((old_field.column,))
972 self.execute(self._delete_fk_sql(model, fk_name))
973 # Has unique been removed?
974 if old_field.unique and (
975 not new_field.unique or self._field_became_primary_key(old_field, new_field)
976 ):
977 # Find the unique constraint for this field
978 meta_constraint_names = {
979 constraint.name for constraint in model._meta.constraints
980 }
981 constraint_names = self._constraint_names(
982 model,
983 [old_field.column],
984 unique=True,
985 primary_key=False,
986 exclude=meta_constraint_names,
987 )
988 if strict and len(constraint_names) != 1:
989 raise ValueError(
990 "Found wrong number (%s) of unique constraints for %s.%s"
991 % (
992 len(constraint_names),
993 model._meta.db_table,
994 old_field.column,
995 )
996 )
997 for constraint_name in constraint_names:
998 self.execute(self._delete_unique_sql(model, constraint_name))
999 # Drop incoming FK constraints if the field is a primary key or unique,
1000 # which might be a to_field target, and things are going to change.
1001 old_collation = old_db_params.get("collation")
1002 new_collation = new_db_params.get("collation")
1003 drop_foreign_keys = (
1004 self.connection.features.supports_foreign_keys
1005 and (
1006 (old_field.primary_key and new_field.primary_key)
1007 or (old_field.unique and new_field.unique)
1008 )
1009 and ((old_type != new_type) or (old_collation != new_collation))
1010 )
1011 if drop_foreign_keys:
1012 # '_meta.related_field' also contains M2M reverse fields, these
1013 # will be filtered out
1014 for _old_rel, new_rel in _related_non_m2m_objects(old_field, new_field):
1015 rel_fk_names = self._constraint_names(
1016 new_rel.related_model, [new_rel.field.column], foreign_key=True
1017 )
1018 for fk_name in rel_fk_names:
1019 self.execute(self._delete_fk_sql(new_rel.related_model, fk_name))
1020 # Removed an index? (no strict check, as multiple indexes are possible)
1021 # Remove indexes if db_index switched to False or a unique constraint
1022 # will now be used in lieu of an index. The following lines from the
1023 # truth table show all True cases; the rest are False:
1024 #
1025 # old_field.db_index | old_field.unique | new_field.db_index | new_field.unique
1026 # ------------------------------------------------------------------------------
1027 # True | False | False | False
1028 # True | False | False | True
1029 # True | False | True | True
1030 if (
1031 old_field.db_index
1032 and not old_field.unique
1033 and (not new_field.db_index or new_field.unique)
1034 ):
1035 # Find the index for this field
1036 meta_index_names = {index.name for index in model._meta.indexes}
1037 # Retrieve only BTREE indexes since this is what's created with
1038 # db_index=True.
1039 index_names = self._constraint_names(
1040 model,
1041 [old_field.column],
1042 index=True,
1043 type_=Index.suffix,
1044 exclude=meta_index_names,
1045 )
1046 for index_name in index_names:
1047 # The only way to check if an index was created with
1048 # db_index=True or with Index(['field'], name='foo')
1049 # is to look at its name (refs #28053).
1050 self.execute(self._delete_index_sql(model, index_name))
1051 # Change check constraints?
1052 old_db_check = self._field_db_check(old_field, old_db_params)
1053 new_db_check = self._field_db_check(new_field, new_db_params)
1054 if old_db_check != new_db_check and old_db_check:
1055 meta_constraint_names = {
1056 constraint.name for constraint in model._meta.constraints
1057 }
1058 constraint_names = self._constraint_names(
1059 model,
1060 [old_field.column],
1061 check=True,
1062 exclude=meta_constraint_names,
1063 )
1064 if strict and len(constraint_names) != 1:
1065 raise ValueError(
1066 "Found wrong number (%s) of check constraints for %s.%s"
1067 % (
1068 len(constraint_names),
1069 model._meta.db_table,
1070 old_field.column,
1071 )
1072 )
1073 for constraint_name in constraint_names:
1074 self.execute(self._delete_check_sql(model, constraint_name))
1075 # Have they renamed the column?
1076 if old_field.column != new_field.column:
1077 self.execute(
1078 self._rename_field_sql(
1079 model._meta.db_table, old_field, new_field, new_type
1080 )
1081 )
1082 # Rename all references to the renamed column.
1083 for sql in self.deferred_sql:
1084 if isinstance(sql, Statement):
1085 sql.rename_column_references(
1086 model._meta.db_table, old_field.column, new_field.column
1087 )
1088 # Next, start accumulating actions to do
1089 actions = []
1090 null_actions = []
1091 post_actions = []
1092 # Type suffix change? (e.g. auto increment).
1093 old_type_suffix = old_field.db_type_suffix(connection=self.connection)
1094 new_type_suffix = new_field.db_type_suffix(connection=self.connection)
1095 # Type, collation, or comment change?
1096 if (
1097 old_type != new_type
1098 or old_type_suffix != new_type_suffix
1099 or old_collation != new_collation
1100 or (
1101 self.connection.features.supports_comments
1102 and old_field.db_comment != new_field.db_comment
1103 )
1104 ):
1105 fragment, other_actions = self._alter_column_type_sql(
1106 model, old_field, new_field, new_type, old_collation, new_collation
1107 )
1108 actions.append(fragment)
1109 post_actions.extend(other_actions)
1110
1111 if new_field.has_db_default():
1112 if (
1113 not old_field.has_db_default()
1114 or new_field.db_default != old_field.db_default
1115 ):
1116 actions.append(
1117 self._alter_column_database_default_sql(model, old_field, new_field)
1118 )
1119 elif old_field.has_db_default():
1120 actions.append(
1121 self._alter_column_database_default_sql(
1122 model, old_field, new_field, drop=True
1123 )
1124 )
1125 # When changing a column NULL constraint to NOT NULL with a given
1126 # default value, we need to perform 4 steps:
1127 # 1. Add a default for new incoming writes
1128 # 2. Update existing NULL rows with new default
1129 # 3. Replace NULL constraint with NOT NULL
1130 # 4. Drop the default again.
1131 # Default change?
1132 needs_database_default = False
1133 if old_field.null and not new_field.null and not new_field.has_db_default():
1134 old_default = self.effective_default(old_field)
1135 new_default = self.effective_default(new_field)
1136 if (
1137 not self.skip_default_on_alter(new_field)
1138 and old_default != new_default
1139 and new_default is not None
1140 ):
1141 needs_database_default = True
1142 actions.append(
1143 self._alter_column_default_sql(model, old_field, new_field)
1144 )
1145 # Nullability change?
1146 if old_field.null != new_field.null:
1147 fragment = self._alter_column_null_sql(model, old_field, new_field)
1148 if fragment:
1149 null_actions.append(fragment)
1150 # Only if we have a default and there is a change from NULL to NOT NULL
1151 four_way_default_alteration = (
1152 new_field.has_default() or new_field.has_db_default()
1153 ) and (old_field.null and not new_field.null)
1154 if actions or null_actions:
1155 if not four_way_default_alteration:
1156 # If we don't have to do a 4-way default alteration we can
1157 # directly run a (NOT) NULL alteration
1158 actions += null_actions
1159 # Combine actions together if we can (e.g. postgres)
1160 if self.connection.features.supports_combined_alters and actions:
1161 sql, params = tuple(zip(*actions))
1162 actions = [(", ".join(sql), sum(params, []))]
1163 # Apply those actions
1164 for sql, params in actions:
1165 self.execute(
1166 self.sql_alter_column
1167 % {
1168 "table": self.quote_name(model._meta.db_table),
1169 "changes": sql,
1170 },
1171 params,
1172 )
1173 if four_way_default_alteration:
1174 if not new_field.has_db_default():
1175 default_sql = "%s"
1176 params = [new_default]
1177 else:
1178 default_sql, params = self.db_default_sql(new_field)
1179 # Update existing rows with default value
1180 self.execute(
1181 self.sql_update_with_default
1182 % {
1183 "table": self.quote_name(model._meta.db_table),
1184 "column": self.quote_name(new_field.column),
1185 "default": default_sql,
1186 },
1187 params,
1188 )
1189 # Since we didn't run a NOT NULL change before we need to do it
1190 # now
1191 for sql, params in null_actions:
1192 self.execute(
1193 self.sql_alter_column
1194 % {
1195 "table": self.quote_name(model._meta.db_table),
1196 "changes": sql,
1197 },
1198 params,
1199 )
1200 if post_actions:
1201 for sql, params in post_actions:
1202 self.execute(sql, params)
1203 # If primary_key changed to False, delete the primary key constraint.
1204 if old_field.primary_key and not new_field.primary_key:
1205 self._delete_primary_key(model, strict)
1206 # Added a unique?
1207 if self._unique_should_be_added(old_field, new_field):
1208 self.execute(self._create_unique_sql(model, [new_field]))
1209 # Added an index? Add an index if db_index switched to True or a unique
1210 # constraint will no longer be used in lieu of an index. The following
1211 # lines from the truth table show all True cases; the rest are False:
1212 #
1213 # old_field.db_index | old_field.unique | new_field.db_index | new_field.unique
1214 # ------------------------------------------------------------------------------
1215 # False | False | True | False
1216 # False | True | True | False
1217 # True | True | True | False
1218 if (
1219 (not old_field.db_index or old_field.unique)
1220 and new_field.db_index
1221 and not new_field.unique
1222 ):
1223 self.execute(self._create_index_sql(model, fields=[new_field]))
1224 # Type alteration on primary key? Then we need to alter the column
1225 # referring to us.
1226 rels_to_update = []
1227 if drop_foreign_keys:
1228 rels_to_update.extend(_related_non_m2m_objects(old_field, new_field))
1229 # Changed to become primary key?
1230 if self._field_became_primary_key(old_field, new_field):
1231 # Make the new one
1232 self.execute(self._create_primary_key_sql(model, new_field))
1233 # Update all referencing columns
1234 rels_to_update.extend(_related_non_m2m_objects(old_field, new_field))
1235 # Handle our type alters on the other end of rels from the PK stuff above
1236 for old_rel, new_rel in rels_to_update:
1237 rel_db_params = new_rel.field.db_parameters(connection=self.connection)
1238 rel_type = rel_db_params["type"]
1239 rel_collation = rel_db_params.get("collation")
1240 old_rel_db_params = old_rel.field.db_parameters(connection=self.connection)
1241 old_rel_collation = old_rel_db_params.get("collation")
1242 fragment, other_actions = self._alter_column_type_sql(
1243 new_rel.related_model,
1244 old_rel.field,
1245 new_rel.field,
1246 rel_type,
1247 old_rel_collation,
1248 rel_collation,
1249 )
1250 self.execute(
1251 self.sql_alter_column
1252 % {
1253 "table": self.quote_name(new_rel.related_model._meta.db_table),
1254 "changes": fragment[0],
1255 },
1256 fragment[1],
1257 )
1258 for sql, params in other_actions:
1259 self.execute(sql, params)
1260 # Does it have a foreign key?
1261 if (
1262 self.connection.features.supports_foreign_keys
1263 and new_field.remote_field
1264 and (
1265 fks_dropped or not old_field.remote_field or not old_field.db_constraint
1266 )
1267 and new_field.db_constraint
1268 ):
1269 self.execute(
1270 self._create_fk_sql(model, new_field, "_fk_%(to_table)s_%(to_column)s")
1271 )
1272 # Rebuild FKs that pointed to us if we previously had to drop them
1273 if drop_foreign_keys:
1274 for _, rel in rels_to_update:
1275 if rel.field.db_constraint:
1276 self.execute(
1277 self._create_fk_sql(rel.related_model, rel.field, "_fk")
1278 )
1279 # Does it have check constraints we need to add?
1280 if old_db_check != new_db_check and new_db_check:
1281 constraint_name = self._create_index_name(
1282 model._meta.db_table, [new_field.column], suffix="_check"
1283 )
1284 self.execute(
1285 self._create_check_sql(model, constraint_name, new_db_params["check"])
1286 )
1287 # Drop the default if we need to
1288 # (Django usually does not use in-database defaults)
1289 if needs_database_default:
1290 changes_sql, params = self._alter_column_default_sql(
1291 model, old_field, new_field, drop=True
1292 )
1293 sql = self.sql_alter_column % {
1294 "table": self.quote_name(model._meta.db_table),
1295 "changes": changes_sql,
1296 }
1297 self.execute(sql, params)
1298 # Reset connection if required
1299 if self.connection.features.connection_persists_old_columns:
1300 self.connection.close()
1301
1302 def _alter_column_null_sql(self, model, old_field, new_field):
1303 """
1304 Hook to specialize column null alteration.
1305
1306 Return a (sql, params) fragment to set a column to null or non-null
1307 as required by new_field, or None if no changes are required.
1308 """
1309 if (
1310 self.connection.features.interprets_empty_strings_as_nulls
1311 and new_field.empty_strings_allowed
1312 ):
1313 # The field is nullable in the database anyway, leave it alone.
1314 return
1315 else:
1316 new_db_params = new_field.db_parameters(connection=self.connection)
1317 sql = (
1318 self.sql_alter_column_null
1319 if new_field.null
1320 else self.sql_alter_column_not_null
1321 )
1322 return (
1323 sql
1324 % {
1325 "column": self.quote_name(new_field.column),
1326 "type": new_db_params["type"],
1327 },
1328 [],
1329 )
1330
1331 def _alter_column_default_sql(self, model, old_field, new_field, drop=False):
1332 """
1333 Hook to specialize column default alteration.
1334
1335 Return a (sql, params) fragment to add or drop (depending on the drop
1336 argument) a default to new_field's column.
1337 """
1338 new_default = self.effective_default(new_field)
1339 default = self._column_default_sql(new_field)
1340 params = [new_default]
1341
1342 if drop:
1343 params = []
1344 elif self.connection.features.requires_literal_defaults:
1345 # Some databases (Oracle) can't take defaults as a parameter
1346 # If this is the case, the SchemaEditor for that database should
1347 # implement prepare_default().
1348 default = self.prepare_default(new_default)
1349 params = []
1350
1351 new_db_params = new_field.db_parameters(connection=self.connection)
1352 if drop:
1353 if new_field.null:
1354 sql = self.sql_alter_column_no_default_null
1355 else:
1356 sql = self.sql_alter_column_no_default
1357 else:
1358 sql = self.sql_alter_column_default
1359 return (
1360 sql
1361 % {
1362 "column": self.quote_name(new_field.column),
1363 "type": new_db_params["type"],
1364 "default": default,
1365 },
1366 params,
1367 )
1368
1369 def _alter_column_database_default_sql(
1370 self, model, old_field, new_field, drop=False
1371 ):
1372 """
1373 Hook to specialize column database default alteration.
1374
1375 Return a (sql, params) fragment to add or drop (depending on the drop
1376 argument) a default to new_field's column.
1377 """
1378 if drop:
1379 sql = self.sql_alter_column_no_default
1380 default_sql = ""
1381 params = []
1382 else:
1383 sql = self.sql_alter_column_default
1384 default_sql, params = self.db_default_sql(new_field)
1385
1386 new_db_params = new_field.db_parameters(connection=self.connection)
1387 return (
1388 sql
1389 % {
1390 "column": self.quote_name(new_field.column),
1391 "type": new_db_params["type"],
1392 "default": default_sql,
1393 },
1394 params,
1395 )
1396
1397 def _alter_column_type_sql(
1398 self, model, old_field, new_field, new_type, old_collation, new_collation
1399 ):
1400 """
1401 Hook to specialize column type alteration for different backends,
1402 for cases when a creation type is different to an alteration type
1403 (e.g. SERIAL in PostgreSQL, PostGIS fields).
1404
1405 Return a 2-tuple of: an SQL fragment of (sql, params) to insert into
1406 an ALTER TABLE statement and a list of extra (sql, params) tuples to
1407 run once the field is altered.
1408 """
1409 other_actions = []
1410 if collate_sql := self._collate_sql(
1411 new_collation, old_collation, model._meta.db_table
1412 ):
1413 collate_sql = f" {collate_sql}"
1414 else:
1415 collate_sql = ""
1416 # Comment change?
1417 comment_sql = ""
1418 if self.connection.features.supports_comments and not new_field.many_to_many:
1419 if old_field.db_comment != new_field.db_comment:
1420 # PostgreSQL and Oracle can't execute 'ALTER COLUMN ...' and
1421 # 'COMMENT ON ...' at the same time.
1422 sql, params = self._alter_column_comment_sql(
1423 model, new_field, new_type, new_field.db_comment
1424 )
1425 if sql:
1426 other_actions.append((sql, params))
1427 if new_field.db_comment:
1428 comment_sql = self._comment_sql(new_field.db_comment)
1429 return (
1430 (
1431 self.sql_alter_column_type
1432 % {
1433 "column": self.quote_name(new_field.column),
1434 "type": new_type,
1435 "collation": collate_sql,
1436 "comment": comment_sql,
1437 },
1438 [],
1439 ),
1440 other_actions,
1441 )
1442
1443 def _alter_column_comment_sql(self, model, new_field, new_type, new_db_comment):
1444 return (
1445 self.sql_alter_column_comment
1446 % {
1447 "table": self.quote_name(model._meta.db_table),
1448 "column": self.quote_name(new_field.column),
1449 "comment": self._comment_sql(new_db_comment),
1450 },
1451 [],
1452 )
1453
1454 def _comment_sql(self, comment):
1455 return self.quote_value(comment or "")
1456
1457 def _alter_many_to_many(self, model, old_field, new_field, strict):
1458 """Alter M2Ms to repoint their to= endpoints."""
1459 # Rename the through table
1460 if (
1461 old_field.remote_field.through._meta.db_table
1462 != new_field.remote_field.through._meta.db_table
1463 ):
1464 self.alter_db_table(
1465 old_field.remote_field.through,
1466 old_field.remote_field.through._meta.db_table,
1467 new_field.remote_field.through._meta.db_table,
1468 )
1469 # Repoint the FK to the other side
1470 self.alter_field(
1471 new_field.remote_field.through,
1472 # The field that points to the target model is needed, so we can
1473 # tell alter_field to change it - this is m2m_reverse_field_name()
1474 # (as opposed to m2m_field_name(), which points to our model).
1475 old_field.remote_field.through._meta.get_field(
1476 old_field.m2m_reverse_field_name()
1477 ),
1478 new_field.remote_field.through._meta.get_field(
1479 new_field.m2m_reverse_field_name()
1480 ),
1481 )
1482 self.alter_field(
1483 new_field.remote_field.through,
1484 # for self-referential models we need to alter field from the other end too
1485 old_field.remote_field.through._meta.get_field(old_field.m2m_field_name()),
1486 new_field.remote_field.through._meta.get_field(new_field.m2m_field_name()),
1487 )
1488
1489 def _create_index_name(self, table_name, column_names, suffix=""):
1490 """
1491 Generate a unique name for an index/unique constraint.
1492
1493 The name is divided into 3 parts: the table name, the column names,
1494 and a unique digest and suffix.
1495 """
1496 _, table_name = split_identifier(table_name)
1497 hash_suffix_part = "%s%s" % (
1498 names_digest(table_name, *column_names, length=8),
1499 suffix,
1500 )
1501 max_length = self.connection.ops.max_name_length() or 200
1502 # If everything fits into max_length, use that name.
1503 index_name = "%s_%s_%s" % (table_name, "_".join(column_names), hash_suffix_part)
1504 if len(index_name) <= max_length:
1505 return index_name
1506 # Shorten a long suffix.
1507 if len(hash_suffix_part) > max_length / 3:
1508 hash_suffix_part = hash_suffix_part[: max_length // 3]
1509 other_length = (max_length - len(hash_suffix_part)) // 2 - 1
1510 index_name = "%s_%s_%s" % (
1511 table_name[:other_length],
1512 "_".join(column_names)[:other_length],
1513 hash_suffix_part,
1514 )
1515 # Prepend D if needed to prevent the name from starting with an
1516 # underscore or a number (not permitted on Oracle).
1517 if index_name[0] == "_" or index_name[0].isdigit():
1518 index_name = "D%s" % index_name[:-1]
1519 return index_name
1520
1521 def _get_index_tablespace_sql(self, model, fields, db_tablespace=None):
1522 if db_tablespace is None:
1523 if len(fields) == 1 and fields[0].db_tablespace:
1524 db_tablespace = fields[0].db_tablespace
1525 elif settings.DEFAULT_INDEX_TABLESPACE:
1526 db_tablespace = settings.DEFAULT_INDEX_TABLESPACE
1527 elif model._meta.db_tablespace:
1528 db_tablespace = model._meta.db_tablespace
1529 if db_tablespace is not None:
1530 return " " + self.connection.ops.tablespace_sql(db_tablespace)
1531 return ""
1532
1533 def _index_condition_sql(self, condition):
1534 if condition:
1535 return " WHERE " + condition
1536 return ""
1537
1538 def _index_include_sql(self, model, columns):
1539 if not columns or not self.connection.features.supports_covering_indexes:
1540 return ""
1541 return Statement(
1542 " INCLUDE (%(columns)s)",
1543 columns=Columns(model._meta.db_table, columns, self.quote_name),
1544 )
1545
1546 def _create_index_sql(
1547 self,
1548 model,
1549 *,
1550 fields=None,
1551 name=None,
1552 suffix="",
1553 using="",
1554 db_tablespace=None,
1555 col_suffixes=(),
1556 sql=None,
1557 opclasses=(),
1558 condition=None,
1559 include=None,
1560 expressions=None,
1561 ):
1562 """
1563 Return the SQL statement to create the index for one or several fields
1564 or expressions. `sql` can be specified if the syntax differs from the
1565 standard (GIS indexes, ...).
1566 """
1567 fields = fields or []
1568 expressions = expressions or []
1569 compiler = Query(model, alias_cols=False).get_compiler(
1570 connection=self.connection,
1571 )
1572 tablespace_sql = self._get_index_tablespace_sql(
1573 model, fields, db_tablespace=db_tablespace
1574 )
1575 columns = [field.column for field in fields]
1576 sql_create_index = sql or self.sql_create_index
1577 table = model._meta.db_table
1578
1579 def create_index_name(*args, **kwargs):
1580 nonlocal name
1581 if name is None:
1582 name = self._create_index_name(*args, **kwargs)
1583 return self.quote_name(name)
1584
1585 return Statement(
1586 sql_create_index,
1587 table=Table(table, self.quote_name),
1588 name=IndexName(table, columns, suffix, create_index_name),
1589 using=using,
1590 columns=(
1591 self._index_columns(table, columns, col_suffixes, opclasses)
1592 if columns
1593 else Expressions(table, expressions, compiler, self.quote_value)
1594 ),
1595 extra=tablespace_sql,
1596 condition=self._index_condition_sql(condition),
1597 include=self._index_include_sql(model, include),
1598 )
1599
1600 def _delete_index_sql(self, model, name, sql=None):
1601 statement = Statement(
1602 sql or self.sql_delete_index,
1603 table=Table(model._meta.db_table, self.quote_name),
1604 name=self.quote_name(name),
1605 )
1606
1607 # Remove all deferred statements referencing the deleted index.
1608 table_name = statement.parts["table"].table
1609 index_name = statement.parts["name"]
1610 for sql in list(self.deferred_sql):
1611 if isinstance(sql, Statement) and sql.references_index(
1612 table_name, index_name
1613 ):
1614 self.deferred_sql.remove(sql)
1615
1616 return statement
1617
1618 def _rename_index_sql(self, model, old_name, new_name):
1619 return Statement(
1620 self.sql_rename_index,
1621 table=Table(model._meta.db_table, self.quote_name),
1622 old_name=self.quote_name(old_name),
1623 new_name=self.quote_name(new_name),
1624 )
1625
1626 def _index_columns(self, table, columns, col_suffixes, opclasses):
1627 return Columns(table, columns, self.quote_name, col_suffixes=col_suffixes)
1628
1629 def _model_indexes_sql(self, model):
1630 """
1631 Return a list of all index SQL statements (field indexes, Meta.indexes)
1632 for the specified model.
1633 """
1634 if not model._meta.managed or model._meta.proxy or model._meta.swapped:
1635 return []
1636 output = []
1637 for field in model._meta.local_fields:
1638 output.extend(self._field_indexes_sql(model, field))
1639
1640 for index in model._meta.indexes:
1641 if (
1642 not index.contains_expressions
1643 or self.connection.features.supports_expression_indexes
1644 ):
1645 output.append(index.create_sql(model, self))
1646 return output
1647
1648 def _field_indexes_sql(self, model, field):
1649 """
1650 Return a list of all index SQL statements for the specified field.
1651 """
1652 output = []
1653 if self._field_should_be_indexed(model, field):
1654 output.append(self._create_index_sql(model, fields=[field]))
1655 return output
1656
1657 def _field_should_be_altered(self, old_field, new_field, ignore=None):
1658 if not old_field.concrete and not new_field.concrete:
1659 return False
1660 ignore = ignore or set()
1661 _, old_path, old_args, old_kwargs = old_field.deconstruct()
1662 _, new_path, new_args, new_kwargs = new_field.deconstruct()
1663 # Don't alter when:
1664 # - changing only a field name
1665 # - changing an attribute that doesn't affect the schema
1666 # - changing an attribute in the provided set of ignored attributes
1667 # - adding only a db_column and the column name is not changed
1668 # - db_table does not change for model referenced by foreign keys
1669 for attr in ignore.union(old_field.non_db_attrs):
1670 old_kwargs.pop(attr, None)
1671 for attr in ignore.union(new_field.non_db_attrs):
1672 new_kwargs.pop(attr, None)
1673 if (
1674 not new_field.many_to_many
1675 and old_field.remote_field
1676 and new_field.remote_field
1677 and old_field.remote_field.model._meta.db_table
1678 == new_field.remote_field.model._meta.db_table
1679 ):
1680 old_kwargs.pop("to", None)
1681 new_kwargs.pop("to", None)
1682 # db_default can take many form but result in the same SQL.
1683 if (
1684 old_kwargs.get("db_default")
1685 and new_kwargs.get("db_default")
1686 and self.db_default_sql(old_field) == self.db_default_sql(new_field)
1687 ):
1688 old_kwargs.pop("db_default")
1689 new_kwargs.pop("db_default")
1690 return self.quote_name(old_field.column) != self.quote_name(
1691 new_field.column
1692 ) or (old_path, old_args, old_kwargs) != (new_path, new_args, new_kwargs)
1693
1694 def _field_should_be_indexed(self, model, field):
1695 return field.db_index and not field.unique
1696
1697 def _field_became_primary_key(self, old_field, new_field):
1698 return not old_field.primary_key and new_field.primary_key
1699
1700 def _unique_should_be_added(self, old_field, new_field):
1701 return (
1702 not new_field.primary_key
1703 and new_field.unique
1704 and (not old_field.unique or old_field.primary_key)
1705 )
1706
1707 def _rename_field_sql(self, table, old_field, new_field, new_type):
1708 return self.sql_rename_column % {
1709 "table": self.quote_name(table),
1710 "old_column": self.quote_name(old_field.column),
1711 "new_column": self.quote_name(new_field.column),
1712 "type": new_type,
1713 }
1714
1715 def _create_fk_sql(self, model, field, suffix):
1716 table = Table(model._meta.db_table, self.quote_name)
1717 name = self._fk_constraint_name(model, field, suffix)
1718 column = Columns(model._meta.db_table, [field.column], self.quote_name)
1719 to_table = Table(field.target_field.model._meta.db_table, self.quote_name)
1720 to_column = Columns(
1721 field.target_field.model._meta.db_table,
1722 [field.target_field.column],
1723 self.quote_name,
1724 )
1725 deferrable = self.connection.ops.deferrable_sql()
1726 return Statement(
1727 self.sql_create_fk,
1728 table=table,
1729 name=name,
1730 column=column,
1731 to_table=to_table,
1732 to_column=to_column,
1733 deferrable=deferrable,
1734 )
1735
1736 def _fk_constraint_name(self, model, field, suffix):
1737 def create_fk_name(*args, **kwargs):
1738 return self.quote_name(self._create_index_name(*args, **kwargs))
1739
1740 return ForeignKeyName(
1741 model._meta.db_table,
1742 [field.column],
1743 split_identifier(field.target_field.model._meta.db_table)[1],
1744 [field.target_field.column],
1745 suffix,
1746 create_fk_name,
1747 )
1748
1749 def _delete_fk_sql(self, model, name):
1750 return self._delete_constraint_sql(self.sql_delete_fk, model, name)
1751
1752 def _deferrable_constraint_sql(self, deferrable):
1753 if deferrable is None:
1754 return ""
1755 if deferrable == Deferrable.DEFERRED:
1756 return " DEFERRABLE INITIALLY DEFERRED"
1757 if deferrable == Deferrable.IMMEDIATE:
1758 return " DEFERRABLE INITIALLY IMMEDIATE"
1759
1760 def _unique_index_nulls_distinct_sql(self, nulls_distinct):
1761 if nulls_distinct is False:
1762 return " NULLS NOT DISTINCT"
1763 elif nulls_distinct is True:
1764 return " NULLS DISTINCT"
1765 return ""
1766
1767 def _unique_supported(
1768 self,
1769 condition=None,
1770 deferrable=None,
1771 include=None,
1772 expressions=None,
1773 nulls_distinct=None,
1774 ):
1775 return (
1776 (not condition or self.connection.features.supports_partial_indexes)
1777 and (
1778 not deferrable
1779 or self.connection.features.supports_deferrable_unique_constraints
1780 )
1781 and (not include or self.connection.features.supports_covering_indexes)
1782 and (
1783 not expressions or self.connection.features.supports_expression_indexes
1784 )
1785 and (
1786 nulls_distinct is None
1787 or self.connection.features.supports_nulls_distinct_unique_constraints
1788 )
1789 )
1790
1791 def _unique_sql(
1792 self,
1793 model,
1794 fields,
1795 name,
1796 condition=None,
1797 deferrable=None,
1798 include=None,
1799 opclasses=None,
1800 expressions=None,
1801 nulls_distinct=None,
1802 ):
1803 if not self._unique_supported(
1804 condition=condition,
1805 deferrable=deferrable,
1806 include=include,
1807 expressions=expressions,
1808 nulls_distinct=nulls_distinct,
1809 ):
1810 return None
1811
1812 if (
1813 condition
1814 or include
1815 or opclasses
1816 or expressions
1817 or nulls_distinct is not None
1818 ):
1819 # Databases support conditional, covering, functional unique,
1820 # and nulls distinct constraints via a unique index.
1821 sql = self._create_unique_sql(
1822 model,
1823 fields,
1824 name=name,
1825 condition=condition,
1826 include=include,
1827 opclasses=opclasses,
1828 expressions=expressions,
1829 nulls_distinct=nulls_distinct,
1830 )
1831 if sql:
1832 self.deferred_sql.append(sql)
1833 return None
1834 constraint = self.sql_unique_constraint % {
1835 "columns": ", ".join([self.quote_name(field.column) for field in fields]),
1836 "deferrable": self._deferrable_constraint_sql(deferrable),
1837 }
1838 return self.sql_constraint % {
1839 "name": self.quote_name(name),
1840 "constraint": constraint,
1841 }
1842
1843 def _create_unique_sql(
1844 self,
1845 model,
1846 fields,
1847 name=None,
1848 condition=None,
1849 deferrable=None,
1850 include=None,
1851 opclasses=None,
1852 expressions=None,
1853 nulls_distinct=None,
1854 ):
1855 if not self._unique_supported(
1856 condition=condition,
1857 deferrable=deferrable,
1858 include=include,
1859 expressions=expressions,
1860 nulls_distinct=nulls_distinct,
1861 ):
1862 return None
1863
1864 compiler = Query(model, alias_cols=False).get_compiler(
1865 connection=self.connection
1866 )
1867 table = model._meta.db_table
1868 columns = [field.column for field in fields]
1869 if name is None:
1870 name = self._unique_constraint_name(table, columns, quote=True)
1871 else:
1872 name = self.quote_name(name)
1873 if condition or include or opclasses or expressions:
1874 sql = self.sql_create_unique_index
1875 else:
1876 sql = self.sql_create_unique
1877 if columns:
1878 columns = self._index_columns(
1879 table, columns, col_suffixes=(), opclasses=opclasses
1880 )
1881 else:
1882 columns = Expressions(table, expressions, compiler, self.quote_value)
1883 return Statement(
1884 sql,
1885 table=Table(table, self.quote_name),
1886 name=name,
1887 columns=columns,
1888 condition=self._index_condition_sql(condition),
1889 deferrable=self._deferrable_constraint_sql(deferrable),
1890 include=self._index_include_sql(model, include),
1891 nulls_distinct=self._unique_index_nulls_distinct_sql(nulls_distinct),
1892 )
1893
1894 def _unique_constraint_name(self, table, columns, quote=True):
1895 if quote:
1896
1897 def create_unique_name(*args, **kwargs):
1898 return self.quote_name(self._create_index_name(*args, **kwargs))
1899
1900 else:
1901 create_unique_name = self._create_index_name
1902
1903 return IndexName(table, columns, "_uniq", create_unique_name)
1904
1905 def _delete_unique_sql(
1906 self,
1907 model,
1908 name,
1909 condition=None,
1910 deferrable=None,
1911 include=None,
1912 opclasses=None,
1913 expressions=None,
1914 nulls_distinct=None,
1915 ):
1916 if not self._unique_supported(
1917 condition=condition,
1918 deferrable=deferrable,
1919 include=include,
1920 expressions=expressions,
1921 nulls_distinct=nulls_distinct,
1922 ):
1923 return None
1924 if condition or include or opclasses or expressions:
1925 sql = self.sql_delete_index
1926 else:
1927 sql = self.sql_delete_unique
1928 return self._delete_constraint_sql(sql, model, name)
1929
1930 def _check_sql(self, name, check):
1931 return self.sql_constraint % {
1932 "name": self.quote_name(name),
1933 "constraint": self.sql_check_constraint % {"check": check},
1934 }
1935
1936 def _create_check_sql(self, model, name, check):
1937 if not self.connection.features.supports_table_check_constraints:
1938 return None
1939 return Statement(
1940 self.sql_create_check,
1941 table=Table(model._meta.db_table, self.quote_name),
1942 name=self.quote_name(name),
1943 check=check,
1944 )
1945
1946 def _delete_check_sql(self, model, name):
1947 if not self.connection.features.supports_table_check_constraints:
1948 return None
1949 return self._delete_constraint_sql(self.sql_delete_check, model, name)
1950
1951 def _delete_constraint_sql(self, template, model, name):
1952 return Statement(
1953 template,
1954 table=Table(model._meta.db_table, self.quote_name),
1955 name=self.quote_name(name),
1956 )
1957
1958 def _constraint_names(
1959 self,
1960 model,
1961 column_names=None,
1962 unique=None,
1963 primary_key=None,
1964 index=None,
1965 foreign_key=None,
1966 check=None,
1967 type_=None,
1968 exclude=None,
1969 ):
1970 """Return all constraint names matching the columns and conditions."""
1971 if column_names is not None:
1972 column_names = [
1973 (
1974 self.connection.introspection.identifier_converter(
1975 truncate_name(name, self.connection.ops.max_name_length())
1976 )
1977 if self.connection.features.truncates_names
1978 else self.connection.introspection.identifier_converter(name)
1979 )
1980 for name in column_names
1981 ]
1982 with self.connection.cursor() as cursor:
1983 constraints = self.connection.introspection.get_constraints(
1984 cursor, model._meta.db_table
1985 )
1986 result = []
1987 for name, infodict in constraints.items():
1988 if column_names is None or column_names == infodict["columns"]:
1989 if unique is not None and infodict["unique"] != unique:
1990 continue
1991 if primary_key is not None and infodict["primary_key"] != primary_key:
1992 continue
1993 if index is not None and infodict["index"] != index:
1994 continue
1995 if check is not None and infodict["check"] != check:
1996 continue
1997 if foreign_key is not None and not infodict["foreign_key"]:
1998 continue
1999 if type_ is not None and infodict["type"] != type_:
2000 continue
2001 if not exclude or name not in exclude:
2002 result.append(name)
2003 return result
2004
2005 def _pk_constraint_sql(self, columns):
2006 return self.sql_pk_constraint % {
2007 "columns": ", ".join(self.quote_name(column) for column in columns)
2008 }
2009
2010 def _delete_primary_key(self, model, strict=False):
2011 constraint_names = self._constraint_names(model, primary_key=True)
2012 if strict and len(constraint_names) != 1:
2013 raise ValueError(
2014 "Found wrong number (%s) of PK constraints for %s"
2015 % (
2016 len(constraint_names),
2017 model._meta.db_table,
2018 )
2019 )
2020 for constraint_name in constraint_names:
2021 self.execute(self._delete_primary_key_sql(model, constraint_name))
2022
2023 def _create_primary_key_sql(self, model, field):
2024 return Statement(
2025 self.sql_create_pk,
2026 table=Table(model._meta.db_table, self.quote_name),
2027 name=self.quote_name(
2028 self._create_index_name(
2029 model._meta.db_table, [field.column], suffix="_pk"
2030 )
2031 ),
2032 columns=Columns(model._meta.db_table, [field.column], self.quote_name),
2033 )
2034
2035 def _delete_primary_key_sql(self, model, name):
2036 return self._delete_constraint_sql(self.sql_delete_pk, model, name)
2037
2038 def _collate_sql(self, collation, old_collation=None, table_name=None):
2039 return "COLLATE " + self.quote_name(collation) if collation else ""
2040
2041 def remove_procedure(self, procedure_name, param_types=()):
2042 sql = self.sql_delete_procedure % {
2043 "procedure": self.quote_name(procedure_name),
2044 "param_types": ",".join(param_types),
2045 }
2046 self.execute(sql)