toolframe-sql-postgres 0.2.0__py3-none-any.whl

toolframe_sql_postgres/provision.py

@@ -0,0 +1,348 @@
+"""Explicit, administrator-run provisioning; never invoked by the runtime plugin."""
+
+from __future__ import annotations
+
+import json
+import re
+import secrets
+
+import psycopg
+from psycopg import sql
+from psycopg.conninfo import conninfo_to_dict, make_conninfo
+from toolframe_sdk import PluginError
+
+from .config import names
+
+
+def identifier(value):
+    if not isinstance(value, str) or not re.fullmatch(r"[a-z][a-z0-9_]{0,62}", value):
+        raise PluginError(
+            "database_name_invalid", "Use a lowercase PostgreSQL database identifier"
+        )
+    return value
+
+
+def role(
+    connection, name, *, password=None, existing=False, memberships=(), created=None
+):
+    found = connection.execute(
+        "SELECT rolsuper,rolcreatedb,rolcreaterole,rolreplication,rolbypassrls,rolcanlogin,rolinherit FROM pg_roles WHERE rolname=%s",
+        (name,),
+    ).fetchone()
+    if found:
+        if not existing or any(found[:5]) or found[5] != bool(password) or found[6]:
+            raise PluginError(
+                "role_conflict",
+                "Existing role cannot be adopted; use matching setup credentials",
+            )
+        parents = connection.execute(
+            "SELECT parent.rolname FROM pg_auth_members m JOIN pg_roles member ON member.oid=m.member JOIN pg_roles parent ON parent.oid=m.roleid WHERE member.rolname=%s",
+            (name,),
+        ).fetchall()
+        if {row[0] for row in parents} != set(memberships):
+            raise PluginError(
+                "role_conflict",
+                "Existing role membership differs from the provisioning contract",
+            )
+        return
+    attributes = (
+        sql.SQL("LOGIN PASSWORD {} NOINHERIT").format(sql.Literal(password))
+        if password
+        else sql.SQL("NOLOGIN NOINHERIT")
+    )
+    connection.execute(
+        sql.SQL(
+            "CREATE ROLE {} {} NOSUPERUSER NOCREATEDB NOCREATEROLE NOREPLICATION NOBYPASSRLS"
+        ).format(sql.Identifier(name), attributes)
+    )
+
+    if created is not None:
+        created.append(("role", name))
+
+
+def provision(admin_dsn, database, application_id, owners, *, previous=None):
+    created = []
+    try:
+        return _provision(
+            admin_dsn,
+            database,
+            application_id,
+            owners,
+            previous=previous,
+            created=created,
+        )
+    except BaseException:
+        if not created:
+            raise
+        # Roll back only resources created by this invocation. Existing data is
+        # never adopted or dropped as a response to a failed setup attempt.
+        try:
+            with psycopg.connect(admin_dsn, autocommit=True) as admin:
+                for kind, name in reversed(created):
+                    if kind == "database":
+                        admin.execute(
+                            sql.SQL("DROP DATABASE {} WITH (FORCE)").format(
+                                sql.Identifier(name)
+                            )
+                        )
+                for kind, name in reversed(created):
+                    if kind == "role":
+                        if previous:
+                            admin.execute(
+                                sql.SQL("REVOKE ALL ON DATABASE {} FROM {}").format(
+                                    sql.Identifier(database), sql.Identifier(name)
+                                )
+                            )
+                        admin.execute(
+                            sql.SQL("DROP ROLE {}").format(sql.Identifier(name))
+                        )
+        except psycopg.Error:
+            raise PluginError(
+                "setup_cleanup_failed",
+                "Setup failed and its new resources need administrator inspection before retrying",
+            ) from None
+        raise
+
+
+def _provision(admin_dsn, database, application_id, owners, *, previous=None, created):
+    """Provision fresh resources or add owners using a previous setup result.
+
+    Returns environment values. Callers must save them privately, never print them.
+    Existing databases/roles are only reused when the stored application identity
+    and the previous credentials match. Other application resources are untouched.
+    """
+    identifier(database)
+    if not application_id or len(application_id) > 256:
+        raise PluginError("application_id_invalid", "Application identity is required")
+    owners = sorted(set(owners))
+    if not owners or any(
+        not re.fullmatch(r"[a-z][a-z0-9-]{0,63}", owner) for owner in owners
+    ):
+        raise PluginError("owner_invalid", "Supply stable plugin IDs to provision")
+    manager = names(application_id, database=database)["manager"]
+    stored = json.loads(previous["TOOLFRAME_POSTGRES_STORES"]) if previous else {}
+    manager_password = secrets.token_hex(32)
+    manager_dsn = make_conninfo(
+        admin_dsn, dbname=database, user=manager, password=manager_password
+    )
+    if previous:
+        if previous["TOOLFRAME_POSTGRES_APPLICATION_ID"] != application_id:
+            raise PluginError(
+                "identity_mismatch", "Setup output belongs to a different application"
+            )
+        manager_dsn = previous["TOOLFRAME_POSTGRES_DSN"]
+        parsed = conninfo_to_dict(manager_dsn)
+        if parsed.get("dbname") != database or parsed.get("user") != manager:
+            raise PluginError(
+                "identity_mismatch", "Setup output belongs to a different database"
+            )
+        manager_dsn = make_conninfo(
+            admin_dsn, dbname=database, user=manager, password=parsed["password"]
+        )
+        # Prove that the retained credentials work before touching any existing resource.
+        with psycopg.connect(manager_dsn) as check:
+            identity = check.execute(
+                "SELECT application_id FROM _toolframe_platform.identity"
+            ).fetchall()
+            if identity != [(application_id,)]:
+                raise PluginError(
+                    "identity_mismatch", "Database application identity differs"
+                )
+        for owner, credentials in stored.items():
+            ns = names(application_id, owner, database=database)
+            if credentials.get("user") != ns["controller"]:
+                raise PluginError(
+                    "identity_mismatch",
+                    "Retained store credentials belong to another owner",
+                )
+            with psycopg.connect(make_conninfo(manager_dsn, **credentials)) as check:
+                identity = check.execute(
+                    sql.SQL("SELECT application_id,owner FROM {}.identity").format(
+                        sql.Identifier(ns["metadata"])
+                    )
+                ).fetchall()
+                if identity != [(application_id, owner)]:
+                    raise PluginError("identity_mismatch", "Store identity differs")
+    with psycopg.connect(admin_dsn, autocommit=True) as admin:
+        if admin.info.server_version < 160000:
+            raise PluginError(
+                "postgres_version_unsupported",
+                "Provisioning requires PostgreSQL 16 or newer",
+            )
+        found = admin.execute(
+            "SELECT pg_get_userbyid(datdba) FROM pg_database WHERE datname=%s",
+            (database,),
+        ).fetchone()
+        if found and (not previous or found[0] != manager):
+            raise PluginError(
+                "database_conflict", "Refusing to adopt an existing database"
+            )
+        role(
+            admin,
+            manager,
+            password=manager_password,
+            existing=bool(previous),
+            created=created,
+        )
+        if not found:
+            admin.execute(
+                sql.SQL("CREATE DATABASE {} OWNER {}").format(
+                    sql.Identifier(database), sql.Identifier(manager)
+                )
+            )
+            created.append(("database", database))
+        admin.execute(
+            sql.SQL("REVOKE ALL ON DATABASE {} FROM PUBLIC").format(
+                sql.Identifier(database)
+            )
+        )
+        for owner in owners:
+            ns = names(application_id, owner, database=database)
+            creds = stored.get(owner) or {
+                "user": ns["controller"],
+                "password": secrets.token_hex(32),
+            }
+            role(
+                admin,
+                ns["controller"],
+                password=creds["password"],
+                existing=owner in stored,
+                memberships=(ns["runtime"],),
+                created=created,
+            )
+            role(admin, ns["runtime"], existing=owner in stored, created=created)
+            admin.execute(
+                sql.SQL("GRANT {} TO {} WITH INHERIT FALSE, SET TRUE").format(
+                    sql.Identifier(ns["runtime"]), sql.Identifier(ns["controller"])
+                )
+            )
+            admin.execute(
+                sql.SQL("GRANT CONNECT ON DATABASE {} TO {}").format(
+                    sql.Identifier(database), sql.Identifier(ns["controller"])
+                )
+            )
+            stored[owner] = creds
+    with psycopg.connect(make_conninfo(admin_dsn, dbname=database)) as db:
+        db.execute("REVOKE ALL ON SCHEMA public FROM PUBLIC")
+        db.execute(
+            sql.SQL(
+                "CREATE SCHEMA IF NOT EXISTS _toolframe_platform AUTHORIZATION {}"
+            ).format(sql.Identifier(manager))
+        )
+        db.execute(sql.SQL("SET LOCAL ROLE {}").format(sql.Identifier(manager)))
+        db.execute(
+            "CREATE TABLE IF NOT EXISTS _toolframe_platform.identity(application_id TEXT PRIMARY KEY)"
+        )
+        current = db.execute(
+            "SELECT application_id FROM _toolframe_platform.identity"
+        ).fetchall()
+        if current and current != [(application_id,)]:
+            raise PluginError(
+                "identity_mismatch", "Database application identity differs"
+            )
+        db.execute(
+            "INSERT INTO _toolframe_platform.identity VALUES (%s) ON CONFLICT DO NOTHING",
+            (application_id,),
+        )
+        db.execute("RESET ROLE")
+        for owner in owners:
+            ns = names(application_id, owner, database=database)
+            for key in ("schema", "metadata"):
+                db.execute(
+                    sql.SQL("CREATE SCHEMA IF NOT EXISTS {} AUTHORIZATION {}").format(
+                        sql.Identifier(ns[key]), sql.Identifier(ns["controller"])
+                    )
+                )
+                db.execute(
+                    sql.SQL("REVOKE ALL ON SCHEMA {} FROM PUBLIC").format(
+                        sql.Identifier(ns[key])
+                    )
+                )
+                db.execute(
+                    sql.SQL("GRANT USAGE ON SCHEMA {} TO {}").format(
+                        sql.Identifier(ns[key]), sql.Identifier(manager)
+                    )
+                )
+            db.execute(
+                sql.SQL("GRANT USAGE ON SCHEMA {} TO {}").format(
+                    sql.Identifier(ns["schema"]), sql.Identifier(ns["runtime"])
+                )
+            )
+            db.execute(
+                sql.SQL("SET LOCAL ROLE {}").format(sql.Identifier(ns["controller"]))
+            )
+            for who, permissions in (
+                (ns["runtime"], "SELECT, INSERT, UPDATE, DELETE"),
+                (manager, "SELECT"),
+            ):
+                db.execute(
+                    sql.SQL(
+                        "ALTER DEFAULT PRIVILEGES IN SCHEMA {} GRANT {} ON TABLES TO {}"
+                    ).format(
+                        sql.Identifier(ns["schema"]),
+                        sql.SQL(permissions),
+                        sql.Identifier(who),
+                    )
+                )
+                db.execute(
+                    sql.SQL("GRANT {} ON ALL TABLES IN SCHEMA {} TO {}").format(
+                        sql.SQL(permissions),
+                        sql.Identifier(ns["schema"]),
+                        sql.Identifier(who),
+                    )
+                )
+                db.execute(
+                    sql.SQL(
+                        "ALTER DEFAULT PRIVILEGES IN SCHEMA {} GRANT USAGE, SELECT ON SEQUENCES TO {}"
+                    ).format(sql.Identifier(ns["schema"]), sql.Identifier(who))
+                )
+                db.execute(
+                    sql.SQL(
+                        "GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA {} TO {}"
+                    ).format(sql.Identifier(ns["schema"]), sql.Identifier(who))
+                )
+            db.execute(
+                sql.SQL(
+                    "ALTER DEFAULT PRIVILEGES IN SCHEMA {} GRANT SELECT ON TABLES TO {}"
+                ).format(sql.Identifier(ns["metadata"]), sql.Identifier(manager))
+            )
+            db.execute(
+                sql.SQL(
+                    "CREATE TABLE IF NOT EXISTS {}.identity(application_id TEXT NOT NULL, owner TEXT NOT NULL)"
+                ).format(sql.Identifier(ns["metadata"]))
+            )
+            identity = db.execute(
+                sql.SQL("SELECT application_id,owner FROM {}.identity").format(
+                    sql.Identifier(ns["metadata"])
+                )
+            ).fetchall()
+            if identity and identity != [(application_id, owner)]:
+                raise PluginError("identity_mismatch", "Store identity differs")
+            if not identity:
+                db.execute(
+                    sql.SQL("INSERT INTO {}.identity VALUES(%s,%s)").format(
+                        sql.Identifier(ns["metadata"])
+                    ),
+                    (application_id, owner),
+                )
+            db.execute(
+                sql.SQL(
+                    "CREATE TABLE IF NOT EXISTS {}.migrations(position INTEGER PRIMARY KEY, revision TEXT UNIQUE NOT NULL, checksum TEXT NOT NULL)"
+                ).format(sql.Identifier(ns["metadata"]))
+            )
+            db.execute(
+                sql.SQL(
+                    "CREATE TABLE IF NOT EXISTS {}.receipts(id TEXT PRIMARY KEY, fingerprint TEXT NOT NULL, result TEXT NOT NULL)"
+                ).format(sql.Identifier(ns["metadata"]))
+            )
+            db.execute(
+                sql.SQL("GRANT SELECT ON ALL TABLES IN SCHEMA {} TO {}").format(
+                    sql.Identifier(ns["metadata"]), sql.Identifier(manager)
+                )
+            )
+            db.execute("RESET ROLE")
+    return {
+        "TOOLFRAME_POSTGRES_APPLICATION_ID": application_id,
+        "TOOLFRAME_POSTGRES_DSN": manager_dsn,
+        "TOOLFRAME_POSTGRES_STORES": json.dumps(stored, separators=(",", ":")),
+    }

