Skip to content
Effect Days 2026 Get your ticket

SqlRunnerStorage

Stores cluster runner registration and shard ownership in SQL.

The SQL-backed RunnerStorage records runners, health flags, machine ids, and shard locks so multiple processes can coordinate which runner owns each shard. This module creates the required runner and lock tables, supports an optional table prefix, uses advisory locks for PostgreSQL and MySQL when enabled, and provides constructors and layers for the storage service.

3 exports Added in v4.0.0 Source

Constructors

make

Added in v4.0.0 Source

Creates a SQL-backed RunnerStorage implementation for registered runners and shard locks, using the configured table prefix and advisory locks where supported and enabled.

When to use

Use to create a SQL-backed RunnerStorage value directly when building custom service or layer composition around the storage implementation.

Details

When prefix is omitted, make uses the cluster prefix, creating cluster_runners and cluster_locks. PostgreSQL and MySQL use advisory locks unless ShardingConfig.shardLockDisableAdvisory is enabled; other dialects use rows in the locks table.

Gotchas

Changing prefix changes both generated table names, so runners using different prefixes do not share registrations or shard locks.

See

  • layer for the default SQL-backed storage layer
  • layerWith for a SQL-backed storage layer with a custom table prefix

Signature

declare const make: (...args: [options: {
  readonly prefix?: string;
}]) => Effect

Layers

layer

Added in v4.0.0 Source

Layer that provides SQL-backed RunnerStorage using the default table prefix.

Signature

declare const layer: Layer.Layer<RunnerStorage.RunnerStorage, SqlError, SqlClient.SqlClient | ShardingConfig.ShardingConfig>

layerWith

Added in v4.0.0 Source

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

Signature

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