Skip to content
Effect Days 2026 Get your ticket

SqlMessageStorage

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.

Request deduplication keys that exceed the 255-character message_id column are hashed with the Crypto 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.

4 exports Added in v4.0.0 Source

Constructors

make

Added in v4.0.0 Source

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

makeEncoded

Added in v4.0.0 Source

Creates 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 MessageStorage constructor

Signature

declare const makeEncoded: (options?: {
  readonly prefix?: string;
}) => Effect.Effect<MessageStorage.Encoded, never, SqlClient.SqlClient | Crypto.Crypto>

Layers

layer

Added in v4.0.0 Source

Layer that provides SQL-backed MessageStorage using the default table prefix and the default snowflake generator.

When to use

Use when a cluster should persist mailbox messages and replies in SQL using the default cluster table prefix and the standard snowflake generator.

Details

The layer runs the SQL migrations through make, provides MessageStorage, and supplies Snowflake.layerGenerator internally. Callers still provide SqlClient, ShardingConfig, and Crypto.Crypto, which is used to hash message deduplication keys that would overflow the fixed-width message_id column.

Gotchas

This layer always uses the cluster table prefix. Use layerWith before deployment if you need a different stable prefix, because changing prefixes later points the runtime at a different set of tables.

See

  • layerWith for the same SQL storage layer with a custom table prefix
  • make for the lower-level service constructor that uses an existing Snowflake.Generator

Signature

declare const layer: Layer.Layer<MessageStorage.MessageStorage, never, SqlClient.SqlClient | ShardingConfig | Crypto.Crypto>

layerWith

Added in v4.0.0 Source

Layer that provides SQL-backed MessageStorage using a custom table prefix.

Signature

declare function layerWith(options: {
  readonly prefix?: string;
}): Layer<MessageStorage, never, Crypto | ShardingConfig | SqlClient>