IF Commons GitHub

physical/schema

Written to: 3 requirements: 3 proved, 0 partly, 0 failing, 0 with no test recorded. 0004-sql-schema FR-001, 0004-sql-schema FR-002, 0004-sql-schema FR-003

The tables and views of a store that merges, made and changed by code: the migrations in order, each one inside one transaction with the version it reaches written in the same transaction, so that a database is at a version or at the one before it and never between. A database of a newer version than the library knows is refused and left as it is, and so is a database of an earlier layout, which is not migrated. The version rows and the blobs are the mergeable tables (a key with ON CONFLICT IGNORE and no row id, so that replaying a dump of them is replaying a union); the facts of the copy, its trust, its epochs and its caches are local and never in a dump; the heads, the files, the siblings and the version vector are views of the rows. The index of search is made where the engine has one (the words of a text in an FTS5 table for SQLite) and the library says whether it did. The statements are written for SQLite and every driver of it; PostgreSQL and DuckDB are refused with a sentence until their layouts are made.

import { migrate } from "./schema.ts";
const done = await migrate(port, naming, { search: "auto" });
done.kind === "ok" && done.value.version; // 3

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

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

migratefunction
function migrate(port: SqlPort, naming: Naming, options?: MigrateOptions): Promise<Result<Migrated, string>>

Brings the database to the latest version of the layout (or to target): each version in its own transaction, the version written with it. A database that is ahead of the library is refused, and so is one of an earlier layout. The index of search is made after the migrations, where the engine has one, and the fact is written.

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

hasSearchfunction
function hasSearch(port: SqlPort, naming: Naming): Promise<boolean>

Whether the database has the table of search.

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

layoutVersionfunction
function layoutVersion(port: SqlPort, naming: Naming): Promise<number>

The version of the layout the database is at: 0 where it has none.

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

MigrateOptionstypeno test imports it
type MigrateOptions = { /** Whether to make the index of search: `auto` makes it where the engine has one, `require` f… (582 characters)
type MigrateOptions = {
  /** Whether to make the index of search: `auto` makes it where the engine has one, `require` fails where it cannot, `off` never makes it. */
  readonly search?: "auto" | "require" | "off";
  /** The version to stop at: the latest where not given. */
  readonly target?: number;
  /** Whether a migration that takes something away may run. */
  readonly destructive?: boolean;
  /** The plan of the migrations: the library's own where not given (a test gives its own to hold the refusal of a destructive step). */
  readonly plan?: typeof MIGRATION_PLAN;
};

What a migration may be asked.

Migratedtypeno test imports it
type Migrated = { readonly from: number; readonly version: number; readonly search: boolean };

What a migration did: the version the database was at, the version it is at, and whether it has the index of search.

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