toolframe_sql_postgres/sql.py

@@ -0,0 +1,203 @@
+"""A bounded SQL surface for managed calls; PostgreSQL roles enforce ownership."""
+
+from __future__ import annotations
+
+from pglast import ast, parse_sql
+from pglast.stream import RawStream
+from pglast.visitors import Visitor
+from toolframe_sdk import PluginError
+
+# These are builtins in pg_catalog, which is first in the fixed search_path.
+FUNCTIONS = frozenset(
+    [
+        "abs",
+        "avg",
+        "count",
+        "length",
+        "char_length",
+        "lower",
+        "upper",
+        "min",
+        "max",
+        "sum",
+        "round",
+        "trim",
+        "btrim",
+        "ltrim",
+        "rtrim",
+        "substr",
+        "substring",
+        "replace",
+        "concat",
+        "concat_ws",
+        "greatest",
+        "least",
+        "nullif",
+    ]
+)
+MUTATIONS = (ast.InsertStmt, ast.UpdateStmt, ast.DeleteStmt)
+DDL = (ast.CreateStmt, ast.IndexStmt, ast.AlterTableStmt, ast.DropStmt)
+
+
+def parameters(source: str, count: int) -> str:
+    """Convert SDK qmarks to PostgreSQL AST parameters, respecting SQL quoting."""
+    result = []
+    i = 0
+    position = 0
+    while i < len(source):
+        char = source[i]
+        if source.startswith("--", i):
+            end = source.find("\n", i)
+            end = len(source) if end < 0 else end
+            result.append(source[i:end])
+            i = end
+        elif source.startswith("/*", i):
+            start = i
+            depth = 1
+            i += 2
+            while i < len(source) and depth:
+                if source.startswith("/*", i):
+                    depth += 1
+                    i += 2
+                elif source.startswith("*/", i):
+                    depth -= 1
+                    i += 2
+                else:
+                    i += 1
+            if depth:
+                raise ValueError("Unclosed SQL comment")
+            result.append(source[start:i])
+        elif char in "\"'":
+            start = i
+            quote = char
+            i += 1
+            # Escape-string syntax is outside the SDK parameter contract.
+            if quote == "'" and start and source[start - 1] in "eE":
+                raise ValueError("Use parameters instead of escape-string literals")
+            while i < len(source):
+                if source[i] == quote:
+                    i += 1
+                    if i < len(source) and source[i] == quote:
+                        i += 1
+                        continue
+                    break
+                i += 1
+            else:
+                raise ValueError("Unclosed SQL literal")
+            result.append(source[start:i])
+        elif char == "$":
+            raise ValueError("Use SDK qmark parameters; dollar quoting is unsupported")
+        elif char == "?":
+            position += 1
+            result.append(f"${position}")
+            i += 1
+        else:
+            result.append(char)
+            i += 1
+    if position != count:
+        raise ValueError("SQL parameter count does not match")
+    return "".join(result)
+
+
+class Guard(Visitor):
+    def __init__(self, *, read_only=False, migration=False):
+        self.read_only, self.migration = read_only, migration
+
+    def visit(self, ancestors, node):
+        if self.read_only and isinstance(node, MUTATIONS):
+            raise ValueError("Read-only query cannot mutate")
+        if isinstance(node, ast.RangeVar) and (
+            node.schemaname
+            or node.catalogname
+            or node.relname.startswith(("_toolframe", "pg_"))
+            or node.relpersistence != "p"
+        ):
+            raise ValueError("Use unqualified permanent store-owned tables")
+        if isinstance(node, ast.IndexStmt) and node.concurrent:
+            raise ValueError("Concurrent indexes cannot run in a migration transaction")
+        if isinstance(node, ast.A_Expr) and node.name and len(node.name) != 1:
+            raise ValueError("Qualified operators are outside the SQL contract")
+        if isinstance(node, ast.FuncCall):
+            parts = [part.sval for part in node.funcname]
+            # PostgreSQL lowers standard LIKE ... ESCAPE into this qualified
+            # builtin during parsing. It only transforms the search pattern;
+            # children still pass through the guard (including bound functions).
+            like_escape = (
+                parts == ["pg_catalog", "like_escape"] and len(node.args or ()) == 2
+            )
+            if not like_escape and (
+                len(parts) != 1 or parts[0].lower() not in FUNCTIONS
+            ):
+                raise ValueError("Function is outside the managed SQL contract")
+        if isinstance(node, ast.TypeName):
+            parts = [part.sval for part in node.names]
+            if any(
+                part
+                in {"regclass", "regproc", "regprocedure", "regnamespace", "regrole"}
+                for part in parts
+            ):
+                raise ValueError("Catalog identity casts are unsupported")
+        if isinstance(node, ast.SelectStmt) and (node.intoClause or node.lockingClause):
+            raise ValueError("SELECT INTO and explicit row locking are unsupported")
+        if isinstance(node, ast.DropStmt):
+            for name in node.objects:
+                if len(name) != 1 or name[0].sval.startswith(("_toolframe", "pg_")):
+                    raise ValueError("Only unqualified store objects may be dropped")
+        if isinstance(node, ast.AlterTableCmd) and node.subtype.name not in {
+            "AT_AddColumn",
+            "AT_DropColumn",
+            "AT_AlterColumnType",
+            "AT_SetNotNull",
+            "AT_DropNotNull",
+            "AT_ColumnDefault",
+            "AT_AddConstraint",
+            "AT_DropConstraint",
+            "AT_ValidateConstraint",
+        }:
+            raise ValueError("Unsupported table alteration")
+
+
+def prepare(source: str, values, method: str):
+    try:
+        if not isinstance(source, str) or len(source) > 900_000:
+            raise ValueError
+        tree = parse_sql(parameters(source, len(values)))
+        if len(tree) != 1:
+            raise ValueError("Exactly one SQL statement is required")
+        statement = tree[0].stmt
+        allowed = (ast.SelectStmt,) if method == "query" else MUTATIONS
+        if not isinstance(statement, allowed):
+            raise TypeError("Unsupported SQL statement")
+        Guard(read_only=method == "query")(statement)
+        returning = getattr(statement, "returningClause", None)
+        if method == "execute_returning" and not returning:
+            raise ValueError("Mutation must include RETURNING")
+        if method == "execute" and returning:
+            raise ValueError("Use execute_returning for returned rows")
+        # AsyncRawCursor accepts native $n placeholders and does not reinterpret '%'.
+        return RawStream()(statement), list(values)
+    except Exception:  # noqa: BLE001 - parser diagnostics can contain bound/literal secrets
+        raise PluginError(
+            "sql_not_supported",
+            "SQL is outside the managed PostgreSQL contract or has invalid parameters",
+        ) from None
+
+
+def migration_statements(source):
+    try:
+        statements = parse_sql(source)
+        for raw in statements:
+            if not isinstance(raw.stmt, (*DDL, *MUTATIONS)):
+                raise TypeError
+            if isinstance(raw.stmt, ast.DropStmt) and raw.stmt.removeType.name not in {
+                "OBJECT_TABLE",
+                "OBJECT_INDEX",
+            }:
+                raise ValueError
+            Guard(migration=True)(raw.stmt)
+            yield RawStream()(raw.stmt)
+    except Exception:  # noqa: BLE001 - redact SQL before crossing the RPC boundary
+        raise PluginError(
+            "migration_sql_invalid",
+            "Migration must contain transactional store-local table/index DDL or DML",
+        ) from None

