v0.166.0
  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        }