Skip to content
Merged
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
2 changes: 1 addition & 1 deletion client-sdks/advanced/state-management.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -120,7 +120,7 @@ final class MyWidget extends ConsumerWidget {
}
```

### Attachment queue
### Attachment Queue

If you're using the attachment queue helper to sync media assets, you can also wrap that in a provider:

Expand Down
6 changes: 3 additions & 3 deletions client-sdks/frameworks/flutter-web-support.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ Install the [latest version](https://pub.dev/packages/powersync/versions) of the
dart pub add powersync:'^2.0.0'
```

### Additional config
### Additional Config

#### Assets
Web support requires `sqlite3.wasm` and worker (`powersync_db.worker.js` and `powersync_sync.worker.js`) assets to be served from the web application. They can be downloaded to the web directory by running the following command in your application's root folder.
Expand All @@ -40,7 +40,7 @@ dart run powersync:setup_web

The same code is used for initializing native and web `PowerSyncDatabase` clients.

#### OPFS for improved performance
#### OPFS for Improved Performance

This SDK supports different storage modes of the SQLite database with varying levels of performance and compatibility:

Expand Down Expand Up @@ -92,7 +92,7 @@ import 'package:sqlite3/sqlite3_common.dart';

in code which needs to run on the Web platform. Isolated native-specific code can still import from `sqlite3.dart`.

### Database connections
### Database Connections

Web database connections do not support concurrency. A single database connection is used. `readLock` and `writeLock` contexts do not implement checks for preventing writable queries in read connections and vice-versa.

