Skip to main content

PowerSync SDK on NuGet

This SDK is distributed via NuGet

Source Code

Refer to the powersync-dotnet repo on GitHub

API Reference (Coming soon)

A full API Reference for this SDK is not yet available. This is planned for a future release.

Example Projects

Gallery of example projects/demo apps built with .NET PowerSync

Changelog

Changelog for the SDK
This SDK is currently in a beta release. It is production-ready for tested use cases. APIs are stable and breaking changes will be communicated clearly.

Supported Frameworks and Targets

The PowerSync .NET SDK supports:
  • .NET Versions: 6, 8, and 9
  • .NET Standard: 2.0 (for compatibility with older libraries and frameworks)
  • .NET Framework: Version 4.8 (requires additional configuration — see the package README)
  • MAUI: Cross-platform support for Android, iOS, Mac Catalyst, and Windows (targeting net8.0 and net9.0 mobile frameworks)
  • WPF: Windows desktop applications
  • Console/CLI: Windows (x64, ARM), macOS (x64, ARM), and Linux (x64, ARM)
Current Limitations:
  • Blazor (web) platforms are not yet supported.
For more details, please refer to the package README.

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.

Quickstart

For desktop/server/binary use-cases and WPF, add the PowerSync.Common NuGet package to your project:
To install a specific version, use --version instead: dotnet add package PowerSync.Common --version <version>
Prerequisites: To sync data between your client-side app and your backend source database, you must have completed the necessary setup for PowerSync, which includes connecting your source database to the PowerSync Service and deploying Sync Streams (or legacy Sync Rules) (steps 1-4 in the Setup Guide).

1. Define the Client-Side Schema

This refers to the for the managed SQLite database exposed by the PowerSync Client SDKs, that your app can read from and write to. The schema is applied when the database is instantiated (as we’ll show in the next step) — .
Generate schema automaticallyIn the PowerSync Dashboard, 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 Streams/Rules.Similar functionality exists in the CLI.Note: The generated schema will not include 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.
You can use this example as a reference when defining your schema. The types available are text, integer and real. These should map directly to the values produced by your Sync Streams (or legacy Sync Rules). If a value doesn’t match, it is cast automatically. For details on how backend source database types are mapped to the SQLite types, see Types.

Schema Definition Syntax

There are two supported syntaxes for defining the schema: Attribute-based (recommended) — Annotate a C# class with [Table], [Column], and [Index] attributes. The same class can then be used directly as the result type in queries, so you define your data structure once:
Unlike the other syntaxes where PowerSync automatically creates an id column, the attribute-based syntax requires you to explicitly declare it. The SDK identifies the id property by looking for either a property named id, or any property with a [Column("id")] attribute (case-insensitive). Having none or more than one is an error.
If you prefer to keep your schema definition separate from your data classes, you can use the object initializer syntax instead:

2. Instantiate the PowerSync Database

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 (or legacy Sync Rules). In your client-side app, you can read from and write to the local SQLite database, whether the user is online or offline. Example: The initialization syntax differs slightly between the Common and MAUI SDKs:

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. Upload client-side writes to your backend API. Any writes that are made to the SQLite database are placed into an upload queue by the PowerSync Client SDK and automatically uploaded to your app backend (where you apply those changes to the backend source database) when the user is connected.
Accordingly, the connector must implement two methods:
  1. PowerSyncBackendConnector.FetchCredentials - This method is automatically invoked by the PowerSync Client SDK to obtain authentication credentials. The SDK caches credentials internally and only calls this method when needed (e.g. on initial connection or when the token is near expiry). See When fetchCredentials() is Called for details, and Authentication Setup for instructions on how the credentials should be generated.
  2. PowerSyncBackendConnector.UploadData - This method will be automatically invoked by the PowerSync Client SDK whenever it needs to upload client-side writes to your app’s backend API. You need to implement how those writes are processed and uploaded in this method. See When uploadData() is Called for details on triggers, throttling, and retry behavior, and Writing Client Changes for considerations on the app backend implementation.
Example:
With your database instantiated and your connector ready, call connect to start syncing data with your backend:
Note: This section assumes you want to use PowerSync to sync your backend source database with SQLite in your app. If you only want to use PowerSync to manage your local SQLite database without sync, instantiate the PowerSync database without calling connect() and refer to our Local-Only guide.

Using PowerSync: CRUD functions

Once the PowerSync instance is configured you can start using the SQLite DB functions. The most commonly used CRUD functions to interact with your SQLite data are:
  • PowerSyncDatabase.Get - get (SELECT) a single row from a table.
  • PowerSyncDatabase.GetAll - get (SELECT) a set of rows from a table.
  • PowerSyncDatabase.Watch - execute a read query every time source tables are modified.
  • PowerSyncDatabase.Execute - execute a write (INSERT/UPDATE/DELETE) query.

Fetching a Single Item

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).

Querying Items (PowerSync.GetAll)

The GetAll method returns a set of rows from a table.

Watching Queries (PowerSync.Watch)

The Watch method executes a read query whenever a change to a dependent table is made. It returns an IAsyncEnumerable so you can use await foreach to consume results.

Mutations (PowerSync.Execute)

The Execute method can be used for executing single SQLite write statements.

Configure Logging

Enable logging to help you debug your app. By default, the SDK uses a no-op logger that doesn’t output any logs. To enable logging, you can configure a custom logger using .NET’s ILogger interface:

Additional Usage Examples

For more usage examples including accessing connection status, monitoring sync progress, and waiting for initial sync, see the Usage Examples page.

Troubleshooting

See Troubleshooting for pointers to debug common issues.

Supported Platforms

See Supported Platforms -> .NET SDK.

Upgrading the SDK

To upgrade to the latest version of the PowerSync package, run the below command in your project folder: