Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions configuration/auth/development-tokens.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,10 @@ This can also be used to generate a token for a specific user to debug issues.

Development tokens can be used for testing purposes either with the [Sync Diagnostics Client](https://diagnostics-app.powersync.com), the [test-client](https://github.com/powersync-ja/powersync-service/tree/main/test-client), or your app itself (for development purposes).

### Using with Sync Test

If you're on PowerSync Cloud, [Sync Test](/tools/powersync-dashboard#sync-test) in the PowerSync Dashboard generates a development token for a user ID and connects a client in your browser with it. You do not need to copy the token.

### Using with Sync Diagnostics Client

The [Sync Diagnostics Client](https://diagnostics-app.powersync.com) allows you to quickly test syncing and inspect a user's SQLite database, to verify that your PowerSync Service configuration and Sync Streams behave as expected.
Expand Down
10 changes: 7 additions & 3 deletions debugging/troubleshooting.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,10 @@
4. **Writes to the backend source database are failing:** PowerSync is not actively involved: use normal debugging techniques (server-side logging; client and server-side error tracking).
5. **Updates are slow to sync, or queries run slow**: See [Performance](#performance)

### Sync Test

If you're on PowerSync Cloud, use [Sync Test](/tools/powersync-dashboard#sync-test) in the dashboard to connect a client as a specific user and inspect it with [PowerSync DevTools](/tools/devtools-overview).

### Sync Diagnostics Client

Access the Sync Diagnostics Client here: [https://diagnostics-app.powersync.com](https://diagnostics-app.powersync.com)
Expand Down Expand Up @@ -101,14 +105,14 @@

The result tells you where to look next:

- **The wait completes, but the data is still missing:** Check that the data was committed to the source database before you created the request, and that the user's Sync Streams include it. To see what the device has synced, use [PowerSync DevTools](/tools/devtools-overview) or the [Sync Diagnostics Client](#sync-diagnostics-client).
- **The wait completes, but the data is still missing:** Check that the data was committed to the source database before you created the request, and that the user's Sync Streams include it. To see what the device has synced, use [PowerSync DevTools](/tools/devtools-overview) in your app. To see what the user's Sync Streams sync, use [Sync Test](#sync-test) or the [Sync Diagnostics Client](#sync-diagnostics-client).
- **The wait fails or does not complete:** The wait has not confirmed catch-up. If it failed, check whether it was canceled or timed out. Check `SyncStatus` for connection, upload, or download errors, then check [replication lag](/maintenance-ops/replication-lag) and [instance logs](#instance-logs).

### Inspect Local SQLite Database

Opening the SQLite file directly is useful for verifying sync state, inspecting raw table contents, and diagnosing unexpected data. See [Understanding the SQLite Database](/maintenance-ops/client-database-diagnostics) for platform-specific instructions (Android, iOS, Web), how to merge the WAL file, and how to analyze storage usage.

Our [Sync Diagnostics Client](/tools/diagnostics-client) and several of our [demo apps](/intro/examples) also contain a SQL console view to inspect the local database contents without pulling the file. Consider implementing similar functionality in your app. See a React example [here](https://github.com/powersync-ja/powersync-js/blob/main/tools/diagnostics-app/src/app/views/sql-console.tsx).
[PowerSync DevTools](/tools/devtools/using-devtools#data-inspector), our [Sync Diagnostics Client](/tools/diagnostics-client), and several of our [demo apps](/intro/examples) also contain a SQL console view to inspect the local database contents without pulling the file. Consider implementing similar functionality in your app. See a React example [here](https://github.com/powersync-ja/powersync-js/blob/main/tools/diagnostics-app/src/app/views/sql-console.tsx).

### Client-Side Logging

Expand Down Expand Up @@ -165,7 +169,7 @@

#### Common Causes of Latency

- **Large initial sync**: if your Sync Streams result in a large dataset, the first sync after connecting will be slow. Inspect bucket sizes and sync state with the [Sync Diagnostics Client](/tools/diagnostics-client).
- **Large initial sync**: if your Sync Streams result in a large dataset, the first sync after connecting will be slow. Inspect bucket sizes and sync state with [Sync Test](#sync-test) if you're on PowerSync Cloud, or with the [Sync Diagnostics Client](/tools/diagnostics-client) if you self-host.
- **Upload queue blocking downloads**: by default, uploads are processed before downloads, so a backlogged upload queue delays receiving new data. Buckets and streams at [priority 0](/sync/streams/prioritized-sync) are not blocked by uploads, but come with the trade-off of potential sync inconsistencies.
- **Replication lag on the source database**: high write volume, long-running transactions, bulk updates, or backfills can cause replication to fall behind faster than the service can drain it. See [Replication Lag](/maintenance-ops/replication-lag) for source-specific causes and fixes.

Check warning on line 174 in debugging/troubleshooting.mdx

View check run for this annotation

Mintlify / Mintlify Validation (powersync) - vale-spellcheck

debugging/troubleshooting.mdx#L174

Did you really mean 'backfills'?
- **Too many buckets per user**: incremental sync overhead scales roughly linearly with the number of buckets per user. See [Too Many Buckets](#psync_s2305-too-many-buckets-/-parameter-query-results) above.
Binary file added images/usage/tools/dashboard-sync-test.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
6 changes: 3 additions & 3 deletions integrations/neon.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -303,14 +303,14 @@ The notes list is empty at first. Create a note, then disconnect your device fro

### Test Your Sync Streams (Optional)

To see which data syncs to a specific user, generate a development token for a user who signed up in the demo app, and open it in the [Sync Diagnostics Client](/tools/diagnostics-client). Use the user's ID as the token subject. This ID is the `owner_id` value of the user's notes.
To see which data syncs to a specific user, connect as a user who signed up in the demo app. Use the user's ID, which is the `owner_id` value of the user's notes.

<Tabs>
<Tab title="Web UI">
In the PowerSync Dashboard, go to the **Sync Test** view. Enter the user ID as the token subject, then click **Generate token** and **Launch Sync Diagnostics Client**.
In the PowerSync Dashboard, go to the [Sync Test](/tools/powersync-dashboard#sync-test) view. Enter the user ID, then click **Connect**.
</Tab>
<Tab title="CLI">
In the demo directory, run the following command and paste the token into the [Sync Diagnostics Client](https://diagnostics-app.powersync.com):
In the demo directory, run the following command to generate a development token for the user. Then paste the token into the [Sync Diagnostics Client](https://diagnostics-app.powersync.com):

```bash
powersync generate token --subject=<user-id>
Expand Down
22 changes: 11 additions & 11 deletions intro/setup-guide.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -617,7 +617,7 @@ For quick development and testing, you can generate a temporary development toke

You'll use this token for two purposes:

- **Testing with the _Sync Diagnostics Client_** (in the next step) to verify your setup and Sync Streams
- **Testing with the _Sync Diagnostics Client_** (in the next step) to verify your setup and Sync Streams, if you self-host
- **Connecting your app** (in a later step) to test the client SDK integration

<Tabs>
Expand Down Expand Up @@ -664,18 +664,18 @@ You'll use this token for two purposes:
</Tab>
</Tabs>

## 6. [Optional] Test Sync with the Sync Diagnostics Client
## 6. [Optional] Test Sync

Before implementing the PowerSync Client SDK in your app, you can validate that syncing is working correctly using our [Sync Diagnostics Client](https://diagnostics-app.powersync.com) (this hosted version works with both PowerSync Cloud and self-hosted setups).

Use the development token you generated in the [previous step](#5-generate-a-development-token) to connect and verify your setup:
Before implementing the PowerSync Client SDK in your app, you can validate that syncing is working correctly. If you're on PowerSync Cloud, use [Sync Test](/tools/powersync-dashboard#sync-test) in the PowerSync Dashboard. If you self-host, use our [Sync Diagnostics Client](https://diagnostics-app.powersync.com) with the development token you generated in the [previous step](#5-generate-a-development-token).

<Tabs>
<Tab title="PowerSync Cloud">
1. Go to [https://diagnostics-app.powersync.com](https://diagnostics-app.powersync.com)
2. Enter your development token at **PowerSync Token** (from the [Generate a Development Token](#5-generate-a-development-token) step above)
3. Enter your PowerSync instance URL at **PowerSync Endpoint** (found in the [PowerSync Dashboard](https://dashboard.powersync.com/) - click **Connect** in the top bar)
4. Click **Proceed**
1. In the [PowerSync Dashboard](https://dashboard.powersync.com/), select your project and instance
2. Go to the **Sync Test** view
3. Enter a user ID
4. Click **Connect**

Sync Test connects a client in your browser as that user and shows [PowerSync DevTools](/tools/devtools-overview) for it. It needs the development tokens setting from the previous step.
</Tab>
<Tab title="Self-Hosted">
1. Go to [https://diagnostics-app.powersync.com](https://diagnostics-app.powersync.com)
Expand All @@ -689,12 +689,12 @@ Use the development token you generated in the [previous step](#5-generate-a-dev
</Tab>
</Tabs>

The Sync Diagnostics Client will connect to your PowerSync Service instance and display [information](https://github.com/powersync-ja/powersync-js/tree/main/tools/diagnostics-app#functionality) about the synced data, and allow you to [query](https://github.com/powersync-ja/powersync-js/tree/main/tools/diagnostics-app#sql-console) the client-side SQLite database.
Both tools show the synced data and let you query the client-side SQLite database. The Sync Diagnostics Client shows this [information](https://github.com/powersync-ja/powersync-js/tree/main/tools/diagnostics-app#functionality) and has a [SQL console](https://github.com/powersync-ja/powersync-js/tree/main/tools/diagnostics-app#sql-console). In Sync Test, use the DevTools **Data Inspector** tab.

<Check>
**Checkpoint:**

Inspect your synced tables in the Sync Diagnostics Client. These should match the Sync Streams you [defined previously](#4-define-sync-streams). This confirms your setup is working correctly before integrating the client SDK into your app.
Inspect your synced tables in Sync Test or the Sync Diagnostics Client. These should match the Sync Streams you [defined previously](#4-define-sync-streams). This confirms your setup is working correctly before integrating the client SDK into your app.
</Check>

## 7. Use the Client SDK
Expand Down
11 changes: 11 additions & 0 deletions maintenance-ops/monitoring-and-alerting.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -169,7 +169,7 @@

#### Excluding Results

Prefix a term or filter with `-` to exclude matching entries. This is useful for hiding known-noisy errors while triaging:

Check warning on line 172 in maintenance-ops/monitoring-and-alerting.mdx

View check run for this annotation

Mintlify / Mintlify Validation (powersync) - vale-spellcheck

maintenance-ops/monitoring-and-alerting.mdx#L172

Did you really mean 'triaging'?

```text
-error:PSYNC_S2106
Expand Down Expand Up @@ -248,6 +248,17 @@

Use the [Session Lifecycle](/debugging/log-reference#session-lifecycle) and [Session Fields](/debugging/log-reference#session-fields) reference to interpret the results.

### Sync As This User

Use **Sync As This User** to reproduce what a user synced. It opens [Sync Test](/tools/powersync-dashboard#sync-test) as the user, with the connection parameters and Sync Stream subscriptions from their sync logs. Sync Test then shows the client in [PowerSync DevTools](/tools/devtools-overview).

1. In the Sync & API logs, hover over an entry that has a user ID.
2. Click the **Sync As This User** button on the entry. If the **Metadata** display option is on, you can also open the menu of the `user_id` pill and choose **Sync As This User**.
3. Check the values in the dialog. If a value is wrong or missing, change it or add it. Sync logs keep only the first 20 connection parameters and shorten values longer than 100 characters, and the dialog notes the values that the logs could not fill in. To use the values from another recent Sync Session of the user, select them under the field.
4. Click **Sync As This User** to open Sync Test and connect.

The button shows only if you can use Sync Test. See the [Sync Test requirements](/tools/powersync-dashboard#sync-test).

### Replication Flush Entries

To investigate replication throughput, select Replicator logs and search for `Flushed`. Each entry reports a batch of writes to bucket storage. See [Flushed Batches](/debugging/log-reference#flushed-batches) for message and field meanings.
Expand Down
2 changes: 1 addition & 1 deletion migration-guides/atlas-device-sync.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -87,7 +87,7 @@ Follow the steps for MongoDB and your client platform/framework in our standard
- [Connect PowerSync To Your Source Database](/intro/setup-guide#3-connect-powersync-to-your-source-database) (MongoDB)
- [Define Sync Streams](/intro/setup-guide#4-define-sync-streams)
- [Generate a Development Token](/intro/setup-guide#5-generate-a-development-token)
- [Test Sync with the Sync Diagnostics Client](/intro/setup-guide#6-optional-test-sync-with-the-sync-diagnostics-client)
- [Test Sync](/intro/setup-guide#6-optional-test-sync)
- [Use the Client SDK](/intro/setup-guide#7-use-the-client-sdk)
- [Install the Client SDK](/intro/setup-guide#install-the-client-sdk)
- [Define Your Client-Side Schema](/intro/setup-guide#define-your-client-side-schema)
Expand Down
2 changes: 1 addition & 1 deletion resources/usage-and-billing/usage-and-billing-faq.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -136,7 +136,7 @@ Narrow the results with structured filters:
![Instance logs filtered to show sync stream complete entries](/images/resources/instance-logs-sync-stream-complete.png)
</Frame>

You may need to scroll to load more logs. To get the filtered logs as a file, click the **Export** (download) button in the top-right of the logs toolbar. It exports the currently visible logs to CSV.
You may need to scroll to load more logs. To get the filtered logs as a file, click the **Export** (download) button on the right of the logs toolbar. It exports the currently visible logs to CSV.

These log entries show which pattern below applies. If both the operation count and the transferred size are high, see [More Operations Than Rows](#more-operations-than-rows). If the operation count is moderate but the size is large, see [Large Rows](#large-rows). If the same user appears repeatedly in quick succession, see [Repetitive Syncing by the Same User](#repetitive-syncing-by-the-same-user).

Expand Down
4 changes: 2 additions & 2 deletions sync/advanced/reducing-bucket-count.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -51,9 +51,9 @@ New checkpoint: 800178 | write: null | buckets: 7 | param_results: 6 ["5#org_dat
- `param_results` is the total number of parameter rows for this connection.
- The array lists the bucket names. Each name already includes its parameter value. The list stops after 20 names.

### Sync Diagnostics Client
### Sync Test and the Sync Diagnostics Client

The [Sync Diagnostics Client](/tools/diagnostics-client) shows the buckets for one user. It does not load for a user who is over the limit, because that user's sync fails before the data loads. Use the instance logs and the error breakdown for those users. The client shows the bucket count, which may not be the limit you reached. Confirm the limit from the error message.
[Sync Test](/tools/powersync-dashboard#sync-test) on PowerSync Cloud and the [Sync Diagnostics Client](/tools/diagnostics-client) show the buckets for one user. Neither loads data for a user who is over the limit, because that user's sync fails before the data loads. Use the instance logs and the error breakdown for those users. Both tools show the bucket count, which may not be the limit you reached. Confirm the limit from the error message.

<BucketCountExampleApp />

Expand Down
2 changes: 1 addition & 1 deletion sync/streams/quickstart.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -257,7 +257,7 @@ const sub = await db.syncStream('todos', { list_id: 'abc' })
- **Primary Key**: PowerSync requires every synced table to have a primary key column named `id` of type `text`. If your backend uses a different column name or type, you'll need to map it. For MongoDB, collections use `_id` as the ID field; you must alias it in your stream queries (e.g. `SELECT *, _id as id FROM your_collection`).
- **Case Sensitivity**: To avoid issues across different databases and platforms, use **lowercase identifiers** for all table and column names in your Sync Streams. If your backend uses mixed case, see [Case Sensitivity](/sync/advanced/case-sensitivity) for how to handle it.
- **Bucket Limits**: Each user has a limit on how many buckets they can sync ([1,000 by default](/resources/performance-and-limits)), and the query pattern determines how many each stream creates. See [Bucket Count](/sync/streams/bucket-count) for how buckets are counted, and [Reducing Bucket Count](/sync/advanced/reducing-bucket-count) to resolve `PSYNC_S2305` errors.
- **Troubleshooting**: If data isn't syncing as expected, the [Sync Diagnostics Client](/tools/diagnostics-client) helps you inspect what's happening for a specific user. You can see which buckets the user has and what data is being synced.
- **Troubleshooting**: If data isn't syncing as expected, inspect what's happening for a specific user with [Sync Test](/tools/powersync-dashboard#sync-test) if you're on PowerSync Cloud, or the [Sync Diagnostics Client](/tools/diagnostics-client) if you self-host. You can see which buckets the user has and what data is being synced.

## Examples & Demos

Expand Down
21 changes: 13 additions & 8 deletions tools/devtools-overview.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -83,13 +83,18 @@ DevTools reads from the database that your app has open, so it shows the same da
</Card>
</CardGroup>

## DevTools vs. Sync Diagnostics Client
## DevTools vs. Sync Test and the Sync Diagnostics Client

Use DevTools to inspect the client in your running app. Use the [Sync Diagnostics Client](/tools/diagnostics-client) to see the data that the Service syncs to a specific user. You can use both in tandem.
Use DevTools to inspect the client in your running app. To see the data that the Service syncs to a specific user without your app, connect a separate client as that user:

| | PowerSync DevTools | Sync Diagnostics Client |
| --- | --- | --- |
| **How it connects** | To your running app | With a user JWT and the PowerSync endpoint |
| **What you inspect** | Local SQLite data and sync state in your app | Sync data: buckets, operations, stream subscriptions |
| **Environment** | Development only | Any environment |
| **SDK-specific** | Yes | No. It works with all SDKs. |
- If you're on PowerSync Cloud, use [Sync Test](/tools/powersync-dashboard#sync-test) in the PowerSync Dashboard. It connects a client in your browser as the user and shows DevTools for that client.
- If you self-host, use the [Sync Diagnostics Client](/tools/diagnostics-client) with a [development token](/configuration/auth/development-tokens) for the user.

Sync Test signs in with a development token that contains only the user ID. If your Sync Streams read other claims from the token, use the Sync Diagnostics Client with a token from your auth provider instead.

| | PowerSync DevTools | Sync Test | Sync Diagnostics Client |
| --- | --- | --- | --- |
| **How it connects** | To your running app | As a user ID, from the PowerSync Dashboard | With a user JWT and the PowerSync endpoint |
| **What you inspect** | Local SQLite data and sync state in your app | The same DevTools panels, for a client in your browser | Sync data: buckets, operations, stream subscriptions |
| **Availability** | Development builds of your app | PowerSync Cloud | PowerSync Cloud and self-hosted |
| **SDK-specific** | Yes | No. It runs the Web SDK. | No. It works with all SDKs. |
2 changes: 1 addition & 1 deletion tools/overview.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ sidebarTitle: "Overview"
</Card>

<Card title="Sync Diagnostics Client" icon="stethoscope" horizontal href="/tools/diagnostics-client">
Web app to inspect and debug syncing. Works with both cloud and self-hosted PowerSync Service instances.
Web app to inspect and debug what a user syncs. Works with both cloud and self-hosted PowerSync Service instances. If you're on PowerSync Cloud, Sync Test in the dashboard does this without a separate app.
</Card>

<Card title="Local Development" icon="code" horizontal href="/tools/local-development">
Expand Down
Loading
Loading