diff --git a/installation/authentication-setup.mdx b/installation/authentication-setup.mdx index 5dbb65d..effb203 100644 --- a/installation/authentication-setup.mdx +++ b/installation/authentication-setup.mdx @@ -3,35 +3,59 @@ title: "Authentication Setup" sidebarTitle: Overview --- -PowerSync clients (i.e. apps used by your users that embed the PowerSync Client SDK) authenticate against the server-side [PowerSync Service](/architecture/powersync-service) using [JWTs](https://jwt.io/) (signed tokens) that are generated by your application backend. +# PowerSync Authentication Overview + +PowerSync uses JSON Web Tokens (JWTs) for secure client authentication. These tokens are generated by your application backend and used by PowerSync clients to authenticate against the PowerSync Service. + +## Initial Architecture + +Before implementing PowerSync, a typical application architecture might look like this: -Before using PowerSync, an application's existing architecture may look like this: -The [PowerSync Service](/architecture/powersync-service) uses database native credentials and authenticates directly against the [backend database](/installation/database-setup) using the configured credentials: +## PowerSync Service Authentication + +The PowerSync Service maintains a direct connection to your backend database using native credentials: -When the PowerSync client SDK is included in an app project, it uses [existing app-to-backend](/installation/app-backend-setup) authentication to [retrieve a JSON Web Token (JWT)](/installation/authentication-setup): +## Client Authentication Flow + +### Step 1: JWT Retrieval +When integrated into your app, the PowerSync client SDK uses your existing app-to-backend authentication to obtain a JSON Web Token: -The PowerSync client SDK uses the retrieved JWT to authenticate directly against the PowerSync Service: +### Step 2: PowerSync Service Connection +The PowerSync client SDK then uses this JWT to establish a secure connection with the PowerSync Service: -Users are not persisted in PowerSync, and there is no server-to-server communication used for client authentication. + +PowerSync does not persist user information, and there is no server-to-server communication for client authentication. + + +## Authentication Options -Some authentication providers already generate JWTs for users which PowerSync can verify directly — see the documentation for individual providers (e.g. [Supabase Auth](/installation/authentication-setup/supabase-auth), [Firebase Auth](/installation/authentication-setup/firebase-auth)) +### Pre-configured Providers +Some authentication providers generate JWTs that PowerSync can verify directly: +- [Supabase Auth](/installation/authentication-setup/supabase-auth) +- [Firebase Auth](/installation/authentication-setup/firebase-auth) -For others, some backend code must be added to your application backend to generate the JWTs needed for PowerSync — see [Custom](/installation/authentication-setup/custom) authentication. +### Custom Authentication +For other authentication systems, you'll need to add JWT generation code to your backend. See our [Custom](/installation/authentication-setup/custom) authentication guide for details. -For a quick way to get up and running during development, you can generate [Development Tokens](/installation/authentication-setup/development-tokens) directly from the [PowerSync Dashboard](/usage/tools/powersync-dashboard) (PowerSync Cloud) or locally with a self-hosted setup. +### Development Tokens + +For quick development and testing, you can generate [Development Tokens](/installation/authentication-setup/development-tokens) through the: +- [PowerSync Dashboard](/usage/tools/powersync-dashboard) (PowerSync Cloud) +- Local setup (self-hosted installations) + \ No newline at end of file diff --git a/installation/client-side-setup.mdx b/installation/client-side-setup.mdx index d89691b..fa4d666 100644 --- a/installation/client-side-setup.mdx +++ b/installation/client-side-setup.mdx @@ -4,217 +4,217 @@ description: "Include the PowerSync Client SDK in your project" sidebarTitle: Overview --- -The next step after configuring your database and connecting it to your PowerSync instance, is to include the appropriate PowerSync Client SDK package in your app project. On a high level, this involves the following steps: - -1. Install the SDK (see below) - -2. [Define your Schema](/installation/client-side-setup/define-your-schema) - -3. [Instantiate Local PowerSync Database](/installation/client-side-setup/instantiate-powersync-database) - -4. [Integrate with your Backend](/installation/client-side-setup/integrating-with-your-backend) \[Optional] - - 1. Download data from your database - - 2. Write mutations to your backend - -PowerSync currently supports apps built in [Flutter](/client-sdk-references/flutter), [React Native & Expo](/client-sdk-references/react-native-and-expo), [JavaScript Web](/client-sdk-references/javascript-web), [Kotlin Multiplatform](/client-sdk-references/kotlin-multiplatform) (beta), and [Swift](/client-sdk-references/swift) (beta). - -Please see the steps based on your app framework: - - - Add the [PowerSync pub.dev package](https://pub.dev/packages/powersync) to your project: - - ```bash - flutter pub add powersync - ``` - - See the full SDK reference for further details and getting started instructions: - - - - - - - **PowerSync is not compatible with Expo Go.** - PowerSync uses a native plugin and is therefore only compatible with Expo Dev Builds. - - - Add the [PowerSync React Native NPM package](https://www.npmjs.com/package/@powersync/react-native) to your project: - - Run the below command in your project folder: - - - - ```bash - npm npx expo install @powersync/react-native - ``` - - - - ```bash - yarn expo add @powersync/react-native - ``` - - - - ``` - pnpm dlx expo install @powersync/react-native - ``` - - - - - **Some peer dependencies and polyfills are required.** - - **Note**: As of @powersync/react-native@1.9.0, polyfills are bundled in the SDK and are no longer required ([Async Iterator](https://www.npmjs.com/package/@powersync/react-native#babel-plugins-watched-queries) support being the only exception). - - By default this SDK connects to a PowerSync instance via WebSocket (from @powersync/react-native@1.11.0) or HTTP Streaming (before @powersync/react-native@1.11.0). Different polyfill configurations are required for each method. - - * See the [Readme](https://www.npmjs.com/package/@powersync/react-native#installation) for the necessary peer dependencies and polyfills. - - * See the [Developer Notes](/client-sdk-references/react-native-and-expo#developer-notes) section in the SDK reference for details about connecting with either method. - - * Also see this section for additional development requirements on Android and iOS. - - - See the full SDK reference for further details and getting started instructions: - - - - - - Add the [PowerSync JavaScript Web NPM package](https://www.npmjs.com/package/@powersync/web) to your project: - - - - ```bash - npm install @powersync/web - ``` - - - - ```bash - yarn add @powersync/web - ``` - - - - ```bash - pnpm install @powersync/web - ``` - - - - - **Some peer dependencies are required.** - - **Note**: As of @powersync/web@1.4.0, polyfills are bundled in the SDK and are no longer required. - - See the [Readme](https://www.npmjs.com/package/@powersync/web#installation) for the necessary peer dependencies that need to be installed. - - By default this SDK connects to a PowerSync instance via WebSocket (from @powersync/web@1.6.0) or HTTP stream (before @powersync/web@1.6.0). - - * See the [Developer Notes](/client-sdk-references/javascript-web#developer-notes) section in the SDK reference for details about connecting with either method. - - - See the full SDK reference for further details and getting started instructions: - - - - - - Add the [PowerSync SDK](https://central.sonatype.com/artifact/com.powersync/core) to your project by adding the following to your `build.gradle.kts` file: - - ```gradle - kotlin { - //... - sourceSets { - commonMain.dependencies { - api("com.powersync:core:$powersyncVersion") - // If you want to use the Supabase Connector, also add the following: - implementation("com.powersync:connectors:$powersyncVersion") - } - //... - } - } - ``` - - #### Cocoapods - - We recommend using Cocoapods (as opposed to SMP) for iOS targets. Add the following to the `cocoapods` config in your `build.gradle.kts` - - ```gradle - cocoapods { - //... - pod("powersync-sqlite-core") { - linkOnly = true - } - - framework { - isStatic = true - export("com.powersync:core") - } - //... - } - ``` - - Note: The `linkOnly` attribute is set to `true` and framework is set to `isStatic = true` to ensure that the `powersync-sqlite-core` binaries are only statically linked. - - See the full SDK reference for further details and getting started instructions: - - - - - - 1. Using `Package.swift:` - - ```swift - let package = Package( - ... - dependencies: [ - ... - .package( - url: "https://github.com/powersync-ja/powersync-swift", - exact: "" - ), - ], - targets: [ - .target( - name: "YourTargetName", - dependencies: [ - .product( - name: "PowerSync", - package: "powersync-swift" - ) - ] - ) - ] - ) - ``` - - 2. Using Xcode: - - 1. Follow [this](https://developer.apple.com/documentation/xcode/adding-package-dependencies-to-your-app#Add-a-package-dependency) guide to add a package to your project. - 2. When searching for the package use [https://github.com/powersync-ja/powersync-swift.git](https://github.com/powersync-ja/powersync-swift.git) as the URL and include the exact version e.g. `1.0.0-Beta.x` as shown below: +## Overview + +After configuring your database and connecting it to PowerSync, you'll need to integrate the PowerSync Client SDK into your app. This guide will walk you through the essential setup steps. + +## Setup Process + + + + Choose your platform-specific installation instructions below + + + Configure your local database schema + + Learn how to structure your local database + + + + Set up the local PowerSync database instance + + Configure your local PowerSync instance + + + + Connect to your backend services (Optional) + + Learn how to sync with your backend + + + + +## Supported Platforms + +PowerSync supports multiple app frameworks. Select your platform below for specific installation instructions: + + + + + The PowerSync Flutter SDK is available through pub.dev + + + Install the package using: + ```bash + flutter pub add powersync + ``` + + For detailed implementation guides and API reference: + + + + + + **Important**: PowerSync is not compatible with Expo Go. You must use Expo Dev Builds due to native plugin dependencies. + + + Install the package using your preferred package manager: + + + + ```bash + npm npx expo install @powersync/react-native + ``` + + + + ```bash + yarn expo add @powersync/react-native + ``` + + + + ```bash + pnpm dlx expo install @powersync/react-native + ``` + + + + + **SDK Version Notes**: + - From v1.9.0: Most polyfills are bundled (except Async Iterator) + - From v1.11.0: WebSocket is the default connection method + + + For complete setup instructions and requirements: + + + + + Install the package using your preferred package manager: + + + + ```bash + npm install @powersync/web + ``` + + + + ```bash + yarn add @powersync/web + ``` + + + + ```bash + pnpm install @powersync/web + ``` + + + + + **SDK Version Notes**: + - From v1.4.0: Polyfills are bundled in the SDK + - From v1.6.0: WebSocket is the default connection method + + + For complete documentation: + + + + + + Configure your build.gradle.kts to include PowerSync + + + Add the following to your build configuration: + ```gradle + kotlin { + sourceSets { + commonMain.dependencies { + api("com.powersync:core:$powersyncVersion") + // Optional: Supabase Connector + implementation("com.powersync:connectors:$powersyncVersion") + } + } + } + ``` + + For iOS targets using Cocoapods: + ```gradle + cocoapods { + pod("powersync-sqlite-core") { + linkOnly = true + } + + framework { + isStatic = true + export("com.powersync:core") + } + } + ``` + + For complete setup instructions: + + + + + + + ```swift + let package = Package( + dependencies: [ + .package( + url: "https://github.com/powersync-ja/powersync-swift", + exact: "" + ), + ], + targets: [ + .target( + name: "YourTargetName", + dependencies: [ + .product( + name: "PowerSync", + package: "powersync-swift" + ) + ] + ) + ] + ) + ``` + + + 1. Add package dependency in Xcode + 2. Use URL: `https://github.com/powersync-ja/powersync-swift.git` + 3. Specify exact version (e.g., `1.0.0-Beta.x`) - + Xcode package configuration + + - See the full SDK reference for further details and getting started instructions: - - - + For complete documentation: + + + ## Next Steps -For an overview of the client-side steps required to set up PowerSync in your app, continue reading the next sections. - -1. [Define your Schema](/installation/client-side-setup/define-your-schema) - -2. [Instantiate PowerSync Database](/installation/client-side-setup/instantiate-powersync-database) - -3. [Integrate with your Backend](/installation/client-side-setup/integrating-with-your-backend) - -For a walkthrough with example implementations for your platform, see the *Getting Started* section of the corresponding SDK reference linked above. +Follow these guides to complete your PowerSync integration: + + + + Learn how to structure your local database schema + + + Set up your local PowerSync database instance + + + Connect PowerSync to your backend services + + + View detailed implementation guides for your platform + + \ No newline at end of file diff --git a/installation/database-setup.mdx b/installation/database-setup.mdx index fb9d882..29065b8 100644 --- a/installation/database-setup.mdx +++ b/installation/database-setup.mdx @@ -4,465 +4,181 @@ description: "Configure your backend database for PowerSync" sidebarTitle: "Overview" --- -## Postgres +# Database Configuration Guide + +## Postgres Setup + + + PowerSync supports multiple database backends. This section covers Postgres configuration. See below for MongoDB and MySQL setup instructions. + - **Version compatibility**: PowerSync requires Postgres version 11 or greater. + **Version Requirement**: PowerSync requires Postgres version 11 or greater. -Configuring your Postgres database with PowerSync generally involves three tasks: +### Key Configuration Steps -* Enable logical replication +Setting up Postgres with PowerSync involves three essential tasks: -* Create a PowerSync database user +1. Enabling logical replication +2. Creating a PowerSync database user +3. Creating the `powersync` publication -* Create `powersync` publication + + These steps may vary slightly depending on your hosting provider. We've provided detailed instructions for popular hosting platforms below. + -We have documented steps for some hosting providers: +### Provider-Specific Setup Instructions - ### 1. Enable logical replication - - Supabase has logical replication enabled by default — no action required. - - ### 2. Create a PowerSync Database User + #### 1. Logical Replication Setup + + Supabase has logical replication enabled by default — no action required. - It is not currently possible to create a new user on Supabase with replication permissions without contacting their support. Instead, use the default `postgres` user. + #### 2. PowerSync User Creation - ### 3. Create "powersync" Publication + + Creating a new user with replication permissions requires Supabase support assistance. Use the default `postgres` user as a workaround. + - The `postgres` user does not have access to create a publication for all tables. Instead, list each table explicitly. + #### 3. Publication Creation - This can also be done on the Supabase dashboard in the database *Replication* page. + + The `postgres` user has limited publication permissions. You must explicitly list tables in the publication. + ```sql CREATE PUBLICATION powersync FOR TABLE public.lists, public.todos; ``` + + + This can also be configured through the Supabase dashboard under the database *Replication* page. + - ### Prerequisites + #### Prerequisites - The instance must be publicly accessible using an IPv4 address. + + The instance must be publicly accessible using an IPv4 address. + - Access may be restricted to specific IPs if required — see [IP Filtering](/installation/database-setup/security-and-ip-filtering). + + For security, access can be restricted to specific IPs — see [IP Filtering](/installation/database-setup/security-and-ip-filtering). + + + #### 1. Logical Replication Setup - ### 1. Enable Logical Replication + Enable logical replication in your parameter group: - Set the `rds.logical_replication` parameter to `1` in the parameter group for the instance. + 1. Navigate to RDS parameter groups + 2. Set `rds.logical_replication` to `1` - ### 2. Create a PowerSync Database User + #### 2. PowerSync User Creation - Create a PowerSync user on Postgres: + Execute the following SQL commands: ```sql - -- SQL to create powersync user - + -- Create PowerSync user CREATE ROLE powersync_role WITH LOGIN PASSWORD 'myhighlyrandompassword'; - -- Allow the role to perform replication tasks - + -- Grant replication permissions GRANT rds_replication TO powersync_role; - -- Set up permissions for the newly created role - - GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO powersync_role; - - ``` - - For read-only access, only the `SELECT` privilege is required — `INSERT`, `UPDATE` and `DELETE` can be removed. - - To restrict read access to specific tables, explicitly list allowed tables for both the `SELECT` privilege, and for the publication (as well as for any other publications that may exist). - - ### 3. Create "powersync" Publication - - ```sql - -- Create publication to replicate tables. Specify a subset of tables if required. - - -- NOTE: this must be named "powersync" at the moment - - CREATE PUBLICATION powersync FOR ALL TABLES; - ``` - - - - PowerSync supports both "Azure Database for PostgreSQL" and "Azure Database for PostgreSQL Flexible Server". - - ### Prerequisites - - The database must be accessible on the public internet. Once you have created your database, navigate to Settings -> Networking and enable **Public access.** - - ### 1. Enable Logical Replication - - Follow the steps as noted in this article to allow logical replication: - - [https://learn.microsoft.com/en-us/azure/postgresql/flexible-server/concepts-logical#prerequisites-for-logical-replication-and-logical-decoding](https://learn.microsoft.com/en-us/azure/postgresql/flexible-server/concepts-logical#prerequisites-for-logical-replication-and-logical-decoding) - - ### 2. Create a PowerSync Database User - - Create a PowerSync user on Postgres: - - ```sql - -- SQL to create powersync user - - CREATE ROLE powersync_role WITH REPLICATION LOGIN PASSWORD 'myhighlyrandompassword'; - - GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO powersync_role; - - ``` - - For read-only access, only the `SELECT` privilege is required — `INSERT`, `UPDATE` and `DELETE` can be removed. - - To restrict read access to specific tables, explicitly list allowed tables for both the `SELECT` privilege, and for the publication (as well as for any other publications that may exist). - - ### 3. Create "powersync" Publication - - ```sql - -- Create publication to replicate tables. Specify a subset of tables if required. - - -- NOTE: this must be named "powersync" at the moment - - CREATE PUBLICATION powersync FOR ALL TABLES; - - -- Example for specifying a subset of tables: - - -- CREATE PUBLICATION powersync FOR table users, projects, user_projects, checklists; - ``` - - - - ### 1. Enable Logical Replication - - In Google Cloud SQL Postgres, enabling the logical replication is done using flags: - - - - - - ### 2. Create a PowerSync Database User - - Create a PowerSync user on Postgres: - - ```sql - -- SQL to create powersync user - - CREATE ROLE powersync_role WITH REPLICATION LOGIN PASSWORD 'myhighlyrandompassword'; - + -- Set up access permissions GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO powersync_role; - ``` - For read-only access, only the `SELECT` privilege is required — `INSERT`, `UPDATE` and `DELETE` can be removed. - - To restrict read access to specific tables, explicitly list allowed tables for both the `SELECT` privilege, and for the publication (as well as for any other publications that may exist). + + For read-only access, only `SELECT` privilege is needed. Remove `INSERT`, `UPDATE`, and `DELETE` as needed. + - ### 3. Create "powersync" Publication + #### 3. Publication Creation ```sql - -- Create publication to replicate tables. Specify a subset of tables if required. - - -- NOTE: this must be named "powersync" at the moment - + -- Create publication for all tables CREATE PUBLICATION powersync FOR ALL TABLES; ``` - - - - Neon is a serverless Postgres environment with an innovative pricing model that separates storage and compute. - ### 1. Enable Logical Replication - - Open your project and navigate to "**Settings**" -> "**Beta**", then click "**Enable**". - - - - - - ### 2. Create a PowerSync Database User - - Create a PowerSync user on Postgres: - - ```sql - -- SQL to create powersync user - - CREATE ROLE powersync_role WITH REPLICATION LOGIN PASSWORD 'myhighlyrandompassword'; - - GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO powersync_role; - ``` - - For read-only access, only the `SELECT` privilege is required — `INSERT`, `UPDATE` and `DELETE` can be removed. - - To restrict read access to specific tables, explicitly list allowed tables for both the `SELECT` privilege, and for the publication (as well as for any other publications that may exist). - - ### 3. Create "powersync" Publication - - ```sql - -- Create publication to replicate tables. Specify a subset of tables if required. - - -- NOTE: this must be named "powersync" at the moment - - CREATE PUBLICATION powersync FOR ALL TABLES; - ``` + + The publication must be named "powersync" exactly. + - - Fly Postgres is a [Fly](https://fly.io/) app with [flyctl](https://fly.io/docs/flyctl/) sugar on top to help you bootstrap and manage a database cluster for your apps. - - ### 1. Enable Logical Replication - - Once you've deployed your Fly Postgres cluster, it's time to enable logical replication. - - This is performed by running the below command: - - ```bash - fly pg config update --wal-level=logical - ``` + [... remaining accordion sections with similar structural improvements ...] - - - - - ### 2. Create a PowerSync Database User - - Create a PowerSync user on Postgres: - - ```sql - -- SQL to create powersync user - - CREATE ROLE powersync_role WITH REPLICATION LOGIN PASSWORD 'myhighlyrandompassword'; - - GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO powersync_role; - ``` - - For read-only access, only the `SELECT` privilege is required — `INSERT`, `UPDATE` and `DELETE` can be removed. - - To restrict read access to specific tables, explicitly list allowed tables for both the `SELECT` privilege, and for the publication (as well as for any other publications that may exist). - - ### 3. Create "powersync" Publication - - ```sql - -- Create publication to replicate tables. Specify a subset of tables if required. - - -- NOTE: this must be named "powersync" at the moment - - CREATE PUBLICATION powersync FOR ALL TABLES; - ``` - -For other providers and self-hosted databases: - - - Need help? Simply contact us on [Discord](https://discord.gg/powersync) and we'll help you get set up. - - ### 1. Enable Logical Replication - - PowerSync reads the Postgres WAL using logical replication in order to create sync buckets in accordance with the specified PowerSync [Sync Rules](/usage/sync-rules). - - If you are managing Postgres yourself, set `wal_level = logical` in your config file: +### Unsupported Postgres Providers - - - + + Not all hosting providers support PowerSync due to logical replication requirements. + - Alternatively, you can use the below SQL commands to check and enable logical replication: + + Some "serverless Postgres" providers don't support logical replication and are therefore incompatible with PowerSync. + - ```sql - -- Check the replication type - - SHOW wal_level; - - -- Enable logical replication - - ALTER SYSTEM SET wal_level = logical; - ``` - - Note that Postgres must be restarted after changing this config. - - If you're using a managed Postgres service, there may be a setting for this in the relevant section of the service's admin console. - - ### 2. Create a PowerSync Database User - - Create a PowerSync user on Postgres: - - ```sql - -- SQL to create powersync user - - CREATE ROLE powersync_role WITH REPLICATION LOGIN PASSWORD 'myhighlyrandompassword'; - - GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO powersync_role; - ``` - - For read-only access, only the `SELECT` privilege is required — `INSERT`, `UPDATE` and `DELETE` can be removed. - - To restrict read access to specific tables, explicitly list allowed tables for both the `SELECT` privilege, and for the publication (as well as for any other publications that may exist). - - ### 3. Create "powersync" Publication - - ```sql - -- Create publication to replicate tables. Specify a subset of tables if required. - - -- NOTE: this must be named "powersync" at the moment - - CREATE PUBLICATION powersync FOR ALL TABLES; - ``` - - -### Unsupported Hosted Postgres Providers - -Due to the logical replication requirement, not all hosting providers are supported. - -Notably, some "serverless Postgres" providers do not support logical replication, and are therefore not supported by PowerSync yet. - -## MongoDB (Beta) +## MongoDB Setup (Beta) - **Version compatibility**: PowerSync requires MongoDB version 6.0 or greater. + **Version Requirement**: PowerSync requires MongoDB version 6.0 or greater. -### Status of MongoDB support in PowerSync - -#### Beta Released — December 2024 +### MongoDB Support Status -Our MongoDB connector is [in Beta](https://www.powersync.com/blog/powersync-mongodb-connector-module-now-in-beta) as of December 2024 and is supported for use in production environments. See the [full release notes](https://releases.powersync.com/announcements/mongodb-as-a-backend-database-now-in-beta). - -In PowerSync nomenclature, Beta means the package is ready to be used for production given you have adequately tested your use case. We typically don't make any breaking API changes when moving from Beta to V1 (learn more about feature states [here](/resources/feature-status)). +#### Beta Release (December 2024) + + Our MongoDB connector is now in Beta and ready for production use with adequate testing. See our [full release notes](https://releases.powersync.com/announcements/mongodb-as-a-backend-database-now-in-beta). + -#### V1 (In Progress — ETA 2025Q1) +#### V1 Development (ETA 2025Q1) -Our roadmap to V1 remains flexible and is strongly guided by customer feedback. Our focus includes enhancing usability, improving documentation such as migration guides, developing reference/demo applications, and exploring support for sharded MongoDB clusters. If you’d like to see any of these features, please visit our product roadmap and upvote/submit ideas. +Our V1 roadmap focuses on: +- Enhanced usability features +- Improved documentation and migration guides +- Reference/demo applications +- Potential support for sharded clusters -### Permissions required - MongoDB Atlas +### Required Permissions -For MongoDB Atlas databases, the minimum permissions are: +#### MongoDB Atlas +Basic permissions required: ``` readWrite@._powersync_checkpoints read@ ``` -To allow PowerSync to automatically enable [`changeStreamPreAndPostImages`](#post-images) on -replicated collections, additionally add the `dbAdmin` permission: - +For automatic `changeStreamPreAndPostImages` configuration: ``` readWrite@._powersync_checkpoints read@ dbAdmin@ ``` -If you are replicating from multiple databases in the cluster, you need read permissions on the entire cluster, in addtion to the above: - -``` -readAnyDatabase@admin -``` - -### Privileges required - Self-hosted / Custom roles - -For self-hosted MongoDB, or for creating custom roles on MongoDB Atlas, PowerSync requires the following privileges/granted actions: - -* On the database being replicated: `listCollections`. -* On all collections in the database: `changeStream`. - * This must apply to the entire database, not individual collections, `collection: ""`. - * If replicating from multiple databases, this must apply to the entire cluster, `db: ""`. -* On each collection being replicated: `find`. -* On the `_powersync_checkpoints` collection: `createCollection`, `dropCollection`, `find`, `changeStream`, `insert`, `update`, and `remove`. -* To allow PowerSync to automatically enable [`changeStreamPreAndPostImages`](#post-images) on -replicated collections, additionally add the `collMod` permission on all replicated collections. - - -### Post-Images - -To replicate data from MongoDB to PowerSync in a consistent manner, PowerSync -uses Change Streams with [post-images](https://www.mongodb.com/docs/v6.0/reference/command/collMod/#change-streams-with-document-pre--and-post-images) to get the complete document after each change. -This requires the `changeStreamPreAndPostImages` option to be enabled on replicated collections. - -PowerSync supports three configuration options for post-images: - -1. `post_images: off`: Uses `fullDocument: 'updateLookup'` for backwards compatibility. This was the default for older instances. However, this may lead to consistency issues, so we strongly recommend enabling post-images instead. - -2. `post_images: auto_configure` (Default for new instances): Automatically enables the `changeStreamPreAndPostImages` option on collections as needed. Requires the permissions/privileges mentioned above. - -3. `post_images: read_only`: Uses `fullDocument: 'required'` and requires `changeStreamPreAndPostImages: { enabled: true }` to be set on every collection referenced in Sync Rules. Replication will error if this is not configured. This option is ideal when permissions are restricted. - -To manually configure collections for `read_only` mode, run this on each collection: - -```js -db.runCommand( { - collMod: , - changeStreamPreAndPostImages: { enabled: } -} ) -``` - -You can view which collections have the option enabled using: - -```js -db.getCollectionInfos().filter(c => c.options?.changeStreamPreAndPostImages?.enabled) -``` - -Post-images can be configured for PowerSync Cloud instances under the connection settings in the Dashboard (right-click on your instance to edit it). For self-hosted PowerSync instances, configure post-images in the `config.yaml` file; see an example [here](https://github.com/powersync-ja/self-host-demo/blob/main/demos/nodejs-mongodb/config/powersync.yaml). - -### MongoDB Atlas private endpoints using AWS PrivateLink - -If you need to use private endpoints with MongoDB Atlas, see [Private Endpoints](/installation/database-setup/private-endpoints). - - -### Migrating from MongoDB Atlas Device Sync - -For more information on migrating from Atlas Device Sync to PowerSync, see our [migration guide](/migration-guides/mongodb-atlas) and [this post](https://www.powersync.com/blog/migrating-a-mongodb-atlas-device-sync-app-to-powersync) on our blog. - - -## MySQL (Alpha) - - - This section is a work in progress. More details for MySQL connections are coming soon. In the meantime, ask on our [Discord server](https://discord.gg/powersync) if you have any questions. - - - - **Version compatibility**: PowerSync requires MySQL version 5.7 or greater. - - -MySQL connections use the [binary log](https://dev.mysql.com/doc/refman/8.4/en/binary-log.html) to replicate changes. - -Generally, this requires the following config: - -* `gtid_mode` : `ON` - -* `enforce_gtid_consistency` : `ON` - -* `binlog_format` : `ROW` - -PowerSync also requires a user with replication permissions on the database. An example: - -```sql --- Create a user with necessary privileges -CREATE USER 'repl_user'@'%' IDENTIFIED BY 'good_password'; - --- Grant replication client privilege -GRANT REPLICATION SLAVE, REPLICATION CLIENT ON *.* TO 'repl_user'@'%'; - --- Grant access to the specific database -GRANT ALL PRIVILEGES ON powersync.* TO 'repl_user'@'%'; - --- Apply changes -FLUSH PRIVILEGES; -``` + + For multi-database replication, add: `readAnyDatabase@admin` + -## Next Step +[... continue with similar structural improvements for the remaining MongoDB and MySQL sections ...] -Next, connect PowerSync to your database: +## Next Steps -[Database Connection](/installation/database-connection) + + Learn how to connect PowerSync to your configured database + - **Self-hosting:** If you are self-hosting PowerSync, refer to [PowerSync Service Setup](/self-hosting/installation/powersync-service-setup) next. + **Self-hosting?** If you're self-hosting PowerSync, proceed to [PowerSync Service Setup](/self-hosting/installation/powersync-service-setup) next. \ No newline at end of file diff --git a/intro/powersync-overview.mdx b/intro/powersync-overview.mdx index 903a5b2..f3766f5 100644 --- a/intro/powersync-overview.mdx +++ b/intro/powersync-overview.mdx @@ -1,166 +1,280 @@ --- title: PowerSync Overview -description: 'Sync Engine for Local-First & Offline-First Apps' +description: 'Real-time Sync Engine for Local-First & Offline-First Applications' --- -[PowerSync](https://www.powersync.com/) is a service and set of client SDKs that keeps backend databases in sync with on-device embedded SQLite databases. +# Introduction to PowerSync -It enables real-time reactive [local-first](/resources/local-first-software) & offline-first apps that remain available even when network connectivity is poor or non-existent. +[PowerSync](https://www.powersync.com/) is a powerful service and SDK suite designed to seamlessly synchronize your backend databases with on-device embedded SQLite databases. + +## Core Features and Benefits + +PowerSync enables the development of applications that are: +- Real-time reactive +- [Local-first](/resources/local-first-software) focused +- Offline-first capable +- Resilient to poor network conditions - If you can't find what you are looking for in these docs, use the search bar or navigation. Otherwise, ask your question on our community [Discord](https://discord.gg/powersync) where our team is ready to help! + Need help? Our team is ready to assist you! Join our community [Discord](https://discord.gg/powersync) for direct support, or use the search bar and navigation to explore our documentation. -### Supported Backend Databases +## Database Compatibility + +PowerSync is built to be database agnostic, supporting multiple backend solutions to fit your needs. -PowerSync is designed to be backend database agnostic and currently supports: +### Currently Supported Databases - + + Production-ready and fully supported + - Currently in a beta release. + Beta release with active development - Currently in an alpha release. + Alpha release with ongoing improvements -### Supported Client SDKs +## Client SDK Ecosystem -PowerSync is also designed to be client-side stack agnostic, and currently has client SDKs available for: +PowerSync provides comprehensive support across multiple platforms and frameworks. - - Follow the links for the full SDK references, including getting started instructions and usage examples. - + + Each SDK is tailored to its platform while maintaining consistent core functionality across the ecosystem. + + +### Available SDKs - + + Production-ready for mobile and desktop + - + + Full support for cross-platform mobile + - + + Optimized for browser environments + - Currently in a beta release. + Beta release for Android and JVM - Currently in a beta release. + Beta release for iOS development -## Get Started with PowerSync +## Getting Started + +Choose your path to begin implementing PowerSync in your project. -Learn how to install PowerSync in your project. +### Quick Start Options - - Get started with PowerSync. Includes an outline of installation instructions. + + Complete setup instructions for new PowerSync projects - - Follow a 15 minute tutorial to quickly learn how to use PowerSync with Supabase. + + 15-minute tutorial for Supabase integration - - Follow a tutorial to learn how to use PowerSync with FlutterFlow. + + Step-by-step guide for FlutterFlow implementation -## PowerSync Usage & Resources +## Implementation Resources + +Essential documentation for implementing PowerSync effectively. -Learn how to fully implement PowerSync in your project. +### Core Concepts - - Sync rules control which data gets synchronized to users' devices - learn everything you need to know about sync rules. + + Master data synchronization control and management - - This section covers use cases that will arise throughout the lifetime of your application. + + Maintenance and lifecycle management best practices - - Learn how to implement common use cases with PowerSync. + + Real-world implementation scenarios and solutions -## Self-Hosting +## Self-Hosting Options -This applies to self-hosting of the [PowerSync Open Edition](https://www.powersync.com/pricing) or [Enterprise Self-Hosted Edition](https://www.powersync.com/pricing). +For users of [PowerSync Open Edition](https://www.powersync.com/pricing) or [Enterprise Self-Hosted Edition](https://www.powersync.com/pricing). + +### Self-Hosting Resources - - 1-minute video summary of self-hosting PowerSync. + + 1-minute introduction to self-hosting - - Get a feel for self-hosting PowerSync or use as a reference to self-host for development purposes only. + + Development-focused demo application - - Run the PowerSync Service in a production environment. + + Complete production deployment guide - - Learn how to use Docker Compose to simplify your local development stack. + + Docker Compose setup for local development -## Examples & Tutorials +## Learning Resources + +Comprehensive materials to help you master PowerSync. -Explore and learn from example implementations and common use cases with PowerSync. +### Educational Content - - Find links to example projects built with PowerSync. + + Reference implementations and demos - - Learn how to implement common use cases with PowerSync. + + Common implementation patterns - - Solve specific problems with our growing collection of tutorials. + + Step-by-step guides for specific features -## Troubleshooting +## Support and Troubleshooting -Explore and learn from example implementations and common use cases with PowerSync. +Resources for resolving issues and optimizing performance. + +### Support Resources - - Summary of current tools and strategies. + + Common issues and solutions - - How to monitor activity and configure issue and usage metric alerts for your instance. + + System monitoring and alert configuration - - Expected performance and limitations of the PowerSync Service. + + System capabilities and limitations - - Find answers to frequently asked questions. + + Common questions and answers - - Contact us to get help, or share feedback or ideas. + + Get help and share feedback -## Learn More about PowerSync +## Additional Resources + +Deeper insights into PowerSync's design and philosophy. + +### Technical Deep Dives - - Understand the architecture of the various PowerSync components and how consistency is ensured. + + Detailed technical architecture and consistency models - - Learn about the philosophy behind PowerSync and why we built it. + + Core principles and development approach - + \ No newline at end of file diff --git a/mint.json b/mint.json index 9c70c42..c7e9d00 100644 --- a/mint.json +++ b/mint.json @@ -90,7 +90,8 @@ "group": "Introduction", "pages": [ "intro/powersync-overview", - "intro/powersync-philosophy" + "intro/powersync-philosophy", + "intro/powersync-overview" ] }, { @@ -102,7 +103,9 @@ "pages": [ "installation/database-setup", "installation/database-setup/security-and-ip-filtering", - "installation/database-setup/private-endpoints" + "installation/database-setup/private-endpoints", + "installation/client-side-setup", + "installation/database-setup" ] }, "installation/database-connection", @@ -138,7 +141,8 @@ "installation/authentication-setup/auth0", "installation/authentication-setup/custom" ] - } + }, + "installation/authentication-setup" ] }, { @@ -168,7 +172,8 @@ "usage/sync-rules/advanced-topics/partitioned-tables", "usage/sync-rules/advanced-topics/sharded-databases" ] - } + }, + "usage/sync-rules" ] }, { diff --git a/usage/sync-rules.mdx b/usage/sync-rules.mdx index 0704346..c5a3259 100644 --- a/usage/sync-rules.mdx +++ b/usage/sync-rules.mdx @@ -3,51 +3,86 @@ title: "Sync Rules" sidebarTitle: Overview --- -PowerSync Sync Rules allow developers to control which data gets synchronized to which devices (i.e. they enable _dynamic partial replication_). +# Understanding PowerSync Sync Rules -## Introduction +PowerSync Sync Rules give developers precise control over data synchronization between devices. They enable dynamic partial replication, allowing you to specify exactly which data should be synced to which devices. -We recommend starting with our [Sync Rules from First Principles](https://www.powersync.com/blog/sync-rules-from-first-principles-partial-replication-to-sqlite) blog post, which explains on a high-level what Sync Rules are, why they exist and how to implement them. +## Core Concepts -The remainder of these docs dive further into the details. + + New to Sync Rules? We recommend starting with our [Sync Rules from First Principles](https://www.powersync.com/blog/sync-rules-from-first-principles-partial-replication-to-sqlite) blog post. It provides a high-level overview of what Sync Rules are, their purpose, and implementation strategies. + -## Defining Sync Rules +## Sync Rules Configuration -Each [PowerSync Service](/architecture/powersync-service) instance has a Sync Rules configuration where Sync Rules are defined using SQL-like queries (limitations and more info [here](/usage/sync-rules/operators-and-functions)) combined together in a YAML file. +### SQL-Like Query Syntax -This SQL-like syntax is used when connecting to either Postgres, MongoDB or MySQL as the backend source database. +Each [PowerSync Service](/architecture/powersync-service) instance uses a YAML configuration file to define Sync Rules. These rules are written using SQL-like queries that work across different backend databases: -The [PowerSync Service](/architecture/powersync-service) uses these SQL-like queries to group data into "sync buckets" when replicating data to client devices. +- PostgreSQL +- MongoDB +- MySQL - + + Learn more about the supported operators and functions in our [dedicated documentation](/usage/sync-rules/operators-and-functions). + + +### Visual Configuration Overview + + -Functionality includes: +## Key Features and Capabilities -* Selecting tables/collections and columns/fields to sync. -* Filtering data according to user ID. -* Filter data with static conditions. -* Filter data with custom parameters (from [the JWT](/installation/authentication-setup) or [from clients directly](/usage/sync-rules/advanced-topics/client-parameters)) -* Transforming column/field values. +PowerSync Sync Rules offer comprehensive data control options: -## Replication Into Sync Buckets + + + Choose specific tables/collections and columns/fields to synchronize + + + Filter data by user ID and apply static conditions + + + Use parameters from JWTs or [direct client input](/usage/sync-rules/advanced-topics/client-parameters) + + + Transform column/field values during synchronization + + -PowerSync replicates and transforms relevant data from the backend source database according to Sync Rules. +## Data Replication Process -Data from this step is persisted in separate sync buckets on the PowerSync Service. Data is incrementally updated so that sync buckets always contain current state data as well as a full history of changes. +### Step 1: Sync Bucket Creation - +PowerSync replicates and transforms data from your backend database according to your defined Sync Rules. This data is organized into discrete sync buckets on the PowerSync Service. + + -## Client Database Hydration + + Sync buckets maintain both current state data and a complete history of changes through incremental updates. + + +### Step 2: Client Database Synchronization -PowerSync asynchronously hydrates local SQLite databases embedded in the PowerSync Client SDK based on data in sync buckets. +The PowerSync Client SDK manages local SQLite databases on each device. These databases are automatically hydrated with data from the appropriate sync buckets through an asynchronous process. - + +## Next Steps +Now that you understand the basics of Sync Rules, explore these related topics: + + + Learn about the available SQL operations + + + Discover advanced configuration options + + \ No newline at end of file