Expand Down
6 changes: 3 additions & 3 deletions client-sdks/frameworks/react-native-web-support.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -86,11 +86,11 @@ this.powersync = new PowerSyncDatabaseWeb({

This `PowerSyncDatabaseWeb` database will be used alongside the native `PowerSyncDatabase` to support platform-specific implementations. See the [Instantiating PowerSync](#implementations) section below for more details.

### 4. Enable multiple platforms
### 4. Enable Multiple Platforms

To target both mobile and web platforms, you need to adjust the Metro configuration and handle platform-specific libraries accordingly.

#### Metro config
#### Metro Config

Refer to the example [here](https://github.com/powersync-ja/powersync-js/blob/main/demos/react-native-web-supabase-todolist/metro.config.js). Setting `config.resolver.resolveRequest` allows Metro to behave differently based on the platform.

Expand Down Expand Up @@ -220,7 +220,7 @@ import { prompt } from 'util/prompt';
/>;
```

### 5. Configure UMD target
### 5. Configure UMD Target

React Native Web requires the UMD target of `@powersync/web` (available at `@powersync/web/umd`). To fully support this target version, configure the following in your project:

Expand Down
4 changes: 2 additions & 2 deletions client-sdks/frameworks/tanstack.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,7 @@ The **TanStack DB** integration lets you use [TanStack DB](https://tanstack.com/

<Note>The PowerSync TanStack DB collection is currently in an [Alpha](/resources/feature-status) release.</Note>

### Quick start
### Quick Start

Install the TanStackDB-PowerSync collection package with a PowerSync SDK. Then define your schema, initialize the PowerSync database, and create a collection. Optionally [connect a backend connector](/configuration/app-backend/client-side-integration) for sync.

Expand Down Expand Up @@ -125,7 +125,7 @@ const documentsCollection = createCollection(
- **Configuration options** — `powerSyncCollectionOptions` supports schema and deserialization schemas, optional serializers, `onDeserializationError`, and `syncBatchSize`. See [PowerSync Collection](https://tanstack.com/db/latest/docs/collections/powersync-collection#4-create-a-tanstack-db-collection) (Configuration Options).
- **TanStackDB transactions** — Batch multiple operations with `PowerSyncTransactor` and `createTransaction`, control commit timing, and wait for persistence. See [Advanced transactions](https://tanstack.com/db/latest/docs/collections/powersync-collection#advanced-transactions).

### Framework support
### Framework Support

PowerSync works with all TanStack DB framework adapters:

Expand Down
2 changes: 1 addition & 1 deletion client-sdks/orms/flutter-orm-support.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ Importantly, it supports propagating change notifications from the PowerSync sid

The use of this package is recommended for Flutter developers who already know Drift, or specifically want the benefits of an ORM for their PowerSync projects.

### Example implementation
### Example Implementation

An example project which showcases setting up and using Drift with PowerSync is available here:

Expand Down
4 changes: 2 additions & 2 deletions client-sdks/reference/rust.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -96,7 +96,7 @@ pub fn app_schema() -> Schema {

Next, you need to instantiate the PowerSync database. PowerSync streams changes from your backend source database into the client-side SQLite database, based on your [Sync Streams](/sync/streams/overview) (or legacy [Sync Rules](/sync/rules/overview)). In your client-side app, you can read from and write to the local SQLite database, whether the user is online or offline.

#### Process setup
#### Process Setup

PowerSync is based on SQLite, and statically links the [PowerSync SQLite core extension](https://github.com/powersync-ja/powersync-sqlite-core), which needs to be enabled for the process before the SDK can be used. The SDK offers a utility to register the extension, and we recommend calling it early in `main()`:

Expand All @@ -113,7 +113,7 @@ fn main() {
}
```

#### Database setup
#### Database Setup

For maximum flexibility, the PowerSync Rust SDK can be configured with different asynchronous runtimes and HTTP clients used to connect to the PowerSync Service.
These dependencies can be configured through the [`PowerSyncEnvironment`](https://docs.rs/powersync/latest/powersync/env/struct.PowerSyncEnvironment.html)
Expand Down
2 changes: 1 addition & 1 deletion client-sdks/reference/swift.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@
</CardGroup>

<Note>
Earlier versions of the Swift SDK (up to v1.13) shipped a PowerSync Kotlin XCFramework under the hood and abstracted it behind Swift protocols.

Check warning on line 29 in client-sdks/reference/swift.mdx

View check run for this annotation

Mintlify / Mintlify Validation (powersync) - vale-spellcheck

client-sdks/reference/swift.mdx#L29

Did you really mean 'XCFramework'?

From v1.14 onward, the Kotlin dependency has been removed entirely. The SDK is now implemented natively in Swift, with the PowerSync sync protocol and SQLite extension handled by our [Rust core](https://github.com/powersync-ja/powersync-sqlite-core).
</Note>
Expand Down Expand Up @@ -183,7 +183,7 @@

* [PowerSyncDatabase.execute](/client-sdks/reference/swift#mutations-powersync-execute) - execute a write (INSERT/UPDATE/DELETE) query.

### Fetching a Single Item ( PowerSync.get / PowerSync.getOptional)
### Fetching a Single Item (PowerSync.get / PowerSync.getOptional)

The `get` method executes a read-only (SELECT) query and returns a single result. It throws an exception if no result is found. Use `getOptional` to return a single optional result (returns `null` if no result is found).

Expand Down
14 changes: 7 additions & 7 deletions debugging/troubleshooting.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@

PowerSync uses internal partitions called [buckets](/architecture/powersync-service#bucket-system) to organize and sync data efficiently. There is a [default limit of 1,000 buckets](/resources/performance-and-limits) per user/client. When this limit is exceeded, you will see a `PSYNC_S2305` error in your PowerSync Service API logs.

#### How buckets are created in Sync Streams
#### How Buckets Are Created in Sync Streams

The number of buckets a stream creates for a given user depends on how your query filters data. The general rule is: one bucket is created per unique value of the filter expression — whether a subquery result, a JOIN, an auth parameter, or a subscription parameter. The 1,000 limit applies to the total across all active streams for a single user.

Expand Down Expand Up @@ -124,7 +124,7 @@

At scale, with 10 orgs and 50 projects per org, this is 10 + 500 = 510 buckets. Even with same-CTE merging, having two CTEs with different cardinalities still causes bucket growth. Every new level of the hierarchy multiplies the bucket count.

#### Diagnosing which streams are contributing
#### Diagnosing Which Streams Are Contributing

- The `PSYNC_S2305` error log includes a breakdown showing which stream definitions are contributing the most bucket instances (top 10 by count).
- PowerSync Service checkpoint logs record the total parameter result count per connection. You can find these in your [instance logs](/maintenance-ops/monitoring-and-alerting). For example:
Expand All @@ -138,7 +138,7 @@

- The [Sync Diagnostics Client](/tools/diagnostics-client) lets you inspect the buckets for a specific user, but note that it will not load for users who have exceeded the bucket limit since their sync connection fails before data can be retrieved. Use the instance logs and error breakdown to diagnose those cases.

#### Reducing bucket count in Sync Streams
#### Reducing Bucket Count in Sync Streams

<AccordionGroup>

Expand Down Expand Up @@ -300,7 +300,7 @@

</AccordionGroup>

#### Increasing the limit
#### Increasing the Limit

The default of 1,000 can be increased upon request for [Team and Enterprise](https://www.powersync.com/pricing) customers. For self-hosted deployments, configure `max_parameter_query_results` in the API service config. The limit applies per individual user — your PowerSync Service instance can track far more buckets in total across all users.

Expand Down Expand Up @@ -344,13 +344,13 @@

The JavaScript SDKs ([React Native](/client-sdks/reference/react-native-and-expo), [web](/client-sdks/reference/javascript-web)) also log the contents of 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
### 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).

### Client-side Logging
### Client-Side Logging

Our client SDKs support logging to troubleshoot issues. Here's how to enable logging in each SDK:

Expand Down Expand Up @@ -407,10 +407,10 @@

* **Large initial sync**: if your sync rules 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).
* **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/advanced/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 410 in debugging/troubleshooting.mdx

View check run for this annotation

Mintlify / Mintlify Validation (powersync) - vale-spellcheck

debugging/troubleshooting.mdx#L410

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](#too-many-buckets-psync_s2305) above.

### Web: Logging queries on the performance timeline
### Web: Logging Queries on the Performance Timeline

Enabling the `debugMode` flag in the [Web SDK](/client-sdks/reference/javascript-web) logs all SQL queries on the Performance timeline in Chrome's Developer Tools (after recording). This can help identify slow-running queries.
<Frame>
Expand Down
2 changes: 1 addition & 1 deletion maintenance-ops/compacting-buckets.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ For self-hosted setups (PowerSync Open Edition & PowerSync Enterprise Self-Hoste

## Background

### Bucket operations
### Bucket Operations

Each bucket is an ordered list of `PUT`, `REMOVE`, `MOVE` and `CLEAR` operations. In normal operation, only `PUT` and `REMOVE` operations are created.

Expand Down
10 changes: 5 additions & 5 deletions maintenance-ops/implementing-schema-changes.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -103,7 +103,7 @@ When the replica identity changes, the entire table is re-replicated again. This

Sync Streams/Sync Rules affected by schema changes will fail "soft" — an alert would be generated, but the system will continue processing changes.

#### Column changes
#### Column Changes

Column changes such as adding, dropping, renaming columns, or changing column types, are not automatically detected by PowerSync (unless it affects the replica identity as described above).

Expand All @@ -115,7 +115,7 @@ Removing a column will not have the values automatically removed for existing ro

Changing a column type, and/or changing the value of a column using an `ALTER TABLE` statement, will not be automatically replicated to PowerSync. In some cases, the change will have no effect on PowerSync (for example changing between `VARCHAR` and `TEXT` types). When the values are expected to change, make an update to every existing row to propagate the changes.

#### Publication changes
#### Publication Changes

A table is not replicated unless it is part of the [powersync publication](/configuration/source-db/setup).

Expand Down Expand Up @@ -209,7 +209,7 @@ When the replication identity changes, the entire table is replicated again. Thi

Sync Streams/Sync Rules affected by schema changes will fail "soft" — an alert would be generated, but the system will continue processing changes.

#### Column changes
#### Column Changes

Column changes such as adding, dropping, renaming columns, or changing column types, are detected by PowerSync but will generally not result in re-replication. (Unless the replica identity was affected as described above).

Expand Down Expand Up @@ -264,7 +264,7 @@ EXEC sys.sp_cdc_enable_table
@capture_instance = N'<NEW_CAPTURE_INSTANCE_NAME>'; -- If a capture instance for the table already exists, you have to specify a different name for the new capture instance.
```

### Supported SQL Server schema changes:
### Supported SQL Server Schema Changes

#### CREATE table

Expand All @@ -285,7 +285,7 @@ PowerSync can detect a table drop by checking for the table existence when the c
Renaming a table is automatically detected and results in the removal of the bucket data for the old table, followed by a snapshot of the newly renamed table.
Once the snapshot is completed, replication will resume.

#### Column changes
#### Column Changes

Some column changes are blocked on the database level if CDC is enabled on a table. These include:

Expand Down
6 changes: 3 additions & 3 deletions resources/usage-and-billing.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -51,15 +51,15 @@ In the "**Subscriptions**" tab you can:
3. View the amount of your upcoming invoice
4. Upgrade or cancel your [PowerSync subscription](https://www.powersync.com/pricing)

### Billing settings
### Billing Settings

In the "**Billing"** tab you can:

1. Update billing details, such as your billing organization name, address and email address which should receive invoices and receipts.
2. Manage your credit card(s) used for payments.
* Credit card details are never stored on our servers; all billing is securely processed by our payment provider, [Stripe](https://stripe.com/).

### Spending caps
### Spending Caps

Spending caps are not yet available, but are planned for a future release.

Expand All @@ -69,7 +69,7 @@ In the meantime, Pro plan invoices over `$100` and Team plan invoices over `$1,0

Usage limits for PowerSync Cloud are specified on our [Pricing page](https://www.powersync.com/pricing).

### Inactive instances
### Inactive Instances

Instances on the Free plan that have had no deploys or client connections for over 7 days will be deprovisioned. This helps us optimize our cloud resources and ensure a better experience for all users.

Expand Down
2 changes: 1 addition & 1 deletion sync/rules/client-parameters.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@ bucket_definitions:
- SELECT * FROM posts WHERE page_number = bucket.page_number
```

### Security consideration
### Security Consideration

An important consideration with client parameters is that a client can pass any value, and sync data accordingly. Hence, client parameters should always be treated with care, and should not be used for access control purposes. Where permissions are required, use token parameters (`request.jwt()`) instead, or use token parameters in combination with client parameters.

Expand Down