effect 4.0.2 → 4.0.4

package/src/cluster/SqlMessageStorage.ts

@@ -8,6 +8,11 @@
  * 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` in the runtime.
+ *
  * 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
@@ -24,7 +29,6 @@ import * as Hex from "../encoding/Hex.ts"
 import * as Layer from "../Layer.ts"
 import * as Option from "../Option.ts"
 import type * as PlatformError from "../PlatformError.ts"
-import * as Schedule from "../Schedule.ts"
 import * as Migrator from "../sql/Migrator.ts"
 import * as SqlClient from "../sql/SqlClient.ts"
 import type { Row } from "../sql/SqlConnection.ts"
@@ -73,19 +77,18 @@ export const makeEncoded: (options?: {
   MessageStorage.Encoded,
   never,
   SqlClient.SqlClient | Crypto.Crypto
-> = Effect.fnUntraced(function*(options) {
+> = (options) => Effect.andThen(runMessageMigrations(options), makeEncodedStorage(options))
+
+const makeEncodedStorage = Effect.fnUntraced(function*(
+  options: {
+    readonly prefix?: string | undefined
+  } | undefined
+) {
   const sql = (yield* SqlClient.SqlClient).withoutTransforms()
   const crypto = yield* Crypto.Crypto
   const prefix = options?.prefix ?? "cluster"
   const table = (name: string) => `${prefix}_${name}`
 
-  yield* Effect.orDie(
-    Migrator.make({})({
-      loader: migrations(options),
-      table: table("migrations")
-    })
-  )
-
   const messageKindAckChunk = sql.literal(String(messageKind.AckChunk))
   const messageKindInterrupt = sql.literal(String(messageKind.Interrupt))
   const replyKindWithExit = sql.literal(String(replyKind.WithExit))
@@ -810,69 +813,27 @@ export const make: (options?: {
 > = (options) => Effect.flatMap(makeEncoded(options), MessageStorage.makeEncoded)
 
 /**
- * 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.
+ * Migration loader for the SQL message storage tables.
  *
  * **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 {@link layerWith} for the same SQL storage layer with a custom table prefix
- * @see {@link make} for the lower-level service constructor that uses an existing `Snowflake.Generator`
+ * History is recorded in `<prefix>_migrations`; the default
+ * prefix is `cluster`.
  *
  * @stability unstable
- * @category layers
- * @since 4.0.0
- */
-export const layer: Layer.Layer<
-  MessageStorage.MessageStorage,
-  never,
-  SqlClient.SqlClient | ShardingConfig | Crypto.Crypto
-> = Layer.effect(MessageStorage.MessageStorage, make()).pipe(
-  Layer.provide(Snowflake.layerGenerator)
-)
-
-/**
- * Layer that provides SQL-backed `MessageStorage` using a custom table prefix.
- *
- * @stability unstable
- * @category layers
- * @since 4.0.0
+ * @category migrations
+ * @since 4.1.0
  */
-export const layerWith = (options: {
-  readonly prefix?: string | undefined
-}): Layer.Layer<MessageStorage.MessageStorage, never, SqlClient.SqlClient | ShardingConfig | Crypto.Crypto> =>
-  Layer.effect(MessageStorage.MessageStorage, make(options)).pipe(
-    Layer.provide(Snowflake.layerGenerator)
-  )
-
-// -------------------------------------------------------------------------------------------------
-// internal
-// -------------------------------------------------------------------------------------------------
-
-const migrations = (options?: {
+export const migrations = (options?: {
   readonly prefix?: string | undefined
-}) => {
+}): Migrator.Loader => {
   const prefix = options?.prefix ?? "cluster"
   const table = (name: string) => `${prefix}_${name}`
   const messagesTable = table("messages")
   const repliesTable = table("replies")
 
+  // The migrator serializes PostgreSQL DDL. Propagate errors: retrying in an
+  // aborted transaction cannot succeed.
   return Migrator.fromRecord({
     "0001_create_tables": Effect.gen(function*() {
       const sql = (yield* SqlClient.SqlClient).withoutTransforms()
@@ -956,7 +917,7 @@ const migrations = (options?: {
               deliver_at BIGINT,
               UNIQUE (message_id)
             )
-          `.pipe(Effect.ignore),
+          `,
         orElse: () =>
           // sqlite
           sql`
