Toolframe PostgreSQL storage

storage-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.3 and Core 0.5.3 or 0.6. Run one Core per application. Core 0.6 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:

uv venv --python 3.14.7 .venv
uv pip install --python .venv/bin/python \
  toolframe-core==0.6.2 toolframe-storage-postgres==0.1.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.

.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:

[plugins.storage-postgres]
source = "pypi:toolframe-storage-postgres==0.1.0"
enabled = true

[bindings]
"toolframe.storage.sql" = "storage-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/storage" = "storage-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.3, Auth 0.2, MCP Auth 0.2 and OIDC Auth 0.2. Each store owner must be provisioned before Core starts its plugin.

.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
• SQL and isolation contract
• Development and verification
• Domain glossary and architecture decisions

For release validation and Trusted Publisher setup, see releasing.

License

Apache-2.0. See LICENSE and NOTICE.