chore(rivetkit): migrate to sqlite instance per-actor for concurrency optimizations

[NathanFlurry]

Description

Please include a summary of the changes and the related issue. Please also include relevant motivation and context.

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

How Has This Been Tested?

Please describe the tests that you ran to verify your changes.

Checklist:

• My code follows the style guidelines of this project
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes

[railway-app]

🚅 Deployed to the rivet-pr-4264 environment in rivet-frontend

Service	Status	Web	Updated (UTC)
website	😴 Sleeping (View Logs)	Web	Feb 23, 2026 at 6:52 am
mcp-hub	✅ Success (View Logs)	Web	Feb 23, 2026 at 6:42 am
frontend-inspector	❌ Build Failed (View Logs)	Web	Feb 23, 2026 at 6:41 am
ladle	❌ Build Failed (View Logs)	Web	Feb 23, 2026 at 6:41 am
frontend-cloud	❌ Build Failed (View Logs)	Web	Feb 23, 2026 at 6:41 am

[NathanFlurry]

• chore: multiplayer cookbook patterns #4261 : 2 dependent PRs (#4266 , #4268 )
• docs: document queue with interval pattern #4265
• chore(rivetkit): migrate to sqlite instance per-actor for concurrency optimizations #4264 👈 (View in Graphite)
• docs: workflows #4256
• chore(rivetkit): update conns to be hibernatable #4260
• chore(inspector): add back database tab #4255
• chore: impl canInvoke for matchmaker #4253
• chore: multiplayer cookbook #4200 : 1 other dependent PR (#4201 )
• feat(dashboard): bring new tabs back #4249
• fix(rivetkit): fix sqlite teardown logic #4259
• main

---

How to use the Graphite Merge Queue

Add the label merge-queue to this PR to add it to the merge queue.

You must have a Graphite account in order to use the merge queue. Sign up using this link.

An organization admin has enabled the Graphite Merge Queue in this repository.

Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue.

This stack of pull requests is managed by Graphite. Learn more about stacking.

[claude]

PR Review: chore(rivetkit): migrate to sqlite instance per-actor for concurrency optimizations

Status: Merged — notes below are for follow-up tracking.

The core approach is sound. wa-sqlite's async build genuinely cannot be used re-entrantly on a single module instance, and scoping SqliteVfs (and therefore the WASM module) per actor is the right fix. The #sqliteMutex propagated into each Database instance ensures serialization within one actor's operations while allowing true parallelism across actors. The finally-block cleanup and the lifecycle test coverage are good additions.

A few things worth tracking as follow-up:

---

Bug: SQL injection in test fixture

In db-lifecycle.ts, the insertValue action builds SQL via string interpolation:

insertValue: async (c, value: string) => {
    await c.db.execute(
        `INSERT INTO lifecycle_data (value, created_at) VALUES ('${value}', ${Date.now()})`,
    );
},

Even in a test fixture this establishes a bad pattern. Use a parameterized query form if the API supports it.

---

Resource concern: SqliteVfs instances abandoned on sleep/wake cycles

In actor.ts, the getter returns a new instance on every call:

get sqliteVfs(): SqliteVfs {
    return new SqliteVfs();
}

In mod.ts, ??= caches the first result, but #cleanupDatabase() sets this.#sqliteVfs = undefined without calling any teardown on the old instance. Since SqliteVfs holds a WASM module (loaded via SQLiteESMFactory), each sleep/wake cycle allocates a new WASM module that is abandoned without explicit cleanup.

SqliteVfs has no destroy() method today, so old instances rely on GC. This is probably acceptable short-term, but adding a SqliteVfs.destroy() that frees the WASM module and calling it in #cleanupDatabase() would prevent WASM memory from accumulating across sleep/wake cycles under load.

---

Redundant guard in #cleanupDatabase()

async #cleanupDatabase() {
    const client = this.#db;
    this.#db = undefined;
    this.#sqliteVfs = undefined;

    if (\!client) {
        return;
    }
    if (\!("db" in this.#config) || \!this.#config.db) {  // unreachable
        return;
    }
    ...
}

If client is truthy, this.#config.db must have existed when the client was created since #initDatabase already gates on \!("db" in this.#config). The second early return is unreachable and can be removed.

---

Fragile actor-ID lookup in the migration-failure test

const actorId = await client.dbLifecycleFailing.get([key]).resolve();

This is called after migration fails on ping(). If the actor is in a torn-down state, resolve() may itself fail or return a stale value. Consider capturing the actor ID before the expected failure (same as dbLifecycle does via getActorId), or deriving it deterministically from the key in test setup.

---

Indentation inconsistencies

Three places have inconsistent indentation that should be cleaned up:

1. registry.ts — items inside the registry array gained an extra level of indentation mid-array.
2. actor-db.ts — the for (const variant of variants) loop body gained extra indentation.
3. db-lifecycle.ts — the onDestroy callback body is over-indented relative to the rest of the object literal.

---

Minor: module-level counters shared across test runs

createCounts, migrateCounts, cleanupCounts, and clientActorIds in db-lifecycle.ts are module-level singletons. crypto.randomUUID() in test keys prevents false positives today, but if count assertions on shared actors like dbLifecycleObserver are ever added, cross-run accumulation could cause flakiness. Consider moving counters into actor state or resetting between suites.

---

Minor: onClose not called if close() throws

In vfs.ts:

async close(): Promise<void> {
    await this.#sqliteMutex.run(async () => {
        await this.#sqlite3.close(this.#handle);
    });
    this.#onClose();  // skipped if close() throws
}

If the SQLite close call throws, onClose (which unregisters the file from sqliteSystem) is never invoked. Since SqliteVfs is now per-actor and discarded after cleanup this is low-risk, but wrapping with try/finally would be cleaner.

---

Overall the concurrency fix is correct and the cleanup path (finally block, calling onDestroy on migration failure, the separate #cleanupDatabase method) is well-structured. The issues above are housekeeping/robustness items rather than blockers.