@mailwoman/resolver-wof-sqlite 9.2.0 → 9.4.0

package/lib/candidate/extract-fold.ts

@@ -0,0 +1,219 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ * @file Pass 4 of the candidate build — fold a postcode or locality extract into the staging table.
+ */
+
+import { DatabaseClient } from "@mailwoman/sqlite/client"
+import { tableExists } from "@mailwoman/sqlite/introspection"
+
+import { CANDIDATE_ANCESTOR_COLUMNS, CANDIDATE_ANCESTOR_TABLE } from "#candidate-ancestors-schema"
+import type { CandidateDatabase } from "#candidate-schema"
+import type { PlaceAttrs, StageRow } from "#candidate/place-attrs"
+import type { WOFDatabase } from "#schema"
+import { normalizeLocalityForKey } from "#street/normalize"
+
+/**
+ * The extract's own region-tier ancestry, when it carries any: extract id → the admin region's id. A locality extract
+ * derived from a national register (the Taiwanese 鄉鎮市區 from the civil-affairs address points) knows which 縣市 each row
+ * belongs to, and writes that as an `ancestors` row against the admin region's WOF id. Without it a folded row has no
+ * region scope, so a `parentID`-scoped probe misses it and the cascade widens to whatever namesake carries the key.
+ *
+ * Only a region the admin build staged (`attrs`) counts: an id the admin does not know cannot be denormalized into a
+ * closure row, and a scope nothing can match would be a silent zero rather than an absence.
+ */
+function extractRegionAncestry(pc: DatabaseClient<WOFDatabase>, attrs: Map<number, PlaceAttrs>): Map<number, number> {
+	const regionOf = new Map<number, number>()
+
+	if (!tableExists(pc, "ancestors")) {
+		return regionOf
+	}
+
+	for (const r of pc
+		.prepare(
+			"SELECT id, MIN(ancestor_id) AS ancestor_id FROM ancestors WHERE ancestor_placetype = 'region' GROUP BY id"
+		)
+		.iterate()) {
+		const rid = Number(r.ancestor_id)
+
+		if (attrs.has(rid)) {
+			regionOf.set(Number(r.id), rid)
+		}
+	}
+
+	return regionOf
+}
+
+/**
+ * Fold ONE extract (`spr` rows at `extractPlacetype` carrying real coordinates) in, then pass 4b: the alias names
+ * hanging off that same extract's `names` table.
+ *
+ * Self-contained by construction — it shares only the staging statement and the code dictionaries with the admin passes
+ * above it, and nothing downstream reads anything it produces except the counters it returns. The one thing it writes
+ * beyond the staging table is a depth-1 closure row for a row whose extract names its region (see
+ * {@link extractRegionAncestry}), so the pick's stamped ancestors agree with the scope it was found under.
+ */
+export function foldExtract(ctx: {
+	/**
+	 * The staging connection. The extract itself is opened read-only here and closed before returning.
+	 */
+	out: DatabaseClient<CandidateDatabase>
+	extractPath: string
+	extractPlacetype: "postalcode" | "locality"
+	ccID: (code: string | null) => number
+	ptID: (pt: string | null) => number
+	stageRow: StageRow
+	/**
+	 * The admin places pass 1 staged — what an extract's region ancestry is resolved against. Absent, no extract row
+	 * takes a region scope (the postcode extracts, which carry none).
+	 */
+	attrs?: Map<number, PlaceAttrs>
+	progress: (phase: string, message: string) => void
+}): { primaries: number; aliases: number; scoped: number; ancestorRows: number } {
+	const { out, extractPath, extractPlacetype, ccID, ptID, stageRow, progress } = ctx
+
+	progress(extractPlacetype === "postalcode" ? "postcodes" : "localities", `reading ${extractPath}`)
+
+	using pc = new DatabaseClient<WOFDatabase>(extractPath, { readOnly: true })
+	const pcPtid = ptID(extractPlacetype)
+	// Per-extract, not the admin `attrs` map: pass 1 only ever sees the admin DB, so the alias pass
+	// below has nothing to join against unless this primary loop records what it staged.
+	const pcAttrs = new Map<number, PlaceAttrs>()
+	const regionOf = ctx.attrs ? extractRegionAncestry(pc, ctx.attrs) : new Map<number, number>()
+
+	const insAncestor = out.prepare(
+		`INSERT OR IGNORE INTO ${CANDIDATE_ANCESTOR_TABLE} VALUES (${CANDIDATE_ANCESTOR_COLUMNS.map(() => "?").join(", ")})`
+	)
+
+	// The region's own closure rows, as the sidecar pass wrote them. A scoped row inherits the whole chain above its
+	// region — macroregion, country — not the region alone: the widened-scope refusal reads a pick's stamped ancestors
+	// against the parent the walk resolved, and a 縣市 that resolves to its macroregion record (`桃園市`, which WOF names
+	// only at that tier) would otherwise contradict a lineage that stops at the region.
+	const regionChain = out.prepare(
+		`SELECT depth, parent_spr_id, parent_placetype_id, parent_name, parent_name_key FROM ${CANDIDATE_ANCESTOR_TABLE} WHERE spr_id = ? ORDER BY depth`
+	)
+
+	let primaries = 0
+	let aliases = 0
+	let scoped = 0
+	let ancestorRows = 0
+
+	out.exec("BEGIN")
+
+	for (const r of pc
+		.prepare(
+			`SELECT id, name, country, latitude, longitude,
+				min_latitude AS mnlat, min_longitude AS mnlon, max_latitude AS mxlat, max_longitude AS mxlon
+			 FROM spr WHERE placetype = ? AND latitude != 0 AND longitude != 0`
+		)
+		.iterate(extractPlacetype)) {
+		const name = String(r.name ?? "")
+		const key = normalizeLocalityForKey(name)
+
+		if (!key) continue
+
+		const lat = r.latitude as number
+		const lon = r.longitude as number
+		const id = Number(r.id)
+		const rid = regionOf.get(id) ?? 0
+
+		// region_id from the extract's own ancestry when it names one, else 0 (a postcode is unique by
+		// name+country — no same-name disambiguation); neg_rank 0 (no population). bbox = the row's own
+		// min/max (falls back to the centroid point).
+		const a: PlaceAttrs = {
+			cid: ccID(r.country as string | null),
+			rid,
+			ptid: pcPtid,
+			name,
+			lat,
+			lon,
+			mnLat: (r.mnlat as number) || lat,
+			mnLon: (r.mnlon as number) || lon,
+			mxLat: (r.mxlat as number) || lat,
+			mxLon: (r.mxlon as number) || lon,
+			pop: 0,
+			neg: 0,
+			pkey: key,
+			// A postcode has no toponym fame — nobody writes an encyclopedia article about SW1A 2AA — and
+			// the score source carries no `postalcode` rows to join against anyway. NULL is the truthful
+			// value: unmeasured, so the ranking key leaves postcode rows exactly where they were.
+			imp: null,
+		}
+
+		pcAttrs.set(id, a)
+		stageRow(key, a, id, 1)
+
+		if (rid !== 0) {
+			const region = ctx.attrs!.get(rid)!
+
+			insAncestor.run(id, 1, rid, region.ptid, region.name, region.pkey)
+
+			scoped++
+
+			ancestorRows++
+
+			for (const link of regionChain.iterate(rid)) {
+				insAncestor.run(
+					id,
+					Number(link.depth) + 1,
+					Number(link.parent_spr_id),
+					Number(link.parent_placetype_id),
+					String(link.parent_name ?? ""),
+					String(link.parent_name_key ?? "")
+				)
+
+				ancestorRows++
+			}
+		}
+
+		primaries++
+	}
+
+	out.exec("COMMIT")
+
+	// --- pass 4b: postcode ALIAS names (#1495) ---
+	//
+	// The delivery-city names GeoNames supplies for a ZIP ("Brooklyn" for 11201) are written into
+	// the extract's `names` table by `postcode/centroid-fills.ts`'s `geonamesNameFill`. Everything
+	// downstream of `names` picked them up EXCEPT this build: `fts.ts` unions `spr.name` with every
+	// `names` row into `place_search.alt_names`, so the FTS backend resolved "Brooklyn" → 11201
+	// while the candidate backend — whose every row IS an exact-tier row — had no key for it at
+	// all. Pass 2 does the equivalent fold for admin places, but reads the ADMIN `place_search`,
+	// and `attrs` holds admin ids only, so a postcode extract could never reach it.
+	//
+	// Same discipline as pass 2: `is_primary = 0` (so `rankByPrimaryPreference` treats it as an
+	// alias, not a canonical postcode name), the row stays denormalized onto the POSTCODE's own
+	// spr_id/coords/bbox, and the display `name` stays the postcode — resolving "brooklyn" answers
+	// with place 11201, it does not rename the place to its delivery city.
+	const hasNames = tableExists(pc, "names")
+
+	if (hasNames) {
+		out.exec("BEGIN")
+
+		for (const r of pc.prepare("SELECT id, name FROM names").iterate()) {
+			const a = pcAttrs.get(Number(r.id))
+
+			if (!a) continue
+
+			const k = normalizeLocalityForKey(String(r.name ?? ""))
+
+			// The postcode's own key is already staged as the primary; `INSERT OR IGNORE` at
+			// materialization dedupes repeats, so this only skips the obvious self-alias.
+			if (!k || k === a.pkey) continue
+
+			stageRow(k, a, Number(r.id), 0)
+
+			aliases++
+		}
+
+		out.exec("COMMIT")
+	} else {
+		// Never a silent zero: real extracts come from `createUnifiedSchema`, which always creates
+		// `names`. A extract without it has no alias surface to lose, but say so rather than reporting
+		// "0 aliases" from a table that was never read.
+		progress("postcode-aliases", `${extractPath} has no \`names\` table — no delivery-city aliases to fold`)
+	}
+
+	return { primaries, aliases, scoped, ancestorRows }
+}

