@mailwoman/sqlite 9.2.0

package/lib/batched.ts

@@ -0,0 +1,69 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Batched bulk-write transactions — the `COMMIT`/`BEGIN` cadence every streaming ingest repeats around its
+ *   raw prepared-statement loop.
+ */
+
+/**
+ * One open batched transaction over a connection.
+ */
+export interface BatchedTransaction {
+	/**
+	 * Record one written row. Every `rowsPerCommit` rows the open transaction is committed and a new one opened; answers
+	 * `true` on the call that committed, so a caller can hang a progress report off the boundary.
+	 */
+	rowWritten(): boolean
+	/**
+	 * Commit the open transaction — the ordinary end of an ingest loop.
+	 */
+	commit(): void
+	/**
+	 * Best-effort `ROLLBACK`, and it must never replace the real error: a build runs with the journal off (nothing is
+	 * ever published without the swap), so SQLite may refuse to unwind. What matters is that the caller sees WHY the
+	 * ingest stopped, not that a scratch file was tidied.
+	 */
+	rollbackQuietly(): void
+}
+
+/**
+ * Open a transaction that commits and reopens itself every `rowsPerCommit` written rows.
+ *
+ * The batch size is the caller's: a geometry table whose rows carry a blob wants a smaller transaction than a
+ * fixed-width staging table, because a larger one grows the write-ahead file without improving throughput.
+ */
+export function beginBatched(
+	database: { exec(sql: string): void },
+	options: { rowsPerCommit: number }
+): BatchedTransaction {
+	let pending = 0
+
+	database.exec("BEGIN")
+
+	return {
+		rowWritten() {
+			pending++
+
+			if (pending < options.rowsPerCommit) return false
+
+			database.exec("COMMIT")
+			database.exec("BEGIN")
+
+			pending = 0
+
+			return true
+		},
+		commit() {
+			database.exec("COMMIT")
+		},
+		rollbackQuietly() {
+			try {
+				database.exec("ROLLBACK")
+			} catch {
+				// The temp artifact is discarded either way.
+			}
+		},
+	}
+}

package/lib/client.ts

