matrix-nodejs-homeserver 0.3.2 → 0.3.4

package/dist/core/notifier.js

@@ -1,53 +1,150 @@
 //#region src/core/notifier.ts
+/** Users whose latest wake-up position is remembered (#50); the oldest are forgotten first. */
+const RECENT_USERS = 1e5;
+/** How soon held wake-ups are looked at again while the position has not reached them. */
+const RELEASE_RETRY_MS = 10;
 /**
 * Wakes long-polling `/sync` requests when something relevant happens. Notifications
 * are broadcast through the cluster adapter so waiters on other instances wake too.
+*
+* https://github.com/k18k/matrix-nodejs-homeserver/issues/50: every wake-up carries the stream
+* position of its change, or an upper bound of it. Writes can complete out of order, so a change
+* may be committed while an earlier write still holds the position below it. As in Synapse
+* (`Notifier._notify_pending_new_room_events`), such a wake-up is held here until the position
+* reaches it: a request is only woken for changes it can see.
 */
 var Notifier = class {
-	waiters = /* @__PURE__ */ new Map();
+	listeners = /* @__PURE__ */ new Map();
+	/** Each user's latest wake-up position, oldest first (re-inserted on update). */
+	recent = /* @__PURE__ */ new Map();
 	cluster;
 	instanceId;
-	constructor(cluster, instanceId) {
+	lastAllocated;
+	position;
+	/** Wake-ups whose change is beyond the position known to be visible. */
+	held = [];
+	/** The highest position known to be visible. */
+	visible = 0;
+	release = null;
+	/**
+	* `lastAllocated`: the highest stream position this instance has allocated (an upper bound of
+	* its changes); `position`: the position below which everything is visible.
+	*/
+	constructor(cluster, instanceId, lastAllocated = () => 0, position = async () => Number.POSITIVE_INFINITY) {
 		this.cluster = cluster;
 		this.instanceId = instanceId;
+		this.lastAllocated = lastAllocated;
+		this.position = position;
 		cluster.subscribe("notify", (msg) => {
-			if (msg?.from !== this.instanceId && Array.isArray(msg?.users)) this.wakeLocal(msg.users);
+			if (msg?.from !== this.instanceId && Array.isArray(msg?.users)) this.hold(msg.users, Number(msg.pos) || 0);
 		});
 	}
-	notify(userIds) {
+	/**
+	* Wake `userIds`. `pos` is the stream position of the change; without it, the highest position
+	* this instance has allocated stands in, which is never below it.
+	*/
+	notify(userIds, pos) {
 		const users = [...userIds];
 		if (!users.length) return;
-		this.wakeLocal(users);
+		const at = pos ?? this.lastAllocated();
+		this.hold(users, at);
 		this.cluster.publish("notify", {
 			from: this.instanceId,
-			users
+			users,
+			pos: at
 		}).catch(() => {});
 	}
-	wakeLocal(userIds) {
+	/** The position may have moved (a write of this instance completed): release what it covers. */
+	advanced() {
+		if (this.held.length) this.scheduleRelease(0);
+	}
+	/** Wake now if the change is visible, otherwise once the position reaches it. */
+	hold(users, pos) {
+		if (pos <= this.visible) return this.wakeLocal(users, pos);
+		this.held.push({
+			users,
+			pos
+		});
+		this.scheduleRelease(0);
+	}
+	scheduleRelease(delay) {
+		if (this.release) return;
+		this.release = setTimeout(() => {
+			this.release = null;
+			this.releaseHeld().catch(() => this.scheduleRelease(RELEASE_RETRY_MS));
+		}, delay);
+		this.release.unref?.();
+	}
+	async releaseHeld() {
+		const highest = Math.max(...this.held.map((h) => h.pos));
+		let pos = await this.position(false);
+		if (pos < highest) pos = await this.position(true);
+		if (pos > this.visible) this.visible = pos;
+		const due = this.held.filter((h) => h.pos <= this.visible);
+		this.held = this.held.filter((h) => h.pos > this.visible);
+		for (const h of due) this.wakeLocal(h.users, h.pos);
+		if (this.held.length) this.scheduleRelease(RELEASE_RETRY_MS);
+	}
+	wakeLocal(userIds, pos) {
 		for (const u of userIds) {
-			const set = this.waiters.get(u);
+			const previous = this.recent.get(u) ?? 0;
+			this.recent.delete(u);
+			this.recent.set(u, Math.max(previous, pos));
+			if (this.recent.size > RECENT_USERS) this.recent.delete(this.recent.keys().next().value);
+			const set = this.listeners.get(u);
 			if (!set) continue;
-			this.waiters.delete(u);
-			for (const wake of set) wake();
+			this.listeners.delete(u);
+			for (const wake of set) wake(pos);
 		}
 	}
 	notifyAll() {
-		this.wakeLocal([...this.waiters.keys()]);
-	}
-	wait(userId, timeoutMs, signal) {
-		return new Promise((resolve) => {
-			let set = this.waiters.get(userId);
-			if (!set) this.waiters.set(userId, set = /* @__PURE__ */ new Set());
-			const done = () => {
-				clearTimeout(timer);
-				set.delete(done);
-				signal?.removeEventListener("abort", done);
-				resolve();
-			};
-			const timer = setTimeout(done, timeoutMs);
-			signal?.addEventListener("abort", done, { once: true });
-			set.add(done);
-		});
+		for (const [u, set] of this.listeners) {
+			this.listeners.delete(u);
+			for (const wake of set) wake(0);
+		}
+	}
+	listen(userId) {
+		let woken = null;
+		let resolveWait = null;
+		let set = this.listeners.get(userId);
+		if (!set) this.listeners.set(userId, set = /* @__PURE__ */ new Set());
+		const onWake = (pos) => {
+			woken = Math.max(woken ?? 0, pos);
+			resolveWait?.(woken);
+		};
+		set.add(onWake);
+		const remove = () => {
+			const current = this.listeners.get(userId);
+			current?.delete(onWake);
+			if (current && current.size === 0) this.listeners.delete(userId);
+		};
+		return {
+			recent: this.recent.get(userId) ?? 0,
+			wait: (timeoutMs, signal) => {
+				if (woken !== null) return Promise.resolve(woken);
+				return new Promise((resolve) => {
+					const done = (result) => {
+						clearTimeout(timer);
+						signal?.removeEventListener("abort", aborted);
+						resolveWait = null;
+						remove();
+						resolve(result);
+					};
+					const aborted = () => done(null);
+					const timer = setTimeout(() => done(null), timeoutMs);
+					signal?.addEventListener("abort", aborted, { once: true });
+					resolveWait = (pos) => done(pos);
+				});
+			},
+			cancel: () => {
+				remove();
+				resolveWait?.(null);
+			}
+		};
+	}
+	/** Wait for a wake-up of `userId` (for callers that do not track positions). */
+	async wait(userId, timeoutMs, signal) {
+		await this.listen(userId).wait(timeoutMs, signal);
 	}
 };
 //#endregion

package/dist/core/push.d.ts

@@ -7,6 +7,14 @@ import { Homeserver } from "../homeserver.js";
  * Push rule evaluation and push gateway delivery. Every new event is evaluated for
  * every local member; matches are stored for unread counts and `/notifications`.
  */
+type Counts = {
+  notification_count: number;
+  highlight_count: number;
+};
+export interface UnreadCounts {
+  readonly room: Readonly<Counts>;
+  readonly threads: Readonly<Record<string, Readonly<Counts>>>;
+}
 export declare class PushService {
   private hs;
   constructor(hs: Homeserver);
@@ -18,16 +26,8 @@ export declare class PushService {
     unthreaded: number;
     threads: Map<string, number>;
   }): boolean;
-  unreadCounts(userId: string, roomId: string): Promise<{
-    room: {
-      notification_count: number;
-      highlight_count: number;
-    };
-    threads: Record<string, {
-      notification_count: number;
-      highlight_count: number;
-    }>;
-  }>;
+  unreadCounts(userId: string, roomId: string): Promise<UnreadCounts>;
+  private countUnread;
   private deliver;
   /** Rows for `GET /notifications`. */
   list(userId: string, opts: {
@@ -43,4 +43,5 @@ export declare class PushService {
     stream: any;
   }[]>;
 }
-//#endregion
+//#endregion
+export {};

package/dist/core/push.js

@@ -3,8 +3,10 @@ import { M, UNSTABLE } from "./m.js";
 import { splitStateKey, toClientEvent } from "./events.js";
 import { getState, powerLevels, userLevel } from "./authrules.js";
 import { globMatch, globSearchWords } from "./glob.js";
-import { KINDS, loadRules } from "./pushrules.js";
+import { KINDS, readOnlyRules } from "./pushrules.js";
 import { isSubscribed } from "../api/threadsubs.js";
+import { upsertMany } from "../storage/batch.js";
+import { freeze } from "./changes.js";
 //#region src/core/push.ts
 /** Look up a dotted path; `\.` escapes a literal dot in a key (e.g. `content.m\.relates_to`). */
 function valueAtPath(obj, path) {
@@ -84,10 +86,6 @@ function threadIdOf(event) {
 	const rel = event.content?.[M.RELATES_TO];
 	return isObject(rel) && rel.rel_type === M.THREAD && typeof rel.event_id === "string" ? rel.event_id : "main";
 }
-/**
-* Push rule evaluation and push gateway delivery. Every new event is evaluated for
-* every local member; matches are stored for unread counts and `/notifications`.
-*/
 var PushService = class {
 	hs;
 	constructor(hs) {
@@ -109,7 +107,7 @@ var PushService = class {
 		const notified = [];
 		for (const userId of members) {
 			if (userId === event.sender || !this.hs.isLocalUser(userId)) continue;
-			const actions = evaluateRules(await loadRules(this.hs, userId), {
+			const actions = evaluateRules(await readOnlyRules(this.hs, userId), {
 				event,
 				userId,
 				displayName: getState(state, M.ROOM.MEMBER, userId)?.content?.displayname ?? null,
@@ -136,9 +134,7 @@ var PushService = class {
 			});
 		}
 		if (notified.length === 0) return;
-		await this.hs.transaction(async (db) => {
-			for (const n of notified) await db.upsert("notifications", n.row);
-		});
+		await this.hs.transaction((db) => upsertMany(db, "notifications", notified.map((n) => n.row)));
 		const pushers = await this.hs.db.findMany("pushers", { where: [{
 			field: "user_id",
 			operator: "in",
@@ -177,23 +173,35 @@ var PushService = class {
 		return row.stream <= read.unthreaded || row.stream <= (read.threads.get(row.thread_id) ?? 0);
 	}
 	async unreadCounts(userId, roomId) {
+		const changes = this.hs.changes;
+		if (!changes) return this.countUnread(userId, roomId);
+		return changes.values.unreadCounts.get(`${userId}|${roomId}`, async () => freeze(await this.countUnread(userId, roomId)));
+	}
+	async countUnread(userId, roomId) {
 		const read = await this.readPositions(userId, roomId);
 		const unthreaded = read.unthreaded;
-		const rows = await this.hs.db.findMany("notifications", { where: [
-			{
-				field: "user_id",
-				value: userId
-			},
-			{
-				field: "room_id",
-				value: roomId
-			},
-			{
-				field: "stream",
-				operator: "gt",
-				value: unthreaded
-			}
-		] });
+		const rows = await this.hs.db.findMany("notifications", {
+			where: [
+				{
+					field: "user_id",
+					value: userId
+				},
+				{
+					field: "room_id",
+					value: roomId
+				},
+				{
+					field: "stream",
+					operator: "gt",
+					value: unthreaded
+				}
+			],
+			fields: [
+				"stream",
+				"thread_id",
+				"highlight"
+			]
+		});
 		const room = {
 			notification_count: 0,
 			highlight_count: 0

package/dist/core/pushrules.js

@@ -131,14 +131,33 @@ function cacheFor(hs) {
 	}
 	return c;
 }
+/** A user's push rules, as a copy the caller may change. */
 async function loadRules(hs, userId) {
+	return structuredClone(await readOnlyRules(hs, userId));
+}
+/**
+* A user's push rules, shared and frozen: for callers that only read them.
+*
+* https://github.com/k18k/matrix-nodejs-homeserver/issues/41: push evaluation copied every
+* member's rules for every message, about 6% of the CPU under load, though it only reads them.
+* The cached rulesets are deep-frozen, so a caller that tries to change one fails loudly instead
+* of changing everyone's.
+*/
+async function readOnlyRules(hs, userId) {
 	const cached = cacheFor(hs).get(userId);
-	if (cached) return structuredClone(cached);
-	const rules = await readRules(hs, userId);
+	if (cached) return cached;
+	const rules = deepFreeze(await readRules(hs, userId));
 	const cache = cacheFor(hs);
 	if (cache.size > 5e3) cache.clear();
 	cache.set(userId, rules);
-	return structuredClone(rules);
+	return rules;
+}
+function deepFreeze(value) {
+	if (value && typeof value === "object" && !Object.isFrozen(value)) {
+		Object.freeze(value);
+		for (const v of Object.values(value)) deepFreeze(v);
+	}
+	return value;
 }
 async function readRules(hs, userId) {
 	const row = await hs.db.findOne("account_data", [
@@ -162,7 +181,7 @@ async function readRules(hs, userId) {
 	return rules;
 }
 async function saveRules(hs, userId, rules) {
-	cacheFor(hs).set(userId, structuredClone(rules));
+	cacheFor(hs).set(userId, deepFreeze(structuredClone(rules)));
 	hs.cluster.publish("pushrules", {
 		from: hs.instanceId,
 		userId
@@ -226,4 +245,4 @@ async function copyRules(hs, userId, oldRoomId, newRoomId) {
 	if (changed) await saveRules(hs, userId, rules);
 }
 //#endregion
-export { KINDS, copyRoomPushRules, defaultRules, loadRules, saveRules, withRulesLock };
+export { KINDS, copyRoomPushRules, defaultRules, loadRules, readOnlyRules, saveRules, withRulesLock };

package/dist/core/rooms.js

@@ -731,6 +731,12 @@ var RoomService = class {
 			events: touched,
 			sharing: true
 		});
+		const changedMembers = /* @__PURE__ */ new Set();
+		for (const k of /* @__PURE__ */ new Set([...Object.keys(oldIds), ...Object.keys(newIds)])) {
+			const [type, userId] = splitStateKey(k);
+			if (type === M.ROOM.MEMBER && oldIds[k] !== newIds[k] && this.hs.isLocalUser(userId)) changedMembers.add(userId);
+		}
+		if (changedMembers.size) this.hs.notifier.notify([...changedMembers, ...await this.interestedUsers(roomId)]);
 		for (const k of Object.keys(oldIds)) {
 			const [type, userId] = splitStateKey(k);
 			if (type !== M.ROOM.MEMBER || this.hs.isLocalUser(userId) || oldIds[k] === newIds[k]) continue;
@@ -995,7 +1001,7 @@ var RoomService = class {
 				if (this.hs.appservices.registrations.length) await this.hs.appservices.onEvent(view, newState).catch((err) => this.hs.logger.warn("Appservice push failed", err));
 				if (isState) await this.hs.delayedEvents.onStateEvent(roomId, pdu.type, pdu.state_key, sender).catch(() => {});
 				wake = async () => {
-					this.hs.notifier.notify(await this.interestedUsers(roomId));
+					this.hs.notifier.notify(await this.interestedUsers(roomId), backfill ? void 0 : stream);
 					this.hs.emit("event", toClientEvent(view));
 					if (this.hs.adminRoom) this.hs.adminRoom.onEvent(view).catch((err) => this.hs.logger.error("Admin command failed", err));
 				};

package/dist/core/semaphore.js

@@ -14,7 +14,7 @@ var Semaphore = class {
 			return await fn();
 		} finally {
 			const next = this.waiting.shift();
-			if (next) next();
+			if (next) setImmediate(next);
 			else this.active--;
 		}
 	}

package/dist/homeserver.d.ts

@@ -26,6 +26,7 @@ import { SettingsService } from "./core/settings.js";
 import { AdminRoomOptions, AdminRoomService } from "./core/adminroom.js";
 import { ResolvedUserAuth, UserAuthAdapter } from "./adapters/auth.js";
 import { MediaAdapter, Thumbnailer } from "./adapters/media.js";
+import { ChangeTracker } from "./core/changes.js";
 import { AddressPolicy } from "./core/outbound.js";
 import { EventEmitter } from "node:events";
 //#region src/homeserver.d.ts
@@ -84,7 +85,7 @@ export interface HomeserverOptions {
   /** Maximum `/sync` long-poll duration in ms. Default: 30000. */
   maxSyncTimeoutMs?: number;
   /**
-   * How many `/sync` responses one process builds at once (default 4). Requests woken together
+   * How many `/sync` responses one process builds at once (default 16). Requests woken together
    * wait in the process instead of queueing their database reads ahead of everything else.
    */
   maxConcurrentSyncs?: number;
@@ -176,6 +177,11 @@ export declare class Homeserver extends EventEmitter {
   readonly serverName: string;
   readonly config: ResolvedConfig;
   readonly db: DatabaseAdapter;
+  /**
+   * Where keys last changed, when this is the only instance on its database (no cluster
+   * adapter): /sync skips the reads that would find nothing new (#51). Null in a cluster.
+   */
+  readonly changes: ChangeTracker | null;
   readonly media: MediaAdapter;
   readonly userAuth: ResolvedUserAuth;
   readonly logger: Logger;

package/dist/homeserver.js

@@ -13,6 +13,8 @@ import { KeyService } from "./core/keys.js";
 import { Notifier } from "./core/notifier.js";
 import { StreamManager, localCluster, newInstanceId } from "./core/cluster.js";
 import { TypingService } from "./core/typing.js";
+import { coalesceReads } from "./storage/batch.js";
+import { ChangeTracker } from "./core/changes.js";
 import { PushService } from "./core/push.js";
 import { SsoService } from "./core/sso.js";
 import { AdminService } from "./core/admin.js";
@@ -52,6 +54,11 @@ var Homeserver = class extends EventEmitter {
 	serverName;
 	config;
 	db;
+	/**
+	* Where keys last changed, when this is the only instance on its database (no cluster
+	* adapter): /sync skips the reads that would find nothing new (#51). Null in a cluster.
+	*/
+	changes;
 	media;
 	userAuth;
 	logger;
@@ -114,7 +121,7 @@ var Homeserver = class extends EventEmitter {
 			defaultRoomVersion,
 			accessTokenLifetimeMs: options.accessTokenLifetimeMs ?? null,
 			maxSyncTimeoutMs: options.maxSyncTimeoutMs ?? 3e4,
-			maxConcurrentSyncs: Math.max(1, options.maxConcurrentSyncs ?? 4),
+			maxConcurrentSyncs: Math.max(1, options.maxConcurrentSyncs ?? 16),
 			urlPreviews: options.urlPreviews ? { allowPrivateAddresses: typeof options.urlPreviews === "object" && !!options.urlPreviews.allowPrivateAddresses } : null,
 			thumbnailer: options.thumbnailer ?? null,
 			rtc: options.rtc ?? {},
@@ -124,19 +131,21 @@ var Homeserver = class extends EventEmitter {
 				roomName: options.serverNotices?.roomName ?? "Server Notices"
 			}
 		};
-		const db = options.databaseAdapter;
-		if (db && typeof db.findOne === "function") this.db = db;
-		else {
+		this.changes = options.cluster ? null : new ChangeTracker();
+		let db = options.databaseAdapter;
+		if (!db || typeof db.findOne !== "function") {
 			this.logger.warn("No database adapter given; using in-memory storage (data is lost on restart)");
-			this.db = memoryAdapter();
+			db = memoryAdapter();
 		}
+		this.db = coalesceReads(this.changes ? this.changes.wrap(db) : db);
 		const media = options.mediaAdapter;
 		this.media = media && typeof media.put === "function" ? media : memoryMedia();
 		this.userAuth = resolveUserAuth(options.userAuthAdapter);
 		this.cluster = options.cluster ?? localCluster();
 		this.instanceId = newInstanceId();
-		this.streams = new StreamManager(this.cluster, this.instanceId);
-		this.notifier = new Notifier(this.cluster, this.instanceId);
+		this.streams = new StreamManager(this.cluster, this.instanceId, (...args) => this.logger.warn(...args));
+		this.notifier = new Notifier(this.cluster, this.instanceId, () => this.streams.lastAllocated, (fresh) => this.streams.position(fresh));
+		this.streams.onAdvance = () => this.notifier.advanced();
 		this.auth = new AuthService(this);
 		this.rooms = new RoomService(this, !options.cluster);
 		this.keys = new KeyService(this);
@@ -196,6 +205,7 @@ var Homeserver = class extends EventEmitter {
 		}
 		const snap = await this.db.max("state_snapshots", "id");
 		if (snap !== null) await this.streams.advanceTo(snap);
+		this.changes?.start(await this.streams.position(true));
 		const oldest = await this.db.findMany("events", {
 			sortBy: {
 				field: "stream",

package/dist/storage/batch.js

@@ -7,5 +7,76 @@ function readBatch(db, queries) {
 	if (db.findManyBatch) return db.findManyBatch(queries);
 	return Promise.all(queries.map((query) => db.findMany(query.model, query.opts)));
 }
+/** Upsert several rows: in a few statements when the adapter can (`upsertMany`), otherwise one by one. */
+async function upsertMany(db, model, rows) {
+	if (rows.length === 0) return;
+	if (db.upsertMany) return db.upsertMany(model, rows);
+	for (const row of rows) await db.upsert(model, row);
+}
+/** At most this many reads go into one coalesced statement. */
+const MAX_COALESCED = 32;
+/**
+* An adapter whose reads (`findMany`, `findOne`) issued within one turn of the event loop are
+* sent together, through `findManyBatch`. Writes and transactions go straight to `db`. Adapters
+* without `findManyBatch` are returned as they are.
+*
+* https://github.com/k18k/matrix-nodejs-homeserver/issues/43: under load, most of the homeserver's
+* and the database's CPU went to the per-statement cost (a socket write, a round trip, parsing)
+* of many small reads issued at the same moment by concurrent requests. Nothing is kept between
+* turns: this merges requests, it does not cache results. A read waits for at most the rest of
+* the current turn. If a coalesced statement fails, its reads are run one by one, so a bad read
+* fails alone.
+*/
+function coalesceReads(db) {
+	if (!db.findManyBatch) return db;
+	let queue = [];
+	const runAlone = (read) => db.findMany(read.query.model, read.query.opts).then(read.resolve, read.reject);
+	const run = async (reads) => {
+		if (reads.length === 1) return runAlone(reads[0]);
+		let results;
+		try {
+			results = await db.findManyBatch(reads.map((r) => r.query), { prepare: false });
+		} catch {
+			for (const read of reads) runAlone(read);
+			return;
+		}
+		reads.forEach((read, i) => read.resolve(results[i]));
+	};
+	const flush = () => {
+		const reads = queue;
+		queue = [];
+		for (let i = 0; i < reads.length; i += MAX_COALESCED) run(reads.slice(i, i + MAX_COALESCED));
+	};
+	const enqueue = (query) => new Promise((resolve, reject) => {
+		if (queue.length === 0) setImmediate(flush);
+		queue.push({
+			query,
+			resolve,
+			reject
+		});
+	});
+	return {
+		findMany: (model, opts) => enqueue({
+			model,
+			opts
+		}),
+		findOne: async (model, where) => (await enqueue({
+			model,
+			opts: {
+				where,
+				limit: 1
+			}
+		}))[0] ?? null,
+		findManyBatch: (queries, options) => db.findManyBatch(queries, options),
+		create: (model, data) => db.create(model, data),
+		upsert: (model, data) => db.upsert(model, data),
+		...db.upsertMany ? { upsertMany: (model, rows) => db.upsertMany(model, rows) } : {},
+		update: (model, where, data) => db.update(model, where, data),
+		delete: (model, where) => db.delete(model, where),
+		max: (model, field) => db.max(model, field),
+		...db.migrate ? { migrate: (schema) => db.migrate(schema) } : {},
+		...db.transaction ? { transaction: (fn) => db.transaction(fn) } : {}
+	};
+}
 //#endregion
-export { readBatch };
+export { coalesceReads, readBatch, upsertMany };

package/dist/storage/schema.js

@@ -192,7 +192,11 @@ const schema = {
 			ts: n
 		},
 		primaryKey: ["user_id", "event_id"],
-		indexes: [["user_id", "room_id"], ["user_id", "stream"]]
+		indexes: [[
+			"user_id",
+			"room_id",
+			"stream"
+		], ["user_id", "stream"]]
 	},
 	sso_identities: {
 		fields: {
@@ -397,7 +401,8 @@ const schema = {
 			last_active_ts: n,
 			stream: n
 		},
-		primaryKey: ["user_id"]
+		primaryKey: ["user_id"],
+		indexes: [["stream"]]
 	},
 	media: {
 		fields: {

package/dist/storage/sql.d.ts

@@ -2,8 +2,10 @@ import { DatabaseAdapter, Row } from "./types.js";
 //#region src/storage/sql.d.ts
 export type SqlDialect = "sqlite" | "postgres" | "mysql";
 export interface SqlExecutor {
-  /** Run a query that returns rows. */
-  query(sql: string, params: unknown[]): Promise<Row[]>;
+  /** Run a query that returns rows; `prepare: false` when the statement is not worth preparing for reuse. */
+  query(sql: string, params: unknown[], options?: {
+    prepare?: boolean;
+  }): Promise<Row[]>;
   /** Run a statement; resolve with the number of affected rows. */
   execute(sql: string, params: unknown[]): Promise<number>;
 }
@@ -36,9 +38,20 @@ export interface SqliteDatabaseLike {
 /** SQLite adapter for `node:sqlite` (`new DatabaseSync(path)`) or `better-sqlite3`. */
 export declare function sqliteAdapter(db: SqliteDatabaseLike, options?: {
   tablePrefix?: string;
+  /**
+   * When commits reach the disk (SQLite's `synchronous`). `"normal"` (the default): at
+   * checkpoints; a commit survives a crash of the process, and a power loss or operating
+   * system crash can roll back the most recent ones, without corrupting the database.
+   * `"full"`: on every commit, which blocks the event loop for an fsync each time.
+   */
+  synchronous?: "normal" | "full";
 }): DatabaseAdapter;
 interface PgQueryable {
-  query(text: string, values?: unknown[]): Promise<{
+  query(config: {
+    text: string;
+    values?: unknown[];
+    name?: string;
+  }): Promise<{
     rows: Row[];
     rowCount: number | null;
   }>;
@@ -53,6 +66,12 @@ export interface PgPoolLike extends PgQueryable {
 /** PostgreSQL adapter for `pg` (node-postgres). Pass a `Pool` to get transactions. */
 export declare function postgresAdapter(pool: PgPoolLike, options?: {
   tablePrefix?: string;
+  /**
+   * Prepare statements on each connection and reuse them (default true). Turn off behind a
+   * connection pooler that does not support prepared statements, such as PgBouncer before 1.21
+   * or in transaction mode without `max_prepared_statements`.
+   */
+  preparedStatements?: boolean;
 }): DatabaseAdapter;
 interface MysqlQueryable {
   query(sql: string, values?: unknown[]): Promise<[any, unknown]>;