plain.postgres 0.102.0__tar.gz → 0.103.0__tar.gz

plain_postgres-0.102.0/plain/postgres/README.md → plain_postgres-0.103.0/PKG-INFO

@@ -1,3 +1,16 @@
+Metadata-Version: 2.4
+Name: plain.postgres
+Version: 0.103.0
+Summary: Model your data and store it in a database.
+Author-email: Dave Gaeddert <dave.gaeddert@dropseed.dev>
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Requires-Python: >=3.13
+Requires-Dist: plain<1.0.0,>=0.134.0
+Requires-Dist: psycopg-pool>=3.2
+Requires-Dist: psycopg>=3.2
+Description-Content-Type: text/markdown
+
 # plain.postgres
 
 **Model your data and store it in a database.**
@@ -687,7 +700,7 @@ Or use `RunSQL` with explicit cascade if the relationship is large.
 
 ### Convergence
 
-Convergence compares the indexes, constraints, foreign keys, and nullability declared on your models against what actually exists in the database, then applies fixes to make them match. You don't need to create migrations for these — just declare them on your model and run `postgres sync`.
+Convergence compares the indexes, constraints, foreign keys, nullability, and [storage parameters](#storage-parameters) declared on your models against what actually exists in the database, then applies fixes to make them match. You don't need to create migrations for these — just declare them on your model and run `postgres sync`.
 
 ```python
 @postgres.register_model
@@ -1078,6 +1091,26 @@ A `code` becomes `ValidationError.code` — useful for test assertions, error tr
 
 `UniqueConstraint` accepts the same `violation_error`. With a single-field unique constraint, a string `violation_error="That email is taken."` auto-routes to that field; otherwise (multi-field, expressions, or a CheckConstraint) errors land on `NON_FIELD_ERRORS` unless you pass the dict form. See [BaseConstraint](./constraints.py#BaseConstraint) for the full signature.
 
+### Storage parameters
+
+Per-table Postgres [storage parameters](https://www.postgresql.org/docs/current/sql-createtable.html#SQL-CREATETABLE-STORAGE-PARAMETERS) (`pg_class.reloptions`) are declared on `model_options` and managed by [convergence](#convergence) — `postgres sync` issues the `ALTER TABLE … SET/RESET (...)` to make the live table match. They're not serialized into migrations.
+
+```python
+class CachedItem(postgres.Model):
+    ...
+
+    model_options = postgres.Options(
+        storage_parameters={
+            # Tighter autovacuum on a churn-heavy table
+            "autovacuum_vacuum_scale_factor": 0.1,
+            # TOAST has its own autovacuum schedule — prefix with `toast.`
+            "toast.autovacuum_vacuum_scale_factor": 0.05,
+        },
+    )
+```
+
+Models are the source of truth: undeclared parameters set on the live table are reset on the next sync. Use this for autovacuum tuning, `fillfactor`, TOAST options, etc. — anything you'd otherwise apply by hand with `ALTER TABLE … SET (...)`.
+
 ### Schema design
 
 #### Index fields used in filters and ordering
@@ -1277,16 +1310,17 @@ fix in their model code. (In JSON output each finding still carries
 it.) Each finding still carries the exact SQL in its suggestion for anyone
 who wants to act.
 
-| Finding             | What it reports                                                                  |
-| ------------------- | -------------------------------------------------------------------------------- |
-| **Stats freshness** | Tables whose planner statistics are missing (never analyzed) or stale            |
-| **Vacuum health**   | Tables with >10% dead tuples                                                     |
-| **Index bloat**     | btree indexes with significant estimated wasted space (≥10 MB, ioguix estimator) |
+| Finding             | What it reports                                                                            |
+| ------------------- | ------------------------------------------------------------------------------------------ |
+| **Stats freshness** | Tables whose planner statistics are missing (never analyzed) or stale                      |
+| **Vacuum health**   | Tables with >10% dead tuples                                                               |
+| **Table bloat**     | Tables with significant estimated wasted space (≥100 MB AND ≥25% bloat, ioguix estimator)  |
+| **Index bloat**     | btree indexes with significant estimated wasted space (≥100 MB AND ≥30%, ioguix estimator) |
 
-If a future release exposes per-table autovacuum / fillfactor parameters in
-`model_options` (see the `postgres-model-storage-parameters` arc), these
-findings can graduate back to the warning tier — because the remedy will be
-expressible in code.
+Now that per-table autovacuum / fillfactor knobs are expressible in
+[storage parameters](#storage-parameters) on `model_options`, these
+findings may graduate back to the warning tier in a future release — the
+remedy is now in code.
 
 ### Informational context
 
@@ -1335,7 +1369,7 @@ heroku run -a your-app "plain postgres diagnose --json"
 
 The `--json` flag must be quoted so Heroku passes it through to the command.
 
-Cumulative-stat checks (`stats_freshness`, `vacuum_health`, `unused_indexes`, `missing_index_candidates`, `index_bloat`) need cumulative stat history after the last reset to be reliable. Check the `stats_reset` informational to see how much history you have. (Note: this list spans both the warning and operational tiers — the common thread is that all five depend on counters that `pg_stat_reset()` wipes.)
+Cumulative-stat checks (`stats_freshness`, `vacuum_health`, `unused_indexes`, `missing_index_candidates`, `table_bloat`, `index_bloat`) need cumulative stat history after the last reset to be reliable. Check the `stats_reset` informational to see how much history you have. (Note: this list spans both the warning and operational tiers — the common thread is that all five depend on counters that `pg_stat_reset()` wipes.)
 
 ### Preflight checks
 

{plain_postgres-0.102.0 → plain_postgres-0.103.0}/plain/postgres/CHANGELOG.md

@@ -1,5 +1,17 @@
 # plain-postgres changelog
 
+## [0.103.0](https://github.com/dropseed/plain/releases/plain-postgres@0.103.0) (2026-05-06)
+
+### What's changed
+
+- **New `storage_parameters` on `model_options`, managed by convergence.** Declare per-table Postgres storage parameters (`pg_class.reloptions`) on the model — autovacuum tuning, `fillfactor`, TOAST options, anything you'd otherwise set with `ALTER TABLE … SET (...)` — and `plain postgres sync` reconciles them via instant catalog-only `ALTER TABLE … SET / RESET (...)` statements. Models are the source of truth: parameters set on the live table that aren't declared on the model get reset, matching how indexes and constraints work. TOAST parameters use a `toast.` prefix (`toast.autovacuum_vacuum_scale_factor`) and are stored on the toast relation. Storage parameters are not serialized into migrations. New public API: `StorageParameterDrift`, `SetStorageParameterFix`, `ResetStorageParameterFix`. ([7fe40f72](https://github.com/dropseed/plain/commit/7fe40f72))
+- **New `table_bloat` health check.** Estimates per-table page-level bloat using the ioguix estimator (same heuristic as pghero). Complements `vacuum_health`: dead-tuple counts only show what autovacuum hasn't reclaimed yet, but a table that's been vacuumed regularly can still carry gigabytes of bloat because plain `VACUUM` marks pages reusable without returning space to the OS. Surfaces tables with both >100 MB wasted bytes AND >25% bloat ratio, with `pg_repack` / `pg_squeeze` / `VACUUM FULL` suggestions. Cross-check caveats now link `vacuum_health` and `table_bloat` findings on the same table. ([ee9dc1d5](https://github.com/dropseed/plain/commit/ee9dc1d5))
+- **Tightened `index_bloat` thresholds.** Now requires both >100 MB wasted bytes AND >30% bloat ratio (was 10 MB only). The previous floor surfaced too many small, healthy indexes; the higher percentage bar reflects that `REINDEX CONCURRENTLY` is cheap so it's only worth flagging genuinely degraded indexes. Results are also capped at 100 rows per check. ([ee9dc1d5](https://github.com/dropseed/plain/commit/ee9dc1d5))
+
+### Upgrade instructions
+
+- No changes required. To opt into the new `storage_parameters` API, declare them on `model_options = postgres.Options(storage_parameters={...})` and run `plain postgres sync`. After upgrading, expect previously-noisy `index_bloat` findings to disappear (now require ≥100 MB AND ≥30%) and the new `table_bloat` check to appear in `plain postgres diagnose`.
+
 ## [0.102.0](https://github.com/dropseed/plain/releases/plain-postgres@0.102.0) (2026-05-05)
 
 ### What's changed

plain_postgres-0.102.0/PKG-INFO → plain_postgres-0.103.0/plain/postgres/README.md

@@ -1,16 +1,3 @@
-Metadata-Version: 2.4
-Name: plain.postgres
-Version: 0.102.0
-Summary: Model your data and store it in a database.
-Author-email: Dave Gaeddert <dave.gaeddert@dropseed.dev>
-License-Expression: BSD-3-Clause
-License-File: LICENSE
-Requires-Python: >=3.13
-Requires-Dist: plain<1.0.0,>=0.134.0
-Requires-Dist: psycopg-pool>=3.2
-Requires-Dist: psycopg>=3.2
-Description-Content-Type: text/markdown
-
 # plain.postgres
 
 **Model your data and store it in a database.**
@@ -700,7 +687,7 @@ Or use `RunSQL` with explicit cascade if the relationship is large.
 
 ### Convergence
 
-Convergence compares the indexes, constraints, foreign keys, and nullability declared on your models against what actually exists in the database, then applies fixes to make them match. You don't need to create migrations for these — just declare them on your model and run `postgres sync`.
+Convergence compares the indexes, constraints, foreign keys, nullability, and [storage parameters](#storage-parameters) declared on your models against what actually exists in the database, then applies fixes to make them match. You don't need to create migrations for these — just declare them on your model and run `postgres sync`.
 
 ```python
 @postgres.register_model
@@ -1091,6 +1078,26 @@ A `code` becomes `ValidationError.code` — useful for test assertions, error tr
 
 `UniqueConstraint` accepts the same `violation_error`. With a single-field unique constraint, a string `violation_error="That email is taken."` auto-routes to that field; otherwise (multi-field, expressions, or a CheckConstraint) errors land on `NON_FIELD_ERRORS` unless you pass the dict form. See [BaseConstraint](./constraints.py#BaseConstraint) for the full signature.
 
+### Storage parameters
+
+Per-table Postgres [storage parameters](https://www.postgresql.org/docs/current/sql-createtable.html#SQL-CREATETABLE-STORAGE-PARAMETERS) (`pg_class.reloptions`) are declared on `model_options` and managed by [convergence](#convergence) — `postgres sync` issues the `ALTER TABLE … SET/RESET (...)` to make the live table match. They're not serialized into migrations.
+
+```python
+class CachedItem(postgres.Model):
+    ...
+
+    model_options = postgres.Options(
+        storage_parameters={
+            # Tighter autovacuum on a churn-heavy table
+            "autovacuum_vacuum_scale_factor": 0.1,
+            # TOAST has its own autovacuum schedule — prefix with `toast.`
+            "toast.autovacuum_vacuum_scale_factor": 0.05,
+        },
+    )
+```
+
+Models are the source of truth: undeclared parameters set on the live table are reset on the next sync. Use this for autovacuum tuning, `fillfactor`, TOAST options, etc. — anything you'd otherwise apply by hand with `ALTER TABLE … SET (...)`.
+
 ### Schema design
 
 #### Index fields used in filters and ordering
@@ -1290,16 +1297,17 @@ fix in their model code. (In JSON output each finding still carries
 it.) Each finding still carries the exact SQL in its suggestion for anyone
 who wants to act.
 
-| Finding             | What it reports                                                                  |
-| ------------------- | -------------------------------------------------------------------------------- |
-| **Stats freshness** | Tables whose planner statistics are missing (never analyzed) or stale            |
-| **Vacuum health**   | Tables with >10% dead tuples                                                     |
-| **Index bloat**     | btree indexes with significant estimated wasted space (≥10 MB, ioguix estimator) |
+| Finding             | What it reports                                                                            |
+| ------------------- | ------------------------------------------------------------------------------------------ |
+| **Stats freshness** | Tables whose planner statistics are missing (never analyzed) or stale                      |
+| **Vacuum health**   | Tables with >10% dead tuples                                                               |
+| **Table bloat**     | Tables with significant estimated wasted space (≥100 MB AND ≥25% bloat, ioguix estimator)  |
+| **Index bloat**     | btree indexes with significant estimated wasted space (≥100 MB AND ≥30%, ioguix estimator) |
 
-If a future release exposes per-table autovacuum / fillfactor parameters in
-`model_options` (see the `postgres-model-storage-parameters` arc), these
-findings can graduate back to the warning tier — because the remedy will be
-expressible in code.
+Now that per-table autovacuum / fillfactor knobs are expressible in
+[storage parameters](#storage-parameters) on `model_options`, these
+findings may graduate back to the warning tier in a future release — the
+remedy is now in code.
 
 ### Informational context
 
@@ -1348,7 +1356,7 @@ heroku run -a your-app "plain postgres diagnose --json"
 
 The `--json` flag must be quoted so Heroku passes it through to the command.
 
-Cumulative-stat checks (`stats_freshness`, `vacuum_health`, `unused_indexes`, `missing_index_candidates`, `index_bloat`) need cumulative stat history after the last reset to be reliable. Check the `stats_reset` informational to see how much history you have. (Note: this list spans both the warning and operational tiers — the common thread is that all five depend on counters that `pg_stat_reset()` wipes.)
+Cumulative-stat checks (`stats_freshness`, `vacuum_health`, `unused_indexes`, `missing_index_candidates`, `table_bloat`, `index_bloat`) need cumulative stat history after the last reset to be reliable. Check the `stats_reset` informational to see how much history you have. (Note: this list spans both the warning and operational tiers — the common thread is that all five depend on counters that `pg_stat_reset()` wipes.)
 
 ### Preflight checks
 

{plain_postgres-0.102.0 → plain_postgres-0.103.0}/plain/postgres/agents/.claude/rules/plain-postgres.md

@@ -36,7 +36,7 @@ Get approval before writing any model code or generating migrations.
 `uv run plain postgres sync` runs three steps: create migrations → apply migrations → converge schema.
 
 - **Migrations** handle tables and columns (CreateModel, AddField, AlterField, etc.)
-- **Convergence** handles indexes, constraints, and FK constraints — declared on the model but NOT serialized into migration files. (FK _columns_ like `team_id bigint` are created by migrations; the actual `FOREIGN KEY` constraint is added by convergence.)
+- **Convergence** handles indexes, constraints, FK constraints, and storage parameters — declared on the model but NOT serialized into migration files. (FK _columns_ like `team_id bigint` are created by migrations; the actual `FOREIGN KEY` constraint is added by convergence.)
 
 This means: when you add an `Index` or `UniqueConstraint` to a model, no migration is generated. The converge step reads the live model class and syncs the database directly. Don't worry about serializing constraint expressions (like `Lower()`) for migrations — they never go there.
 

{plain_postgres-0.102.0 → plain_postgres-0.103.0}/plain/postgres/convergence/__init__.py

@@ -12,6 +12,7 @@ from .analysis import (
     ModelAnalysis,
     NullabilityDrift,
     ReadOnlyConnectionError,
+    StorageParameterDrift,
     analyze_model,
 )
 from .fixes import (
@@ -26,8 +27,10 @@ from .fixes import (
     RebuildIndexFix,
     RenameConstraintFix,
     RenameIndexFix,
+    ResetStorageParameterFix,
     SetColumnDefaultFix,
     SetNotNullFix,
+    SetStorageParameterFix,
     ValidateConstraintFix,
 )
 from .planning import (
@@ -70,8 +73,11 @@ __all__ = [
     "RebuildIndexFix",
     "RenameConstraintFix",
     "RenameIndexFix",
+    "ResetStorageParameterFix",
     "SetColumnDefaultFix",
     "SetNotNullFix",
+    "SetStorageParameterFix",
+    "StorageParameterDrift",
     "ValidateConstraintFix",
     "analyze_model",
     "can_auto_fix",

{plain_postgres-0.102.0 → plain_postgres-0.103.0}/plain/postgres/convergence/analysis.py

@@ -191,8 +191,44 @@ class ColumnDefaultDrift:
                 )
 
 
+@dataclass
+class StorageParameterDrift:
+    """Mismatch between declared and live `pg_class.reloptions` for a table.
+
+    `key` carries a `toast.` prefix when the parameter belongs to the table's
+    TOAST relation; convergence emits and reads it accordingly.
+    """
+
+    kind: DriftKind
+    table: str
+    key: str
+    declared_value: str | None = None
+    actual_value: str | None = None
+
+    def describe(self) -> str:
+        match self.kind:
+            case DriftKind.MISSING:
+                return (
+                    f"{self.table}: storage parameter {self.key} missing "
+                    f"(expected {self.declared_value})"
+                )
+            case DriftKind.CHANGED:
+                return (
+                    f"{self.table}: storage parameter {self.key} mismatch — "
+                    f"db has {self.actual_value}, model declares "
+                    f"{self.declared_value}"
+                )
+            case _:
+                return (
+                    f"{self.table}: storage parameter {self.key} not declared "
+                    f"(db has {self.actual_value})"
+                )
+
+
 type ColumnDrift = NullabilityDrift | ColumnDefaultDrift
-type Drift = IndexDrift | ConstraintDrift | ForeignKeyDrift | ColumnDrift
+type Drift = (
+    IndexDrift | ConstraintDrift | ForeignKeyDrift | ColumnDrift | StorageParameterDrift
+)
 
 
 # Status objects — analysis results with optional drift
@@ -236,6 +272,7 @@ class ModelAnalysis:
     columns: list[ColumnStatus] = field(default_factory=list)
     indexes: list[IndexStatus] = field(default_factory=list)
     constraints: list[ConstraintStatus] = field(default_factory=list)
+    storage_parameter_drifts: list[StorageParameterDrift] = field(default_factory=list)
 
     @cached_property
     def drifts(self) -> list[Drift]:
@@ -249,15 +286,17 @@ class ModelAnalysis:
         for con in self.constraints:
             if con.drift:
                 result.append(con.drift)
+        result.extend(self.storage_parameter_drifts)
         return result
 
     @cached_property
     def issue_count(self) -> int:
-        """Total issues (table + columns + indexes + constraints)."""
+        """Total issues (table + columns + indexes + constraints + storage)."""
         count = len(self.table_issues)
         count += sum(1 for col in self.columns if col.issue)
         count += sum(1 for idx in self.indexes if idx.issue)
         count += sum(1 for con in self.constraints if con.issue)
+        count += len(self.storage_parameter_drifts)
         return count
 
     def to_dict(self) -> dict[str, Any]:
@@ -300,6 +339,15 @@ class ModelAnalysis:
                 }
                 for con in self.constraints
             ],
+            "storage_parameter_drifts": [
+                {
+                    "key": d.key,
+                    "kind": d.kind,
+                    "declared_value": d.declared_value,
+                    "actual_value": d.actual_value,
+                }
+                for d in self.storage_parameter_drifts
+            ],
         }
 
 
@@ -328,9 +376,59 @@ def analyze_model(
         columns=_compare_columns(model, db, table_name, cursor),
         indexes=_compare_indexes(cursor, model, db, table_name),
         constraints=_compare_constraints(cursor, model, db, table_name),
+        storage_parameter_drifts=_compare_storage_parameters(model, db, table_name),
     )
 
 
+def _compare_storage_parameters(
+    model: type[Model], db: TableState, table: str
+) -> list[StorageParameterDrift]:
+    """Diff declared `model_options.storage_parameters` against `pg_class.reloptions`.
+
+    Declared keys missing from the DB → MISSING. Mismatched values → CHANGED.
+    Live keys not declared → UNDECLARED (so convergence can RESET them, keeping
+    the model as the source of truth — matches how indexes/constraints work).
+    """
+    declared = model.model_options.storage_parameters
+    actual = db.storage_parameters
+    drifts: list[StorageParameterDrift] = []
+
+    for key, declared_value in declared.items():
+        actual_value = actual.get(key)
+        if actual_value is None:
+            drifts.append(
+                StorageParameterDrift(
+                    kind=DriftKind.MISSING,
+                    table=table,
+                    key=key,
+                    declared_value=declared_value,
+                )
+            )
+        elif actual_value != declared_value:
+            drifts.append(
+                StorageParameterDrift(
+                    kind=DriftKind.CHANGED,
+                    table=table,
+                    key=key,
+                    declared_value=declared_value,
+                    actual_value=actual_value,
+                )
+            )
+
+    for key, actual_value in actual.items():
+        if key not in declared:
+            drifts.append(
+                StorageParameterDrift(
+                    kind=DriftKind.UNDECLARED,
+                    table=table,
+                    key=key,
+                    actual_value=actual_value,
+                )
+            )
+
+    return drifts
+
+
 # Column comparison
 
 

{plain_postgres-0.102.0 → plain_postgres-0.103.0}/plain/postgres/convergence/fixes.py

@@ -4,6 +4,9 @@ from abc import ABC, abstractmethod
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, ClassVar
 
+import psycopg
+import psycopg.sql
+
 from plain.logs import get_framework_logger
 from plain.runtime import settings as plain_settings
 
@@ -555,3 +558,42 @@ class DropIndexFix(Fix):
         sql = f"DROP INDEX CONCURRENTLY IF EXISTS {quote_name(self.name)}"
         _execute_autocommit(sql)
         return sql
+
+
+@dataclass
+class SetStorageParameterFix(Fix):
+    """Set a single `pg_class.reloptions` parameter (catalog-only, instant)."""
+
+    pass_order = 2
+
+    table: str
+    key: str
+    value: str
+
+    def describe(self) -> str:
+        return f"{self.table}: set storage parameter {self.key} = {self.value}"
+
+    def apply(self) -> str:
+        conn = get_connection()
+        quoted = psycopg.sql.quote(self.value, conn.connection)
+        sql = f"ALTER TABLE {quote_name(self.table)} SET ({self.key} = {quoted})"
+        _execute_and_commit(sql)
+        return sql
+
+
+@dataclass
+class ResetStorageParameterFix(Fix):
+    """Reset a single `pg_class.reloptions` parameter (catalog-only, instant)."""
+
+    pass_order = 2
+
+    table: str
+    key: str
+
+    def describe(self) -> str:
+        return f"{self.table}: reset storage parameter {self.key}"
+
+    def apply(self) -> str:
+        sql = f"ALTER TABLE {quote_name(self.table)} RESET ({self.key})"
+        _execute_and_commit(sql)
+        return sql

{plain_postgres-0.102.0 → plain_postgres-0.103.0}/plain/postgres/convergence/planning.py

@@ -14,6 +14,7 @@ from .analysis import (
     ForeignKeyDrift,
     IndexDrift,
     NullabilityDrift,
+    StorageParameterDrift,
     analyze_model,
 )
 from .fixes import (
@@ -29,8 +30,10 @@ from .fixes import (
     RenameConstraintFix,
     RenameIndexFix,
     ReplaceForeignKeyFix,
+    ResetStorageParameterFix,
     SetColumnDefaultFix,
     SetNotNullFix,
+    SetStorageParameterFix,
     ValidateConstraintFix,
 )
 
@@ -140,6 +143,16 @@ def _plan_drift(drift: Drift) -> PlanItem:
             return PlanItem(drift, SetColumnDefaultFix(t, col, default_sql))
         case ColumnDefaultDrift(kind=DriftKind.UNDECLARED, table=t, column=col):
             return PlanItem(drift, DropColumnDefaultFix(t, col))
+        case StorageParameterDrift(
+            kind=DriftKind.MISSING | DriftKind.CHANGED,
+            table=t,
+            key=k,
+            declared_value=v,
+        ):
+            assert v is not None
+            return PlanItem(drift, SetStorageParameterFix(t, k, v))
+        case StorageParameterDrift(kind=DriftKind.UNDECLARED, table=t, key=k):
+            return PlanItem(drift, ResetStorageParameterFix(t, k))
         case _:
             raise ValueError(f"Unhandled drift: {drift}")