@@ -0,0 +1,163 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+
+import {
+	DatabaseSync,
+	type DatabaseSyncOptions,
+	type FunctionOptions,
+	type SQLInputValue,
+	type SQLOutputValue,
+	type StatementSync,
+} from "node:sqlite"
+
+import { Kysely, type KyselyConfig } from "kysely"
+import { PathBuilder, type PathBuilderLike } from "path-ts"
+
+import type { Database } from "#database-schema"
+import { SqliteDialect } from "#dialect"
+import type { SqliteDialectConfig } from "#dialect-config"
+
+/**
+ * A SQLite client for one database file: a Kysely query builder over `node:sqlite`, plus the two raw statements Kysely
+ * cannot express.
+ *
+ * The client opens the file. A caller says which file and which schema; it never builds the connection itself.
+ *
+ * ```ts
+ * using kdb = new DatabaseClient<MySchema>("db.sqlite", { readOnly: true })
+ * ```
+ *
+ * Handing that job to callers is what let one database be described by two schemas — the type argument here and a
+ * second one on the handle — with nothing to make them agree. It also split ownership: `SqliteDriver.destroy()` closes
+ * whatever connection it was given, so a shared handle has two owners and the first `destroy()` closes it under the
+ * other. One construction gives one schema, one owner, and a lifetime `using` can end.
+ *
+ * `exec` and `prepare` reach the same connection for the work Kysely does not model. See `core/db/schema.ts`.
+ */
+/**
+ * A connection's non-Kysely surface: the statements Kysely does not model, plus ending the connection.
+ *
+ * Schema-agnostic by construction — none of these members mentions `DB` — so a `DatabaseClient<AnySchema>` satisfies it
+ * and a helper need not name its caller's schema. That matters because Kysely is INVARIANT in `DB`: a parameter typed
+ * `DatabaseClient` (the empty default) would reject every real client. This is the narrowing the
+ * `mailwoman/no-database-handle-cast` rule prescribes, applied to the raw side.
+ */
+export type RawStatements = Pick<DatabaseClient, "exec" | "prepare" | "function" | "destroy"> & Disposable
+
+export class DatabaseClient<DB = Database> extends Kysely<DB> implements Disposable {
+	/**
+	 * A memory-only database, for tests and other ephemeral work. The connection is open until the client is disposed.
+	 */
+	public static temp<DB = Database>(): DatabaseClient<DB> {
+		return new DatabaseClient<DB>(":memory:")
+	}
+
+	readonly #database: DatabaseSync
+
+	constructor(location: PathBuilderLike, options?: DatabaseSyncOptions, config?: Partial<KyselyConfig>)
+	constructor(database: DatabaseSync, config?: Partial<KyselyConfig>)
+	constructor(dialectConfig: SqliteDialectConfig, config?: Partial<KyselyConfig>)
+	constructor(
+		source: PathBuilderLike | DatabaseSync | SqliteDialectConfig,
+		optionsOrConfig?: DatabaseSyncOptions | Partial<KyselyConfig>,
+		config?: Partial<KyselyConfig>
+	) {
+		let database: DatabaseSync
+		let kyselyConfig: Partial<KyselyConfig> | undefined
+
+		if (typeof source === "string" || source instanceof PathBuilder) {
+			const location = source.toString()
+			const options = optionsOrConfig as DatabaseSyncOptions | undefined
+			// node:sqlite checks the argument count, not the value: `new DatabaseSync(path, undefined)` throws.
+			const openArgs: [string, DatabaseSyncOptions?] = options ? [location, options] : [location]
+
+			database = new DatabaseSync(...openArgs)
+			kyselyConfig = config
+		} else {
+			const dialectConfig = "database" in source ? source : { database: source }
+
+			if (typeof dialectConfig.database === "function") {
+				throw new TypeError(
+					"DatabaseClient needs an open connection: a lazy `() => Promise<DatabaseSync>` leaves `exec` and " +
+						"`prepare` with nothing to reach. Pass the database path instead."
+				)
+			}
+
+			database = dialectConfig.database
+			kyselyConfig = optionsOrConfig as Partial<KyselyConfig> | undefined
+		}
+
+		super({
+			...kyselyConfig,
+			dialect: new SqliteDialect({ database }),
+		})
+
+		this.#database = database
+	}
+
+	/**
+	 * Run a statement Kysely does not model: `PRAGMA`, `VACUUM`, `ANALYZE`, `ATTACH`, FTS5 virtual-table DDL.
+	 *
+	 * Not to be confused with Kysely's `execute()`, which runs a compiled query. This one takes SQL text and returns
+	 * nothing.
+	 */
+	exec(sql: string): void {
+		this.#database.exec(sql)
+	}
+
+	/**
+	 * A prepared statement on this client's connection, for the bulk-write path.
+	 *
+	 * Kysely compiles per call, which a positional insert loop over millions of rows cannot afford. Reach for this only
+	 * there and in the other cases `AGENTS.md` lists as deliberately raw; everything cold goes through the query builder,
+	 * where the schema is checked.
+	 */
+	prepare(sql: string): StatementSync {
+		return this.#database.prepare(sql)
+	}
+
+	/**
+	 * Register a user-defined SQL function on this client's connection, callable from any statement it runs.
+	 *
+	 * SQLite resolves the name at statement-compile time, so registration must precede the first query that uses it.
+	 */
+	function(name: string, options: FunctionOptions, fn: (...args: SQLOutputValue[]) => SQLInputValue): void
+	function(name: string, fn: (...args: SQLOutputValue[]) => SQLInputValue): void
+	function(
+		name: string,
+		optionsOrFn: FunctionOptions | ((...args: SQLOutputValue[]) => SQLInputValue),
+		fn?: (...args: SQLOutputValue[]) => SQLInputValue
+	): void {
+		if (typeof optionsOrFn === "function") {
+			this.#database.function(name, optionsOrFn)
+
+			return
+		}
+
+		this.#database.function(name, optionsOrFn, fn!)
+	}
+
+	/**
+	 * End the connection at scope exit, synchronously.
+	 *
+	 * `destroy()` is Kysely's teardown and returns a promise, which `Symbol.dispose` cannot await — calling it here would
+	 * return with the file still open, and the next thing to touch that path (a `sealDatabase`, a reader expecting a
+	 * finalized statement) would see a connection that should have been gone. `node:sqlite`'s `close()` is synchronous,
+	 * so `using` closes the file before the scope ends.
+	 *
+	 * Kysely's own driver state is not unwound here. It holds this one connection and nothing else, and a query issued
+	 * afterwards fails on the closed handle rather than on a pool that thinks it is alive.
+	 */
+	[Symbol.dispose](): void {
+		this.#database[Symbol.dispose]()
+	}
+}
+
+/**
+ * The `node:sqlite` types a caller needs when it holds a statement or binds a value. Re-exported so nothing has to
+ * reach past this package for them.
+ */
+export type { DatabaseSyncOptions, SQLInputValue, SQLOutputValue, StatementSync } from "node:sqlite"

