Skip to content

Adopt structured error type #96

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Jun 30, 2025
Merged

Adopt structured error type #96

merged 7 commits into from
Jun 30, 2025

Conversation

simolus3
Copy link
Contributor

@simolus3 simolus3 commented Jun 30, 2025

This is a preparation step to improve error handling in the sync client - basically, we'll want some operations to be "retryable" - e.g. if we reach a "database locked" error during sync_local, there's no reason to shut the entire sync iteration down. A client could just retry after unlocking the database.
Other errors, like e.g. a decoding error for sync lines or a state mismatch (like receiving a checkpoint_diff without a checkpoint line firs) are still fatal though.

To reliably determine which errors interrupt a sync iteration and which don't, this begins by refactoring the error handling in core:

  1. SQLiteError has been renamed to PowerSyncError, because we're not just dealing with SQLite errors after all.
  2. PowerSyncError defines an enum of all possible errors in the core extension. We can still "rethrow" SQLite errors (and also add context if necessary), but other issues like e.g. problems decoding JSON now have their own enum entry depending on where they occur (like ArgumentError or SyncProtocolError).
  3. We use the thiserror crate to simplify defining this error type - the messages returned by our SQLite functions have also been improved somewhat.
  4. All places that report errors in the core extension have been refactored to use appropriate enum entries. The enum entry for sqlite result codes is exclusively used for errors that actually originate in SQLite. (This changes the result code in some cases, but I don't think that could break anything).

As a follow-up, #97 will change the sync client to use the structured errors to determine which are fatal and which can be retried. We could technically do the same thing with result codes alone, but it's still nice to be explicit about which error types are recoverable.

@simolus3 simolus3 merged commit 625fa83 into main Jun 30, 2025
21 checks passed
@simolus3 simolus3 deleted the refactor-errors branch June 30, 2025 16:55
@simolus3 simolus3 mentioned this pull request Jul 8, 2025
10 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants