Skip to content
Effect 4.0 is here. One ecosystem. Zero dependencies.

SqlRunnerStorage unstable

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

layer, layerWith, and make 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 in the runtime.

6 exports Since v4.0.0 Source

Constructors

make

unstable
Since v4.0.0

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

make first runs the runner storage migrations, so the connection needs permission to create tables. When prefix is omitted, make uses the cluster prefix, creating cluster_runners, cluster_locks, and the cluster_runner_migrations history table. PostgreSQL and MySQL use advisory locks unless ShardingConfig.shardLockDisableAdvisory is enabled; other dialects use rows in the locks table.

Gotchas

Changing prefix changes all 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
  • layerStorage for a storage layer that does not run migrations

Signature

declare function make(options: {
  readonly prefix?: string;
}): Effect<{
  readonly acquire: (address: RunnerAddress, shardIds: Iterable<ShardId>) => Effect<Array<ShardId>, PersistenceError>;
  readonly getRunners: Effect<Array<readonly [Runner, boolean]>, PersistenceError>;
  readonly refresh: (address: RunnerAddress, shardIds: Iterable<ShardId>) => Effect<Array<ShardId>, PersistenceError>;
  readonly register: (runner: Runner, healthy: boolean) => Effect<number & Brand<"~effect/cluster/MachineId">, PersistenceError>;
  readonly release: (address: RunnerAddress, shardId: ShardId) => Effect<void, PersistenceError>;
  readonly releaseAll: (address: RunnerAddress) => Effect<void, PersistenceError>;
  readonly setRunnerHealth: (address: RunnerAddress, healthy: boolean) => Effect<void, PersistenceError>;
  readonly unregister: (address: RunnerAddress) => Effect<void, PersistenceError>;
}, SqlError, Scope | ShardingConfig | SqlClient>

Layers

layer

unstable
Since v4.0.0

Layer that provides SQL-backed RunnerStorage using the default table prefix, running the runner storage migrations first.

See

  • layerWith for the same layer with a custom table prefix

Signature

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

layerMigrations

unstable
Since v4.1.0

Runs the SQL runner 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>_runner_migrations. Migration errors become defects. This layer does not require ShardingConfig.

Signature

declare function layerMigrations(options: {
  readonly prefix?: string;
}): Layer<never, never, SqlClient>

layerStorage

unstable
Since v4.1.0

Provides SQL-backed RunnerStorage without DDL or startup schema checks.

Details

Run layerMigrations separately before using this layer.

Signature

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

layerWith

unstable
Since v4.0.0

Provides SQL-backed RunnerStorage with a custom table prefix, running migrations first.

Details

The connection needs DDL permissions. PostgreSQL takes an exclusive lock on the migration history table. Use layerMigrations and layerStorage to migrate separately.

Signature

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

Migrations

migrations

unstable
Since v4.1.0

Migration loader for the SQL runner storage tables.

Details

History is recorded in <prefix>_runner_migrations; the default prefix is cluster. The locks table is created regardless of advisory lock settings.

Signature

declare function migrations(options: {
  readonly prefix?: string;
}): Loader