IF Commons GitHub

physical/store

Written to: 7 requirements: 7 proved, 0 partly, 0 failing, 0 with no test recorded. 0005-sql-store FR-001, 0005-sql-store FR-002, 0005-sql-store FR-003, 0005-sql-store FR-004, 0005-sql-store FR-005, 0005-sql-store FR-006 and 1 more

The store of a database that merges: a file is the winner among the heads of its path, a set of immutable version rows in the table of versions (each write or delete a new row that replaces the heads of its path, the bytes of a put in the table of blobs under the digest), its revision the digest of its bytes (sha256:, made here so that the same bytes are the same revision in every store), and every operation is one or more statements of the language, run through the port in one transaction. The winner, the siblings and the next id are the pure model's (@intellectual-frontiers/anyfs/merge), applied to the rows of the path; an expectation of a revision or of no file is decided against the winner in the same transaction that writes, so that two writers of one database cannot both win. The store also merges: it says what it holds (the version vector), gives the delta past a vector and takes a delta, whole or not at all. The order of a list is the order of the bytes of the paths, by a range and never by a pattern, so that a path with a percent sign, an underscore or a backslash in it is an ordinary name.

import { openSqlStore } from "./store.ts";
const opened = await openSqlStore(port, { target: "fleet.db" });
if (opened.kind === "ok") await opened.value.store.write(path, bytes, expectAny);

Source: commons/anyfs-sql/src/physical/store.ts

2 of 8 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

openSqlStorefunction
function openSqlStore(port: SqlPort, options?: SqlOptions): Promise<Result<SqlStore, string>>

Opens the store of a database: brings the layout to its version, settles who this copy is and whom it trusts, and gives the store.

Imported by 22 tests of the run (22 passed, 0 failed): the library's results

SQL_CAPABILITIESconstno test imports it
const SQL_CAPABILITIES: readonly ["read", "write", "list", "stat", "delete", "cas", "batch", "rename", "history", "merge"]

The capabilities of every SQL store: those of a store that merges.

SearchableSqlStoretypeno test imports it
type SearchableSqlStore = Store<(typeof SQL_CAPABILITIES)[number] | "search">;

The type of the same store where the engine has search.

SqlFactstypeno test imports it
type SqlFacts = { readonly dialect: SqlDialect; readonly naming: Naming; readonly version: number; readonly search: boolean };

What the store knows of its database.

SqlOptionstypeno test imports it
type SqlOptions = { /** The prefix of the tables and the schema where the database has one. */ readonly naming?: Nam… (1735 characters)
type SqlOptions = {
  /** The prefix of the tables and the schema where the database has one. */
  readonly naming?: NamingOptions;
  /** What the place of the store calls the database: a file name or a label; never a credential. */
  readonly target?: string;
  /** The largest object, in bytes: below the limit of the engine, 64 MiB where not given. */
  readonly maxObject?: number;
  /** The clock that makes ids, in milliseconds. */
  readonly clock?: () => number;
  /** Whether the store has the index of search: `auto` where the engine has one. */
  readonly search?: MigrateOptions["search"];
  /** The most bytes of an object that are indexed for search (1 MiB where not given). */
  readonly searchMaxBytes?: number;
  /** Whether the layout is brought to the latest version (`migrate`, the default) or only checked (`check`: a database at an older version is refused). */
  readonly layout?: "migrate" | "check";
  /** The identity of the replica a new database takes: random where not given. A database that has one keeps it. */
  readonly replica?: ReplicaId;
  /** What tells a copy of the database from the original (the identity of its file): a database whose stored fingerprint is another is a copy and takes a new replica identity. `none` where not given. */
  readonly fingerprint?: string;
  /** Whom the database takes changes and rows from: itself alone where not given. `open` takes any, `allowlist` the replicas named (and itself), `signed` the deltas a verifier accepts. */
  readonly trust?: Trust;
  /** How far ahead of the wall clock an id is taken: five minutes where not given. */
  readonly maxDrift?: number;
  /** What a delta may hold: the defaults where not given. */
  readonly limits?: Limits;
};

What a store is opened with.

SqlSiblingtypeno test imports it
type SqlSibling = { readonly id: string; readonly kind: "put" | "tombstone"; readonly rev: Revision | undefined; readonly replica: ReplicaId };

A sibling: a head of a path that is not the winner.

SqlStoretype
type SqlStore = { readonly store: SqlStoreOf; readonly searchable: SearchableSqlStore | undefined; readonly facts:… (2015 characters)
type SqlStore = {
  readonly store: SqlStoreOf;
  readonly searchable: SearchableSqlStore | undefined;
  readonly facts: SqlFacts;
  /** Who this copy of the database is. */
  readonly replica: ReplicaId;
  /** Where the file was a copy and took a new identity: the identity it had. */
  readonly forkedFrom: ReplicaId | undefined;
  /** The heads of a path that are not the winner. */
  siblings(path: Path): Promise<readonly SqlSibling[]>;
  /** What is wrong with the rows and blobs the database holds, whatever way they came. */
  verify(): Promise<readonly MergeFinding[]>;
  /** How many deltas the database holds back until what they wait for arrives. */
  pending(): Promise<number>;
  /** The index of search made again from the files, after rows were put in by a SQL import. */
  reindex(): Promise<void>;
  /** The log of the engine folded into the file, so that a file copied now is the whole database: `done` for an engine that keeps a log, `not-needed` for one that does not. Closing the port does it too. */
  checkpoint(): Promise<"done" | "not-needed">;
  /** Collects the rows every replica of a roster holds, against what each has reported; refused where a replica of the roster has not reported, and the epoch it writes keeps an old dump from bringing back what was collected. */
  compact(input: CompactInput): Promise<Result<Compacted, string>>;
  /** Takes an epoch another replica made, where this one holds all the rows it covers. */
  adopt(proposal: EpochProposal): Promise<Result<Compacted | "nothing", string>>;
  /** Retires a replica that will not return: it is no longer trusted, and who did it, when and why is written down. */
  retire(replica: ReplicaId, reason: string, at: string): Promise<Result<Retired, string>>;
  /** The replicas that were retired. */
  retired(): Promise<readonly Retired[]>;
  /** The epochs, oldest first. */
  epochs(): Promise<readonly EpochRow[]>;
  /** The context the merge and the dump work in. */
  readonly ctx: Ctx;
  readonly port: SqlPort;
};

An opened store: the store, the same store with search where the engine has it, the facts of the layout, and what a program reads of the replica that the interface of a store does not give.

Imported by 26 tests of the run (26 passed, 0 failed): the library's results

SqlStoreOftypeno test imports it
type SqlStoreOf = Store<(typeof SQL_CAPABILITIES)[number]>;

The type of the store of a database, without search.

Titles, headings, exports, tables, columns and requirements. Esc closes.