Release request: open-retry fix from #147 — SQLITE_BUSY_RECOVERY (261) at cold-start open hit in production on 1.14.3

[amitmai]

Summary

We hit the exact failure class that #147 fixes, in production, on a released SDK version (1.14.3) — and since the latest release (1.14.4, June 22) predates that merge (June 29), every app on a released version is still exposed. Requesting a release that includes #147.

What we observed (production, iOS 26.5.2, SDK 1.14.3)

One second after a cold app launch:

sqliteError(extendedResultCode: 261, offset: nil,
            message: Optional("database is locked"),
            errorString: Optional("database is locked"),
            sql: Optional("pragma journal_mode = WAL"))

Extended code 261 = SQLITE_BUSY_RECOVERY. Root cause on 1.14.3: configureConnection runs pragma journal_mode = WAL before its own pragma busy_timeout = 30000, so the WAL transition executes at the default busy_timeout = 0 and throws instantly on a transient recovery/contention lock instead of waiting. The connect then fails and every watch stream consuming the database dies.

We reproduced it deterministically in a test: open a file-backed PowerSyncDatabase while a competing connection holds an EXCLUSIVE lock → the open throws the BUSY family at pragma journal_mode = WAL. Arming busy_timeout first (via the public initialStatements: parameter — our current workaround) makes the same contended open wait out the lock and succeed.

#147 fixes this properly on main (busy_timeout ordered first + the async open-retry loop covering the handler-less WAL-transition case). It just hasn't shipped.

Ask

A tagged release including #147. Happy to provide any more detail from our production event or the reproduction test.

[simolus3]

We'll release the outstanding changes soon, likely today.

However, this error still shouldn't have happened: Since the current version of the SDK doesn't let you share databases across processes and we use an internal mutex to avoid concurrent writes, it should be impossible to run into database is locked errors even without the busy timeout.

open a file-backed PowerSyncDatabase while a competing connection holds an EXCLUSIVE lock

Do you have multiple PowerSyncDatabase instances in your app? This condition should never be reached in a real app.

[amitmai]

Thanks — glad the open-retry release is imminent.

You're right it shouldn't happen with a single instance, and we do use exactly one file-backed PowerSyncDatabase (one owner object, one open in our provider; our share extension never opens the DB). Digging in, the trigger looks like our account-switch teardown: we called disconnectAndClear() and then dropped the reference (set it to nil), but we never called an explicit close(). Since disconnectAndClear() keeps the SQLite connection open for potential reconnect, the old connection's file handle was only released on ARC deallocation — which lags if a lingering watch Task/actor still retains the database. On a fast sign-out → sign-in, our new open then raced the not-yet-deallocated old connection on the same dbFilename → database is locked.

Two questions:

1. Is disconnectAndClear() expected to be followed by an explicit close() before opening a new PowerSyncDatabase on the same dbFilename, or should it release the connection itself?
2. Is there a supported close/teardown API we should await to guarantee the file is fully released before re-opening?

We've gone ahead and added a deterministic close() as the final step of our account-switch teardown (before the next open), and it resolves the issue on our side. Happy to confirm against the open-retry release when it lands. Thanks for the pointer!

[simolus3]

Glad to hear you were able to resolve the issue! Indeed, disconnectAndClear() does not close the database itself, it just clears contents. Calling and awaiting close() is the pattern I'd recommend as well, all connections should be fully released afterwards.

If you use disconnectAndClear() for account switching only, there's technically no reason to also close and re-open the database though. The database keeps being usable after disconnectAndClear() (e.g. you can insert new local data, and also call connect() again). But if you want to keep doing that, there's no harm in a close() + re-open apart from the fact that it might be slightly slower.

Unrelated to the issue here: The soft: true flag on disconnectAndClear might be interesting for account-switching use cases. It will delete visible data from the database while keeping internal downloaded data around. If the new user has access to some of the buckets of the old user, the next sync will be faster since not all data would have to be downloaded again.

[amitmai]

Thanks, that all matches what we're seeing — close() + re-open on account switch is working cleanly for us.

You're right that it's optional; the reason we hit database is locked at all was that our own view-scoped watch Tasks were strong-capturing the PowerSyncDatabase and outliving sign-out (SwiftUI defers their deinit), so a fast re-sign-in make() raced a still-open connection on the same filename. We've since added a store-level registry that cancels + drains all watch tasks before close(), so the references are released deterministically now. Between that and the explicit close(), it's solid.

Great tip on soft: true — we do have a real account-switching case where two accounts on one device can share buckets (family sharing), so a soft clear that avoids re-downloading shared bucket data would be a nice win. We've filed it to evaluate (carefully, since our teardown also has a photo-byte-cleanup ordering invariant). Appreciate the thorough responses!

[simolus3]

We've just released version 1.15.0 containing the requested fix.