SqlMessageStorage unstable
Persists cluster mailbox messages and replies in SQL.
The SQL-backed MessageStorage stores encoded cluster envelopes and reply
chunks so runners can recover mailbox state after restarts. It supports
redelivering unprocessed messages, deduplicating requests by primary key, and
replaying reply chunks until they are acknowledged. This module includes the
storage constructor, layers, migrations, optional table prefixes, and the row
mapping needed by encoded message storage.
layer, layerWith, make, and makeEncoded run the migrations before
building the storage. To run migrations with a different connection, such as
a schema owner in a deploy step, use layerMigrations there and
layerStorage or makeEncodedStorage in the runtime.
Request deduplication keys that exceed the 255-character message_id
column are hashed with the Digest.Digest service before they are written, so
composed keys of any length are supported; shorter keys are stored as
plaintext, byte-compatible with rows written by previous versions.
Constructors
Creates a SQL-backed MessageStorage implementation, running its migrations
and using the optional table prefix.
Signature
declare const make: (options?: { readonly prefix?: string;}) => Effect.Effect<MessageStorage.MessageStorage["Service"], never, SqlClient.SqlClient | Snowflake.Generator | Digest.Digest>makeEncoded
unstableCreates a SQL-backed encoded message storage driver, running its migrations and using the optional table prefix.
When to use
Use when you need the SQL-backed encoded driver directly, such as when composing a custom message storage adapter.
Details
The optional prefix controls the table names for messages, replies, and
migrations; when omitted, cluster is used.
Gotchas
Changing prefix after deployment points the runtime at a different set of
tables, including the migration history table.
See
- make for the decoded
MessageStorageconstructor - makeEncodedStorage for construction without migrations
Signature
declare const makeEncoded: (options?: { readonly prefix?: string;}) => Effect.Effect<MessageStorage.Encoded, never, SqlClient.SqlClient | Digest.Digest>makeEncodedStorage
unstableCreates a SQL-backed encoded message storage driver without running migrations or executing startup SQL.
When to use
Use when composing a custom encoded adapter with a runtime SQL connection that does not have schema-management privileges.
Details
The optional prefix controls the message and reply table names; when omitted,
cluster is used.
Gotchas
Run layerMigrations separately with the same prefix before using the driver.
This constructor does not create tables or check that the schema is up to date.
See
- makeEncoded for construction that runs migrations
- layerMigrations for running migrations separately
- layerStorage for providing decoded storage without migrations
Signature
declare const makeEncodedStorage: (options?: { readonly prefix?: string;}) => Effect.Effect<MessageStorage.Encoded, never, SqlClient.SqlClient | Digest.Digest>Layers
Provides SQL-backed MessageStorage with the cluster table prefix,
running migrations first and supplying Snowflake.layerGenerator.
Details
The connection needs DDL permissions. PostgreSQL takes an exclusive lock
on the migration history table. Use layerWith for a custom prefix or
layerMigrations and layerStorage to migrate separately.
Signature
declare const layer: Layer.Layer<MessageStorage.MessageStorage, never, SqlClient.SqlClient | ShardingConfig | Digest.Digest>layerMigrations
unstableRuns the SQL message storage migrations without providing storage.
Details
Use an owner connection in a deploy step, then use layerStorage with a
DML-only runtime connection. History is recorded in <prefix>_migrations.
Migration errors become defects.
On PostgreSQL, use the role's search_path to select a schema. A
schema-qualified prefix such as app.cluster produces an invalid index name.
Signature
declare function layerMigrations(options: { readonly prefix?: string;}): Layer<never, never, SqlClient>layerStorage
unstableProvides SQL-backed MessageStorage without DDL or startup schema checks.
Details
Run layerMigrations separately before using this layer.
This layer supplies Snowflake.layerGenerator internally.
Signature
declare function layerStorage(options: { readonly prefix?: string;}): Layer<MessageStorage, never, ShardingConfig | SqlClient | Digest>Provides SQL-backed MessageStorage with a custom table prefix,
running migrations first.
Details
Migration errors become defects. Use layerMigrations and layerStorage
to migrate separately.
Signature
declare function layerWith(options: { readonly prefix?: string;}): Layer<MessageStorage, never, ShardingConfig | SqlClient | Digest>Migrations
migrations
unstableMigration loader for the SQL message storage tables.
Details
History is recorded in <prefix>_migrations; the default
prefix is cluster.
Signature
declare function migrations(options?: { readonly prefix?: string;}): Loader