Back a live volume with SQLite
Use SqliteLiveImageStore with LiveVolume.open to commit a complete volume image for each mutation. This is separate from named, create-only SQLite checkpoints.
Install the packages
This example uses Bun and its SQLite provider. Install the persistence package and matching runtime dependencies:
bun add @effect-vfs/persistence@latest
bun add "effect@$(npm view @effect-vfs/persistence@latest peerDependencies.effect)" "@effect/sql-sqlite-bun@$(npm view @effect-vfs/persistence@latest peerDependencies.effect)" "@effect/platform-bun@$(npm view @effect-vfs/persistence@latest peerDependencies.effect)"The persistence package includes @effect-vfs/core.
Write, close, and reopen a volume
Save this as live-volume.ts. The program creates a local directory, writes a file to a live volume, closes it,
and reads the file after reopening the database:
import * as BunCrypto from "@effect/platform-bun/BunCrypto"
import * as BunFileSystem from "@effect/platform-bun/BunFileSystem"
import * as BunPath from "@effect/platform-bun/BunPath"
import { LiveVolume } from "@effect-vfs/core"
import * as SqliteLiveImageStore from "@effect-vfs/persistence/SqliteLiveImageStore"
import * as SqliteClient from "@effect/sql-sqlite-bun/SqliteClient"
import { ByteSize, Effect, FileSystem, Layer, Path } from "effect"
const platform = Layer.mergeAll(BunCrypto.layer, BunFileSystem.layer, BunPath.layer)
const options = {
maxImageBytes: ByteSize.megabytes(4),
volume: { maxBytes: ByteSize.megabytes(1) }
}
const storeFor = (filename: string) =>
SqliteLiveImageStore.layer({
filename,
maxImageBytes: options.maxImageBytes,
maxDatabaseBytes: ByteSize.megabytes(16)
}).pipe(Layer.provide(SqliteClient.layer({ filename, disableWAL: true })))
const program = Effect.gen(function* () {
const fs = yield* FileSystem.FileSystem
const path = yield* Path.Path
const filename = path.resolve("live-data/live.sqlite")
yield* fs.makeDirectory(path.dirname(filename), { recursive: true })
yield* Effect.scoped(
Effect.gen(function* () {
const volume = yield* LiveVolume.open(options)
const caller = yield* volume.caller()
yield* caller.writeFile("/hello.txt", new TextEncoder().encode("hello after reopen"), {
access: "write",
create: "ifMissing",
truncate: true
})
})
).pipe(Effect.provide(storeFor(filename)))
return yield* Effect.scoped(
Effect.gen(function* () {
const volume = yield* LiveVolume.open(options)
return new TextDecoder().decode(yield* (yield* volume.caller()).readFile("/hello.txt"))
})
).pipe(Effect.provide(storeFor(filename)))
})
console.log(await Effect.runPromise(program.pipe(Effect.provide(platform))))Run bun run live-volume.ts. It prints hello after reopen and leaves the database in live-data/.
Each acquisition uses a dedicated SQLite client for the same absolute filename as the store. The first scope closes
its volume before releasing the store and database connection, so the second acquisition can obtain ownership.
The store holds an exclusive SQLite lock while open. A second open through the same acquired store fails with Ownership.
Share live volumes across requests
For several requests to share a volume, replace program in the preceding file with this definition.
It reuses storeFor, options, and platform. Use the absolute database filename as the registry key:
const program = Effect.scoped(
Effect.gen(function* () {
const fs = yield* FileSystem.FileSystem
const path = yield* Path.Path
const filename = path.resolve("live-data/live.sqlite")
yield* fs.makeDirectory(path.dirname(filename), { recursive: true })
const registry = yield* LiveVolume.makeRegistry({
store: storeFor,
volume: options,
capacity: 8,
idleTimeToLive: "5 seconds"
})
return yield* Effect.scoped(
Effect.gen(function* () {
const volume = yield* registry.get(filename)
return yield* (yield* volume.caller()).readDirectory("/")
})
)
})
)The outer scope owns the registry. Each request borrows in a shorter scope. Concurrent borrowers of one key share one acquisition and one volume. Keep the registry alive until all requests finish. Closing its scope shuts down every volume before releasing its store Layer, including volumes with active borrowers.
The idle timeout keeps unused entries available for reuse while retaining their memory and storage locks.
Capacity exhaustion fails with Cause.ExceededCapacityError instead of evicting an idle entry. Canonicalize keys
and use one registry per set of backing stores. The registry coordinates ownership within one process only.
Handle rejected and uncertain commits
The store distinguishes a confirmed rejection from an unknown commit outcome. A confirmed rejection leaves the live volume unchanged. After an unknown outcome, the volume stops serving operations. Close and reopen it before continuing; do not retry writes against the frozen instance.
Provision disk space for both the database and its adjacent DELETE-mode rollback journal. maxDatabaseBytes does not cap peak journal space. For database cap D, page size P, and journal header sector size S, reserve at least D + S + floor(D / P) * (P + 8) bytes, plus filesystem allocation and directory overhead. This bound assumes the SQLite VFS honors the page cap, reports a finite sector size, and runs without ATTACH, VACUUM, external writers, or other SQL that creates disk temporary files. Check those assumptions on the target driver and filesystem. The application must reserve this space on a dedicated filesystem or quota if admission depends on the bound.
Durability qualification
The store has process-restart and recorded VM hard-stop evidence, but not physical power-loss qualification or a guarantee across storage stacks. Volume.durability remains memory-only, and the store must not be used to promise NFS FILE_SYNC4.
For crash-durability experiments, supply syncDatabaseDirectory and verify that it syncs the database's containing directory on the target driver, OS, and filesystem. The store calls it during every startup after verifying the database path and before exposing the store. A working callback alone does not qualify crash or power-loss durability. Validate the SQLite flush behavior, temporary-space assumptions, and recovery gates for the intended deployment. Until then, use this provider for bounded local experiments.
See the SqliteLiveImageStore API reference and LiveVolume API reference for exact options and errors.