# Architecture Overview Source: https://docs.powersync.com/architecture/architecture-overview The core components of PowerSync are the service and client SDKs

The [PowerSync Service](/architecture/powersync-service) and client SDK operate in unison to keep client-side SQLite databases in sync with a backend database. Learn about their architecture: ### Protocol Learn about the sync protocol used between PowerSync clients and a [PowerSync Service](/architecture/powersync-service): ### Self-Hosted Architecture For more details on typical architecture of a production self-hosted deployment, see here: # Client Architecture Source: https://docs.powersync.com/architecture/client-architecture ### Reading and Writing Data From the client-side perspective, there are two data flow paths: * Reading data from the server or downloading data (to the SQLite database) * Writing changes back to the server, or uploading data (from the SQLite database) #### Reading Data App clients always read data from a local SQLite database. The local database is asynchronously hydrated from the PowerSync Service. A developer configures [Sync Rules](/usage/sync-rules) for their PowerSync instance to control which data is synced to which users. The PowerSync Service connects directly to the backend database and uses a change stream to hydrate dynamic data partitions, called [sync buckets](/usage/sync-rules/organize-data-into-buckets). Sync buckets are used to partition data according to the configured Sync Rules. (In most use cases, only a subset of data is required in a client's database and not a copy of the entire backend database.)

The local SQLite database embedded in the PowerSync SDK is automatically kept in sync with the backend database, based on the [Sync Rules](/usage/sync-rules) configured by the developer:

#### Writing Data Client-side data modifications, namely updates, deletes and inserts, are persisted in the embedded SQLite database as well as stored in an upload queue. The upload queue is a blocking [FIFO](https://en.wikipedia.org/wiki/FIFO_%28computing_and_electronics%29) queue that gets processed when network connectivity is available. Each entry in the queue is processed by writing the entry to your existing backend application API, using a function [defined by you](/installation/client-side-setup/integrating-with-your-backend) (the developer). This is to ensure that existing backend business logic is honored when uploading data changes. For more information, see the section on [integrating with your backend](/installation/client-side-setup/integrating-with-your-backend).

### Schema On the client, the application [defines a schema](/installation/client-side-setup/define-your-schema) with tables, columns and indexes. These are then usable as if they were actual SQLite tables, while in reality these are created as SQLite views. The client SDK maintains the following tables: 1. `ps_data__` This contains the data for `

` , in JSON format. This table's schema does not change when columns are added, removed or changed. 2. `ps_data_local__

` Same as the above, but for local-only tables. 3. `

` (VIEW) - this is a view on the above table, with each defined column extracted from the JSON field. For example, a "description" text column would be `CAST(data ->> '$.description' as TEXT)`. 4. `ps_untyped` - Any synced table that does is not defined in the client-side schema is placed here. If the table is added to the schema at a later point, the data is then migrated to `ps_data__

`. 5. `ps_oplog` - This is data as received by the [PowerSync Service](/architecture/powersync-service), grouped per bucket. 6. `ps_crud` - The local upload queue. 7. `ps_buckets` - A small amount of metadata for each bucket. 8. `ps_migrations` - Table keeping track of SDK schema migrations. Most rows will be present in at least two tables — the `ps_data__

` table, and in `ps_oplog`. It may be present multiple times in `ps_oplog`, if it was synced via multiple buckets. The copy in `ps_oplog` may be newer than the one in `ps_data__

`. Only when a full checkpoint has been downloaded, will the data be copied over to the individual tables. If multiple rows with the same table and id has been synced, only one will be preserved (the one with the highest `op_id`). If you run into limitations with the above JSON-based SQLite view system, check out [the Raw Tables experimental feature](/usage/use-case-examples/raw-tables) which allows you to define and manage raw SQLite tables to work around some limitations. We are actively seeking feedback about this functionality. # Consistency Source: https://docs.powersync.com/architecture/consistency PowerSync uses the concept of "checkpoints" to ensure the data is consistent. ## PowerSync: Designed for causal+ consistency PowerSync is designed to have [Causal+ Consistency](https://jepsen.io/consistency/models/causal), while providing enough flexibility for applications to perform their own data validations and conflict handling. ## How it works: Checkpoints A checkpoint is a single point-in-time on the server (similar to an [LSN in Postgres](https://www.postgresql.org/docs/current/datatype-pg-lsn.html)) with a consistent state — only fully committed transactions are part of the state. The client only updates its local state when it has all the data matching a checkpoint, and then it updates the state to exactly match that of the checkpoint. There is no intermediate state while downloading large sets of changes such as large server-side transactions. Different tables and sync buckets are all included in the same consistent checkpoint, to ensure that the state is consistent over all data in the app. ## Local client changes Local changes are applied on top of the last checkpoint received from the server, as well as being persisted into an upload queue. While changes are present in the upload queue, the client does not advance to a new checkpoint. This means the client never has to resolve conflicts locally. Only once all the local changes have been acknowledged by the server, and the data for that new checkpoint is downloaded by the client, does the client advance to the next checkpoint. This ensures that the operations are always ordered correctly on the client. ## Types of local operations The client automatically records changes to the local database as PUT, PATCH or DELETE operations — corresponding to INSERT, UPDATE or DELETE statements. These are grouped together in a batch per local transaction. Since the developer has full control over how operations are applied, more advanced operations can be modeled on top of these three. For example an insert-only "operations" table can be added, that records additional metadata for individual operations. ## Validation and conflict handling With PowerSync offering full flexibility in how changes are applied on the server, it is also the developer's responsibility to implement this correctly to avoid consistency issues. Some scenarios to consider: While the client was offline, a record was modified locally. By the time the client is online again, that record has been deleted. Some options for handling the change: * Discard the change. * Discard the entire transaction. * Re-create the record. * Record the change elsewhere, potentially notifying the user and allowing the user to resolve the issue. Some other examples include foreign-key or not-null constraints, maximum size of numeric fields, unique constraints, and access restrictions (such as row-level security policies). With an online-only application, the user typically sees the error as soon as it occurs, and can make changes as required. In an offline-capable application, these errors may occur much later than when the change was made, so more care is required to handle these cases. Special care must be taken so that issues such as those do not block the upload queue — the queue cannot advance if the server does not acknowledge a change. There is no single correct choice on how to handle write failures such as mentioned above — the best action depends on the specific application and scenario. However, we do have some suggestions for general approaches: 1. In general, consider relaxing constraints somewhat on the server where it is not absolutely important. It may be better to accept data that is somewhat inconsistent (e.g. a client not applying all expected validations), rather than discarding the data completely. 2. If it is critical to preserve all client changes and preserve the order of changes: 1. Block the client's queue on unexpected errors (don't acknowledge the change). 2. Implement error monitoring to be notified of issues, and resolve the issues as soon as possible. 3. If it is critical to preserve all client changes, but the exact order may not be critical: 1. On a constraint error, persist the transaction in a separate server-side queue, and acknowledge the change. 2. The server-side queue can then be inspected and retried asynchronously, without blocking the client-side queue. 4. If it is acceptable to lose some changes due to constraint errors: 1. Discard the change, or the entire transaction if the changes must all be applied together. 2. Implement error notifications to detect these issues. See also: * [Handling Update Conflicts](/usage/lifecycle-maintenance/handling-update-conflicts) * [Custom Conflict Resolution](/usage/lifecycle-maintenance/handling-update-conflicts/custom-conflict-resolution) If you have any questions about consistency, please [join our Discord](https://discord.gg/powersync) to discuss. # PowerSync Protocol Source: https://docs.powersync.com/architecture/powersync-protocol This contains a broad overview of the sync protocol used between PowerSync clients and a [PowerSync Service](/architecture/powersync-service) instance. For details, see the implementation in the various client SDKs. ## Design The PowerSync protocol is designed to efficiently sync changes to clients, while maintaining [consistency](/architecture/consistency) and integrity of data. The same process is used to download the initial set of data, bulk download changes after being offline for a while, and incrementally stream changes while connected. ## Concepts ### Buckets All synced data is grouped into [buckets](/usage/sync-rules/organize-data-into-buckets). A bucket represents a collection of synced rows, synced to any number of users. [Buckets](/usage/sync-rules/organize-data-into-buckets) is a core concept that allows PowerSync to efficiently scale to thousands of concurrent users, incrementally syncing changes to hundreds of thousands of rows to each. Each bucket keeps an ordered list of changes to rows within the bucket — generally as "PUT" or "REMOVE" operations. * PUT is the equivalent of "INSERT OR REPLACE" * REMOVE is slightly different from "DELETE": a row is only deleted from the client if it has been removed from *all* buckets synced to the client. ### Checkpoints A checkpoint is a sequential id that represents a single point-in-time for consistency purposes. This is further explained in [Consistency](/architecture/consistency). ### Checksums For any checkpoint, the client and server can compute a per-bucket checksum. This is essentially the sum of checksums of individual operations within the bucket, which each individual checksum being a hash of the operation data. The checksum helps to ensure that the client has all the correct data. If the bucket data changes on the server, for example because of a manual edit to the underlying bucket storage, the checksums will stop matching, and the client will re-download the entire bucket. Note: Checksums are not a cryptographically secure method to verify data integrity. Rather, it is designed to detect simple data mismatches, whether due to bugs, manual data modification, or other corruption issues. ### Compacting To avoid indefinite growth in size of buckets, the history of a bucket can be compacted. Stale updates are replaced with marker entries, which can be merged together, while keeping the same checksums. ## Protocol A client initiates a sync session using: 1. A JWT token that typically contains the user\_id, and additional parameters (optional). 2. A list of current buckets and the latest operation id in each. The server then responds with a stream of: 1. "Checkpoint available": A new checkpoint id, with a checksum for each bucket in the checkpoint. 2. "Data": New operations for the above checkpoint for each relevant bucket, starting from the last operation id as sent by the client. 3. "Checkpoint complete": Sent once all data for the checkpoint have been sent. The server then waits until a new checkpoint is available, then repeats the above sequence. The stream can be interrupted at any time, at which point the client will initiate a new session, resuming from the last point. If a checksum validation fails on the client, the client will delete the bucket and start a new sync session. Data for individual rows are represented using JSON. The protocol itself is schemaless - the client is expected to use their own copy of the schema, and gracefully handle schema differences. #### Write Checkpoints Write checkpoints are used to ensure clients have synced their own changes back before applying downloaded data locally. Creating a write checkpoint is a separate operation, which is performed by the client after all data has been uploaded. It is important that this happens after the data has been written to the backend source database. The server then keeps track of the current CDC stream position on the database (LSN in Postgres and SQL Server, resume token in MongoDB and GTID+Binlog Position in MySQL), and notifies the client when the data has been replicated, as part of checkpoint data in the normal data stream. # PowerSync Service Source: https://docs.powersync.com/architecture/powersync-service Each PowerSync instance runs a copy of the PowerSync Service. The primary purpose of this service is to stream changes to clients. This service has the following components: ## Replication The service continuously replicates data from the source database, then: 1. Pre-processes the data according to the [sync rules](/usage/sync-rules) (both data queries and parameter queries), splitting data into [sync buckets](/usage/sync-rules/organize-data-into-buckets) and transforming the data if required. 2. Persists each operation into the relevant sync buckets, ready to be streamed to clients. The recent history of operations to each row is stored, not only the current version. This supports the "append-only" structure of sync buckets, which allows clients to efficiently stream changes while maintaining data integrity. Sync buckets can be compacted to avoid an ever-growing history. Replication is initially performed by taking a snapshot of all tables defined in the sync rules, then data is incrementally replicated using [logical replication](https://www.postgresql.org/docs/current/logical-replication.html). When sync rules are updated, this process restarts with a new snapshot. ## Authentication The service authenticates users using [JWTs](/installation/authentication-setup), before allowing access to data. ## Streaming Sync Once a user is authenticated: 1. The service calculates a list of buckets for the user to sync using [parameter queries](/usage/sync-rules/parameter-queries). 2. The service streams any operations added to those buckets since the last time the user connected. The service then continuously monitors for buckets that are added or removed, as well as for new operations within those buckets, and streams those changes. Only the internal (replicated) storage of the PowerSync Service is used — the source database is not queried directly during streaming. ## Source Code To access the source code for the PowerSync Service, refer to the [powersync-service](https://github.com/powersync-ja/powersync-service) repo on GitHub. ## See Also * [PowerSync Overview](/intro/powersync-overview) # Capacitor (alpha) Source: https://docs.powersync.com/client-sdk-references/capacitor Full SDK reference for using PowerSync in Capacitor clients This SDK is distributed via NPM Refer to `packages/capacitor` in the `powersync-js` repo on GitHub Full API reference for the SDK Gallery of example projects/demo apps built with Capacitor and PowerSync Changelog for the SDK This SDK is currently in an [**alpha** release](/resources/feature-status). The SDK is largely built on our stable [Web SDK](/client-sdk-references/javascript-web), so that functionality can be considered stable. However, the [Capacitor Community SQLite](https://github.com/capacitor-community/sqlite) integration for mobile platforms is in alpha for real-world testing and feedback. There are [known limitations](#limitations) currently. **Built on the Web SDK** The PowerSync Capacitor SDK is built on top of the [PowerSync Web SDK](/client-sdk-references/javascript-web). It shares the same API and usage patterns as the Web SDK. The main differences are: * Uses Capacitor-specific SQLite implementation (`@capacitor-community/sqlite`) for native Android and iOS platforms * Certain features are not supported on native Android and iOS platforms, see [limitations](#limitations) below for details All code examples from the Web SDK apply to Capacitor — use `@powersync/web` for imports instead of `@powersync/capacitor`. See the [JavaScript Web SDK reference](/client-sdk-references/javascript-web) for ORM support, SPA framework integration, and developer notes. ### SDK Features * **Real-time streaming of database changes**: Changes made by one user are instantly streamed to all other users with access to that data. This keeps clients automatically in sync without manual polling or refresh logic. * **Direct access to a local SQLite database**: Data is stored locally, so apps can read and write instantly without network calls. This enables offline support and faster user interactions. * **Asynchronous background execution**: The SDK performs database operations in the background to avoid blocking the application’s main thread. This means that apps stay responsive, even during heavy data activity. * **Query subscriptions for live updates**: The SDK supports query subscriptions that automatically push real-time updates to client applications as data changes, keeping your UI reactive and up to date. * **Automatic schema management**: PowerSync syncs schemaless data and applies a client-defined schema using SQLite views. This architecture means that PowerSync SDKs can handle schema changes gracefully without requiring explicit migrations on the client-side. ## Installation ## Install Package Add the [PowerSync Capacitor NPM package](https://www.npmjs.com/package/@powersync/capacitor) to your project: ```bash theme={null} npm install @powersync/capacitor ``` ```bash theme={null} yarn add @powersync/capacitor ``` ```bash theme={null} pnpm install @powersync/capacitor ``` This package uses [`@powersync/web`](https://www.npmjs.com/package/@powersync/web) as a peer dependency. For additional `@powersync/web` configuration and instructions see the [Web SDK README](/client-sdk-references/javascript-web). ## Install Peer Dependencies You must also install the following peer dependencies: ```bash theme={null} npm install @capacitor-community/sqlite @powersync/web @journeyapps/wa-sqlite ``` ```bash theme={null} yarn add @capacitor-community/sqlite @powersync/web @journeyapps/wa-sqlite ``` ```bash theme={null} pnpm install @capacitor-community/sqlite @powersync/web @journeyapps/wa-sqlite ``` See the [Capacitor Community SQLite repository](https://github.com/capacitor-community/sqlite) for additional instructions. ## Sync Capacitor Plugins After installing, sync your Capacitor project: ```bash theme={null} npx cap sync ``` ## Getting Started Before implementing the PowerSync SDK in your project, make sure you have completed these steps: * Signed up for a PowerSync Cloud account ([here](https://accounts.journeyapps.com/portal/powersync-signup?s=docs)) or [self-host PowerSync](/self-hosting/getting-started). * [Configured your backend database](/installation/database-setup) and connected it to your PowerSync instance. * [Installed](/client-sdk-references/capacitor#installation) the PowerSync Capacitor SDK. ### 1. Define the Schema The first step is defining the schema for the local SQLite database. This schema represents a "view" of the downloaded data. No migrations are required — the schema is applied directly when the local PowerSync database is constructed (as we'll show in the next step). **Generate schema automatically** In the [PowerSync Dashboard](https://dashboard.powersync.com/), select your project and instance and click the **Connect** button in the top bar to generate the client-side schema in your preferred language. The schema will be generated based off your Sync Rules. Similar functionality exists in the [CLI](/usage/tools/cli). **Note:** The generated schema will exclude an `id` column, as the client SDK automatically creates an `id` column of type `text`. Consequently, it is not necessary to specify an `id` column in your schema. For additional information on IDs, refer to [Client ID](/usage/sync-rules/client-id). The types available are `text`, `integer` and `real`. These should map directly to the values produced by the [Sync Rules](/usage/sync-rules). If a value doesn't match, it is cast automatically. For details on how Postgres types are mapped to the types below, see the section on [Types](/usage/sync-rules/types) in the *Sync Rules* documentation. **Example**: **Note on imports**: While you install `@powersync/capacitor`, the Capacitor SDK extends the Web SDK so you import general components from `@powersync/web` (installed as a peer dependency). See the [JavaScript Web SDK schema definition section](/client-sdk-references/javascript-web#1-define-the-schema) for more advanced examples. ```js theme={null} // AppSchema.ts import { column, Schema, Table } from '@powersync/web'; const lists = new Table({ created_at: column.text, name: column.text, owner_id: column.text }); const todos = new Table( { list_id: column.text, created_at: column.text, completed_at: column.text, description: column.text, created_by: column.text, completed_by: column.text, completed: column.integer }, { indexes: { list: ['list_id'] } } ); export const AppSchema = new Schema({ todos, lists }); // For types export type Database = (typeof AppSchema)['types']; export type TodoRecord = Database['todos']; // OR: // export type Todo = RowType; export type ListRecord = Database['lists']; ``` **Note**: No need to declare a primary key `id` column, as PowerSync will automatically create this. ### 2. Instantiate the PowerSync Database Next, you need to instantiate the PowerSync database — this is the core managed database. Its primary functions are to record all changes in the local database, whether online or offline. In addition, it automatically uploads changes to your app backend when connected. **Example**: The Capacitor PowerSyncDatabase automatically detects the platform and uses the appropriate database drivers: * **Android and iOS**: Uses [Capacitor Community SQLite](https://github.com/capacitor-community/sqlite) for native database access * **Web**: Falls back to the PowerSync Web SDK ```js theme={null} import { PowerSyncDatabase } from '@powersync/capacitor'; // Import general components from the Web SDK package import { Schema } from '@powersync/web'; import { Connector } from './Connector'; import { AppSchema } from './AppSchema'; /** * The Capacitor PowerSyncDatabase will automatically detect the platform * and use the appropriate database drivers. */ export const db = new PowerSyncDatabase({ // The schema you defined in the previous step schema: AppSchema, database: { // Filename for the SQLite database — it's important to only instantiate one instance per file. dbFilename: 'powersync.db' } }); ``` When using custom database factories, be sure to specify the `CapacitorSQLiteOpenFactory` for Capacitor platforms: ```js theme={null} import { PowerSyncDatabase } from '@powersync/capacitor'; import { WASQLiteOpenFactory, CapacitorSQLiteOpenFactory } from '@powersync/capacitor'; import { Schema } from '@powersync/web'; const db = new PowerSyncDatabase({ schema: AppSchema, database: isWeb ? new WASQLiteOpenFactory({ dbFilename: "mydb.sqlite" }) : new CapacitorSQLiteOpenFactory({ dbFilename: "mydb.sqlite" }) }); ``` Once you've instantiated your PowerSync database, you will need to call the [connect()](https://powersync-ja.github.io/powersync-js/web-sdk/classes/AbstractPowerSyncDatabase#connect) method to activate it. ```js theme={null} export const setupPowerSync = async () => { // Uses the backend connector that will be created in the next section const connector = new Connector(); db.connect(connector); }; ``` ### 3. Integrate with your Backend The PowerSync backend connector provides the connection between your application backend and the PowerSync client-side managed SQLite database. It is used to: 1. Retrieve an auth token to connect to the PowerSync instance. 2. Apply local changes on your backend application server (and from there, to your backend database) Accordingly, the connector must implement two methods: 1. [PowerSyncBackendConnector.fetchCredentials](https://github.com/powersync-ja/powersync-js/blob/ed5bb49b5a1dc579050304fab847feb8d09b45c7/packages/common/src/client/connection/PowerSyncBackendConnector.ts#L16) - This is called every couple of minutes and is used to obtain credentials for your app backend API. -> See [Authentication Setup](/installation/authentication-setup) for instructions on how the credentials should be generated. 2. [PowerSyncBackendConnector.uploadData](https://github.com/powersync-ja/powersync-js/blob/ed5bb49b5a1dc579050304fab847feb8d09b45c7/packages/common/src/client/connection/PowerSyncBackendConnector.ts#L24) - Use this to upload client-side changes to your app backend. -> See [Writing Client Changes](/installation/app-backend-setup/writing-client-changes) for considerations on the app backend implementation. **Example**: See the [JavaScript Web SDK backend integration section](/client-sdk-references/javascript-web#3-integrate-with-your-backend) for connector examples with Supabase and Firebase authentication, and handling `uploadData` with batch operations. ```js theme={null} import { UpdateType } from '@powersync/web'; export class Connector { async fetchCredentials() { // Implement fetchCredentials to obtain a JWT from your authentication service. // See https://docs.powersync.com/installation/authentication-setup // If you're using Supabase or Firebase, you can re-use the JWT from those clients, see // - https://docs.powersync.com/installation/authentication-setup/supabase-auth // - https://docs.powersync.com/installation/authentication-setup/firebase-auth return { endpoint: '[Your PowerSync instance URL or self-hosted endpoint]', // Use a development token (see Authentication Setup https://docs.powersync.com/installation/authentication-setup/development-tokens) to get up and running quickly token: 'An authentication token' }; } async uploadData(database) { // Implement uploadData to send local changes to your backend service. // You can omit this method if you only want to sync data from the database to the client // See example implementation here: https://docs.powersync.com/client-sdk-references/javascript-web#3-integrate-with-your-backend } } ``` ## Using PowerSync: CRUD functions Once the PowerSync instance is configured you can start using the SQLite DB functions. **All CRUD examples from the JavaScript Web SDK apply**: The Capacitor SDK uses the same API as the Web SDK. See the [JavaScript Web SDK CRUD functions section](/client-sdk-references/javascript-web#using-powersync-crud-functions) for examples of `get`, `getAll`, `watch`, `execute`, `writeTransaction`, incremental watch updates, and differential results. The most commonly used CRUD functions to interact with your SQLite data are: * [PowerSyncDatabase.get](/client-sdk-references/javascript-web#fetching-a-single-item) - get (SELECT) a single row from a table. * [PowerSyncDatabase.getAll](/client-sdk-references/javascript-web#querying-items-powersync.getall) - get (SELECT) a set of rows from a table. * [PowerSyncDatabase.watch](/client-sdk-references/javascript-web#watching-queries-powersync.watch) - execute a read query every time source tables are modified. * [PowerSyncDatabase.execute](/client-sdk-references/javascript-web#mutations-powersync.execute) - execute a write (INSERT/UPDATE/DELETE) query. ### Fetching a Single Item The [get](https://powersync-ja.github.io/powersync-js/web-sdk/classes/PowerSyncDatabase#get) method executes a read-only (SELECT) query and returns a single result. It throws an exception if no result is found. Use [getOptional](https://powersync-ja.github.io/powersync-js/web-sdk/classes/PowerSyncDatabase#getoptional) to return a single optional result (returns `null` if no result is found). ```js theme={null} // Find a list item by ID export const findList = async (id) => { const result = await db.get('SELECT * FROM lists WHERE id = ?', [id]); return result; } ``` ### Querying Items (PowerSync.getAll) The [getAll](https://powersync-ja.github.io/powersync-js/web-sdk/classes/PowerSyncDatabase#getall) method returns a set of rows from a table. ```js theme={null} // Get all list IDs export const getLists = async () => { const results = await db.getAll('SELECT * FROM lists'); return results; } ``` ### Watching Queries (PowerSync.watch) The [watch](https://powersync-ja.github.io/powersync-js/web-sdk/classes/PowerSyncDatabase#watch) method executes a read query whenever a change to a dependent table is made. ```javascript theme={null} async function* pendingLists(): AsyncIterable { for await (const result of db.watch( `SELECT * FROM lists WHERE state = ?`, ['pending'] )) { yield result.rows?._array ?? []; } } ``` ```javascript theme={null} const pendingLists = (onResult: (lists: any[]) => void): void => { db.watch( 'SELECT * FROM lists WHERE state = ?', ['pending'], { onResult: (result: any) => { onResult(result.rows?._array ?? []); } } ); } ``` For advanced watch query features like incremental updates and differential results, see [Live Queries / Watch Queries](/usage/use-case-examples/watch-queries). ### Mutations (PowerSync.execute, PowerSync.writeTransaction) The [execute](https://powersync-ja.github.io/powersync-js/web-sdk/classes/PowerSyncDatabase#execute) method can be used for executing single SQLite write statements. ```js theme={null} // Delete a list item by ID export const deleteList = async (id) => { const result = await db.execute('DELETE FROM lists WHERE id = ?', [id]); return TodoList.fromRow(results); } // OR: using a transaction const deleteList = async (id) => { await db.writeTransaction(async (tx) => { // Delete associated todos await tx.execute(`DELETE FROM ${TODOS_TABLE} WHERE list_id = ?`, [id]); // Delete list record await tx.execute(`DELETE FROM ${LISTS_TABLE} WHERE id = ?`, [id]); }); }; ``` ## Configure Logging ```js theme={null} import { createBaseLogger, LogLevel } from '@powersync/web'; const logger = createBaseLogger(); // Configure the logger to use the default console output logger.useDefaults(); // Set the minimum log level to DEBUG to see all log messages // Available levels: DEBUG, INFO, WARN, ERROR, TRACE, OFF logger.setLevel(LogLevel.DEBUG); ``` Enable verbose output in the developer tools for detailed logs. ## Limitations * Encryption for native mobile platforms is not yet supported. * Multiple tab support is not available for native Android and iOS targets. * `PowerSyncDatabase.executeRaw` does not support results where multiple columns would have the same name in SQLite * `PowerSyncDatabase.execute` has limited support on Android. The SQLCipher Android driver exposes queries and executions as separate APIs, so there is no single method that handles both. While PowerSyncDatabase.execute accepts both, on Android we treat a statement as a query only when the SQL starts with select (case-insensitive). ## Additional Resources See the [JavaScript Web SDK reference](/client-sdk-references/javascript-web) for: * [ORM Support](/client-sdk-references/javascript-web/javascript-orm/overview) * [SPA Framework Integration](/client-sdk-references/javascript-web/javascript-spa-frameworks) * [Usage Examples](/client-sdk-references/javascript-web/usage-examples) * [Developer Notes](/client-sdk-references/javascript-web#developer-notes) ## Troubleshooting See [Troubleshooting](/resources/troubleshooting) for pointers to debug common issues. ## Supported Platforms See [Supported Platforms -> Capacitor SDK](/resources/supported-platforms#capacitor-sdk). # JavaScript ORM Support Source: https://docs.powersync.com/client-sdk-references/capacitor/javascript-orm-support # .NET (alpha) Source: https://docs.powersync.com/client-sdk-references/dotnet SDK reference for using PowerSync in .NET clients. This SDK is distributed via NuGet Refer to the `powersync-dotnet` repo on GitHub A full API Reference for this SDK is not yet available. This is planned for a future release. Gallery of example projects/demo apps built with .NET PowerSync Changelog for the SDK This SDK is currently in an [**alpha** release](/resources/feature-status). It is not suitable for production use as breaking changes may still occur. ## Supported Frameworks and Targets The PowerSync .NET SDK supports: * **.NET Versions**: 6, 8, and 9 * **.NET Framework**: Version 4.8 (requires additional configuration) * **MAUI**: Cross-platform support for Android, iOS, and Windows * **WPF**: Windows desktop applications **Current Limitations**: * Blazor (web) platforms are not yet supported. For more details, please refer to the package [README](https://github.com/powersync-ja/powersync-dotnet/tree/main?tab=readme-ov-file). ## SDK Features * Provides real-time streaming of database changes. * Offers direct access to the SQLite database, enabling the use of SQL on both client and server sides. * Provides watched queries that allow listening for live updates to data. * Eliminates the need for client-side database migrations as these are managed automatically. ## Quickstart For desktop/server/binary use-cases and WPF, add the [`PowerSync.Common`](https://www.nuget.org/packages/PowerSync.Common/) NuGet package to your project: ```bash theme={null} dotnet add package PowerSync.Common --prerelease ``` For MAUI apps, add both [`PowerSync.Common`](https://www.nuget.org/packages/PowerSync.Common/) and [`PowerSync.Maui`](https://www.nuget.org/packages/PowerSync.Maui/) NuGet packages to your project: ```bash theme={null} dotnet add package PowerSync.Common --prerelease dotnet add package PowerSync.Maui --prerelease ``` Add `--prerelease` while this package is in alpha. Next, make sure that you have: * Signed up for a PowerSync Cloud account ([here](https://accounts.journeyapps.com/portal/powersync-signup?s=docs)) or [self-host PowerSync](/self-hosting/getting-started). * [Configured your backend database](/installation/database-setup) and connected it to your PowerSync instance. ### 1. Define the schema The first step is defining the schema for the local SQLite database. This schema represents a "view" of the downloaded data. No migrations are required — the schema is applied directly when the local PowerSync database is constructed (as we'll show in the next step). **Generate schema automatically** In the [PowerSync Dashboard](https://dashboard.powersync.com/), select your project and instance and click the **Connect** button in the top bar to generate the client-side schema in your preferred language. The schema will be generated based off your Sync Rules. Similar functionality exists in the [CLI](/usage/tools/cli). **Note:** The generated schema will exclude an `id` column, as the client SDK automatically creates an `id` column of type `text`. Consequently, it is not necessary to specify an `id` column in your schema. For additional information on IDs, refer to [Client ID](/usage/sync-rules/client-id). You can use [this example](https://github.com/powersync-ja/powersync-dotnet/blob/main/demos/CommandLine/AppSchema.cs) as a reference when defining your schema. ### 2. Instantiate the PowerSync Database Next, you need to instantiate the PowerSync database — this is the core managed database. Its primary functions are to record all changes in the local database, whether online or offline. In addition, it automatically uploads changes to your app backend when connected. **Example**: The initialization syntax differs slightly between the Common and MAUI SDKs: ```cs theme={null} using PowerSync.Common.Client; class Demo { static async Task Main() { var db = new PowerSyncDatabase(new PowerSyncDatabaseOptions { Database = new SQLOpenOptions { DbFilename = "tododemo.db" }, Schema = AppSchema.PowerSyncSchema, }); await db.Init(); } } ``` ```cs theme={null} using PowerSync.Common.Client; using PowerSync.Common.MDSQLite; using PowerSync.Maui.SQLite; class Demo { static async Task Main() { // Ensures the DB file is stored in a platform appropriate location var dbPath = Path.Combine(FileSystem.AppDataDirectory, "maui-example.db"); var factory = new MAUISQLiteDBOpenFactory(new MDSQLiteOpenFactoryOptions() { DbFilename = dbPath }); var Db = new PowerSyncDatabase(new PowerSyncDatabaseOptions() { Database = factory, // Supply a factory Schema = AppSchema.PowerSyncSchema, }); await db.Init(); } } ``` ### 3. Integrate with your Backend The PowerSync backend connector provides the connection between your application backend and the PowerSync client-side managed SQLite database. It is used to: 1. Retrieve an auth token to connect to the PowerSync instance. 2. Apply local changes on your backend application server (and from there, to your backend database) Accordingly, the connector must implement two methods: 1. [PowerSyncBackendConnector.FetchCredentials](https://github.com/powersync-ja/powersync-dotnet/blob/main/demos/CommandLine/NodeConnector.cs#L50) - This is called every couple of minutes and is used to obtain credentials for your app backend API. -> See [Authentication Setup](/installation/authentication-setup) for instructions on how the credentials should be generated. 2. [PowerSyncBackendConnector.UploadData](https://github.com/powersync-ja/powersync-dotnet/blob/main/demos/CommandLine/NodeConnector.cs#L72) - Use this to upload client-side changes to your app backend. -> See [Writing Client Changes](/installation/app-backend-setup/writing-client-changes) for considerations on the app backend implementation. **Example**: ```cs theme={null} using System; using System.Collections.Generic; using System.Net.Http; using System.Text; using System.Text.Json; using System.Threading.Tasks; using PowerSync.Common.Client; using PowerSync.Common.Client.Connection; using PowerSync.Common.DB.Crud; public class MyConnector : IPowerSyncBackendConnector { private readonly HttpClient _httpClient; // User credentials for the current session public string UserId { get; private set; } // Service endpoints private readonly string _backendUrl; private readonly string _powerSyncUrl; private string? _clientId; public MyConnector() { _httpClient = new HttpClient(); // In a real app, this would come from your authentication system UserId = "user-123"; // Configure your service endpoints _backendUrl = "https://your-backend-api.example.com"; _powerSyncUrl = "https://your-powersync-instance.powersync.journeyapps.com"; } public async Task FetchCredentials() { try { // Obtain a JWT from your authentication service. // See https://docs.powersync.com/installation/authentication-setup // If you're using Supabase or Firebase, you can re-use the JWT from those clients, see // - https://docs.powersync.com/installation/authentication-setup/supabase-auth // - https://docs.powersync.com/installation/authentication-setup/firebase-auth var authToken = "your-auth-token"; // Use a development token (see Authentication Setup https://docs.powersync.com/installation/authentication-setup/development-tokens) to get up and running quickly // Return credentials with PowerSync endpoint and JWT token return new PowerSyncCredentials(_powerSyncUrl, authToken); } catch (Exception ex) { Console.WriteLine($"Error fetching credentials: {ex.Message}"); throw; } } public async Task UploadData(IPowerSyncDatabase database) { // Get the next transaction to upload CrudTransaction? transaction; try { transaction = await database.GetNextCrudTransaction(); } catch (Exception ex) { Console.WriteLine($"UploadData Error: {ex.Message}"); return; } // If there's no transaction, there's nothing to upload if (transaction == null) { return; } // Get client ID if not already retrieved _clientId ??= await database.GetClientId(); try { // Convert PowerSync operations to your backend format var batch = new List