package/lib/database-schema.ts

@@ -0,0 +1,30 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Shared `Database` typing for the Kysely client at `core/kysley/client.ts`.
+ *
+ *   This file intentionally ships an empty schema. Consumers that want compile-time table typing
+ *   should extend `Kysely<TheirSchema>` directly rather than baking a schema into core — the WOF
+ *   resolver (Phase 4.2), corpus adapters, and any future consumer all touch different tables.
+ *
+ *   The exported `Database` interface exists so `client.ts` has a target for `Kysely<Database>` and
+ *   the boilerplate compiles without forcing a concrete schema commitment.
+ *
+ *   IT IS THE DEFAULT, NOT THE ONLY OPTION, and reading it as the only option is how `as never` gets written. Every
+ *   table name typed against `Record<string, never>` IS `never`, so `insertInto("poi")` cannot compile and a caller
+ *   who believes no alternative exists casts — which disarms not just that one check but every type-level guarantee
+ *   anyone later adds to the table (#1757 has the worked case: a branded key column whose check a neighbouring
+ *   `as never` had already defeated).
+ */
+
+/**
+ * Empty schema marker, and the DEFAULT type argument only.
+ *
+ * Consumers declare their own schema interface and pass it directly: `new Kysely<MySchema>({…})` or `new
+ * DatabaseClient<MySchema>(…)`. `DatabaseClient<DB = Database>` is generic today, so this is available now — the
+ * sentence here once deferred it to "Phase 4.2 work", which had already landed, and a reader who believed that had no
+ * option but to cast.
+ */
+export type Database = Record<string, never>

package/lib/dialect-config.ts

@@ -0,0 +1,30 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+
+import type { DatabaseSync } from "node:sqlite"
+
+import type { DatabaseConnection } from "kysely"
+
+/**
+ * Config for the SQLite dialect.
+ */
+export interface SqliteDialectConfig {
+	/**
+	 * A node:sqlite DatabaseSync instance or a function that returns one.
+	 *
+	 * If a function is provided, it's called once when the first query is executed.
+	 *
+	 * https://nodejs.org/api/sqlite.html#class-databasesync
+	 */
+	database: DatabaseSync | (() => Promise<DatabaseSync>)
+
+	/**
+	 * Called once when the first query is executed.
+	 *
+	 * This is a Kysely specific feature and does not come from the `node:sqlite` module.
+	 */
+	onCreateConnection?: (connection: DatabaseConnection) => Promise<void>
+}

package/lib/dialect.ts

