Skip to content

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.

@stability ― unstable

@category ― layers

@since ― 4.0.0

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>"

@see ― String for non-secret string settings

@stability ― stable

@category ― constructors

@since ― 2.0.0

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 layers
const 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 Logger
const 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 together
const allServicesLayer = userServiceLayer.pipe(
Layer.provideMerge(Layer.mergeAll(databaseLayer, loggerLayer))
)
// Now the resulting layer provides UserService, Database, AND Logger
const 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"]

@see ― provide for keeping dependency services private

@stability ― stable

@category ― providing services

@since ― 2.0.0

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 layers
const 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 Logger
const 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 layer
const userServiceWithDependencies = userServiceLayer.pipe(
Layer.provide(Layer.mergeAll(databaseLayer, loggerLayer))
)
// Now UserService layer has no dependencies
const 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"]

@see ― provideMerge for retaining the dependency services

@stability ― stable

@category ― providing services

@since ― 2.0.0

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

.

@stability ― unstable

@category ― layers

@since ― 4.0.0

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 layers
const 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 Logger
const 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 together
const allServicesLayer = userServiceLayer.pipe(
Layer.provideMerge(Layer.mergeAll(databaseLayer, loggerLayer))
)
// Now the resulting layer provides UserService, Database, AND Logger
const 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"]

@see ― provide for keeping dependency services private

@stability ― stable

@category ― providing services

@since ― 2.0.0

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.

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.

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.