Deploy and operate
PostgreSQL
PostgreSQL stores history and accepted work using your application’s Effect SQL client. Your host must route each Thread to one live process. The adapter does not provide distributed ownership, lease-based takeover, or a worker service.
import { import NodeCrypto
NodeCrypto } from "@effect/platform-node";import { import PgClient
PgClient } from "@effect/sql-pg";import { import PersistentHistory
PersistentHistory } from "@yielded/agent";import { import PostgresStorage
PostgresStorage } from "@yielded/agent-storage-postgres";import { import Config
Config, import Layer
Layer } from "effect";
const const Database: Layer.Layer<PgClient.PgClient | SqlClient, Config.ConfigError | SqlError, never>
Database = import PgClient
PgClient.const layerConfig: <never>(config: { readonly idleTimeout?: Config.Config<Input | undefined> | undefined; readonly maxConnections?: Config.Config<number | undefined> | undefined; readonly minConnections?: Config.Config<number | undefined> | undefined; readonly connectionTTL?: Config.Config<Input | undefined> | undefined; readonly acquireTimeout?: Config.Config<Input | undefined> | undefined; readonly url?: { readonly label: Config.Config<string | undefined>; readonly "~effect/Redacted": { ...; } | Config.Config<...>; readonly "~effect/Equal": Config.Config<...>; readonly "~effect/Hash": Config.Config<...>; readonly pipe: Config.Config<...>; } | Config.Config<...> | undefined; ... 23 more ...; readonly onAcquire?: Config.Config<...> | undefined;} | Config.Config<...>) => Layer.Layer<...>
Creates a client layer from wrapped pool configuration.
layerConfig({ url?: { readonly label: Config.Config<string | undefined>; readonly "~effect/Redacted": { readonly _A: Config.Config<Covariant<string>>; } | Config.Config<{ readonly _A: Covariant<string>; }>; readonly "~effect/Equal": Config.Config<(that: Equal) => boolean>; readonly "~effect/Hash": Config.Config<() => number>; readonly pipe: Config.Config<{ <A>(this: A): A; <A, B = never>(this: A, ab: (_: A) => B): B; <A, B = never, C = never>(this: A, ab: (_: A) => B, bc: (_: B) => C): C; <A, B = never, C = never, D = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D): D; <A, B = never, C = never, D = never, E = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D, de: (_: D) => E): E; <A, B = never, C = never, D = never, E = never, F = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D, de: (_: D) => E, ef: (_: E) => F): F; <A, B = never, C = never, D = never, E = never, F = never, G = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D, de: (_: D) => E, ef: (_: E) => F, fg: (_: F) => G): G; <A, B = never, C = never, D = never, E = never, F = never, G = never, H = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D, de: (_: D) => E, ef: (_: E) => F, fg: (_: F) => G, gh: (_: G) => H): H; <A, B = never, C = never, D = never, E = never, F = never, G = never, H = never, I = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D, de: (_: D) => E, ef: (_: E) => F, fg: (_: F) => G, gh: (_: G) => H, hi: (_: H) => I): I; <A, B = never, C = never, D = never, E = never, F = never, G = never, H = never, I = never, J = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D, de: (_: D) => E, ef: (_: E) => F, fg: (_: F) => G, gh: (_: G) => H, hi: (_: H) => I, ij: (_: I) => J): J; <A, B = never, C = never, D = never, E = never, F = never, G = never, H = never, I = never, J = never, K = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D, de: (_: D) => E, ef: (_: E) => F, fg: (_: F) => G, gh: (_: G) => H, hi: (_: H) => I, ij: (_: I) => J, jk: (_: J) => K): K; <A, B = never, C = never, D = never, E = never, F = never, G = never, H = never, I = never, J = never, K = never, L = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D, de: (_: D) => E, ef: (_: E) => F, fg: (_: F) => G, gh: (_: G) => H, hi: (_: H) => I, ij: (_: I) => J, jk: (_: J) => K, kl: (_: K) => L): L; <A, B = never, C = never, D = never, E = never, F = never, G = never, H = never, I = never, J = never, K = never, L = never, M = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D, de: (_: D) => E, ef: (_: E) => F, fg: (_: F) => G, gh: (_: G) => H, hi: (_: H) => I, ij: (_: I) => J, jk: (_: J) => K, kl: (_: K) => L, lm: (_: L) => M): M; <A, B = never, C = never, D = never, E = never, F = never, G = never, H = never, I = never, J = never, K = never, L = never, M = never, N = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D, de: (_: D) => E, ef: (_: E) => F, fg: (_: F) => G, gh: (_: G) => H, hi: (_: H) => I, ij: (_: I) => J, jk: (_: J) => K, kl: (_: K) => L, lm: (_: L) => M, mn: (_: M) => N): N; <A, B = never, C = never, D = never, E = never, F = never, G = never, H = never, I = never, J = never, K = never, L = never, M = never, N = never, O = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D, de: (_: D) => E, ef: (_: E) => F, fg: (_: F) => G, gh: (_: G) => H, hi: (_: H) => I, ij: (_: I) => J, jk: (_: J) => K, kl: (_: K) => L, lm: (_: L) => M, mn: (_: M) => N, no: (_: N) => O): O; <A, B = never, C = never, D = never, E = never, F = never, G = never, H = never, I = never, J = never, K = never, L = never, M = never, N = never, O = never, P = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D, de: (_: D) => E, ef: (_: E) => F, fg: (_: F) => G, gh: (_: G) => H, hi: (_: H) => I, ij: (_: I) => J, jk: (_: J) => K, kl: (_: K) => L, lm: (_: L) => M, mn: (_: M) => N, no: (_: N) => O, op: (_: O) => P): P; <A, B = never, C = never, D = never, E = never, F = never, G = never, H = never, I = never, J = never, K = never, L = never, M = never, N = never, O = never, P = never, Q = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D, de: (_: D) => E, ef: (_: E) => F, fg: (_: F) => G, gh: (_: G) => H, hi: (_: H) => I, ij: (_: I) => J, jk: (_: J) => K, kl: (_: K) => L, lm: (_: L) => M, mn: (_: M) => N, no: (_: N) => O, op: (_: O) => P, pq: (_: P) => Q): Q; <A, B = never, C = never, D = never, E = never, F = never, G = never, H = never, I = never, J = never, K = never, L = never, M = never, N = never, O = never, P = never, Q = never, R = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D, de: (_: D) => E, ef: (_: E) => F, fg: (_: F) => G, gh: (_: G) => H, hi: (_: H) => I, ij: (_: I) => J, jk: (_: J) => K, kl: (_: ...
url: import Config
Config.function Redacted(name?: string): Config.Config<import("effect/Redacted").Redacted<string>>
Creates a config for a redacted string value. The parsed result is wrapped
in a Redacted container that hides the value from logs and toString.
When to use
Use to read secret string settings that should not be exposed in logs or
string output.
Details
Shortcut for Config.schema(Schema.Redacted(Schema.String), name).
Example (Reading a secret)
import { Config, ConfigProvider, Effect } from "effect"
const program = Config.Redacted("API_KEY").pipe(Effect.map(String))
const provider = ConfigProvider.fromEnv({ env: { API_KEY: "sk-1234567890abcdef" }})
Effect.runSync( program.pipe(Effect.provideService(ConfigProvider.ConfigProvider, provider))) // => "<redacted>"
Redacted("DATABASE_URL"),});
const const Persistence: Layer.Layer<PgClient.PgClient | SqlClient | ThreadReader | ThreadStore | StorageOwner | ThreadImport | SubmissionLedger | SettlementPublisher, Config.ConfigError | SqlError | PostgresStorageError | PostgresStorageCompatibilityError | PostgresStorageCorruptionError | PostgresWriteContention, never>
Persistence = import PostgresStorage
PostgresStorage.const layer: Layer.Layer<ThreadReader | ThreadStore | StorageOwner | ThreadImport | SubmissionLedger | SettlementPublisher, PostgresStorageError | PostgresStorageCompatibilityError | PostgresStorageCorruptionError | PostgresWriteContention, SqlClient | Digest | SecureRandom>
Thread history and submissions with default settings. Requires SqlClient, Digest, and SecureRandom.
SQL text parameters, including identities, must exclude NUL and unpaired UTF-16
surrogates. Canonical JSON payload strings remain intact through escaped encoding.
layer.Pipeable.pipe<Layer.Layer<ThreadReader | ThreadStore | StorageOwner | ThreadImport | SubmissionLedger | SettlementPublisher, PostgresStorageError | PostgresStorageCompatibilityError | PostgresStorageCorruptionError | PostgresWriteContention, SqlClient | Digest | SecureRandom>, Layer.Layer<...>, Layer.Layer<...>>(this: Layer.Layer<...>, ab: (_: Layer.Layer<...>) => Layer.Layer<...>, bc: (_: Layer.Layer<...>) => Layer.Layer<...>): Layer.Layer<...> (+21 overloads)
pipe( import Layer
Layer.const provideMerge: <never, Config.ConfigError | SqlError, PgClient.PgClient | SqlClient>(that: Layer.Layer<PgClient.PgClient | SqlClient, Config.ConfigError | SqlError, never>) => <RIn2, E2, ROut2>(self: Layer.Layer<ROut2, E2, RIn2>) => Layer.Layer<PgClient.PgClient | SqlClient | ROut2, Config.ConfigError | SqlError | E2, Exclude<RIn2, PgClient.PgClient | SqlClient>> (+3 overloads)
Feeds the output services of the dependency layer into the requirements of
this layer, returning a layer that provides both sets of services.
When to use
Use when you need to compose Layers while keeping both the constructed
service and the dependency used to build it available.
Details
Prefer
provide
when the dependency should stay private.
Example (Providing dependencies while retaining services)
import { Context, Effect, Layer } from "effect"
class Database extends Context.Service<Database, { readonly query: (sql: string) => Effect.Effect<string>}>()("Database") {}
class Logger extends Context.Service<Logger, { readonly log: (msg: string) => Effect.Effect<void>}>()("Logger") {}
class UserService extends Context.Service<UserService, { readonly getUser: (id: string) => Effect.Effect<{ id: string name: string }>}>()("UserService") {}
// Create dependency layersconst databaseLayer = Layer.succeed(Database, { query: Effect.fn("Database.query")((sql: string) => Effect.succeed(`DB: ${sql}`))})
const logs: Array<string> = []const loggerLayer = Layer.succeed(Logger, { log: Effect.fn("Logger.log")((msg: string) => Effect.sync(() => logs.push(`[LOG] ${msg}`)))})
// UserService depends on Database and Loggerconst userServiceLayer = Layer.effect(UserService, Effect.gen(function*() { const database = yield* Database const logger = yield* Logger
return { getUser: Effect.fn("UserService.getUser")(function*(id: string) { yield* logger.log(`Looking up user ${id}`) const result = yield* database.query( `SELECT * FROM users WHERE id = ${id}` ) return { id, name: result } }) }}))
// Provide dependencies and merge all services togetherconst allServicesLayer = userServiceLayer.pipe( Layer.provideMerge(Layer.mergeAll(databaseLayer, loggerLayer)))
// Now the resulting layer provides UserService, Database, AND Loggerconst program = Effect.gen(function*() { const userService = yield* UserService const logger = yield* Logger // Still available! const database = yield* Database // Still available!
const user = yield* userService.getUser("123") yield* logger.log(`Found user: ${user.name}`)
return user}).pipe( Effect.provide(allServicesLayer))Effect.runSync(program) // => { id: "123", name: "DB: SELECT * FROM users WHERE id = 123" }logs // => ["[LOG] Looking up user 123", "[LOG] Found user: DB: SELECT * FROM users WHERE id = 123"]
provideMerge(const Database: Layer.Layer<PgClient.PgClient | SqlClient, Config.ConfigError | SqlError, never>
Database), import Layer
Layer.const provide: <never, never, Digest | SecureRandom | Mac | Kdf | Aead | Cipher | Signature | KeyAgreement | KeyWrap>(that: Layer.Layer<Digest | SecureRandom | Mac | Kdf | Aead | Cipher | Signature | KeyAgreement | KeyWrap, never, never>) => <RIn2, E2, ROut2>(self: Layer.Layer<ROut2, E2, RIn2>) => Layer.Layer<ROut2, E2, Exclude<RIn2, Digest | ... 7 more ... | KeyWrap>> (+3 overloads)
Feeds the output services of the dependency layer into the requirements of
this layer, returning a layer that only provides the services from this layer.
When to use
Use when you need to hide an implementation dependency layer from callers.
Details
In serviceLayer.pipe(Layer.provide(dependencyLayer)), the dependency layer is
built first and is used to satisfy the requirements of serviceLayer.
Example (Providing layer dependencies)
import { Context, Effect, Layer } from "effect"
class Database extends Context.Service<Database, { readonly query: (sql: string) => Effect.Effect<string>}>()("Database") {}
class UserService extends Context.Service<UserService, { readonly getUser: (id: string) => Effect.Effect<{ id: string name: string }>}>()("UserService") {}
class Logger extends Context.Service<Logger, { readonly log: (msg: string) => Effect.Effect<void>}>()("Logger") {}
// Create dependency layersconst databaseLayer = Layer.succeed(Database, { query: Effect.fn("Database.query")((sql: string) => Effect.succeed(`DB: ${sql}`))})
const logs: Array<string> = []const loggerLayer = Layer.succeed(Logger, { log: Effect.fn("Logger.log")((msg: string) => Effect.sync(() => logs.push(`[LOG] ${msg}`)))})
// UserService depends on Database and Loggerconst userServiceLayer = Layer.effect(UserService, Effect.gen(function*() { const database = yield* Database const logger = yield* Logger
return { getUser: Effect.fn("UserService.getUser")(function*(id: string) { yield* logger.log(`Looking up user ${id}`) const result = yield* database.query( `SELECT * FROM users WHERE id = ${id}` ) return { id, name: result } }) }}))
// Provide dependencies to UserService layerconst userServiceWithDependencies = userServiceLayer.pipe( Layer.provide(Layer.mergeAll(databaseLayer, loggerLayer)))
// Now UserService layer has no dependenciesconst program = Effect.gen(function*() { const userService = yield* UserService return yield* userService.getUser("123")}).pipe( Effect.provide(userServiceWithDependencies))Effect.runSync(program) // => { id: "123", name: "DB: SELECT * FROM users WHERE id = 123" }logs // => ["[LOG] Looking up user 123"]
provide(import NodeCrypto
NodeCrypto.const layer: Layer.Layer<Digest | SecureRandom | Mac | Kdf | Aead | Cipher | Signature | KeyAgreement | KeyWrap, never, never>
Layer that provides every effect/crypto service with the Node.js
implementations.
Details
This merges the family layers of this module, so it requires nothing. It
keeps the node:crypto implementations of
layerDigest
,
layerMac
,
layerKdf
, and
layerAead
.
layer),);
const const History: Layer.Layer<PgClient.PgClient | SqlClient | ThreadReader | ThreadStore | StorageOwner | ThreadImport | SubmissionLedger | SettlementPublisher | ThreadHistory, Config.ConfigError | SqlError | PostgresStorageError | PostgresStorageCompatibilityError | PostgresStorageCorruptionError | PostgresWriteContention, never>
History = import PersistentHistory
PersistentHistory.const layer: Layer.Layer<ThreadHistory, never, ThreadStore | StorageOwner>
Provide retained history to the normal AgentRuntime entry points. Each successful Run appends
one three-record batch. Staging is private to that Run; interruption discards it. The scoped
storage owner and the loaded tail reject stale writes without replaying external execution. A storage failure
after append may leave the whole Run recorded. Adapter failpoints cover both durable mutations.
layer.Pipeable.pipe<Layer.Layer<ThreadHistory, never, ThreadStore | StorageOwner>, Layer.Layer<PgClient.PgClient | SqlClient | ThreadReader | ThreadStore | StorageOwner | ThreadImport | SubmissionLedger | SettlementPublisher | ThreadHistory, Config.ConfigError | SqlError | PostgresStorageError | PostgresStorageCompatibilityError | PostgresStorageCorruptionError | PostgresWriteContention, never>>(this: Layer.Layer<...>, ab: (_: Layer.Layer<...>) => Layer.Layer<...>): Layer.Layer<...> (+21 overloads)
pipe(import Layer
Layer.const provideMerge: <never, Config.ConfigError | SqlError | PostgresStorageError | PostgresStorageCompatibilityError | PostgresStorageCorruptionError | PostgresWriteContention, PgClient.PgClient | SqlClient | ThreadReader | ThreadStore | StorageOwner | ThreadImport | SubmissionLedger | SettlementPublisher>(that: Layer.Layer<...>) => <RIn2, E2, ROut2>(self: Layer.Layer<...>) => Layer.Layer<...> (+3 overloads)
Feeds the output services of the dependency layer into the requirements of
this layer, returning a layer that provides both sets of services.
When to use
Use when you need to compose Layers while keeping both the constructed
service and the dependency used to build it available.
Details
Prefer
provide
when the dependency should stay private.
Example (Providing dependencies while retaining services)
import { Context, Effect, Layer } from "effect"
class Database extends Context.Service<Database, { readonly query: (sql: string) => Effect.Effect<string>}>()("Database") {}
class Logger extends Context.Service<Logger, { readonly log: (msg: string) => Effect.Effect<void>}>()("Logger") {}
class UserService extends Context.Service<UserService, { readonly getUser: (id: string) => Effect.Effect<{ id: string name: string }>}>()("UserService") {}
// Create dependency layersconst databaseLayer = Layer.succeed(Database, { query: Effect.fn("Database.query")((sql: string) => Effect.succeed(`DB: ${sql}`))})
const logs: Array<string> = []const loggerLayer = Layer.succeed(Logger, { log: Effect.fn("Logger.log")((msg: string) => Effect.sync(() => logs.push(`[LOG] ${msg}`)))})
// UserService depends on Database and Loggerconst userServiceLayer = Layer.effect(UserService, Effect.gen(function*() { const database = yield* Database const logger = yield* Logger
return { getUser: Effect.fn("UserService.getUser")(function*(id: string) { yield* logger.log(`Looking up user ${id}`) const result = yield* database.query( `SELECT * FROM users WHERE id = ${id}` ) return { id, name: result } }) }}))
// Provide dependencies and merge all services togetherconst allServicesLayer = userServiceLayer.pipe( Layer.provideMerge(Layer.mergeAll(databaseLayer, loggerLayer)))
// Now the resulting layer provides UserService, Database, AND Loggerconst program = Effect.gen(function*() { const userService = yield* UserService const logger = yield* Logger // Still available! const database = yield* Database // Still available!
const user = yield* userService.getUser("123") yield* logger.log(`Found user: ${user.name}`)
return user}).pipe( Effect.provide(allServicesLayer))Effect.runSync(program) // => { id: "123", name: "DB: SELECT * FROM users WHERE id = 123" }logs // => ["[LOG] Looking up user 123", "[LOG] Found user: DB: SELECT * FROM users WHERE id = 123"]
provideMerge(const Persistence: Layer.Layer<PgClient.PgClient | SqlClient | ThreadReader | ThreadStore | StorageOwner | ThreadImport | SubmissionLedger | SettlementPublisher, Config.ConfigError | SqlError | PostgresStorageError | PostgresStorageCompatibilityError | PostgresStorageCorruptionError | PostgresWriteContention, never>
Persistence));Install @yielded/agent-storage-postgres@beta and @effect/sql-pg alongside your
Effect and platform packages. Create the database and set DATABASE_URL in the
host environment. Provide History around AgentRuntime.run, plus model and tool
services, as in the planner example.
Reuse the returned Thread ID for follow-ups.
What is retained
Section titled “What is retained”This history assembly retains each successful Run atomically across restarts; it
does not recover interrupted execution. PostgresStorage.layer also supplies the
Submission ledger and settlement publisher for a
custom durable runtime.
Your application must drive recovery and pending work. The supplied Node host uses SQLite.
Database ownership
Section titled “Database ownership”Share one pool and storage Layer within the owning process. Stop that owner before routing its Threads to a replacement. Database persistence does not transfer live execution authority.
Use PostgresStorage.layerWith(options) to configure storage:
| Option | Default |
|---|---|
schema |
"public" |
observationPollInterval |
25 ms |
lockTimeout |
5000 ms |
verifyOnOpen |
false |
The Layer initializes tables on acquisition. Pre-provisioning the schema avoids requiring database-wide schema creation permission. Storage leaves the client’s search path and application query transforms unchanged.
Before upgrading a storage layout, stop every owner sharing that schema. Open it once with the new release to apply the atomic upgrade, then restart those owners on the same release. Older releases cannot reopen the upgraded layout.
Call storage writes and snapshot reads outside sql.withTransaction; the adapter
owns its transactions. It rejects unsupported layouts and formats.
Keep original stores intact when an open fails.