@@ -0,0 +1,67 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+
+import {
+	SqliteAdapter,
+	SqliteIntrospector,
+	SqliteQueryCompiler,
+	type DatabaseIntrospector,
+	type Dialect,
+	type DialectAdapter,
+	type Driver,
+	type Kysely,
+	type QueryCompiler,
+} from "kysely"
+
+import type { SqliteDialectConfig } from "#dialect-config"
+import { SqliteDriver } from "#driver"
+
+/**
+ * SQLite dialect that uses the [`node:sqlite`](https://nodejs.org/api/sqlite.html) library.
+ *
+ * The constructor takes an instance of {@link SqliteDialectConfig}.
+ *
+ * ```ts
+ * import { DatabaseSync } from "node:sqlite"
+ *
+ * new SqliteDialect({
+ * 	database: new DatabaseSync("db.sqlite"),
+ * })
+ * ```
+ *
+ * If you want the pool to only be created once it's first used, `database` can be a function:
+ *
+ * ```ts
+ * import { DatabaseSync } from "node:sqlite"
+ *
+ * new SqliteDialect({
+ * 	database: async () => new DatabaseSync("db.sqlite"),
+ * })
+ * ```
+ */
+export class SqliteDialect implements Dialect {
+	protected config: SqliteDialectConfig
+
+	constructor(config: SqliteDialectConfig) {
+		this.config = Object.freeze({ ...config })
+	}
+
+	createDriver(): Driver {
+		return new SqliteDriver(this.config)
+	}
+
+	createQueryCompiler(): QueryCompiler {
+		return new SqliteQueryCompiler()
+	}
+
+	createAdapter(): DialectAdapter {
+		return new SqliteAdapter()
+	}
+
+	createIntrospector(db: Kysely<unknown>): DatabaseIntrospector {
+		return new SqliteIntrospector(db)
+	}
+}

package/lib/driver.ts

@@ -0,0 +1,175 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+
+import type { DatabaseSync, StatementSync } from "node:sqlite"
+
+import {
+	CompiledQuery,
+	createQueryId,
+	type DatabaseConnection,
+	type Driver,
+	IdentifierNode,
+	type QueryCompiler,
+	type QueryResult,
+	RawNode,
+	SelectQueryNode,
+} from "kysely"
+
+import type { SqliteDialectConfig } from "#dialect-config"
+
+class ConnectionMutex {
+	#promise?: Promise<void>
+	#resolve?: () => void
+
+	async lock(): Promise<void> {
+		while (this.#promise) {
+			await this.#promise
+		}
+
+		this.#promise = new Promise((resolve) => {
+			this.#resolve = resolve
+		})
+	}
+
+	unlock(): void {
+		const resolve = this.#resolve
+
+		this.#promise = undefined
+		this.#resolve = undefined
+
+		resolve?.()
+	}
+}
+
+export class SqliteDriver implements Driver {
+	readonly #config: SqliteDialectConfig
+	readonly #connectionMutex = new ConnectionMutex()
+
+	#db?: DatabaseSync
+	#connection?: DatabaseConnection
+
+	constructor(config: SqliteDialectConfig) {
+		this.#config = Object.freeze({ ...config })
+	}
+
+	async init(): Promise<void> {
+		const db = typeof this.#config.database === "function" ? await this.#config.database() : this.#config.database
+
+		this.#db = db
+		this.#connection = new SqliteConnection(db)
+
+		if (this.#config.onCreateConnection) {
+			await this.#config.onCreateConnection(this.#connection)
+		}
+	}
+
+	async acquireConnection(): Promise<DatabaseConnection> {
+		// SQLite only has one single connection. We use a mutex here to wait
+		// until the single connection has been released.
+		await this.#connectionMutex.lock()
+
+		// biome-ignore lint/style/noNonNullAssertion: :shrug:
+		return this.#connection!
+	}
+
+	async beginTransaction(connection: DatabaseConnection): Promise<void> {
+		await connection.executeQuery(CompiledQuery.raw("begin"))
+	}
+
+	async commitTransaction(connection: DatabaseConnection): Promise<void> {
+		await connection.executeQuery(CompiledQuery.raw("commit"))
+	}
+
+	async rollbackTransaction(connection: DatabaseConnection): Promise<void> {
+		await connection.executeQuery(CompiledQuery.raw("rollback"))
+	}
+
+	async savepoint(
+		connection: DatabaseConnection,
+		savepointName: string,
+		compileQuery: QueryCompiler["compileQuery"]
+	): Promise<void> {
+		await connection.executeQuery(compileQuery(parseSavepointCommand("savepoint", savepointName), createQueryId()))
+	}
+
+	async rollbackToSavepoint(
+		connection: DatabaseConnection,
+		savepointName: string,
+		compileQuery: QueryCompiler["compileQuery"]
+	): Promise<void> {
+		await connection.executeQuery(compileQuery(parseSavepointCommand("rollback to", savepointName), createQueryId()))
+	}
+
+	async releaseSavepoint(
+		connection: DatabaseConnection,
+		savepointName: string,
+		compileQuery: QueryCompiler["compileQuery"]
+	): Promise<void> {
+		await connection.executeQuery(compileQuery(parseSavepointCommand("release", savepointName), createQueryId()))
+	}
+
+	async releaseConnection(): Promise<void> {
+		this.#connectionMutex.unlock()
+	}
+
+	async destroy(): Promise<void> {
+		this.#db?.[Symbol.dispose]()
+	}
+}
+
+class SqliteConnection implements DatabaseConnection {
+	readonly #db: DatabaseSync
+
+	constructor(db: DatabaseSync) {
+		this.#db = db
+	}
+
+	executeQuery<O>(compiledQuery: CompiledQuery): Promise<QueryResult<O>> {
+		const { sql, parameters } = compiledQuery
+		const stmt = this.#db.prepare(sql)
+
+		const args = Array.isArray(parameters) ? parameters : []
+
+		if (stmt.columns().length) {
+			const rows = stmt.all(...args) as O[]
+
+			return Promise.resolve({ rows })
+		}
+
+		const result = stmt.run(...args)
+
+		return Promise.resolve({
+			numAffectedRows: BigInt(result.changes),
+			insertID: BigInt(result.lastInsertRowid),
+			rows: [],
+		})
+	}
+
+	async *streamQuery<R>(compiledQuery: CompiledQuery, _chunkSize: number): AsyncIterableIterator<QueryResult<R>> {
+		const { sql, parameters, query } = compiledQuery
+		const stmt: StatementSync = this.#db.prepare(sql)
+		const args = Array.isArray(parameters) ? parameters : []
+
+		if (!SelectQueryNode.is(query)) {
+			throw new Error("Sqlite driver only supports streaming of select queries")
+		}
+
+		const iter = stmt.iterate(...args) as IterableIterator<R>
+
+		for (const row of iter) {
+			yield {
+				rows: [row],
+			}
+		}
+	}
+}
+
+function parseSavepointCommand(command: string, savepointName: string): RawNode {
+	return RawNode.createWithChildren([
+		RawNode.createWithSql(`${command} `),
+		IdentifierNode.create(savepointName), // ensures savepointName gets sanitized
+	])
+}