package/{candidate → lib/candidate}/name-roles.ts

@@ -2,21 +2,23 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- * @file Pass 3c of the candidate build — the `name_role` detectors and the cuts they are judged by.
+ * @file Pass 3c of the candidate build — the `name_role` detectors and the thresholds they are judged by.
  */
 
-import type { DatabaseSync } from "node:sqlite"
-
 import { isOfficialLanguage } from "@mailwoman/codex/country"
+import type { DatabaseClient } from "@mailwoman/sqlite/client"
+import { tableExists } from "@mailwoman/sqlite/introspection"
 
-import { normalizeLocalityForKey } from "../street-normalize.ts"
-import { isOwnNameVariant } from "./own-name.ts"
-import type { PlaceAttrs } from "./place-attrs.ts"
+import type { CandidateDatabase } from "#candidate-schema"
+import { isOwnNameVariant } from "#candidate/own-name"
+import type { PlaceAttrs } from "#candidate/place-attrs"
+import type { WOFDatabase } from "#schema"
+import { normalizeLocalityForKey } from "#street/normalize"
 
 /**
- * Key-count cut for the gloss anomaly detector (#1730) — the sweep's own boundary: 4,000 places carried >= 50 keys, and
- * a legitimate famous place at that count (New York, 176 keys) is separated by the PROMINENCE gate, never by this
- * number alone.
+ * Key-count threshold for the gloss anomaly detector (#1730) — the sweep's own boundary: 4,000 places carried >= 50
+ * keys, and a legitimate famous place at that count (New York, 176 keys) is separated by the PROMINENCE check, never by
+ * this number alone.
  */
 export const GLOSS_KEY_THRESHOLD = 50
 
