Troubleshooting
Summary of common troubleshooting tools and pointers.
Troubleshooting techniques depend on the type of issue:
Connection issues between client and server: See Client-side Diagnostics
Expected data not appearing on device: See Client-side Diagnostics
Data lagging behind on PowerSync service: Data on the PowerSync service instance cannot currently directly be inspected. This is something we are investigating.
Writes to the backend database are failing: PowerSync is not actively involved: use normal debugging techniques (server-side logging; client and server-side error tracking).
Updates are slow to sync: See Performance
Client-side Diagnostics
Diagnostics app
This is a standalone web app that presents data from the perspective of a specific user. It can be used to:
See stats about the user's local database.
Inspect tables, rows and sync buckets on the device.
Query the local SQL database.
Identify common issues. E.g. too many sync buckets.
See the Readme for further details and getting started instructions.
Diagnostics API
We also provide diagnostics via an API on the client. Examples include the connection status, last completed sync time, and local upload queue size.
If for example, a change appears to be missing on the client, you can check if the last completed sync time is greater than the time the change occurred.
The JavaScript SDKs (React Native, web) also log the contents of sync bucket changes to console.debug if verbose logging is enabled. This should log which PUT/PATCH/DELETE operations have been applied from the server.
Inspect local SQLite Database
Another useful debugging tool as a developer is to open the SQLite file and inspect the contents. We share an example of how to do this on iOS from macOS in this video:
Essentially, run the following to grab the SQLite file:
find ~/Library/Developer/CoreSimulator/Devices -name "mydb.sqlite"
The diagnostics app and several of our demo apps also contain a SQL console view to inspect the local database contents. Consider implementing similar functionality in your app.
See an example here.
Logging
Our client SDKs support logging to troubleshoot issues. Logging is enabled by default in our Flutter SDK. See the following usage examples for enabling logging in our JavaScript SDKs:
Performance
When running into issues with data sync performance, first review our expected Performance and Limits.
These are some common pointers when it comes to diagnosing and understanding performance issues:
You will notice differences in performance based on the row size (think 100 byte rows vs 8KB rows)
At this point the initial sync can take a while. We are busy implementing functionality to "compact" the data, so that initial sync will be faster. Right now, as a workaround, you can deploy any change to sync rules, which will have a similar effect.
You can get big performance gains by using transactions & batching as explained in this blog post.
Last updated
