fix(sqlite): make startup migrations concurrency-safe

[lklynet]

What changed

SQLite startup now handles concurrent processes safely. It retries WAL setup after SQLITE_BUSY, rechecks the schema version inside an immediate migration transaction, and avoids write locks when the schema is already current. Startup also repairs missing search-index triggers, rebuilds outdated search documents, and creates the unique Lidarr artist index atomically while preserving the winning mappings.

Why

Concurrent Aurral starts could contend while setting WAL mode or applying the same migration and index changes, causing startup failures or inconsistent indexes. These changes serialize required writes and let up-to-date databases start without taking a write lock.

Scope checklist

• This pull request has one clear purpose
• I kept unrelated fixes, refactors, formatting changes, dependency updates, and features out of this pull request
• If this adds a feature, I linked the approved feature request or included the Discord context in the Why section

Linked issue

None provided.

Testing

Added focused regression tests for concurrent startup on fresh and upgraded databases, migration rollback, startup with an existing writer, missing search-index triggers, and outdated search documents. Test execution was not reported in the supplied change details.

Release impact

• Major: incompatible change
• Minor: backward-compatible feature
• Patch: backward-compatible fix
• None: documentation, CI, tests, or internal-only change

[github-actions]

Aurral preview image ready

This image was rebuilt from the latest push to this pull request. It will be replaced when you push another change.

docker pull ghcr.io/lklynet/aurral:pr-912

To test it with your existing Docker Compose setup:

1. Back up your Aurral config.
2. Temporarily change the Aurral service image to ghcr.io/lklynet/aurral:pr-912.
3. Run docker compose pull aurral && docker compose up -d aurral.
4. Exercise the behavior changed by this pull request.
5. Restore the image reference that was configured before testing.

View the preview workflow run · Report a problem

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: QUIET

Plan: Advanced

Run ID: 12e3e4ec-8dc3-4978-bac3-f94d333fd18e

📥 Commits

Reviewing files that changed from the base of the PR and between 561c5ce and 56d8438.

📒 Files selected for processing (1)

• backend/config/db-sqlite.js

Included review availability: Your plan provides up to 4 included reviews per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

SQLite startup now sets a busy timeout before WAL setup and retries WAL setup when SQLite reports a busy error. Schema migration rechecks the schema version inside its transaction. Lidarr artist mapping setup now removes duplicate mappings and creates a unique index when needed. Library search initialization checks FTS5 support, required triggers, and the stored index version before returning or rebuilding the index. Tests cover startup concurrency, index recovery, deduplication, and restoration after index creation failure.

Merge Risk: 🟡 Moderate · up to 56d84

A database held busy through WAL setup can still prevent the service from starting. Resolve or explicitly accept that startup limitation before merging.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 8 functions across 7 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the main change: making SQLite startup migrations safe under concurrency.
Description check	✅ Passed	The description explains what changed, why it changed, scope, testing areas, and release impact. It does not provide test execution results, but the description is otherwise complete and focused.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Note

Quiet mode is enabled, so only the most important comments were posted inline. Other review comments are grouped below.

🟡 Other comments (1)

backend/config/db-sqlite.js-31-31 (1)

31-31: 🩺 Stability & Availability | 🟡 Minor | ⚡ Quick win

Continue startup when the WAL switch stays busy, and match extended busy codes.

better-sqlite3 enables extended result codes. As a result, error.code can be SQLITE_BUSY_RECOVERY or SQLITE_BUSY_SNAPSHOT. The strict !== "SQLITE_BUSY" check does not retry these codes and throws on the first attempt.

On the fifth busy attempt, the loop also rethrows and stops startup. WAL is a concurrency optimization, not a correctness requirement. If another process keeps the lock, startup should keep the current journal mode and continue. The next start can switch to WAL.

🛠️ Proposed fix

   } catch (error) {
-    if (error?.code !== "SQLITE_BUSY" || attempt === 4) throw error;
+    if (!String(error?.code || "").startsWith("SQLITE_BUSY")) throw error;
+    if (attempt === 4) {
+      console.warn("SQLite WAL setup skipped: database is busy");
+      break;
+    }
     Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);
   }