@@ -1016,18 +977,7 @@ const migrations = (options?: {
               CREATE INDEX IF NOT EXISTS ${sql(requestIdLookupIndex)}
               ON ${messagesTableSql} (request_id)
             `
-          }).pipe(
-            sql.withTransaction,
-            Effect.tapDefect((error) =>
-              Effect.annotateLogs(Effect.logDebug("Failed to create indexes", error), {
-                package: "@effect/cluster",
-                module: "SqlMessageStorage"
-              })
-            ),
-            Effect.retry({
-              schedule: Schedule.spaced(1000)
-            })
-          ),
+          }),
         orElse: () =>
           // sqlite
           Effect.all([
@@ -1121,17 +1071,7 @@ const migrations = (options?: {
           sql`
             CREATE INDEX IF NOT EXISTS ${sql(replyLookupIndex)}
             ON ${repliesTableSql} (request_id, kind, acked);
-          `.pipe(
-            Effect.tapDefect((error) =>
-              Effect.annotateLogs(Effect.logDebug("Failed to create indexes", error), {
-                package: "@effect/cluster",
-                module: "SqlMessageStorage"
-              })
-            ),
-            Effect.retry({
-              schedule: Schedule.spaced(1000)
-            })
-          ),
+          `,
         orElse: () =>
           // sqlite
           sql`
@@ -1180,6 +1120,100 @@ const migrations = (options?: {
   })
 }
 
+const runMessageMigrations = (options?: {
+  readonly prefix?: string | undefined
+}): Effect.Effect<void, never, SqlClient.SqlClient> =>
+  Migrator.make({})({
+    loader: migrations(options),
+    table: `${options?.prefix ?? "cluster"}_migrations`
+  }).pipe(Effect.asVoid, Effect.orDie)
+
+/**
+ * Runs 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.
+ *
+ * @stability unstable
+ * @category layers
+ * @since 4.1.0
+ */
+export const layerMigrations = (options: {
+  readonly prefix?: string | undefined
+}): Layer.Layer<never, never, SqlClient.SqlClient> => Layer.effectDiscard(runMessageMigrations(options))
+
+/**
+ * Provides SQL-backed `MessageStorage` without DDL or startup schema checks.
+ *
+ * **Details**
+ *
+ * Run `layerMigrations` separately before using this layer.
+ * This layer supplies `Snowflake.layerGenerator` internally.
+ *
+ * @stability unstable
+ * @category layers
+ * @since 4.1.0
+ */
+export const layerStorage = (options: {
+  readonly prefix?: string | undefined
+}): Layer.Layer<MessageStorage.MessageStorage, never, SqlClient.SqlClient | ShardingConfig | Crypto.Crypto> =>
+  Layer.effect(
+    MessageStorage.MessageStorage,
+    Effect.flatMap(makeEncodedStorage(options), MessageStorage.makeEncoded)
+  ).pipe(
+    Layer.provide(Snowflake.layerGenerator)
+  )
+
+/**
+ * Provides SQL-backed `MessageStorage` with a custom table prefix,
+ * running migrations first.
+ *
+ * **Details**
+ *
+ * Migration errors become defects. Use `layerMigrations` and `layerStorage`
+ * to migrate separately.
+ *
+ * @stability unstable
+ * @category layers
+ * @since 4.0.0
+ */
+export const layerWith = (options: {
+  readonly prefix?: string | undefined
+}): Layer.Layer<MessageStorage.MessageStorage, never, SqlClient.SqlClient | ShardingConfig | Crypto.Crypto> =>
+  layerStorage(options).pipe(
+    Layer.provide(layerMigrations(options))
+  )
+
+/**
+ * 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.
+ *
+ * @stability unstable
+ * @category layers
+ * @since 4.0.0
+ */
+export const layer: Layer.Layer<
+  MessageStorage.MessageStorage,
+  never,
+  SqlClient.SqlClient | ShardingConfig | Crypto.Crypto
+> = layerWith({})
+
+// -------------------------------------------------------------------------------------------------
+// internal
+// -------------------------------------------------------------------------------------------------
+
 const messageKind = {
   "Request": 0,
   "AckChunk": 1,

package/src/cluster/SqlRunnerStorage.ts

@@ -3,10 +3,15 @@
  *
  * 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
+ * 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.
+ *
  * @stability unstable
  * @since 4.0.0
  */
@@ -17,6 +22,7 @@ import * as Effect from "../Effect.ts"
 import * as Fiber from "../Fiber.ts"
 import * as Layer from "../Layer.ts"
 import * as Scope from "../Scope.ts"
+import * as Migrator from "../sql/Migrator.ts"
 import * as SqlClient from "../sql/SqlClient.ts"
 import type { Connection } from "../sql/SqlConnection.ts"
 import type { SqlError } from "../sql/SqlError.ts"
@@ -41,36 +47,7 @@ const postgresLockNamespace = (prefix: string): number => {
   return hash | 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**
- *
- * 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 {@link layer} for the default SQL-backed storage layer
- * @see {@link layerWith} for a SQL-backed storage layer with a custom table prefix
- *
- * @stability unstable
- * @category constructors
- * @since 4.0.0
- */
-export const make = Effect.fnUntraced(function*(options: {
+const makeStorage = Effect.fnUntraced(function*(options: {
   readonly prefix?: string | undefined
 }) {
   const config = yield* ShardingConfig.ShardingConfig
@@ -183,99 +160,9 @@ export const make = Effect.fnUntraced(function*(options: {
   const runnersTable = table("runners")
   const runnersTableSql = sql(runnersTable)
 
-  yield* sql.onDialectOrElse({
-    mssql: () =>
-      sql`
-        IF OBJECT_ID(N'${runnersTableSql}', N'U') IS NULL
-        CREATE TABLE ${runnersTableSql} (
-          machine_id INT IDENTITY PRIMARY KEY,
-          address VARCHAR(255) NOT NULL,
-          runner TEXT NOT NULL,
-          healthy BIT NOT NULL DEFAULT 1,
-          last_heartbeat DATETIME NOT NULL DEFAULT GETDATE(),
-          UNIQUE(address)
-        )
-      `,
-    mysql: () =>
-      sql`
-        CREATE TABLE IF NOT EXISTS ${runnersTableSql} (
-          machine_id INT AUTO_INCREMENT PRIMARY KEY,
-          address VARCHAR(255) NOT NULL,
-          runner TEXT NOT NULL,
-          healthy BOOLEAN NOT NULL DEFAULT TRUE,
-          last_heartbeat DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
-          UNIQUE(address)
-        )
-      `,
-    pg: () =>
-      sql`
-        CREATE TABLE IF NOT EXISTS ${runnersTableSql} (
-          machine_id SERIAL PRIMARY KEY,
-          address VARCHAR(255) NOT NULL,
-          runner TEXT NOT NULL,
-          healthy BOOLEAN NOT NULL DEFAULT TRUE,
-          last_heartbeat TIMESTAMP NOT NULL DEFAULT NOW(),
-          UNIQUE(address)
-        )
-      `,
-    orElse: () =>
-      // sqlite
-      sql`
-        CREATE TABLE IF NOT EXISTS ${runnersTableSql} (
-          machine_id INTEGER PRIMARY KEY AUTOINCREMENT,
-          address TEXT NOT NULL,
-          runner TEXT NOT NULL,
-          healthy INTEGER NOT NULL DEFAULT 1,
-          last_heartbeat DATETIME NOT NULL DEFAULT (CURRENT_TIMESTAMP),
-          UNIQUE(address)
-        )
-      `
-  })
-
   const locksTable = table("locks")
   const locksTableSql = sql(locksTable)
 
-  yield* sql.onDialectOrElse({
-    mssql: () =>
-      sql`
-        IF OBJECT_ID(N'${locksTableSql}', N'U') IS NULL
-        CREATE TABLE ${locksTableSql} (
-          shard_id VARCHAR(50) PRIMARY KEY,
-          address VARCHAR(255) NOT NULL,
-          acquired_at DATETIME NOT NULL
-        )
-      `,
-    mysql: () =>
-      disableAdvisoryLocks ?
-        sql`
-          CREATE TABLE IF NOT EXISTS ${locksTableSql} (
-            shard_id VARCHAR(50) PRIMARY KEY,
-            address VARCHAR(255) NOT NULL,
-            acquired_at DATETIME NOT NULL
-          )
-        ` :
-        Effect.void,
-    pg: () =>
-      disableAdvisoryLocks ?
-        sql`
-          CREATE TABLE IF NOT EXISTS ${locksTableSql} (
-            shard_id VARCHAR(50) PRIMARY KEY,
-            address VARCHAR(255) NOT NULL,
-            acquired_at TIMESTAMP NOT NULL
-          )
-        ` :
-        Effect.void,
-    orElse: () =>
-      // sqlite
-      sql`
-        CREATE TABLE IF NOT EXISTS ${locksTableSql} (
-          shard_id TEXT PRIMARY KEY,
-          address TEXT NOT NULL,
-          acquired_at DATETIME NOT NULL
-        )
-      `
-  })
-
   const sqlNowString = sql.onDialectOrElse({
     pg: () => "NOW()",
     mysql: () => "NOW()",
@@ -765,20 +652,213 @@ export const make = Effect.fnUntraced(function*(options: {
 }, withTracerDisabled)
 
 /**
- * Layer that provides SQL-backed `RunnerStorage` using the default table prefix.
+ * 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 {@link layer} for the default SQL-backed storage layer
+ * @see {@link layerWith} for a SQL-backed storage layer with a custom table prefix
+ * @see {@link layerStorage} for a storage layer that does not run migrations
  *
  * @stability unstable
- * @category layers
+ * @category constructors
  * @since 4.0.0
  */
-export const layer: Layer.Layer<
-  RunnerStorage.RunnerStorage,
+export const make = (options: {
+  readonly prefix?: string | undefined
+}): Effect.Effect<
+  RunnerStorage.RunnerStorage["Service"],
   SqlError,
-  SqlClient.SqlClient | ShardingConfig.ShardingConfig
-> = Layer.effect(RunnerStorage.RunnerStorage)(make({}))
+  SqlClient.SqlClient | ShardingConfig.ShardingConfig | Scope.Scope
+> => Effect.andThen(runRunnerMigrations(options), makeStorage(options))
 
 /**
- * Layer that provides SQL-backed `RunnerStorage` using a custom table prefix.
+ * 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.
+ *
+ * @stability unstable
+ * @category migrations
+ * @since 4.1.0
+ */
+export const migrations = (options: {
+  readonly prefix?: string | undefined
+}): Migrator.Loader => {
+  const prefix = options.prefix ?? "cluster"
+  const table = (name: string) => `${prefix}_${name}`
+  const runnersTable = table("runners")
+  const locksTable = table("locks")
+
+  return Migrator.fromRecord({
+    // Existing deployments may have these tables but no migration history.
+    "0001_create_tables": Effect.gen(function*() {
+      const sql = (yield* SqlClient.SqlClient).withoutTransforms()
+      const runnersTableSql = sql(runnersTable)
+      const locksTableSql = sql(locksTable)
+
+      yield* sql.onDialectOrElse({
+        mssql: () =>
+          sql`
+            IF OBJECT_ID(N'${runnersTableSql}', N'U') IS NULL
+            CREATE TABLE ${runnersTableSql} (
+              machine_id INT IDENTITY PRIMARY KEY,
+              address VARCHAR(255) NOT NULL,
+              runner TEXT NOT NULL,
+              healthy BIT NOT NULL DEFAULT 1,
+              last_heartbeat DATETIME NOT NULL DEFAULT GETDATE(),
+              UNIQUE(address)
+            )
+          `,
+        mysql: () =>
+          sql`
+            CREATE TABLE IF NOT EXISTS ${runnersTableSql} (
+              machine_id INT AUTO_INCREMENT PRIMARY KEY,
+              address VARCHAR(255) NOT NULL,
+              runner TEXT NOT NULL,
+              healthy BOOLEAN NOT NULL DEFAULT TRUE,
+              last_heartbeat DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+              UNIQUE(address)
+            )
+          `,
+        pg: () =>
+          sql`
+            CREATE TABLE IF NOT EXISTS ${runnersTableSql} (
+              machine_id SERIAL PRIMARY KEY,
+              address VARCHAR(255) NOT NULL,
+              runner TEXT NOT NULL,
+              healthy BOOLEAN NOT NULL DEFAULT TRUE,
+              last_heartbeat TIMESTAMP NOT NULL DEFAULT NOW(),
+              UNIQUE(address)
+            )
+          `,
+        orElse: () =>
+          // sqlite
+          sql`
+            CREATE TABLE IF NOT EXISTS ${runnersTableSql} (
+              machine_id INTEGER PRIMARY KEY AUTOINCREMENT,
+              address TEXT NOT NULL,
+              runner TEXT NOT NULL,
+              healthy INTEGER NOT NULL DEFAULT 1,
+              last_heartbeat DATETIME NOT NULL DEFAULT (CURRENT_TIMESTAMP),
+              UNIQUE(address)
+            )
+          `
+      })
+
+      yield* sql.onDialectOrElse({
+        mssql: () =>
+          sql`
+            IF OBJECT_ID(N'${locksTableSql}', N'U') IS NULL
+            CREATE TABLE ${locksTableSql} (
+              shard_id VARCHAR(50) PRIMARY KEY,
+              address VARCHAR(255) NOT NULL,
+              acquired_at DATETIME NOT NULL
+            )
+          `,
+        mysql: () =>
+          sql`
+            CREATE TABLE IF NOT EXISTS ${locksTableSql} (
+              shard_id VARCHAR(50) PRIMARY KEY,
+              address VARCHAR(255) NOT NULL,
+              acquired_at DATETIME NOT NULL
+            )
+          `,
+        pg: () =>
+          sql`
+            CREATE TABLE IF NOT EXISTS ${locksTableSql} (
+              shard_id VARCHAR(50) PRIMARY KEY,
+              address VARCHAR(255) NOT NULL,
+              acquired_at TIMESTAMP NOT NULL
+            )
+          `,
+        orElse: () =>
+          // sqlite
+          sql`
+            CREATE TABLE IF NOT EXISTS ${locksTableSql} (
+              shard_id TEXT PRIMARY KEY,
+              address TEXT NOT NULL,
+              acquired_at DATETIME NOT NULL
+            )
+          `
+      })
+    })
+  })
+}
+
+const runRunnerMigrations = (options: {
+  readonly prefix?: string | undefined
+}): Effect.Effect<void, never, SqlClient.SqlClient> =>
+  Migrator.make({})({
+    loader: migrations(options),
+    // Message and runner migration ids overlap, so keep separate histories.
+    table: `${options.prefix ?? "cluster"}_runner_migrations`
+  }).pipe(Effect.asVoid, Effect.orDie)
+
+/**
+ * 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`.
+ *
+ * @stability unstable
+ * @category layers
+ * @since 4.1.0
+ */
+export const layerMigrations = (options: {
+  readonly prefix?: string | undefined
+}): Layer.Layer<never, never, SqlClient.SqlClient> => Layer.effectDiscard(runRunnerMigrations(options))
+
+/**
+ * Provides SQL-backed `RunnerStorage` without DDL or startup schema checks.
+ *
+ * **Details**
+ *
+ * Run `layerMigrations` separately before using this layer.
+ *
+ * @stability unstable
+ * @category layers
+ * @since 4.1.0
+ */
+export const layerStorage = (options: {
+  readonly prefix?: string | undefined
+}): Layer.Layer<RunnerStorage.RunnerStorage, never, SqlClient.SqlClient | ShardingConfig.ShardingConfig> =>
+  Layer.effect(RunnerStorage.RunnerStorage)(makeStorage(options))
+
+/**
+ * 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.
  *
  * @stability unstable
  * @category layers
@@ -788,3 +868,19 @@ export const layerWith = (options: {
   readonly prefix?: string | undefined
 }): Layer.Layer<RunnerStorage.RunnerStorage, SqlError, SqlClient.SqlClient | ShardingConfig.ShardingConfig> =>
   Layer.effect(RunnerStorage.RunnerStorage)(make(options))
+
+/**
+ * Layer that provides SQL-backed `RunnerStorage` using the default table prefix,
+ * running the runner storage migrations first.
+ *
+ * @see {@link layerWith} for the same layer with a custom table prefix
+ *
+ * @stability unstable
+ * @category layers
+ * @since 4.0.0
+ */
+export const layer: Layer.Layer<
+  RunnerStorage.RunnerStorage,
+  SqlError,
+  SqlClient.SqlClient | ShardingConfig.ShardingConfig
+> = layerWith({})