plain.postgres 0.110.2__tar.gz → 0.111.1__tar.gz

plain_postgres-0.110.2/plain/postgres/README.md → plain_postgres-0.111.1/PKG-INFO

@@ -1,3 +1,16 @@
+Metadata-Version: 2.4
+Name: plain.postgres
+Version: 0.111.1
+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.**
@@ -18,6 +31,7 @@
 - [Forms](#forms)
 - [Architecture](#architecture)
 - [Diagnostics](#diagnostics)
+- [Tracing](#tracing)
 - [Settings](#settings)
 - [FAQs](#faqs)
 - [Installation](#installation)
@@ -1418,6 +1432,21 @@ These are static, code-level checks that catch issues before you deploy. The `di
 - **Historical trending** — `diagnose` is stateless; it reports on the current state of cumulative stats. Continuous monitoring is out of scope.
 - **Niche server checks** (WAL bloat, replication slot age, etc.) — better covered by your Postgres provider's monitoring or a dedicated tool; users on self-hosted setups that need them typically have their own tooling.
 
+## Tracing
+
+Every query runs inside an OpenTelemetry `CLIENT` span with standard `db.*` attributes, so queries show up as children of whatever request, job, or chore triggered them. You don't configure anything for this — it's on by default and only exports if your app exports traces (e.g. with [plain.connect](../../../plain-connect/plain/connect/README.md)).
+
+If code runs a query with _no_ active span — a background thread, a polling loop — that query's span becomes its own single-span trace. For framework-internal housekeeping queries where that's pure noise, you can suppress query tracing entirely:
+
+```python
+from plain.postgres.otel import suppress_db_tracing
+
+with suppress_db_tracing():
+    MyModel.query.count()  # No span, no query metrics
+```
+
+This is meant for infrastructure code (pollers, metric gauge callbacks, test fixtures) — not for hiding application queries, which you almost always want visible in traces.
+
 ## Settings
 
 The connection is configured with a single URL (`POSTGRES_URL`). `DATABASE_URL` is read as a platform-compat fallback. Set the URL to `none` to explicitly disable the database (e.g. during Docker image builds).

{plain_postgres-0.110.2 → plain_postgres-0.111.1}/plain/postgres/CHANGELOG.md

@@ -1,5 +1,29 @@
 # plain-postgres changelog
 
+## [0.111.1](https://github.com/dropseed/plain/releases/plain-postgres@0.111.1) (2026-07-10)
+
+### What's changed
+
+- `suppress_db_tracing` is now documented public API (`plain.postgres.otel.suppress_db_tracing`), with a new [Tracing](https://github.com/dropseed/plain/blob/master/plain-postgres/plain/postgres/README.md#tracing) section in the README. Use it around framework-style housekeeping queries (pollers, gauge callbacks) that run outside any entry span, where each query would otherwise export as its own single-span root trace. ([0560eb69b8](https://github.com/dropseed/plain/commit/0560eb69b8))
+- Hardened the schema-convergence invariants behind `plain postgres sync` / `converge` / `schema`: a malformed drift now fails loudly at plan time instead of constructing a fix with missing fields, and column/foreign-key comparison asserts it never silently drops a detected drift. ([cb9aa7087c](https://github.com/dropseed/plain/commit/cb9aa7087c))
+- Internal restructuring of the convergence subsystem: the per-kind drift classes were decomposed into shape dataclasses, and `plain.postgres.convergence` no longer re-exports the drift, fix, and status types — it is an internal subsystem driven through the CLI commands, and its `__init__` now only exposes what the CLI uses. No CLI behavior changes. ([75216e16c9](https://github.com/dropseed/plain/commit/75216e16c9), [2b2e57f876](https://github.com/dropseed/plain/commit/2b2e57f876))
+
+### Upgrade instructions
+
+- No changes required.
+
+## [0.111.0](https://github.com/dropseed/plain/releases/plain-postgres@0.111.0) (2026-06-30)
+
+### What's changed
+
+- Slicing a `QuerySet` now always returns a `QuerySet`, even when its results are already cached — previously, slicing an already-evaluated queryset returned a plain `list`. The returned queryset carries the sliced cache, so iterating it won't re-query, but re-chaining it (adding a `.filter()`, ordering, etc.) drops the cache and applies the slice as SQL `LIMIT`/`OFFSET` so the rows stay correct. ([d60e07d6ad](https://github.com/dropseed/plain/commit/d60e07d6ad))
+- Step slicing (e.g. `qs[::2]`) now raises `ValueError` instead of silently evaluating the queryset and returning a stepped `list`. Negative indexing and negative slice bounds continue to raise, as before. `RawQuerySet` is unaffected — it is always fully materialized, so its slicing keeps plain `list` semantics, where step and negative slicing still work. ([d60e07d6ad](https://github.com/dropseed/plain/commit/d60e07d6ad), [a873a521d4](https://github.com/dropseed/plain/commit/a873a521d4))
+
+### Upgrade instructions
+
+- If you relied on `queryset[a:b]` returning a `list` — for example checking `isinstance(result, list)`, calling list methods like `.append()` on it, or re-slicing it with a step — wrap it in `list(queryset[a:b])` to materialize it explicitly.
+- Replace any step slicing of a queryset (`queryset[::2]`) with a `list(...)` conversion first, since it now raises `ValueError`.
+
 ## [0.110.2](https://github.com/dropseed/plain/releases/plain-postgres@0.110.2) (2026-06-26)
 
 ### What's changed

plain_postgres-0.110.2/PKG-INFO → plain_postgres-0.111.1/plain/postgres/README.md

@@ -1,16 +1,3 @@
-Metadata-Version: 2.4
-Name: plain.postgres
-Version: 0.110.2
-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.**
@@ -31,6 +18,7 @@ Description-Content-Type: text/markdown
 - [Forms](#forms)
 - [Architecture](#architecture)
 - [Diagnostics](#diagnostics)
+- [Tracing](#tracing)
 - [Settings](#settings)
 - [FAQs](#faqs)
 - [Installation](#installation)
@@ -1431,6 +1419,21 @@ These are static, code-level checks that catch issues before you deploy. The `di
 - **Historical trending** — `diagnose` is stateless; it reports on the current state of cumulative stats. Continuous monitoring is out of scope.
 - **Niche server checks** (WAL bloat, replication slot age, etc.) — better covered by your Postgres provider's monitoring or a dedicated tool; users on self-hosted setups that need them typically have their own tooling.
 
+## Tracing
+
+Every query runs inside an OpenTelemetry `CLIENT` span with standard `db.*` attributes, so queries show up as children of whatever request, job, or chore triggered them. You don't configure anything for this — it's on by default and only exports if your app exports traces (e.g. with [plain.connect](../../../plain-connect/plain/connect/README.md)).
+
+If code runs a query with _no_ active span — a background thread, a polling loop — that query's span becomes its own single-span trace. For framework-internal housekeeping queries where that's pure noise, you can suppress query tracing entirely:
+
+```python
+from plain.postgres.otel import suppress_db_tracing
+
+with suppress_db_tracing():
+    MyModel.query.count()  # No span, no query metrics
+```
+
+This is meant for infrastructure code (pollers, metric gauge callbacks, test fixtures) — not for hiding application queries, which you almost always want visible in traces.
+
 ## Settings
 
 The connection is configured with a single URL (`POSTGRES_URL`). `DATABASE_URL` is read as a platform-compat fallback. Set the URL to `none` to explicitly disable the database (e.g. during Docker image builds).

plain_postgres-0.111.1/plain/postgres/convergence/__init__.py

@@ -0,0 +1,40 @@
+"""Internal subsystem powering the ``plain postgres sync`` / ``converge`` /
+``schema`` commands.
+
+This is not a public import API. End users drive convergence through those CLI
+commands, not by importing from here, and it is intentionally absent from the
+top-level ``plain.postgres`` surface. The names re-exported below exist for the
+rest of ``plain.postgres`` (the CLI) to use; the drift types, ``DriftKind``,
+the ``Fix`` classes, and the ``Status`` records are convergence-internal and
+live in the ``.analysis`` / ``.fixes`` / ``.planning`` submodules.
+"""
+
+from .analysis import (
+    ModelAnalysis,
+    ReadOnlyConnectionError,
+    analyze_model,
+)
+from .planning import (
+    ConvergencePlan,
+    ConvergenceResult,
+    FixResult,
+    PlanItem,
+    can_auto_fix,
+    execute_plan,
+    plan_convergence,
+    plan_model_convergence,
+)
+
+__all__ = [
+    "ConvergencePlan",
+    "ConvergenceResult",
+    "FixResult",
+    "ModelAnalysis",
+    "PlanItem",
+    "ReadOnlyConnectionError",
+    "analyze_model",
+    "can_auto_fix",
+    "execute_plan",
+    "plan_convergence",
+    "plan_model_convergence",
+]