Based on learnings: "setting PRAGMA journal_mode=WAL can fail with 'database is locked' … code should catch/ignore this specific failure and continue with schema creation and normal writes rather than aborting."

Source: Learnings

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: QUIET

Plan: Advanced

Run ID: b518afc3-38ca-4a7f-bdbe-dfac5e180585

📥 Commits

Reviewing files that changed from the base of the PR and between 492e600 and 5589c2e.

📒 Files selected for processing (7)

• .tests/library/library-search-index.test.js
• .tests/migration/lidarr-artist-index.test.js
• .tests/migration/v2-migration.test.js
• backend/config/db-sqlite.js
• backend/config/library-search-index.js
• backend/config/lidarr-artist-index.js
• backend/config/schema-migration-v2.js

Files not reviewed due to moderation or processing errors (2)

• backend/config/library-search-index.js
• .tests/library/library-search-index.test.js

Included review availability: Your plan provides up to 4 included reviews per hour; 2 remain after this review.

[lklynet]

CodeRabbit WAL note: c15de71 now retries the extended SQLITE_BUSY_* codes. Startup still fails if WAL setup stays busy after the retries. Each attempt already waits the 5s busy timeout, and a database locked that long would fail the schema migration next anyway.

[coderabbitai]

Note

Quiet mode is enabled, so only the most important comments were posted inline. Other review comments are grouped below.

🟡 Other comments (1)

backend/config/library-search-index.js-216-221 (1)

216-221: 🩺 Stability & Availability | 🟡 Minor | ⚡ Quick win

Return false before BEGIN IMMEDIATE when FTS5 is unavailable.

Line 216 returns early only when fts5Enabled is truthy. When FTS5 is unavailable, every startup therefore enters db.transaction(...).immediate().

The transaction only reads state and then returns false from createSearchSchema. It writes nothing. It still acquires a RESERVED lock on each start.

Assume another process holds a write transaction or runs a migration at the same time. Then BEGIN IMMEDIATE waits for the busy timeout and can throw SQLITE_BUSY, which fails startup on a no-op path. This contradicts the PR goal of avoiding write locks when no schema change is needed.

🔒️ Proposed fix

-  const current = hasCurrentSearchIndex();
-  if (fts5Enabled && current.hasIndex && current.hasTriggers && current.version === SEARCH_INDEX_VERSION) return true;
+  if (!fts5Enabled) return false;
+  const current = hasCurrentSearchIndex();
+  if (current.hasIndex && current.hasTriggers && current.version === SEARCH_INDEX_VERSION) return true;
 
   return db.transaction(() => {
     const { hasIndex, hasTriggers, version } = hasCurrentSearchIndex();
-    if (fts5Enabled && hasIndex && hasTriggers && version === SEARCH_INDEX_VERSION) return true;
-    if (fts5Enabled) {
-      db.exec(`
+    if (hasIndex && hasTriggers && version === SEARCH_INDEX_VERSION) return true;
+    db.exec(`
         DROP TRIGGER IF EXISTS library_search_documents_ai;
         ...
-      `);
-    }
+    `);

This follows the retrieved learnings on SQLite lock contention across processes.

Source: Learnings

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: QUIET

Plan: Advanced

Run ID: 29b78ea5-8bb7-4c51-896d-2a4a52417c0f

📥 Commits

Reviewing files that changed from the base of the PR and between 5589c2e and c15de71.

📒 Files selected for processing (3)

• .tests/library/library-search-index.test.js
• backend/config/db-sqlite.js
• backend/config/library-search-index.js

Included review availability: Your plan provides up to 4 included reviews per hour; 2 remain after this review.

[github-actions]

Available on nightly

A linked pull request was merged into main and is now included in the latest nightly build. Linked issues stay open until this change ships in a stable release.

docker pull ghcr.io/lklynet/aurral:nightly

• Build: nightly.295+4a7dcc0
• View the nightly workflow · View changes on main