​

Usage Metrics FAQs

​

Billing FAQs

​

Usage Troubleshooting

​

Concurrent connections

​

Sync operations

​

Key Scenarios to Watch For

1. New App Installations: When a new user installs your app, PowerSync needs to sync the complete operations history. We help manage this by:
   • Running automatic daily compacting on Cloud instances
   • Providing manual defragmentation options (in the PowerSync Dashboard)
2. Existing Users: While compacting and defragmenting reduces the operations history, they trigger additional sync operations for existing users.
   • Want to optimize this? Check out our defragmenting guide
3. Sync Rule Deployments: When you deploy changes to Sync Rules, PowerSync recreates the sync buckets from scratch. This has two effects:
   • New app installations will sync fewer operations since the operations history is reset.
   • Existing users will temporarily experience increased sync operations as they need to re-sync the updated buckets.
   We are planning incremental sync rule reprocessing, which will allow PowerSync to only reprocess buckets whose definitions have changed, rather than all buckets.
4. Unsynced Columns: Any row update triggers a new operation in the logical replication stream, regardless of which columns changed. In other words, PowerSync tracks changes at the row level, not the column level. This means:
   • Updates to columns not included in your Sync Rules still create sync operations.
   • Even a no-op update like UPDATE mytable SET id = id generates a new operation for each affected row.
   While selectively syncing columns helps with data access control and reducing data transfer size, it doesn’t reduce the number of sync operations.

​

Data hosted

1. A current copy of the data, which should be roughly equal to the subset of your source data that is covered by your sync rules configuration;
2. A history of all operations on data in buckets. This can be bigger than the source, since it includes the history, and one row can be in multiple buckets; and
3. Data for parameter lookups. This should be fairly small in most cases.

​

Troubleshooting Strategies

1. Identify Timing
   • Use Usage Metrics to pinpoint usage spikes.
2. Review Logs
   • Use Instance Logs to review sync service logs during the spike(s).
   • Enable the Metadata option.
   • Search for “Sync stream complete” entries (use your browser’s search function) to review:
     • How many operations synced
     • The size of data transferred
     • Which clients/users were involved
     

     Example of 'Sync stream complete' logs
3. Compare Metrics Use the Diagnostics app to compare total rows vs. operations synced to the user device. If you are seeing a much higher number of operations, you might benefit from defragmentation.
4. Detailed Sync Operations
   • Use the test-client’s fetch-operations command with the --raw flag:
     Copy

     node dist/bin.js fetch-operations --raw --token your-jwt --endpoint https://12345.powersync.journeyapps.com
     

     This returns the individual operations for a user in JSON. Example response:
     Copy

     {
        "by_user[\"0b32a7cb-26fb-4993-9c60-9291a430337e\"]": [
            {
            "op_id": "0",
            "op": "CLEAR",
            "checksum": 2082236117
            },
            {
            "op_id": "1145383",
            "op": "PUT",
            "object_type": "todos",
            "object_id": "69688ea0-d3f6-46c9-81a2-cdbe54eeb54d",
            "checksum": 3246341700,
            "subkey": "6752f74f8176c1b5ba851480/fcb2cd3c-dcef-5c46-8b17-7b83d31fda2b",
            "data": "{\"id\":\"69688ea0-d3f6-46c9-81a2-cdbe54eeb54d\",\"created_at\":\"2024-09-16 10:16:35.352665Z\",\"description\":\"Buy groceries\",\"user_id\":\"0b32a7cb-26fb-4993-9c60-9291a430337e\"}"
            },
            {
            "op_id": "1145387",
            "op": "PUT",
            "object_type": "todos",
            "object_id": "7e4a4550-af3b-4876-a01a-10dc0084f0a6",
            "checksum": 1103209588,
            "subkey": "6752f74f8176c1b5ba851480/75bbc91d-cfc9-5b22-9f85-ea31a8720bf8",
            "data": "{\"id\":\"7e4a4550-af3b-4876-a01a-10dc0084f0a6\",\"created_at\":\"2024-10-07 16:17:37Z\",\"description\":\"Plant tomatoes\",\"user_id\":\"0b32a7cb-26fb-4993-9c60-9291a430337e\"}"
            }
        ]
      }
     

​

Accident Forgiveness