@@ -39,9 +41,9 @@ export const GLOSS_EXCLUDED_PLACETYPES: ReadonlySet<string> = new Set([
 
 /**
  * Pass 3c — the #1730 name-role prototype: two independent detectors over the staged rows, WRITE-ONLY in this
- * generation (no ranking consumer; the rank penalty is its own D-rule-gated step with the `gloss_key` board as
- * tripwire). Both stamp `is_primary = 0` rows only — a place's canonical name and the `place_abbr` region abbreviations
- * are never a gloss or a variant.
+ * generation (no ranking consumer; the rank penalty is its own D-rule-conditional step with the `gloss_key` board as
+ * regression check). Both stamp `is_primary = 0` rows only — a place's canonical name and the `place_abbr` region
+ * abbreviations are never a gloss or a variant.
  *
  * - `gloss` is ANOMALY-based, and stamps only the certain core: key volume at/over the threshold + a non-admin placetype
  *
@@ -55,8 +57,8 @@ export const GLOSS_EXCLUDED_PLACETYPES: ReadonlySet<string> = new Set([
  * any role.
  */
 export function stampNameRoles(ctx: {
-	src: DatabaseSync
-	out: DatabaseSync
+	src: DatabaseClient<WOFDatabase>
+	out: DatabaseClient<CandidateDatabase>
 	attrs: Map<number, PlaceAttrs>
 	keyCounts: Map<number, number>
 	glossThreshold: number
@@ -94,8 +96,7 @@ export function stampNameRoles(ctx: {
 	const insRoleKey = out.prepare("INSERT OR IGNORE INTO role_key VALUES (?, ?)")
 
 	// Zero abbr stamps from a skipped detector is a different fact from zero variants found.
-	const hasSourceNames =
-		src.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='names'").get() !== undefined
+	const hasSourceNames = tableExists(src, "names")
 
 	if (hasSourceNames) {
 		out.exec("BEGIN")

package/{candidate → lib/candidate}/own-name.ts

@@ -9,7 +9,7 @@
  *   — rather than a different name that merely shares the folded key?
  *
  *   The comparator is `levenshteinSimilarity`, NOT Jaro-Winkler: JW's common-prefix bonus scores
- *   the load-bearing NEGATIVE case (`chanchun` vs `cancun`, 0.925) above real positives
+ *   the required NEGATIVE case (`chanchun` vs `cancun`, 0.925) above real positives
  *   (`saint george s` vs `st georges` expanded, 0.914), so no JW threshold separates them.
  *   Measured on the #1882 census contests, edit similarity separates every case with margin:
  *
@@ -127,6 +127,7 @@ export function romanizeNameKey(key: string): string | null {
  * Edit similarity between a holder's primary name key and one of its alias keys, both romanized and
  * abbreviation-expanded. `null` when either side's script is uncovered.
  */
+// repo-health-ignore export-name-affix -- romanizes and expands abbreviations first; `nameSimilarity` compares as given.
 export function ownNameSimilarity(primaryKey: string, aliasKey: string): number | null {
 	const primary = romanizeNameKey(primaryKey)
 	const alias = romanizeNameKey(aliasKey)

package/{candidate → lib/candidate}/place-attrs.ts

@@ -5,7 +5,7 @@
  * @file The per-place record every candidate-staging pass writes its rows from.
  *
  *   Pass 1 reduces each current `spr` row to one {@link PlaceAttrs}; every later pass (alias bags,
- *   region abbreviations, country display names, the currency backfill, the shard folds) discovers
+ *   region abbreviations, country display names, the currency backfill, the extract folds) discovers
  *   ADDITIONAL name keys for a place already in that map and stages a row against the same record.
  *   That is what keeps each candidate row denormalized without re-reading the source, and it is why
  *   a pass needs exactly four things to stage: the key it found, the place, the id the row hangs on,
@@ -38,7 +38,7 @@ export interface PlaceAttrs {
  * Stage one candidate row: a normalized name key, the place it belongs to, the source id the row hangs on, and whether
  * the key is that place's canonical name (`is_primary`).
  *
- * `sid` is passed separately rather than read off the place because a shard fold and the alias pass stage rows for ids
- * the admin `attrs` map never held.
+ * `sid` is passed separately rather than read off the place because a extract fold and the alias pass stage rows for
+ * ids the admin `attrs` map never held.
  */
 export type StageRow = (k: string, a: PlaceAttrs, sid: number, isPrimary: number) => void

package/{candidate-ancestors-schema.ts → lib/candidate-ancestors-schema.ts}

@@ -50,7 +50,7 @@
  *   "contained along the canonical hierarchy", never "not contained at all".
  *
  *   ABSENCE SEMANTICS (meaning-of-zero): a place with no `candidate_interval` row has no recorded
- *   ancestry in the source (shard-fed postcodes and localities, isolated places, cycle-skipped
+ *   ancestry in the source (extract-fed postcodes and localities, isolated places, cycle-skipped
  *   rows). Absence is UNVERIFIABLE, never a containment verdict.
  */
 
@@ -59,8 +59,8 @@ import { sql, type Kysely } from "kysely"
 // Type-only and circular on purpose (candidate-schema extends CandidateAncestorsDatabase): Kysely's
 // DB parameter is invariant, so the DDL functions must take the FULL database type their caller
 // holds. Erased at runtime.
-import type { CandidateDatabase } from "./candidate-schema.ts"
-import type { NameKey } from "./street-normalize.ts"
+import type { CandidateDatabase } from "#candidate-schema"
+import type { NameKey } from "#street/normalize"
 
 /**
  * The deepest chain the sidecar stores per place. WOF containment within the resolvable placetypes (country …
@@ -76,7 +76,7 @@ export const MAX_ANCESTOR_DEPTH = 8
 export const CANDIDATE_ANCESTOR_TABLE = "candidate_ancestor"
 
 /**
- * The interval-label table's name — the closure table's seal-time sibling; existence-gated the same way.
+ * The interval-label table's name — the closure table's seal-time sibling; existence-restricted the same way.
  */
 export const CANDIDATE_INTERVAL_TABLE = "candidate_interval"
 

package/{candidate-fts.ts → lib/candidate-fts.ts}

@@ -25,10 +25,10 @@
  *   fallback only needs to recover the name_key, then re-probes the B-tree for its rows).
  */
 
-import type { DatabaseSync } from "node:sqlite"
+import type { DatabaseClient } from "@mailwoman/sqlite/client"
 
 /**
- * Name of the FTS5 trigram virtual table this module owns. The reader gates its fuzzy fallback on it.
+ * Name of the FTS5 trigram virtual table this module owns. The reader conditions its fuzzy fallback on it.
  */
 export const CANDIDATE_FTS_TABLE = "candidate_fts"
 
@@ -36,7 +36,7 @@ export const CANDIDATE_FTS_TABLE = "candidate_fts"
  * Build (or rebuild) {@link CANDIDATE_FTS_TABLE} from the materialized `candidate` table. Call after the candidate
  * B-tree is populated (build pipeline) or against an existing candidate DB (migration).
  */
-export function createCandidateFTS(db: DatabaseSync): void {
+export function createCandidateFTS<DB>(db: DatabaseClient<DB>): void {
 	db.exec(`DROP TABLE IF EXISTS ${CANDIDATE_FTS_TABLE}`)
 	db.exec(`CREATE VIRTUAL TABLE ${CANDIDATE_FTS_TABLE} USING fts5(name_key, tokenize='trigram')`)
 

package/{candidate-importance.ts → lib/candidate-importance.ts}

@@ -27,7 +27,7 @@
  *   Warwick in America the fame of Warwick, Rhode Island, which is the fan-out defect
  *   `importance-fanout.ts` documents one layer up, re-introduced at the join. So the group is
  *   disambiguated GEOGRAPHICALLY: the nearest centroid wins, and only within
- *   {@link IMPORTANCE_JOIN_GATE_KM}. Two artifacts describing the same settlement put its centroid in
+ *   {@link IMPORTANCE_JOIN_RADIUS_KM}. Two artifacts describing the same settlement put its centroid in
  *   almost the same place; two same-named towns in one country do not.
  *
  *   ## What lands in the column
@@ -41,11 +41,11 @@
  *   (`resolver/toponym-prior.ts`) leaves an unmeasured candidate exactly where population put it.
  */
 
-import { DatabaseSync } from "node:sqlite"
-
 import { haversineKm } from "@mailwoman/spatial"
+import { DatabaseClient } from "@mailwoman/sqlite/client"
 
-import { normalizeLocalityForKey } from "./street-normalize.ts"
+import type { CandidateDatabase } from "#candidate-schema"
+import { normalizeLocalityForKey } from "#street/normalize"
 
 /**
  * How far apart two artifacts may put the same place's centroid and still be read as the same place.
@@ -55,18 +55,18 @@ import { normalizeLocalityForKey } from "./street-normalize.ts"
  * country, placetype)`). The nearest-centroid distance is **exactly 0.00 km for 577,080 of them (56.6%)** — the two
  * snapshots agree to the bit — and 656,755 (64.4%) are inside 500 m.
  *
- * What sets the gate is where that mode ENDS, and the per-kilometre density says so plainly. It falls from 1,076
- * places/km over 3–5 km to a trough of **441 places/km over 7–10 km**, then climbs back and flattens onto a plateau of
- * 760–780 places/km from 30 km out to 100 km and beyond. That plateau is the background rate of two DIFFERENT towns
- * wearing one name in one country, and it does not decay with distance because there is no reason it should. 10 km is
- * the floor between the two populations. Admitting it scores 679,163 places (66.6% of the matched set); pushing the
- * gate to 25 km buys 8,722 more, and by then better than half of each additional kilometre is the wrong town.
+ * What sets the radius is where that mode ENDS, and the per-kilometre density states. It falls from 1,076 places/km
+ * over 3–5 km to a trough of **441 places/km over 7–10 km**, then climbs back and flattens onto a plateau of 760–780
+ * places/km from 30 km out to 100 km and beyond. That plateau is the background rate of two DIFFERENT towns wearing one
+ * name in one country, and it does not decay with distance because there is no reason it should. 10 km is the floor
+ * between the two populations. Admitting it scores 679,163 places (66.6% of the matched set); pushing the radius to 25
+ * km buys 8,722 more, and by then better than half of each additional kilometre is the wrong town.
  *
  * The four-row bare-GB board is insensitive across this whole range — 5 km and 25 km were both measured and select
- * identical rows — so the value is chosen by what the join MEANS, not by what it scores. The gate is the definition of
- * "this is the same place"; widening it past the floor starts handing one town's fame to another.
+ * identical rows — so the value is chosen by what the join MEANS, not by what it scores. The radius is the definition
+ * of "this is the same place"; widening it past the floor starts handing one town's fame to another.
  */
-export const IMPORTANCE_JOIN_GATE_KM = 10
+export const IMPORTANCE_JOIN_RADIUS_KM = 10
 
 /**
  * One scored place from the source: where it is, and what it scored.
@@ -111,17 +111,17 @@ export class ImportanceIndex {
 	readonly #groups: Map<string, ScoredPlace[]>
 	readonly stats: ImportanceIndexStats
 	/**
-	 * Places {@link find} matched inside the gate.
+	 * Places {@link find} matched inside the radius.
 	 */
 	matched = 0
 	/**
-	 * Places {@link find} REFUSED — the key matched a scored group, but the nearest member of it was outside the gate, so
-	 * it is a different place wearing the same name.
+	 * Places {@link find} REFUSED — the key matched a scored group, but the nearest member of it was outside the radius,
+	 * so it is a different place wearing the same name.
 	 *
 	 * This is the number worth watching across rebuilds. A jump means the score source and the admin source have drifted
-	 * apart and the join is being asked to guess; it does not mean the gate is too tight.
+	 * apart and the join is being asked to guess; it does not mean the radius is too tight.
 	 */
-	gated = 0
+	refused = 0
 
 	constructor(groups: Map<string, ScoredPlace[]>, stats: ImportanceIndexStats) {
 		this.#groups = groups
@@ -130,7 +130,7 @@ export class ImportanceIndex {
 
 	/**
 	 * The importance of the scored place nearest `(lat, lon)` sharing `name`'s folded key, `country` and `placetype`, or
-	 * null when there is no such place within {@link IMPORTANCE_JOIN_GATE_KM}.
+	 * null when there is no such place within {@link IMPORTANCE_JOIN_RADIUS_KM}.
 	 *
 	 * Null is UNMEASURED. Never substitute a zero, and never fall back to a population-derived value here — the source
 	 * column already carries that fallback where it has one, and inventing a second one would make an absence
@@ -157,8 +157,8 @@ export class ImportanceIndex {
 			}
 		}
 
-		if (!best || bestKm > IMPORTANCE_JOIN_GATE_KM) {
-			this.gated++
+		if (!best || bestKm > IMPORTANCE_JOIN_RADIUS_KM) {
+			this.refused++
 
 			return null
 		}
@@ -182,47 +182,43 @@ export class ImportanceIndex {
  * 25 s.
  */
 export function loadImportanceIndex(databasePath: string): ImportanceIndex {
-	const db = new DatabaseSync(databasePath, { readOnly: true })
-
-	try {
-		const groups = new Map<string, ScoredPlace[]>()
-		let places = 0
-		let unkeyable = 0
-
-		for (const row of db
-			.prepare(
-				`SELECT s.name AS name, s.country AS country, s.placetype AS placetype,
-					s.latitude AS latitude, s.longitude AS longitude, i.importance AS importance
-				 FROM place_importance i JOIN spr s ON s.id = i.id
-				 WHERE s.is_current != 0 AND s.is_deprecated = 0`
-			)
-			.iterate()) {
-			const importance = Number(row.importance)
-
-			if (!Number.isFinite(importance)) continue
-			const nameKey = normalizeLocalityForKey(String(row.name ?? ""))
-
-			if (!nameKey) {
-				unkeyable++
-
-				continue
-			}
+	using db = new DatabaseClient<CandidateDatabase>(databasePath, { readOnly: true })
 
-			const key = groupKey(nameKey, row.country as string | null, row.placetype as string | null)
-			let group = groups.get(key)
+	const groups = new Map<string, ScoredPlace[]>()
+	let places = 0
+	let unkeyable = 0
 
-			if (!group) {
-				group = []
-				groups.set(key, group)
-			}
+	for (const row of db
+		.prepare(
+			`SELECT s.name AS name, s.country AS country, s.placetype AS placetype,
+				s.latitude AS latitude, s.longitude AS longitude, i.importance AS importance
+			 FROM place_importance i JOIN spr s ON s.id = i.id
+			 WHERE s.is_current != 0 AND s.is_deprecated = 0`
+		)
+		.iterate()) {
+		const importance = Number(row.importance)
 
-			group.push({ lat: Number(row.latitude), lon: Number(row.longitude), importance })
+		if (!Number.isFinite(importance)) continue
+		const nameKey = normalizeLocalityForKey(String(row.name ?? ""))
 
-			places++
+		if (!nameKey) {
+			unkeyable++
+
+			continue
 		}
 
-		return new ImportanceIndex(groups, { places, keys: groups.size, unkeyable })
-	} finally {
-		db.close()
+		const key = groupKey(nameKey, row.country as string | null, row.placetype as string | null)
+		let group = groups.get(key)
+
+		if (!group) {
+			group = []
+			groups.set(key, group)
+		}
+
+		group.push({ lat: Number(row.latitude), lon: Number(row.longitude), importance })
+
+		places++
 	}
+
+	return new ImportanceIndex(groups, { places, keys: groups.size, unkeyable })
 }