package/lib/index.ts

@@ -0,0 +1,25 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The one way a Mailwoman SQLite connection comes into being.
+ *
+ *   `DatabaseClient` opens the file; `openBuiltClient` opens a built artifact with the seal check. A caller says which
+ *   file and which schema and never constructs the connection, so one database carries one schema, one owner, and a
+ *   lifetime `using` can end. `new DatabaseSync` appears once in this package and nowhere else in the repository.
+ *
+ *   It lives outside `@mailwoman/core` because it needs none of core's 11 MB of parser reference data — its whole
+ *   dependency set is `kysely`. That is what lets the leaf lookups use it.
+ */
+
+export * from "#batched"
+export * from "#client"
+export * from "#database-schema"
+export * from "#dialect"
+export * from "#dialect-config"
+export * from "#introspection"
+export * from "#schema-columns"
+export * from "#sealed"
+export * from "#sealed-build"
+export * from "#sealed-db"

package/lib/introspection.ts

@@ -0,0 +1,57 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ * @file Questions asked of `sqlite_master`.
+ *
+ *   ITS OWN SUBPATH ON PURPOSE — do not fold this into the package barrel. `@mailwoman/sqlite`'s root export
+ *   reaches `node:sqlite`, and the docs demo bundles this package for the browser; importing the barrel to
+ *   ask whether a table exists dragged the builtin into that graph. The split is what keeps these three
+ *   pure-SQL questions reachable from a bundled consumer.
+ */
+
+import type { DatabaseClient } from "#client"
+
+/**
+ * Whether a TABLE named `name` exists. An index, view or trigger of that name answers `false`.
+ */
+export function tableExists<DB>(db: DatabaseClient<DB>, name: string): boolean {
+	return Boolean(db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?").get(name))
+}
+
+/**
+ * `COUNT(*)` over `table`. The name is interpolated, so it must come from the schema, never from input.
+ */
+export function countRows<DB>(db: DatabaseClient<DB>, table: string): number {
+	const row = db.prepare(`SELECT COUNT(*) AS n FROM ${table}`).get() as { n?: number } | undefined
+
+	return Number(row?.n ?? 0)
+}
+
+/**
+ * Whether an INDEX named `name` exists.
+ */
+export function indexExists<DB>(db: DatabaseClient<DB>, name: string): boolean {
+	return Boolean(db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'index' AND name = ?").get(name))
+}
+
+/**
+ * Every table name, sorted. Virtual tables are tables here, the way `sqlite_master` records them.
+ */
+export function listTables<DB>(db: DatabaseClient<DB>): string[] {
+	const rows = db.prepare("SELECT name FROM sqlite_master WHERE type = 'table' ORDER BY name").all() as Array<{
+		name: string
+	}>
+
+	return rows.map((row) => row.name)
+}
+
+/**
+ * Whether `table` has a column named `column`. The table name is spliced into a PRAGMA, so it must come from the
+ * schema, never from input.
+ */
+export function hasColumn<DB>(db: DatabaseClient<DB>, table: string, column: string): boolean {
+	const rows = db.prepare(`PRAGMA table_info(${table})`).all() as Array<{ name: string }>
+
+	return rows.some((row) => row.name === column)
+}

package/lib/schema-columns.ts

@@ -0,0 +1,52 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The column groups every polygon layer's schema repeats, as schema-builder helpers — so the
+ *   `WITHOUT ROWID`-versus-blob discipline is stated once, beside the columns it governs.
+ */
+
+import type { CreateTableBuilder, Kysely } from "kysely"
+
+/**
+ * The slice of a Kysely handle a schema module's DDL touches. Kysely is invariant in its schema parameter, so naming
+ * only the member the builders call lets a caller pass its own wider handle.
+ */
+export type SchemaHandle<DB> = Pick<Kysely<DB>, "schema">
+
+/**
+ * The precomputed bounding box plus the unsimplified ring blob every polygon truth table carries.
+ *
+ * A table taking these stays a PLAIN rowid table, never `WITHOUT ROWID`: the `rings` blob is exactly the payload
+ * clustering into the B-tree penalizes — every index page becomes a geometry page.
+ */
+export function addRingGeometryColumns<TB extends string, C extends string>(
+	builder: CreateTableBuilder<TB, C>
+): CreateTableBuilder<TB, C | "min_lat" | "min_lon" | "max_lat" | "max_lon" | "rings"> {
+	return builder
+		.addColumn("min_lat", "real", (column) => column.notNull())
+		.addColumn("min_lon", "real", (column) => column.notNull())
+		.addColumn("max_lat", "real", (column) => column.notNull())
+		.addColumn("max_lon", "real", (column) => column.notNull())
+		.addColumn("rings", "blob", (column) => column.notNull())
+}
+
+/**
+ * The cell-index columns every polygon summary tier carries: the 48-bit short cell, the resolution it was captured at
+ * (a short cell does not name its own, and a mixed-resolution table cannot be probed without it), the key the row
+ * names, and its containment.
+ *
+ * Small fixed-width rows probed by their exact primary key are the `WITHOUT ROWID` shape — the caller adds its own
+ * primary-key constraint and the raw `without rowid` modifier, because the key differs per layer.
+ */
+export function addCellIndexColumns<TB extends string, C extends string, K extends string>(
+	builder: CreateTableBuilder<TB, C>,
+	keyColumn: K
+): CreateTableBuilder<TB, C | K | "h3_cell" | "resolution" | "containment"> {
+	return builder
+		.addColumn("h3_cell", "integer", (column) => column.notNull())
+		.addColumn("resolution", "integer", (column) => column.notNull())
+		.addColumn(keyColumn, "text", (column) => column.notNull())
+		.addColumn("containment", "text", (column) => column.notNull())
+}