Belay.Storage.Postgres (Belay v1.0.0)

Copy Markdown View Source

Postgres storage over Postgrex — no Ecto. Claims use FOR UPDATE SKIP LOCKED; workflow settlement and parent notification happen inside the acking transaction; uniqueness is enforced by partial unique indexes; the clock is always a query parameter, never now().

Summary

Functions

ensure_database!(url)

Create the database if missing (connects to the postgres db).

migrate!(url)

Create or update the schema (idempotent).

parse_url(url)

Convert a PostgreSQL URL into Postgrex options.

reset!(url)

Drop and recreate the schema (tests only).

truncate!(ref)

Truncate all Belay tables (tests).

Functions

ensure_database!(url)

@spec ensure_database!(String.t()) :: :ok

Create the database if missing (connects to the postgres db).

migrate!(url)

@spec migrate!(String.t()) :: :ok

Create or update the schema (idempotent).

Migrations are serialized with a transaction-scoped advisory lock, so multiple application nodes may run this concurrently during a deploy.

parse_url(url)

@spec parse_url(String.t()) :: keyword()

Convert a PostgreSQL URL into Postgrex options.

Credentials and database names are percent-decoded. TLS follows libpq's sslmode meaning rather than collapsing every mode to one boolean:

  • disable → no TLS
  • require (also ssl=true) → encrypt without certificate verification (ssl: [verify: :verify_none]), matching libpq — so a managed-Postgres URL like ?sslmode=require connects without needing the server's CA in your trust store
  • verify-ca / verify-full → verified TLS (ssl: true), which in current Postgrex checks the certificate chain against the system CA store; provide cacerts: via an explicit ssl: option if your CA is not there
  • allow / prefer → rejected (they need TLS fallback negotiation Postgrex does not implement)

Explicit storage options are merged after these URL-derived options by child_spec/1, so callers may override with a custom ssl: keyword list, socket options, timeouts, or other Postgrex settings.

reset!(url)

@spec reset!(String.t()) :: :ok

Drop and recreate the schema (tests only).

truncate!(ref)

@spec truncate!(GenServer.server()) :: :ok

Truncate all Belay tables (tests).