journeyapps/powersync-diagnostics-app repository overview

⁠Sync Diagnostics Client

A browser-based tool for inspecting PowerSync sync behavior and databases. Supports both live syncing from a PowerSync instance, and offline inspection of a SQLite database (by uploading a file).

A hosted version of the Sync Diagnostics Client is available at https://diagnostics-app.powersync.com/⁠. It can also be run as a local standalone web app. It is based on the PowerSync Web SDK⁠.

⁠Running the Sync Diagnostics Client

⁠Docker

docker run --pull always -p 8082:80 journeyapps/powersync-diagnostics-app

The app will be available on http://localhost:8082⁠.

⁠Local Development

In the root of the repository, run:

pnpm install
pnpm build:packages

Then in this directory:

pnpm dev

The app is now available on http://localhost:5173/⁠.

⁠Getting Started

The landing page offers two paths:

• Connect to PowerSync: Live sync diagnostics using a JWT token. View real-time sync status, bucket data, and manage connection/client parameters.
• Inspect SQLite File: Offline inspection of a local SQLite database file. No authentication required.

⁠Connect to PowerSync

Connecting as a user requires a PowerSync Token (JWT) and Endpoint.

⁠PowerSync Token

Generate a development token⁠ for the user.

⁠PowerSync Endpoint

For PowerSync development tokens, the endpoint is populated automatically from the JWT. For other JWTs (e.g. Supabase tokens), enter it manually.

• PowerSync Cloud: Use your instance URL.
• Self-hosted (Docker): The internal Docker URL won't be reachable from outside the network. Use the endpoint as exposed by docker-proxy, e.g. http://localhost:8080.

You can also deep-link directly with a ?token= query parameter to auto-sign-in.

⁠Sync Overview

The main dashboard after connecting:

• Summary stats: Bucket count, total rows, downloaded/total operations, data size, metadata size, last synced time.
• Tables: All synced tables with row count and data size.
• Buckets: Per-bucket breakdown including download progress, operation counts, and status.
• Clear & Redownload: Clears all local data and re-syncs from the server.
• Compacting alert: Shown when total operations significantly exceed total rows, indicating bucket history has accumulated.

⁠Sync Stream Subscriptions

Manage Sync Stream subscriptions directly from the Sync Overview page:

• View all active Sync Stream subscriptions with their parameters, priority, sync time, and eviction time.
• Add Subscription: Subscribe to a new Sync Stream with optional subscription parameters and priority.
• Unsubscribe: Remove explicit subscriptions (triggers a reconnect to apply the change).

⁠SQL Console

Execute read-only SQL queries against the live PowerSync database:

• Query history is persisted across sessions.
• Large result sets are automatically limited to 10,000 rows to prevent UI freezes.
• Results are displayed in a searchable, sortable, paginated table.

⁠Dynamic Schema

The schema is dynamically inferred from downloaded data and automatically updated as new data arrives. This page displays the current inferred schema for reference.

Note: Tables with 0 synced rows won't appear in the schema. To refresh after Sync Streams / Sync Rules changes, use "Clear & Redownload" on the Sync Overview page.

⁠Connection Parameters / Client Parameters

Manage Connection Parameters⁠ (Sync Streams) / Client Parameters⁠ (Sync Rules) that are sent with sync requests:

• Add, edit, and delete key-value parameters.
• Supports string, number, boolean, array, and object types.
• Changes trigger an automatic reconnect after a short debounce.

⁠SQLite File Inspector

The File Inspector allows offline inspection of SQLite database files. It is useful for analysis of database files extracted from devices. No authentication is required.

⁠Opening a File

Drag and drop a SQLite database file, or click to browse. The file is opened in-browser using wa-sqlite - nothing is uploaded to a server.

⁠Database Overview

• File info: File name, size, last modified date.
• Database structure: Tables, views, indexes, and triggers with their SQL definitions and row counts.
• PowerSync stats: If the file is a PowerSync database (contains ps_ tables), aggregate stats are shown: total rows, data/metadata size, CRUD queue, bucket count. Warnings are shown for pending CRUD entries (failed uploads) or when compacting is recommended.

⁠SQL Console

Execute read-only SQL queries against the uploaded file. Works the same as the SQL Console for live synced databases, with separate query history.

⁠Known Issues

• Having the app open in multiple tabs may cause issues.
• When syncing large amounts of data, the dashboard may be slow while operations are being downloaded.