toolframe_sql_postgres-0.2.0.dist-info/METADATA

@@ -0,0 +1,104 @@
+Metadata-Version: 2.5
+Name: toolframe-sql-postgres
+Version: 0.2.0
+Summary: Managed PostgreSQL stores for Toolframe plugins
+Project-URL: Homepage, https://github.com/toolframe/toolframe-sql-postgres
+Project-URL: Repository, https://github.com/toolframe/toolframe-sql-postgres
+Project-URL: Documentation, https://github.com/toolframe/toolframe-sql-postgres#readme
+Project-URL: Issues, https://github.com/toolframe/toolframe-sql-postgres/issues
+Author-email: byfb <62798989+byfb@users.noreply.github.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Requires-Python: >=3.14
+Requires-Dist: pglast==8.4
+Requires-Dist: psycopg[binary]<4,>=3.3
+Requires-Dist: toolframe-sdk==0.4.0
+Description-Content-Type: text/markdown
+
+# Toolframe PostgreSQL storage
+
+`sql-postgres` stores Toolframe plugin data in PostgreSQL. Entry Register,
+Auth, MCP Auth and OIDC Auth use a separate schema per plugin inside one database
+per application environment. Database access is loaded **only from the runtime
+process environment**; credentials do not belong in `toolframe.toml`.
+
+This release requires Toolframe SDK 0.4 and Core 0.7. Run one Core per
+application. Core 0.7 can separately store its management journal in a dedicated
+PostgreSQL database; SQLite remains the default. Configuration, private keys and
+artifacts still need a persistent application home. PostgreSQL storage does not
+make Core stateless or enable multiple replicas.
+Existing SQLite data is not imported. Plugins are trusted Python code.
+
+## Quick start
+
+Use Python 3.14+, PostgreSQL 16+, and `pg_dump` / `pg_restore` with the **same major
+version** as the server. PostgreSQL 16 is the integration-test baseline.
+
+Install the host and provider CLI from PyPI:
+
+```sh
+uv venv --python 3.14.7 .venv
+uv pip install --python .venv/bin/python \
+  toolframe-core==0.7.0 toolframe-sql-postgres==0.2.0
+.venv/bin/toolframe-core --home ./app init
+```
+
+Read `[application].id` from `app/toolframe.toml`. Supply an administrator DSN from
+your secret manager as `TOOLFRAME_POSTGRES_SETUP_DSN`. It is used only by setup.
+The CLI output file contains generated runtime credentials and must remain private.
+
+```sh
+.venv/bin/toolframe-postgres setup \
+  --application-id '<id from app/toolframe.toml>' \
+  --database toolframe_development \
+  --owner entry-register --owner auth --owner mcp-auth --owner oidc-auth \
+  --output ./app/.toolframe/postgres-environment.json
+unset TOOLFRAME_POSTGRES_SETUP_DSN
+```
+
+Add the provider to `app/toolframe.toml`:
+
+```toml
+[plugins.sql-postgres]
+source = "pypi:toolframe-sql-postgres==0.2.0"
+enabled = true
+
+[bindings]
+"toolframe.sql" = "sql-postgres"
+```
+
+This configuration sends every SQL consumer to PostgreSQL. Core builds with
+multiple SQL provider support can also run SQLite, using an explicit per-plugin
+override such as `"entry-register/sql" = "sql-sqlite"` in `[bindings]`.
+Choose bindings before initializing stores: changing a retained store's provider
+is rejected and does not copy data. Earlier Core builds require one enabled
+storage provider. The package version alone does not identify multiple-provider
+support; build the matching Core revision when using mixed providers.
+
+Install the matching business plugins
+before enabling them: Entry Register 0.4, Auth 0.3, MCP Auth 0.3 and OIDC Auth 0.3.
+Each store owner must be provisioned before Core starts its plugin.
+
+```sh
+.venv/bin/toolframe-postgres run \
+  --env-file ./app/.toolframe/postgres-environment.json -- \
+  .venv/bin/toolframe-core --home ./app serve
+```
+
+The `run` helper exports the private document as environment variables and replaces
+itself with Core. It removes setup/test administrator variables. Containers can
+inject the same runtime values directly; the provider does not read that file.
+
+- [Setup, environment and recovery](docs/operations.md)
+- [SQL and isolation contract](docs/storage-contract.md)
+- [Development and verification](docs/development.md)
+- [Domain glossary](docs/glossary.md) and [architecture decisions](docs/adr/0001-plugin-storage-boundary.md)
+
+For release validation and Trusted Publisher setup, see [releasing](docs/releasing.md).
+
+## License
+
+Apache-2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).
+
+For development hooks and contribution rules, see [Contributing](CONTRIBUTING.md).

