1from collections.abc import Generator
2from typing import TYPE_CHECKING, Any
3
4if TYPE_CHECKING:
5 from typing import Self
6
7
8from types import TracebackType
9
10from plain.logs import get_framework_logger
11from plain.postgres.ddl import compile_database_default_sql
12from plain.postgres.dialect import build_timeout_set_clauses, quote_name
13from plain.postgres.fields import Field
14from plain.postgres.fields.base import ColumnField
15from plain.postgres.fields.related import RelatedField
16from plain.postgres.fields.reverse_related import ManyToManyRel
17from plain.postgres.transaction import atomic
18from plain.runtime import settings as plain_settings
19
20if TYPE_CHECKING:
21 from plain.postgres.base import Model
22 from plain.postgres.connection import DatabaseConnection
23 from plain.postgres.fields import Field
24
25logger = get_framework_logger()
26
27
28class DatabaseSchemaEditor:
29 """
30 Responsible for emitting schema-changing statements to PostgreSQL - model
31 creation/removal/alteration, field renaming, index management, and so on.
32 """
33
34 sql_create_table = "CREATE TABLE %(table)s (%(definition)s)"
35 sql_rename_table = "ALTER TABLE %(old_table)s RENAME TO %(new_table)s"
36 sql_delete_table = "DROP TABLE %(table)s CASCADE"
37
38 sql_create_column = "ALTER TABLE %(table)s ADD COLUMN %(column)s %(definition)s"
39 sql_alter_column = "ALTER TABLE %(table)s %(changes)s"
40 sql_alter_column_no_default = "ALTER COLUMN %(column)s DROP DEFAULT"
41 sql_delete_column = "ALTER TABLE %(table)s DROP COLUMN %(column)s CASCADE"
42 sql_rename_column = (
43 "ALTER TABLE %(table)s RENAME COLUMN %(old_column)s TO %(new_column)s"
44 )
45
46 def __init__(
47 self,
48 connection: DatabaseConnection,
49 atomic: bool = True,
50 collect_sql: bool = False,
51 ):
52 self.connection = connection
53 self.collect_sql = collect_sql
54 self.atomic_migration = atomic and not collect_sql
55 # `atomic_migration` goes False under collect_sql=True (we don't open
56 # a real transaction for preview), but the collected SQL should still
57 # reflect a real atomic run. Track the user's `atomic` intent
58 # separately so the SET LOCAL prelude is emitted in the atomic=True
59 # preview case, and skipped in the atomic=False case (where SET LOCAL
60 # would be a no-op with WARNING outside a transaction block).
61 self._atomic_intent = atomic
62
63 # State-managing methods
64
65 def __enter__(self) -> Self:
66 self.executed_sql: list[str] = []
67 if self.atomic_migration:
68 self.atomic = atomic()
69 self.atomic.__enter__()
70 return self
71
72 def __exit__(
73 self,
74 exc_type: type[BaseException] | None,
75 exc_value: BaseException | None,
76 traceback: TracebackType | None,
77 ) -> None:
78 if self.atomic_migration:
79 self.atomic.__exit__(exc_type, exc_value, traceback)
80
81 # Core utility functions
82
83 def execute(
84 self,
85 sql: str,
86 params: tuple[Any, ...] | list[Any] | None = (),
87 *,
88 set_timeouts: bool = True,
89 ) -> None:
90 """Execute the given SQL statement, with optional parameters.
91
92 When ``set_timeouts`` is True (default), ``SET LOCAL lock_timeout`` and
93 ``SET LOCAL statement_timeout`` are prepended to the SQL so DDL fails
94 fast if it can't acquire its lock or if a blocking statement runs
95 longer than configured. Values come from ``POSTGRES_MIGRATION_*``
96 settings. ``RunSQL(no_timeout=True)`` passes ``set_timeouts=False`` as
97 an escape hatch for long-running data migrations.
98 """
99 sql_str = sql
100
101 # Merge the query client-side, as PostgreSQL won't do it server-side.
102 if params is not None:
103 sql_str = self.connection.compose_sql(sql_str, params)
104 params = None
105
106 # SET LOCAL only works inside a transaction block. Skip the prelude
107 # when the editor was opened with atomic=False (e.g. a migration that
108 # needs to issue CONCURRENTLY via RunSQL) — otherwise Postgres would
109 # silently WARN and ignore the timeouts. Users of non-atomic
110 # migrations manage timeouts explicitly in their RunSQL if needed.
111 if set_timeouts and self._atomic_intent:
112 sql_str = (
113 build_timeout_set_clauses(
114 lock_timeout=plain_settings.POSTGRES_MIGRATION_LOCK_TIMEOUT,
115 statement_timeout=plain_settings.POSTGRES_MIGRATION_STATEMENT_TIMEOUT,
116 )
117 + sql_str
118 )
119
120 # Log the command we're running, then run it
121 logger.debug("Schema SQL executed", extra={"sql": sql_str, "params": params})
122
123 # Track executed SQL for display in migration output
124 self.executed_sql.append(sql_str)
125
126 if self.collect_sql:
127 return
128
129 with self.connection.cursor() as cursor:
130 cursor.execute(sql_str, params)
131
132 def table_sql(self, model: type[Model]) -> tuple[str, list[Any]]:
133 """Take a model and return its table definition."""
134 column_sqls = []
135 params = []
136 for field in model._model_meta.fields:
137 definition, extra_params = self.column_sql(
138 model, field, include_default=field.has_persistent_column_default()
139 )
140 if definition is None:
141 continue
142 # Autoincrement SQL (e.g. GENERATED BY DEFAULT AS IDENTITY).
143 col_type_suffix = field.db_type_suffix()
144 if col_type_suffix:
145 definition += f" {col_type_suffix}"
146 if extra_params:
147 params.extend(extra_params)
148 # FK constraints are handled by convergence, not during table creation.
149 # Add the SQL to our big list.
150 column_sqls.append(f"{quote_name(field.column)} {definition}")
151 # Constraints are not created inline — they're managed by convergence.
152 sql = self.sql_create_table % {
153 "table": quote_name(model.model_options.db_table),
154 "definition": ", ".join(col for col in column_sqls if col),
155 }
156 return sql, params
157
158 # Field <-> database mapping functions
159
160 def _iter_column_sql(
161 self,
162 column_db_type: str,
163 params: list[Any],
164 model: type[Model],
165 field: ColumnField,
166 include_default: bool,
167 ) -> Generator[str]:
168 yield column_db_type
169 null = field.allow_null
170 # Include a default value, if requested.
171 if include_default:
172 db_default_expr = field.get_db_default_expression()
173 if db_default_expr is not None:
174 # Expression defaults are inlined into the DDL — they render
175 # as parameter-free SQL and become the column's persistent
176 # DEFAULT.
177 yield f"DEFAULT {self._compile_expression(db_default_expr)}"
178 else:
179 default_value = self.effective_default(field)
180 if default_value is not None:
181 yield "DEFAULT %s"
182 params.append(default_value)
183
184 if not null:
185 yield "NOT NULL"
186 else:
187 yield "NULL"
188
189 if field.primary_key:
190 yield "PRIMARY KEY"
191
192 def column_sql(
193 self, model: type[Model], field: Field, include_default: bool = False
194 ) -> tuple[str | None, list[Any] | None]:
195 """
196 Return the column definition for a field. The field must already have
197 had set_attributes_from_name() called.
198 """
199 # Get the column's type and use that as the basis of the SQL.
200 column_db_type = field.db_type()
201 # Check for fields that aren't actually columns (e.g. M2M).
202 if column_db_type is None:
203 return None, None
204 assert isinstance(field, ColumnField)
205 params: list[Any] = []
206 return (
207 " ".join(
208 # This appends to the params being returned.
209 self._iter_column_sql(
210 column_db_type,
211 params,
212 model,
213 field,
214 include_default,
215 )
216 ),
217 params,
218 )
219
220 def _compile_expression(self, expression: Any) -> str:
221 """Compile a DB-default expression (Now, GenRandomUUID) for inlining into DDL."""
222 return compile_database_default_sql(expression)
223
224 def effective_default(self, field: Field) -> Any:
225 """Return a field's declared literal DEFAULT value, prepared for the
226 database. Returns None for fields without a user-declared default —
227 expression defaults take the `get_db_default_expression()` path
228 instead."""
229 from plain.postgres.fields.base import DefaultableField
230
231 if not isinstance(field, DefaultableField) or not field.has_default():
232 return None
233 return field.get_db_prep_save(field.get_default(), self.connection)
234
235 # Actions
236
237 def create_model(self, model: type[Model]) -> None:
238 """Create a table for the given model."""
239 sql, params = self.table_sql(model)
240 # Prevent using [] as params, in the case a literal '%' is used in the
241 # definition.
242 self.execute(sql, params or None)
243
244 def delete_model(self, model: type[Model]) -> None:
245 """Delete a model from the database."""
246 self.execute(
247 self.sql_delete_table
248 % {
249 "table": quote_name(model.model_options.db_table),
250 }
251 )
252
253 def alter_db_table(
254 self, model: type[Model], old_db_table: str, new_db_table: str
255 ) -> None:
256 """Rename the table a model points to."""
257 if old_db_table == new_db_table:
258 return
259 self.execute(
260 self.sql_rename_table
261 % {
262 "old_table": quote_name(old_db_table),
263 "new_table": quote_name(new_db_table),
264 }
265 )
266
267 def add_field(self, model: type[Model], field: Field) -> None:
268 """
269 Create a field on a model. Usually involves adding a column, but may
270 involve adding a table instead (for M2M fields).
271 """
272 # Get the column's definition
273 definition, params = self.column_sql(
274 model,
275 field,
276 include_default=field.has_persistent_column_default(),
277 )
278 # It might not actually have a column behind it
279 if definition is None:
280 return
281 if col_type_suffix := field.db_type_suffix():
282 definition += f" {col_type_suffix}"
283 # FK constraints are handled by convergence, not inline during add_field.
284 # Build the SQL and run it
285 sql = self.sql_create_column % {
286 "table": quote_name(model.model_options.db_table),
287 "column": quote_name(field.column),
288 "definition": definition,
289 }
290 self.execute(sql, params)
291
292 def remove_field(self, model: type[Model], field: Field) -> None:
293 """
294 Remove a field from a model. Usually involves deleting a column,
295 but for M2Ms may involve deleting a table.
296 """
297 # It might not actually have a column behind it
298 if field.db_type() is None:
299 return
300 # FK constraints are dropped automatically by CASCADE on DROP COLUMN.
301 # Delete the column
302 sql = self.sql_delete_column % {
303 "table": quote_name(model.model_options.db_table),
304 "column": quote_name(field.column),
305 }
306 self.execute(sql)
307
308 def alter_field(
309 self,
310 model: type[Model],
311 old_field: Field,
312 new_field: Field,
313 ) -> None:
314 """
315 Allow a field's type, uniqueness, nullability, default, column,
316 constraints, etc. to be modified.
317 `old_field` is required to compute the necessary changes.
318 """
319 if not self._field_should_be_altered(old_field, new_field):
320 return
321 # Ensure this field is even column-based
322 old_type = old_field.db_type()
323 new_type = new_field.db_type()
324 if (old_type is None and not isinstance(old_field, RelatedField)) or (
325 new_type is None and not isinstance(new_field, RelatedField)
326 ):
327 raise ValueError(
328 f"Cannot alter field {old_field} into {new_field} - they do not properly define "
329 "db_type (are you using a badly-written custom field?)",
330 )
331 elif (
332 old_type is None
333 and new_type is None
334 and isinstance(old_field, RelatedField)
335 and isinstance(old_field.remote_field, ManyToManyRel)
336 and isinstance(new_field, RelatedField)
337 and isinstance(new_field.remote_field, ManyToManyRel)
338 ):
339 # Both sides have through models; this is a no-op.
340 return
341 elif old_type is None or new_type is None:
342 raise ValueError(
343 f"Cannot alter field {old_field} into {new_field} - they are not compatible types "
344 "(you cannot alter to or from M2M fields, or add or remove "
345 "through= on M2M fields)"
346 )
347
348 assert isinstance(old_field, ColumnField)
349 assert isinstance(new_field, ColumnField)
350 self._alter_field(
351 model,
352 old_field,
353 new_field,
354 old_type,
355 new_type,
356 )
357
358 def _alter_field(
359 self,
360 model: type[Model],
361 old_field: ColumnField,
362 new_field: ColumnField,
363 old_type: str,
364 new_type: str,
365 ) -> None:
366 """Column rename + column type change.
367
368 Also drops the existing expression DEFAULT when the column type is
369 changing (Postgres rejects the cast otherwise). Nullability and
370 column DEFAULT reconciliation are convergence-managed — see
371 ``plain.postgres.convergence``.
372 """
373 if old_field.column != new_field.column:
374 self.execute(
375 self._rename_field_sql(
376 model.model_options.db_table, old_field, new_field
377 )
378 )
379 # Postgres rejects ALTER COLUMN TYPE when the existing expression DEFAULT
380 # can't cast to the new type. Drop it first; convergence re-applies it.
381 if old_field.db_returning and old_type != new_type:
382 self.execute(
383 self.sql_alter_column
384 % {
385 "table": quote_name(model.model_options.db_table),
386 "changes": self.sql_alter_column_no_default
387 % {"column": quote_name(new_field.column)},
388 }
389 )
390 if (
391 old_type != new_type
392 or old_field.db_type_suffix() != new_field.db_type_suffix()
393 ):
394 type_sql, type_params = self._alter_column_type_sql(
395 old_field, new_field, new_type
396 )
397 self.execute(
398 self.sql_alter_column
399 % {
400 "table": quote_name(model.model_options.db_table),
401 "changes": type_sql,
402 },
403 type_params,
404 )
405
406 def _alter_column_type_sql(
407 self,
408 old_field: Field,
409 new_field: Field,
410 new_type: str,
411 ) -> tuple[str, list[Any]]:
412 """Return an ``(sql, params)`` ALTER COLUMN TYPE fragment."""
413 sql = "ALTER COLUMN %(column)s TYPE %(type)s"
414 # USING cast when the base data type changed (e.g. varchar → int),
415 # not just a parameter like max_length.
416 if old_field.unqualified_db_type() != new_field.unqualified_db_type():
417 sql += " USING %(column)s::%(type)s"
418 return (
419 sql
420 % {
421 "column": quote_name(new_field.column),
422 "type": new_type,
423 },
424 [],
425 )
426
427 def _field_should_be_altered(
428 self, old_field: Field, new_field: Field, ignore: set[str] | None = None
429 ) -> bool:
430 ignore = ignore or set()
431 _, old_path, old_args, old_kwargs = old_field.deconstruct()
432 _, new_path, new_args, new_kwargs = new_field.deconstruct()
433 # Don't alter when:
434 # - changing only a field name
435 # - changing an attribute that doesn't affect the schema
436 # - changing an attribute in the provided set of ignored attributes
437 for attr in ignore.union(old_field.non_migration_attrs):
438 old_kwargs.pop(attr, None)
439 for attr in ignore.union(new_field.non_migration_attrs):
440 new_kwargs.pop(attr, None)
441 return quote_name(old_field.column) != quote_name(new_field.column) or (
442 old_path,
443 old_args,
444 old_kwargs,
445 ) != (new_path, new_args, new_kwargs)
446
447 def _rename_field_sql(self, table: str, old_field: Field, new_field: Field) -> str:
448 return self.sql_rename_column % {
449 "table": quote_name(table),
450 "old_column": quote_name(old_field.column),
451 "new_column": quote_name(new_field.column),
452 }