SqlStorage

The Storage port over any effect/sql SqlClient, ported from pi-durable’s portable SQLite storage.

Every record is stored as JSON next to the columns its indexes need. A commit runs in one SQL transaction: it reads the metadata row (next sequence, next ID floor), validates the batch against the stored state, writes the rows and advances the metadata, so a rejected or failed batch leaves nothing behind.

Documents keep their content as revisions, each a base (a complete value) or a delta (a JSON Patch), keyed by the commit sequence that wrote them. A read at a point takes the newest base at or before it and replays the deltas after it. Latest-only documents (every scope but rewindable conversation documents) keep no history: a new base or a retirement deletes their older revisions. document.copy (forks, asOf copies) materializes the source inside the commit’s transaction and stores it as the copy’s base.

IDs. mintId hands out candidates from memory, starting at the persisted floor; only committed IDs are protected from reuse, and every commit raises the persisted floor above every ID it wrote or that was minted.

The schema is the SQLite dialect (STRICT tables, json_valid checks); queries avoid dialect-specific syntax. The layer refuses other dialects until they get their own migrations.

import { SqliteClient } from "@effect/sql-sqlite-node"
import { SqlStorage } from "@effective-harness/core"
import * as Layer from "effect/Layer"

const StorageLive = SqlStorage.layer().pipe(Layer.provide(SqliteClient.layer({ filename: "session.sqlite" })))

Since v0.0.0

---

utils

Options (interface)

Options of make and layer.

Signature

export interface Options {
  /** The schema history to apply on open. Default: `migrations`. */
  readonly migrations?: ReadonlyArray<SqlMigration>
}

Source

Since v0.0.0

SqlMigration (interface)

One schema step. Versions are contiguous from 1; all pending steps apply in one transaction.

Signature

export interface SqlMigration {
  readonly version: number
  readonly statements: ReadonlyArray<string>
}

Source

Since v0.0.0

currentSchemaVersion

The schema version this module reads and writes.

Signature

declare const currentSchemaVersion: number

Source

Since v0.0.0

layer

Storage over the SqlClient in context, migrated on build. Closing the layer’s scope closes this handle only; the database belongs to the SqlClient layer, so a new layer over the same database resumes where it stopped.

Signature

declare const layer: (options?: Options) => Layer.Layer<Storage, StorageFailure, SqlClient.SqlClient>

Source

Since v0.0.0

make

Migrate the database, then open a Storage over it. The handle closes with the scope; the database stays with the SqlClient.

Signature

declare const make: (
  options?: Options
) => Effect.Effect<StorageShape, StorageFailure, SqlClient.SqlClient | Scope.Scope>

Source

Since v0.0.0

migrate

Apply every pending migration atomically: all of them, or none when one fails. Repeating it is a no-op. Fails when the database is newer than steps.

Signature

declare const migrate: (steps?: ReadonlyArray<SqlMigration>) => Effect.Effect<void, StorageFailure, SqlClient.SqlClient>

Source

Since v0.0.0

migrations

The immutable, ordered schema history. New migrations are appended after the initial schema.

Signature

declare const migrations: ReadonlyArray<SqlMigration>

Source

Since v0.0.0