toolframe_sql_postgres-0.2.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+toolframe_sql_postgres/__init__.py,sha256=yxb8kdJcYr5KWyUPPSiS5ESBye1Hqq1tID5GSux87jU,81
+toolframe_sql_postgres/backup.py,sha256=37i1N8YJQNraBHr1J6rAjDLn6ZUe7ytSz3Z1E65nP6o,5538
+toolframe_sql_postgres/cli.py,sha256=0UoyIDX564pNVFZlSi5TS5GbvSu8P1NwkhZP14lCLo0,8079
+toolframe_sql_postgres/config.py,sha256=PZLvDVsMHTMwFxknTQ1KLsG8dD8_UF1R6m_017sD030,3699
+toolframe_sql_postgres/plugin.py,sha256=089XX0DJXcHOp50Ot886pdrmt41SGVzDyHEen0zggCo,23748
+toolframe_sql_postgres/provision.py,sha256=rxrang9Tvgq6dsBJ636lG0GZLrgY8da2G2sDumHZR4Q,14568
+toolframe_sql_postgres/sql.py,sha256=_EsmE8mUCnsgoUJLg-xk377zBCb66t6587vnecYlf20,7805
+toolframe_sql_postgres-0.2.0.dist-info/METADATA,sha256=f0IPQ4hSITRYtEhCByARpdIotfO-Ok-uFMp1T5TJ6EQ,4297
+toolframe_sql_postgres-0.2.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+toolframe_sql_postgres-0.2.0.dist-info/entry_points.txt,sha256=tE0jNFs0Go3xlOk0fCPxWM8mlnVmMIqTiCSdwOwAgsI,144
+toolframe_sql_postgres-0.2.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+toolframe_sql_postgres-0.2.0.dist-info/licenses/NOTICE,sha256=NJT1YiIiAYUGjix9VOzO18OJRNb8NeCSd5XkbU7VJhw,43
+toolframe_sql_postgres-0.2.0.dist-info/RECORD,,

toolframe_sql_postgres-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

toolframe_sql_postgres-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+toolframe-postgres = toolframe_sql_postgres.cli:main
+
+[toolframe.plugins]
+sql-postgres = toolframe_sql_postgres.plugin:plugin