From 3a24b95304088fa0a505ac65d0d6d3ac9f1afbad Mon Sep 17 00:00:00 2001 From: Benita Volkmann Date: Wed, 12 Aug 2026 15:31:01 +0200 Subject: [PATCH 01/16] WIP: full reference for service.yaml --- .../self-hosted-instances.mdx | 681 +++++++++++++++--- configuration/source-db/connection.mdx | 2 +- configuration/source-db/setup.mdx | 2 +- intro/setup-guide.mdx | 2 +- maintenance-ops/self-hosting/aws-ecs.mdx | 2 +- sync/streams/overview.mdx | 2 +- 6 files changed, 605 insertions(+), 86 deletions(-) diff --git a/configuration/powersync-service/self-hosted-instances.mdx b/configuration/powersync-service/self-hosted-instances.mdx index 5025a2fc..569b64aa 100644 --- a/configuration/powersync-service/self-hosted-instances.mdx +++ b/configuration/powersync-service/self-hosted-instances.mdx @@ -1,6 +1,6 @@ --- title: "Self-Hosted Instance Configuration" -description: "Configure self-hosted PowerSync Service deployments using YAML or environment variables." +description: "Configuration methods, file structure, and a reference of all available config file options for self-hosted PowerSync Service deployments." sidebarTitle: "Self-Hosted Instances" --- @@ -14,9 +14,25 @@ The PowerSync Service is configured using key/value pairs in a config file, and Both YAML and JSON config files are supported. You can see examples of the above configuration methods in the [docker-compose](https://github.com/powersync-ja/self-host-demo/blob/d61cea4f1e0cc860599e897909f11fb54420c3e6/docker-compose.yaml#L46) file of our `self-host-demo` app. +### Environment Variable Substitution + +The config file uses custom tags for environment variable substitution. + +Using `!env [variable name]` will substitute the value of the environment variable named `[variable name]`. For example, with the environment variable `PS_MONGO_URI=mongodb://mongo:27017/powersync`, the YAML + +```yaml +storage: + type: mongodb + uri: !env PS_MONGO_URI +``` + +resolves to `uri: mongodb://mongo:27017/powersync`. + +Only environment variables with names starting with `PS_` can be substituted. + ## Configuration File Structure -Below is a skeleton config file you can copy and paste to edit locally: +Below is a skeleton config file with the most common options. See the [Configuration Reference](#configuration-reference) for all available options. ```yaml service.yaml # Settings for source database replication @@ -51,10 +67,10 @@ storage: # uri: postgresql://powersync_storage_user:secure_password@storage-db:5432/postgres # sslmode: disable -# The port which the PowerSync API server will listen on -port: 80 +# The port which the PowerSync API server will listen on (defaults to 8080) +port: 8080 -# Specify Sync Streams or legacy Sync Rules (see Sync Streams section below). +# Specify Sync Streams or legacy Sync Rules (see the sync_config section below). # Referencing a separate file is recommended so you can edit streams/rules without nesting YAML. sync_config: path: sync-config.yaml @@ -71,11 +87,11 @@ client_auth: # JWKS audience audience: ['powersync-dev', 'powersync'] - # Settings for telemetry reporting - # See https://docs.powersync.com/maintenance-ops/self-hosting/usage-reporting - telemetry: - # Opt out of reporting anonymized usage metrics to PowerSync telemetry service - disable_telemetry_sharing: false +# Settings for telemetry reporting +# See https://docs.powersync.com/maintenance-ops/self-hosting/usage-reporting +telemetry: + # Opt out of reporting anonymized usage metrics to PowerSync telemetry service + disable_telemetry_sharing: false # System-level configuration options system: @@ -86,46 +102,50 @@ system: format: text # 'json' or 'text' ``` -### Example +### Supplementary Resources -A detailed `service.yaml` config example with additional comments can be found here: +These external resources supplement the [Configuration Reference](#configuration-reference) below: - - + + A working config example from the `self-host-demo` app, including environment variable substitution. -### Config File Schema + + A machine-readable schema of the config file, published as `@powersync/service-schema`. + -The config file schema is available here: + + Add this comment to the top of your YAML config file to get validation and autocomplete in editors that support the [YAML language server](https://github.com/redhat-developer/yaml-language-server) (for example VS Code with the YAML extension): - - - + ```yaml + # yaml-language-server: $schema=https://unpkg.com/@powersync/service-schema@latest/json-schema/powersync-config.json + ``` + -## Source Database Connections +## Configuration Reference -Specify the connection to your source database in the `replication` section of the config file: +The config file supports the following top-level keys, documented in the sections below: -```yaml service.yaml -# Settings for source database replication -replication: - # Specify database connection details - # Note only 1 connection is currently supported - # Multiple connection support is on the roadmap - connections: - - type: postgresql - # The PowerSync server container can access the Postgres DB via the DB's service name. - # In this case the hostname is pg-db +| Key | Purpose | +| ------------------------------ | --------------------------------------------------------------------------- | +| [`replication`](#replication) | Source database connection(s) to replicate from | +| [`storage`](#storage) | Bucket storage database connection | +| [`port`](#port) | Port for the PowerSync API server | +| [`sync_config`](#sync_config) | Sync Streams (or legacy Sync Rules) definition | +| [`client_auth`](#client_auth) | JWT authentication for client connections | +| [`api`](#api) | Admin API tokens and performance/safety limits | +| [`telemetry`](#telemetry) | Telemetry sharing and Prometheus metrics | +| [`healthcheck`](#healthcheck) | Health check probe mechanisms | +| [`migrations`](#migrations) | Storage database schema migration behavior | +| [`system`](#system) | Service logging | +| [`metadata`](#metadata) | Custom metadata key-value pairs | +| [`parameters`](#parameters) | Global parameters | - # The connection URI or individual parameters can be specified. - uri: postgresql://postgres:mypassword@pg-db:5432/postgres +### replication - # SSL settings - sslmode: disable # 'verify-full' (default) or 'verify-ca' or 'disable' - # Note: 'disable' is only suitable for local/private networks, not for public networks -``` +Specify the connection to your source database in `replication.connections`. Only one connection is currently supported; multiple connection support is on the roadmap. -For details on connecting to your source database, see [Connect PowerSync to Your Source Database](/intro/setup-guide#3-connect-powersync-to-your-source-database) in the Setup Guide. +For instructions on preparing your source database, see [Source Database Setup](/configuration/source-db/setup). If you are using hosted Supabase, you will need to enable IPv6 for Docker as per [the Docker docs](https://docs.docker.com/config/daemon/ipv6/) @@ -135,32 +155,376 @@ For details on connecting to your source database, see [Connect PowerSync to You This is because Supabase only allows direct database connections over IPv6 — PowerSync cannot connect using the connection pooler. -## Bucket Storage Database +All connection types support these common options: + + + The connection type. One of `postgresql`, `mongodb`, `mysql`, `mssql`, or `convex`. + + + + Unique identifier for the connection. Optional when only a single connection is present. + + + + Additional meta tag for the connection, used for categorization or grouping. + + + + When enabled, allows executing queries against this connection through the service's admin API (authenticated using [`api.tokens`](#api)). + + + + Block connections to any of these IP ranges. Include `local` to block anything not in public unicast ranges. + + +The remaining options depend on the connection type: + + + + ```yaml service.yaml + replication: + connections: + - type: postgresql + uri: postgresql://postgres:mypassword@pg-db:5432/postgres + sslmode: verify-full + ``` + + + Connection URI in the format `postgresql://user:password@hostname:5432/database`. Individual connection parameters take precedence over values in the URI. + + + + Database hostname. Required if not specified in `uri`. + + + + Database port. + + + + Database username. Required if not specified in `uri`. + + + + Database password. Required if not specified in `uri`. + + + + Database name. Required if not specified in `uri`. + + + + SSL mode: `verify-full`, `verify-ca`, or `disable`. `disable` is only suitable for local/private networks, not for public networks. + + + + CA certificate content in PEM format. Required for `verify-ca`, optional for `verify-full`. + + + + Client certificate content in PEM format, for TLS client authentication. + + + + Client private key content in PEM format, for TLS client authentication. + + + + Use a servername for TLS that is different from `hostname`. + + + + Prefix for Postgres logical replication slot names and replication stream names. + + + + Maximum number of connections to the source database, per service process. + + + + Connection timeout in seconds. Takes precedence over a `connect_timeout` query parameter in the URI. + + + + Interval in seconds between source connection heartbeats. Must be between 5 and 60. + + + + + ```yaml service.yaml + replication: + connections: + - type: mongodb + uri: mongodb+srv://myuser:mypassword@cluster0.abcde.mongodb.net/mydatabase + post_images: auto_configure + ``` + + + Connection URI in the format `mongodb://` or `mongodb+srv://`. Standard connection options such as `connectTimeoutMS`, `socketTimeoutMS`, `serverSelectionTimeoutMS`, `maxPoolSize` and `maxIdleTimeMS` can be set as query parameters in the URI. + + + + Database name. Defaults to the database in the URI path. + + + + Database username. Defaults to the username in the URI. + + + + Database password. Defaults to the password in the URI. + + + + Controls how change stream post-images are used: `off`, `auto_configure`, or `read_only`. `auto_configure` is recommended for new instances. See [Post Images](/configuration/source-db/setup#post-images) for details on each option. + + + + Interval in seconds between source connection heartbeats. Must be between 5 and 60. + + + + + MySQL support is currently in a [Beta release](/resources/feature-status). + + ```yaml service.yaml + replication: + connections: + - type: mysql + uri: mysql://repl_user:mypassword@mysql-db:3306/inventory + ``` + + + Connection URI in the format `mysql://user:password@hostname:3306/database`. Individual connection parameters take precedence over values in the URI. + + + + Database hostname. Required if not specified in `uri`. + + + + Database port. + + + + Database username. Required if not specified in `uri`. + + + + Database password. Required if not specified in `uri`. + + + + Database name. Required if not specified in `uri`. + + + + Server ID used when connecting as a replication client. + + + + CA certificate content in PEM format. + + + + Client certificate content in PEM format, for TLS client authentication. + + + + Client private key content in PEM format, for TLS client authentication. + + + + The combined size in MB of binlog events that can be queued in memory before throttling is applied. + + + + + SQL Server support is currently in a [Beta release](/resources/feature-status). Also see [SQL Server Additional Configuration](/configuration/source-db/sql-server-additional-configuration). + + ```yaml service.yaml + replication: + connections: + - type: mssql + uri: mssql://powersync_user:mypassword@mssql-db:1433/inventory + ``` + + + Connection URI in the format `mssql://user:password@hostname:1433/database`. Individual connection parameters take precedence over values in the URI. + + + + Database hostname. Required if not specified in `uri`. + + + + Database port. + + + + Database username. Required if not specified in `uri` or `authentication`. + + + + Database password. Required if not specified in `uri` or `authentication`. + + + + Database name. Required if not specified in `uri`. + + + + The database schema to replicate from. + + + + Alternative authentication configuration, instead of `username` and `password`. + + + Authentication method: `default` (SQL Server login) or `azure-active-directory-service-principal-secret`. + + + For `default`: `userName` and `password`. For `azure-active-directory-service-principal-secret`: `clientId`, `clientSecret` and `tenantId` from your registered Azure application. + + + + + + Additional replication settings. + + + Interval in milliseconds to wait between CDC polling cycles. + + + Maximum number of transactions to poll per polling cycle. + + + Whether to trust the server certificate. Set to `true` for local development and self-signed certificates. + + + + + + Interval in seconds between source connection heartbeats. Must be between 5 and 60. + + + + + The Convex replicator is currently released as an [experimental feature](/resources/feature-status). See [Convex source database setup](/configuration/source-db/setup#convex). + + ```yaml service.yaml + replication: + connections: + - type: convex + deployment_url: https://happy-animal-123.convex.cloud + deploy_key: !env PS_CONVEX_DEPLOY_KEY + ``` + + + The URL of your Convex deployment. + + + + A deploy key for the Convex deployment, used to authenticate against the Convex Streaming Export API. + + + + Interval in milliseconds between polling for new changes. + + + + Timeout in milliseconds for requests to the Convex API. + + + + +### storage + +The PowerSync Service requires a storage database to store the data and metadata for [buckets](/architecture/powersync-service#bucket-system). You can use either MongoDB or Postgres for this purpose. + + + The _bucket storage database_ is separate from your _source database_. + + + + The storage backend type: `mongodb` or `postgresql`. + + + + Maximum number of connections to the storage database, per service process. + -The PowerSync Service requires a storage database to store the data and metadata for [buckets](/architecture/powersync-service#bucket-system). You can use either MongoDB or Postgres for this purpose. The bucket storage database should be specified in the `storage` section of the config file: + + Block connections to any of these IP ranges. Include `local` to block anything not in public unicast ranges. + + +#### MongoDB Storage ```yaml service.yaml -# Connection settings for bucket storage (MongoDB and Postgres are supported) storage: - # Option 1: MongoDB Storage type: mongodb uri: mongodb://mongo:27017/powersync_demo - # Use these if authentication is required. The user should have `readWrite` and `dbAdmin` roles - # username: myuser - # password: mypassword - - # Option 2: Postgres Storage - # type: postgresql - # This accepts the same parameters as a Postgres replication source connection - # uri: postgresql://powersync_storage_user:secure_password@storage-db:5432/postgres - # sslmode: disable ``` - - The _bucket storage database_ is separate from your _source database_. - - -### MongoDB Storage + + Connection URI in the format `mongodb://` or `mongodb+srv://`. Standard connection options such as `connectTimeoutMS`, `socketTimeoutMS`, `serverSelectionTimeoutMS`, `maxPoolSize` and `maxIdleTimeMS` can be set as query parameters in the URI. + + + + Database name. Defaults to the database in the URI path. + + + + Database username. Defaults to the username in the URI. The user should have `readWrite` and `dbAdmin` roles. + + + + Database password. Defaults to the password in the URI. + + + + Throttles the clearing of old bucket data after deploying a new sync configuration, by pausing between batches. The pause is proportional to the previous batch duration. Increase this to reduce the impact of clear operations on the storage cluster, or use `0` to clear as fast as possible. Must be between 0 and 20. + + + + Read preference for bulk checksum and bucket data reads: `primary`, `primaryPreferred`, `secondary`, `secondaryPreferred`, or `nearest`. If unset, MongoDB driver defaults are used. This is an experimental option and may be removed in a future release. + + + + Experimental support for storing large bucket data chunks in S3-compatible object storage instead of MongoDB. + + + Must be `s3`. + + + Name of the S3 bucket. + + + Region of the S3 bucket. + + + Key prefix for stored objects. + + + Custom endpoint, for S3-compatible object storage providers. + + + Use path-style addressing, required by some S3-compatible providers. + + + Access key ID for authentication. + + + Secret access key for authentication. + + + Maximum number of concurrent object storage requests. + + + Chunks smaller than this byte threshold stay inline in MongoDB instead of being offloaded to object storage. + + + MongoDB requires at least one replica set node. A single node is fine for development/staging environments, but a 3-node replica set is recommended [for production](/maintenance-ops/self-hosting/deployment-architecture) deployments. @@ -187,11 +551,34 @@ If you are rolling your own Docker environment, you can include this init script - 'sleep 10 && mongosh --host mongo:27017 --eval ''try{rs.status().ok && quit(0)} catch {} rs.initiate({_id: "rs0", version: 1, members: [{ _id: 0, host : "mongo:27017" }]})''' ``` -### Postgres Storage +#### Postgres Storage Available since version 1.3.8 of the [`powersync-service`](https://hub.docker.com/r/journeyapps/powersync-service), you can use Postgres as an alternative bucket storage database. -#### Database Setup +```yaml service.yaml +storage: + type: postgresql + uri: postgresql://powersync_storage_user:secure_password@storage-db:5432/postgres +``` + +Postgres storage accepts the same connection options as a [Postgres replication connection](#replication): `uri`, `hostname`, `port`, `username`, `password`, `database`, `sslmode`, `cacert`, `client_certificate`, `client_private_key` and `tls_servername`. In addition, batch limits can be tuned: + + + Limits for batch operations during replication. Increasing these limits can improve replication performance, at the cost of higher memory usage. + + + Maximum estimated byte size of operations written in a single transaction. + + + Maximum number of records written in a single transaction. + + + Maximum byte size of `current_data` documents looked up at a time. + + + + +##### Database Setup You'll need to create a dedicated user and schema for PowerSync bucket storage. You can either: @@ -213,11 +600,9 @@ GRANT USAGE ON SCHEMA powersync TO powersync_storage_user; GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA powersync TO powersync_storage_user; ``` -#### Demo App - A demo app with Postgres bucket storage is available [here](https://github.com/powersync-ja/self-host-demo/tree/main/demos/nodejs-postgres-bucket-storage). -#### Postgres Version Requirements +##### Postgres Version Requirements Separate Postgres servers are required for replication connections (i.e. source database) and bucket storage **if using Postgres versions below 14**. @@ -226,12 +611,34 @@ Separate Postgres servers are required for replication connections (i.e. source | Below 14 | Separate servers are required for the source and bucket storage. Replication will be blocked if the same server is detected. | | 14 and above | The source database and bucket storage database can be on the same server. Using the same database (with separate schemas) is supported but may lead to higher CPU usage. Using separate servers remains an option. | -## Sync Streams +### port + + + The port on which the PowerSync API server will listen for connections. Can be specified as a number or string. + + +### sync_config + +Your [Sync Streams](/sync/streams/overview) (or legacy [Sync Rules](/sync/rules/overview)) configuration can be in a separate file (recommended) or inline in the main config. The `sync_config:` key is used for both Sync Streams and Sync Rules. + + + Path to the Sync Streams/Sync Rules YAML file. Ensure the file is available at that path, e.g. in the same directory as your main config or on a mounted volume. + -Your Sync Streams (or legacy Sync Rules) configuration can be in a separate file (recommended) or inline in the main config. The `sync_config:` key is used for both Sync Streams and Sync Rules. + + Inline Sync Streams/Sync Rules content as a string, as an alternative to `path`. + + + + Whether to exit the process if there is an error parsing the Sync Streams/Sync Rules configuration. + + + + The top-level `sync_rules` key is a deprecated alias for `sync_config`. Use `sync_config` in new configurations. + - **Separate file**: Referencing a file with `path:` keeps your main config tidy and makes editing Sync Streams/Sync Rules easier. Ensure the file is available at that path (e.g. in the same directory as your main config or on a mounted volume). + **Separate file**: Referencing a file with `path:` keeps your main config tidy and makes editing Sync Streams easier. @@ -276,10 +683,8 @@ sync_config: ``` -For more information, see [Sync Streams](/sync/streams/overview) (recommended) or [Sync Rules](/sync/rules/overview) (legacy). - - To verify that your Sync Rules are functioning correctly, inspect the contents of your bucket storage database. + To verify that your Sync Streams are functioning correctly, inspect the contents of your bucket storage database. #### MongoDB Example @@ -292,9 +697,9 @@ For more information, see [Sync Streams](/sync/streams/overview) (recommended) o ``` -## Client Authentication +### client_auth -Client authentication is configured in the `client_auth` section: +Authentication of client (application end user) connections is configured in the `client_auth` section. For more details, see [Client Authentication](/configuration/auth/overview). ```yaml service.yaml client_auth: @@ -318,22 +723,136 @@ client_auth: audience: ['powersync-dev', 'powersync'] ``` - - For production environments, we recommend using JWKS with asymmetric keys (RS256, EdDSA, or ECDSA) rather than shared secrets (HS256). Asymmetric keys provide better security through public/private key separation and easier key rotation. See [Custom Authentication](/configuration/auth/custom) for more details. - + + URI or array of URIs pointing to JWKS endpoints, used to fetch public keys for JWT verification. + -For more details, see [Client Authentication](/configuration/auth/overview). + + Inline JWKS configuration, as an alternative or in addition to `jwks_uri`. + + + An array of JSON Web Keys (JWKs). Supported key types are RSA (`RS256`, `RS384`, `RS512`), HMAC (`HS256`, `HS384`, `HS512`), OKP (`EdDSA` with `Ed25519` or `Ed448`) and EC (`ES256`, `ES384`, `ES512` with curves `P-256`, `P-384` or `P-521`). See [Custom Authentication](/configuration/auth/custom) for details. + + + -## Environment Variables + + Enables Supabase authentication integration. JWKS details are derived from the Supabase connection. See [Supabase Auth](/configuration/auth/supabase-auth). + -The config file uses custom tags for environment variable substitution. + + Legacy JWT secret for Supabase authentication (HS256 shared secret). + -Using `!env [variable name]` will substitute the value of the environment variable named `[variable name]`. + + Valid audiences for JWT validation. + -Only environment variables with names starting with `PS_` can be substituted. + + IP ranges to reject when resolving JWKS URIs. Include `local` to block anything not in public unicast ranges. + -See examples here: + + When `true`, blocks JWKS URIs that resolve to local network addresses. Use `jwks_reject_ip_ranges` instead. + + + + For production environments, we recommend using JWKS with asymmetric keys (RS256, EdDSA, or ECDSA) rather than shared secrets (HS256). Asymmetric keys provide better security through public/private key separation and easier key rotation. See [Custom Authentication](/configuration/auth/custom) for more details. + - - - \ No newline at end of file +### api + + + Access tokens for the service's admin API routes, provided by clients as a Bearer token. Authentication of these routes is disabled if no tokens are configured. + + + + Performance and safety parameters for the API service. + + + Maximum number of connections (HTTP streams or WebSockets) per API process. + + + Maximum concurrency when fetching data from storage. This should not be significantly more than `storage.max_pool_size`, otherwise it would block on the pool. Increasing this can significantly increase memory usage in some cases. + + + Maximum number of buckets for each connection. More buckets increase latency and memory usage. While the actual number is controlled by your sync configuration, this hard limit ensures that the service errors instead of crashing when the sync configuration is misconfigured. + + + Related to `max_buckets_per_connection`, but this limit applies directly to parameter query results, before they are converted into a unique set of buckets. + + + Number of minutes to keep client-requested write checkpoint records. Expired records are removed by the compact job. Must be a positive integer. + + + How long to keep cached bucket counts before refreshing them, in minutes. Bucket counts may be affected by compacting. + + + + +### telemetry + +See [Usage Reporting](/maintenance-ops/self-hosting/usage-reporting) and [Monitoring](/maintenance-ops/self-hosting/monitoring) for details. + + + When `true`, disables sharing of anonymized usage metrics with the PowerSync telemetry service. + + + + Port on which Prometheus metrics will be exposed. When set, metrics will be available on this port for scraping. + + + + Endpoint that anonymized telemetry is reported to. You typically do not need to change this. + + +### healthcheck + +Configures how health check status is exposed. See [Health Checks](/maintenance-ops/self-hosting/healthchecks) for details on the available probes and endpoints. + + + Mechanisms for exposing health check data. If this is not configured, the service defaults to legacy behavior for backwards compatibility (filesystem probes always enabled, plus HTTP probes depending on the service mode). When `probes` is configured, each mechanism requires explicit opt-in. + + + Enables exposing health check status via filesystem files. + + + Enables exposing health check status via HTTP endpoints. + + + Enables the legacy behavior described above. + + + + +### migrations + + + When `true`, disables automatic storage database schema migrations on startup. Migrations can then be triggered externally by altering the container `command`. + + +### system + + + Service logging configuration. + + + Log level for the service logs: `silly`, `debug`, `verbose`, `http`, `info`, `warn`, or `error`. The `PS_LOG_LEVEL` environment variable takes precedence over this option. + + + Log output format: `json` or `text`. Defaults to `json` when the `NODE_ENV` environment variable is set to `production`. The `PS_LOG_FORMAT` environment variable takes precedence over this option. + + + + +### metadata + + + Custom metadata key-value pairs (string values) for the service. + + +### parameters + + + Global parameters (number, string, boolean or null values) that can be referenced in the sync configuration. + diff --git a/configuration/source-db/connection.mdx b/configuration/source-db/connection.mdx index 011330c2..1e06c7d8 100644 --- a/configuration/source-db/connection.mdx +++ b/configuration/source-db/connection.mdx @@ -9,7 +9,7 @@ Each database provider has their quirks when it comes to specifying connection d Jump to: [Postgres](#postgres-provider-specifics) | [MongoDB](#mongodb-specifics) | [MySQL](#mysql-specifics) | [SQL Server](#sql-server-specifics) | [Convex](#convex-specifics) -The below instructions are currently written for PowerSync Cloud. For self-hosted PowerSync instances, specify database connection details in the config file as documented [here](/configuration/powersync-service/self-hosted-instances#source-database-connections). +The below instructions are currently written for PowerSync Cloud. For self-hosted PowerSync instances, specify database connection details in the config file as documented [here](/configuration/powersync-service/self-hosted-instances#replication). ## Postgres Provider Specifics diff --git a/configuration/source-db/setup.mdx b/configuration/source-db/setup.mdx index 1d39d0ad..4adc0aab 100644 --- a/configuration/source-db/setup.mdx +++ b/configuration/source-db/setup.mdx @@ -803,6 +803,6 @@ Next, connect PowerSync to your database: - + diff --git a/intro/setup-guide.mdx b/intro/setup-guide.mdx index 2b99ddf0..9967aaab 100644 --- a/intro/setup-guide.mdx +++ b/intro/setup-guide.mdx @@ -587,7 +587,7 @@ streams: path: sync-config.yaml ``` - Put your streams in `sync-config.yaml` (see [Self-Hosted Instance Configuration](/configuration/powersync-service/self-hosted-instances#sync-streams) for full examples). Alternatively, you can use inline `content: |` with the YAML nested under `sync_config`. + Put your streams in `sync-config.yaml` (see [Self-Hosted Instance Configuration](/configuration/powersync-service/self-hosted-instances#sync_config) for full examples). Alternatively, you can use inline `content: |` with the YAML nested under `sync_config`. diff --git a/maintenance-ops/self-hosting/aws-ecs.mdx b/maintenance-ops/self-hosting/aws-ecs.mdx index 6632a7b3..1d26a3f4 100644 --- a/maintenance-ops/self-hosting/aws-ecs.mdx +++ b/maintenance-ops/self-hosting/aws-ecs.mdx @@ -28,7 +28,7 @@ Your configuration must include: telemetry: prometheus_port: 9090 ``` -- [Bucket Storage](/configuration/powersync-service/self-hosted-instances#bucket-storage-database): Connection details for your bucket storage database. PowerSync supports MongoDB or Postgres as bucket storage databases. In this guide, we focus on MongoDB. +- [Bucket Storage](/configuration/powersync-service/self-hosted-instances#storage): Connection details for your bucket storage database. PowerSync supports MongoDB or Postgres as bucket storage databases. In this guide, we focus on MongoDB. For bucket storage, we recommend configuring an **AWS PrivateLink** to establish a secure, private connection between your ECS tasks and MongoDB Atlas that doesn't traverse the public internet. diff --git a/sync/streams/overview.mdx b/sync/streams/overview.mdx index c2439495..c33777d8 100644 --- a/sync/streams/overview.mdx +++ b/sync/streams/overview.mdx @@ -51,7 +51,7 @@ streams: query: SELECT * FROM todos WHERE owner_id = auth.user_id() ``` -You can also use inline `sync_config: content: |` with the YAML nested in your main config. See [Self-Hosted Instance Configuration](/configuration/powersync-service/self-hosted-instances#sync-streams--sync-rules) for both options. +You can also use inline `sync_config: content: |` with the YAML nested in your main config. See [Self-Hosted Instance Configuration](/configuration/powersync-service/self-hosted-instances#sync_config) for both options. From 8f6f0eaf71cdd9054b833ccccb976eff84a3ecf5 Mon Sep 17 00:00:00 2001 From: Benita Volkmann Date: Wed, 19 Aug 2026 16:46:41 +0200 Subject: [PATCH 02/16] Better intro and overview for both cloud and self-hosted instances --- .../powersync-service/cloud-instances.mdx | 47 +++++++++++++++---- .../self-hosted-instances.mdx | 4 +- 2 files changed, 42 insertions(+), 9 deletions(-) diff --git a/configuration/powersync-service/cloud-instances.mdx b/configuration/powersync-service/cloud-instances.mdx index b0208d39..31994c45 100644 --- a/configuration/powersync-service/cloud-instances.mdx +++ b/configuration/powersync-service/cloud-instances.mdx @@ -6,17 +6,48 @@ description: "Create and configure PowerSync Cloud instances with a database con import CreateCloudInstance from '/snippets/create-cloud-instance.mdx'; +A PowerSync instance is a running deployment of the [PowerSync Service](/architecture/powersync-service): it replicates data from your source database and streams it to clients based on your [Sync Streams](/sync/streams/overview). On PowerSync Cloud, instances are hosted and managed for you, and you create and configure them in the [PowerSync Dashboard](https://dashboard.powersync.com/) or with the [PowerSync CLI](/tools/cli). + ## Create a PowerSync Instance - + + + + + + + Install the [PowerSync CLI](/tools/cli) (requires Node.js/npm), then log in and scaffold the config directory: + + ```bash + npm install -g powersync + powersync login + powersync init cloud + ``` + + This creates a `powersync/` directory with `service.yaml` (instance name, region, connection, auth) and `sync-config.yaml` (sync config). Edit `powersync/service.yaml` to set your instance name and region. + + Then create the instance and link the directory to it: + + ```bash + powersync link cloud --create --project-id= + ``` + + Find your project ID in the [PowerSync Dashboard](https://dashboard.powersync.com/) URL, or run `powersync fetch instances` after logging in. + + + +## Configure Your Instance + +A new instance needs three things before clients can sync: -## Instance Settings +1. A connection to your source database. See [Source Database Connection](/configuration/source-db/connection). +2. Client authentication. See [Authentication Setup](/configuration/auth/overview). When getting started, you can use temporary [development tokens](/configuration/auth/development-tokens) instead of setting up a full auth provider. +3. A sync configuration defining what data syncs to which clients, written as [Sync Streams](/sync/streams/overview). -After creating an instance, you can configure various settings through the [PowerSync Dashboard](https://dashboard.powersync.com/): +In the Dashboard, each of these has its own view in the instance's sidebar. With the CLI, the database connection and client auth settings live in `service.yaml` and the sync configuration in `sync-config.yaml`; run `powersync deploy` to apply changes. -- **Database Connections**: Connect your instance to your source database. See [Source Database Connection](/configuration/source-db/connection) for details. -- **Client Auth**: Configure how clients authenticate. See [Authentication Setup](/configuration/auth/overview) for details. -- **Sync Streams / Sync Rules (legacy)**: Define what data to sync to clients. See [Sync Streams & Sync Rules Overview](/sync/overview) for details. -- **Settings**: Advanced instance-specific settings. +Other lower-level instance-level options are available in the Dashboard under the instance's Settings view. The CLI has corresponding commands for these operations. -For more information about managing instances, see the [PowerSync Dashboard](/tools/powersync-dashboard) documentation. +For more information see: +- [PowerSync Dashboard](/tools/powersync-dashboard) documentation +- [PowerSync CLI](/tools/cli) documentation diff --git a/configuration/powersync-service/self-hosted-instances.mdx b/configuration/powersync-service/self-hosted-instances.mdx index 569b64aa..f46c64ab 100644 --- a/configuration/powersync-service/self-hosted-instances.mdx +++ b/configuration/powersync-service/self-hosted-instances.mdx @@ -4,6 +4,8 @@ description: "Configuration methods, file structure, and a reference of all avai sidebarTitle: "Self-Hosted Instances" --- +A PowerSync instance is a running deployment of the [PowerSync Service](/architecture/powersync-service): it replicates data from your source database and streams it to clients based on your [Sync Streams](/sync/streams/overview). When self-hosting, you run the service in your own infrastructure and configure each instance with a config file, as described below. + ## Configuration Methods The PowerSync Service is configured using key/value pairs in a config file, and supports the following configuration methods: @@ -619,7 +621,7 @@ Separate Postgres servers are required for replication connections (i.e. source ### sync_config -Your [Sync Streams](/sync/streams/overview) (or legacy [Sync Rules](/sync/rules/overview)) configuration can be in a separate file (recommended) or inline in the main config. The `sync_config:` key is used for both Sync Streams and Sync Rules. +Your Sync Streams (or legacy Sync Rules) configuration can be in a separate file (recommended) or inline in the main config. The `sync_config:` key is used for both Sync Streams and Sync Rules. Path to the Sync Streams/Sync Rules YAML file. Ensure the file is available at that path, e.g. in the same directory as your main config or on a mounted volume. From 34eed37f5568faf32c1320aa0f8f22749646d748 Mon Sep 17 00:00:00 2001 From: Benita Volkmann Date: Wed, 19 Aug 2026 16:56:49 +0200 Subject: [PATCH 03/16] More natural flow of the self-hosted instance page --- .../powersync-service/cloud-instances.mdx | 2 +- .../self-hosted-instances.mdx | 61 +++++++++++-------- 2 files changed, 35 insertions(+), 28 deletions(-) diff --git a/configuration/powersync-service/cloud-instances.mdx b/configuration/powersync-service/cloud-instances.mdx index 31994c45..a7ab378d 100644 --- a/configuration/powersync-service/cloud-instances.mdx +++ b/configuration/powersync-service/cloud-instances.mdx @@ -46,7 +46,7 @@ A new instance needs three things before clients can sync: In the Dashboard, each of these has its own view in the instance's sidebar. With the CLI, the database connection and client auth settings live in `service.yaml` and the sync configuration in `sync-config.yaml`; run `powersync deploy` to apply changes. -Other lower-level instance-level options are available in the Dashboard under the instance's Settings view. The CLI has corresponding commands for these operations. +Other lower-level instance options, such as compacting buckets and deprovisioning, are available in the Dashboard under the instance's Settings view. The CLI has corresponding commands for most of these operations. For more information see: - [PowerSync Dashboard](/tools/powersync-dashboard) documentation diff --git a/configuration/powersync-service/self-hosted-instances.mdx b/configuration/powersync-service/self-hosted-instances.mdx index f46c64ab..05ad0791 100644 --- a/configuration/powersync-service/self-hosted-instances.mdx +++ b/configuration/powersync-service/self-hosted-instances.mdx @@ -1,40 +1,21 @@ --- title: "Self-Hosted Instance Configuration" -description: "Configuration methods, file structure, and a reference of all available config file options for self-hosted PowerSync Service deployments." +description: "How to configure a self-hosted PowerSync Service instance with a config file, and a reference of all available options." sidebarTitle: "Self-Hosted Instances" --- A PowerSync instance is a running deployment of the [PowerSync Service](/architecture/powersync-service): it replicates data from your source database and streams it to clients based on your [Sync Streams](/sync/streams/overview). When self-hosting, you run the service in your own infrastructure and configure each instance with a config file, as described below. -## Configuration Methods +## Configure Your Instance -The PowerSync Service is configured using key/value pairs in a config file, and supports the following configuration methods: +A self-hosted instance needs four things before clients can sync: -1. Inject config as an environment variable (which contains the Base64 encoding of a config file) -2. Use a config file mounted on a volume -3. Specify the config as a command line parameter (again Base64 encoded) +1. A connection to your source database, which PowerSync replicates data from. See [Source Database Setup](/configuration/source-db/setup) for preparing the database. +2. A [bucket storage](/architecture/powersync-service#bucket-storage) database, where the PowerSync Service stores the data it prepares for syncing to clients. MongoDB and Postgres are supported. +3. Client authentication. See [Authentication Setup](/configuration/auth/overview). When getting started, you can use temporary [development tokens](/configuration/auth/development-tokens) instead of setting up a full auth provider. +4. A sync configuration defining what data syncs to which clients, written as [Sync Streams](/sync/streams/overview). -Both YAML and JSON config files are supported. You can see examples of the above configuration methods in the [docker-compose](https://github.com/powersync-ja/self-host-demo/blob/d61cea4f1e0cc860599e897909f11fb54420c3e6/docker-compose.yaml#L46) file of our `self-host-demo` app. - -### Environment Variable Substitution - -The config file uses custom tags for environment variable substitution. - -Using `!env [variable name]` will substitute the value of the environment variable named `[variable name]`. For example, with the environment variable `PS_MONGO_URI=mongodb://mongo:27017/powersync`, the YAML - -```yaml -storage: - type: mongodb - uri: !env PS_MONGO_URI -``` - -resolves to `uri: mongodb://mongo:27017/powersync`. - -Only environment variables with names starting with `PS_` can be substituted. - -## Configuration File Structure - -Below is a skeleton config file with the most common options. See the [Configuration Reference](#configuration-reference) for all available options. +You define all of these in the service config file, along with operational settings such as the API port and logging. The sync configuration is usually kept in a separate file that the main config references (recommended), but can also be defined inline. The skeleton below shows the most common options; the [Configuration Reference](#configuration-reference) documents all of them. ```yaml service.yaml # Settings for source database replication @@ -124,6 +105,32 @@ These external resources supplement the [Configuration Reference](#configuration ``` +## Supplying the Config File + +Both YAML and JSON config files are supported. The PowerSync Service can read the config in three ways: + +1. From a config file mounted on a volume +2. From an environment variable containing the Base64 encoding of the config file +3. From a command line parameter (also Base64 encoded) + +You can see examples of these methods in the [docker-compose](https://github.com/powersync-ja/self-host-demo/blob/d61cea4f1e0cc860599e897909f11fb54420c3e6/docker-compose.yaml#L46) file of our `self-host-demo` app. + +### Environment Variable Substitution + +The config file uses custom tags for environment variable substitution. + +Using `!env [variable name]` will substitute the value of the environment variable named `[variable name]`. For example, with the environment variable `PS_MONGO_URI=mongodb://mongo:27017/powersync`, the YAML + +```yaml +storage: + type: mongodb + uri: !env PS_MONGO_URI +``` + +resolves to `uri: mongodb://mongo:27017/powersync`. + +Only environment variables with names starting with `PS_` can be substituted. + ## Configuration Reference The config file supports the following top-level keys, documented in the sections below: From 28ba30304c87e0562a16f3c3ad00f315b8542f50 Mon Sep 17 00:00:00 2001 From: Benita Volkmann Date: Wed, 19 Aug 2026 17:05:27 +0200 Subject: [PATCH 04/16] Swap the order of supplementary materials --- .../self-hosted-instances.mdx | 42 +++++++++---------- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/configuration/powersync-service/self-hosted-instances.mdx b/configuration/powersync-service/self-hosted-instances.mdx index 05ad0791..e2a605fd 100644 --- a/configuration/powersync-service/self-hosted-instances.mdx +++ b/configuration/powersync-service/self-hosted-instances.mdx @@ -15,7 +15,7 @@ A self-hosted instance needs four things before clients can sync: 3. Client authentication. See [Authentication Setup](/configuration/auth/overview). When getting started, you can use temporary [development tokens](/configuration/auth/development-tokens) instead of setting up a full auth provider. 4. A sync configuration defining what data syncs to which clients, written as [Sync Streams](/sync/streams/overview). -You define all of these in the service config file, along with operational settings such as the API port and logging. The sync configuration is usually kept in a separate file that the main config references (recommended), but can also be defined inline. The skeleton below shows the most common options; the [Configuration Reference](#configuration-reference) documents all of them. +You define all of these in the service config file, along with some operational settings. The sync configuration is usually kept in a separate file that the main config references (recommended), but can also be defined inline. The skeleton below shows the most common options; the [Configuration Reference](#configuration-reference) documents all of them. ```yaml service.yaml # Settings for source database replication @@ -85,26 +85,6 @@ system: format: text # 'json' or 'text' ``` -### Supplementary Resources - -These external resources supplement the [Configuration Reference](#configuration-reference) below: - - - A working config example from the `self-host-demo` app, including environment variable substitution. - - - - A machine-readable schema of the config file, published as `@powersync/service-schema`. - - - - Add this comment to the top of your YAML config file to get validation and autocomplete in editors that support the [YAML language server](https://github.com/redhat-developer/yaml-language-server) (for example VS Code with the YAML extension): - - ```yaml - # yaml-language-server: $schema=https://unpkg.com/@powersync/service-schema@latest/json-schema/powersync-config.json - ``` - - ## Supplying the Config File Both YAML and JSON config files are supported. The PowerSync Service can read the config in three ways: @@ -131,6 +111,26 @@ resolves to `uri: mongodb://mongo:27017/powersync`. Only environment variables with names starting with `PS_` can be substituted. +### Supplementary Resources + +These external resources supplement the [Configuration Reference](#configuration-reference) below: + + + A working config example from the `self-host-demo` app, including environment variable substitution. + + + + A machine-readable schema of the config file, published as `@powersync/service-schema`. + + + + Add this comment to the top of your YAML config file to get validation and autocomplete in editors that support the [YAML language server](https://github.com/redhat-developer/yaml-language-server) (for example VS Code with the YAML extension): + + ```yaml + # yaml-language-server: $schema=https://unpkg.com/@powersync/service-schema@latest/json-schema/powersync-config.json + ``` + + ## Configuration Reference The config file supports the following top-level keys, documented in the sections below: From 358334d23b16a8d4bea20b54c0a14dee33d4e055 Mon Sep 17 00:00:00 2001 From: Benita Volkmann Date: Wed, 19 Aug 2026 17:24:33 +0200 Subject: [PATCH 05/16] AI feedback --- .../config/vocabularies/PowerSync/accept.txt | 2 + .../self-hosted-instances.mdx | 73 +++++++------------ 2 files changed, 27 insertions(+), 48 deletions(-) diff --git a/.github/vale/config/vocabularies/PowerSync/accept.txt b/.github/vale/config/vocabularies/PowerSync/accept.txt index 2b30b744..459fea47 100644 --- a/.github/vale/config/vocabularies/PowerSync/accept.txt +++ b/.github/vale/config/vocabularies/PowerSync/accept.txt @@ -4,6 +4,7 @@ addon addons agnostically allowlisting +anonymized autoscaling backpressure baz @@ -123,6 +124,7 @@ toolchains ttl uncomment uncheck +unicast unprovisioned unmounts unsynced diff --git a/configuration/powersync-service/self-hosted-instances.mdx b/configuration/powersync-service/self-hosted-instances.mdx index e2a605fd..f3285e91 100644 --- a/configuration/powersync-service/self-hosted-instances.mdx +++ b/configuration/powersync-service/self-hosted-instances.mdx @@ -99,9 +99,9 @@ You can see examples of these methods in the [docker-compose](https://github.com The config file uses custom tags for environment variable substitution. -Using `!env [variable name]` will substitute the value of the environment variable named `[variable name]`. For example, with the environment variable `PS_MONGO_URI=mongodb://mongo:27017/powersync`, the YAML +`!env [variable name]` substitutes the value of the environment variable named `[variable name]`. For example, with the environment variable `PS_MONGO_URI=mongodb://mongo:27017/powersync`, the YAML -```yaml +```yaml service.yaml storage: type: mongodb uri: !env PS_MONGO_URI @@ -150,7 +150,7 @@ The config file supports the following top-level keys, documented in the section | [`metadata`](#metadata) | Custom metadata key-value pairs | | [`parameters`](#parameters) | Global parameters | -### replication +### `replication` Specify the connection to your source database in `replication.connections`. Only one connection is currently supported; multiple connection support is on the roadmap. @@ -161,7 +161,7 @@ For instructions on preparing your source database, see [Source Database Setup]( If your host OS does not support Docker IPv6 e.g. macOS, you will need to run Supabase locally. - This is because Supabase only allows direct database connections over IPv6 — PowerSync cannot connect using the connection pooler. + This is because Supabase only allows direct database connections over IPv6. PowerSync cannot connect using the connection pooler. All connection types support these common options: @@ -447,7 +447,7 @@ The remaining options depend on the connection type: -### storage +### `storage` The PowerSync Service requires a storage database to store the data and metadata for [buckets](/architecture/powersync-service#bucket-system). You can use either MongoDB or Postgres for this purpose. @@ -547,7 +547,7 @@ mongosh "mongodb+srv://powersync.abcdef.mongodb.net/" --apiVersion 1 --username If you are rolling your own Docker environment, you can include this init script in your `docker-compose` file to configure a replica set as once-off operation: -```yaml +```yaml docker-compose.yaml # Initializes the MongoDB replica set. This service will not usually be actively running mongo-rs-init: image: mongo:7.0 @@ -620,15 +620,15 @@ Separate Postgres servers are required for replication connections (i.e. source | Below 14 | Separate servers are required for the source and bucket storage. Replication will be blocked if the same server is detected. | | 14 and above | The source database and bucket storage database can be on the same server. Using the same database (with separate schemas) is supported but may lead to higher CPU usage. Using separate servers remains an option. | -### port +### `port` The port on which the PowerSync API server will listen for connections. Can be specified as a number or string. -### sync_config +### `sync_config` -Your Sync Streams (or legacy Sync Rules) configuration can be in a separate file (recommended) or inline in the main config. The `sync_config:` key is used for both Sync Streams and Sync Rules. +Your [Sync Streams](/sync/streams/overview) (or legacy [Sync Rules](/sync/rules/overview)) configuration can be in a separate file (recommended) or inline in the main config. The `sync_config:` key and its options work the same for Sync Streams and legacy Sync Rules. Path to the Sync Streams/Sync Rules YAML file. Ensure the file is available at that path, e.g. in the same directory as your main config or on a mounted volume. @@ -647,11 +647,11 @@ Your Sync Streams (or legacy Sync Rules) configuration can be in a separate file - **Separate file**: Referencing a file with `path:` keeps your main config tidy and makes editing Sync Streams easier. + Referencing a separate file with `path:` keeps your main config tidy and makes editing Sync Streams easier. -```yaml Sync Streams — Separate File (Recommended) +```yaml Separate File (Recommended) # sync-config.yaml (reference from main config with sync_config: path: sync-config.yaml) config: edition: 3 @@ -661,7 +661,7 @@ streams: query: SELECT * FROM todos WHERE owner_id = auth.user_id() ``` -```yaml Sync Streams — Inline +```yaml Inline sync_config: content: | config: @@ -671,42 +671,19 @@ sync_config: auto_subscribe: true query: SELECT * FROM todos WHERE owner_id = auth.user_id() ``` - -```yaml Sync Rules — Separate File (Legacy) -# sync-config.yaml (reference from main config with sync_config: path: sync-config.yaml) -bucket_definitions: - global: - data: - - SELECT * FROM lists - - SELECT * FROM todos -``` - -```yaml Sync Rules — Inline (Legacy) -sync_config: - content: | - bucket_definitions: - global: - data: - - SELECT * FROM lists - - SELECT * FROM todos -``` - - To verify that your Sync Streams are functioning correctly, inspect the contents of your bucket storage database. - - #### MongoDB Example - - If you are running MongoDB in Docker, run the following: + + To verify that your Sync Streams are functioning correctly, inspect the contents of your bucket storage database. For example, if you are running MongoDB in Docker, run the following: ```bash docker exec -it {MongoDB container name} mongosh "mongodb://{MongoDB service host}/{MongoDB database name}" --eval "db.bucket_data.find().pretty()" # Example docker exec -it self-host-demo-mongo-1 mongosh "mongodb://localhost:27017/powersync_demo" --eval "db.bucket_data.find().pretty()" ``` - + -### client_auth +### `client_auth` Authentication of client (application end user) connections is configured in the `client_auth` section. For more details, see [Client Authentication](/configuration/auth/overview). @@ -769,7 +746,7 @@ client_auth: For production environments, we recommend using JWKS with asymmetric keys (RS256, EdDSA, or ECDSA) rather than shared secrets (HS256). Asymmetric keys provide better security through public/private key separation and easier key rotation. See [Custom Authentication](/configuration/auth/custom) for more details. -### api +### `api` Access tokens for the service's admin API routes, provided by clients as a Bearer token. Authentication of these routes is disabled if no tokens are configured. @@ -799,7 +776,7 @@ client_auth: -### telemetry +### `telemetry` See [Usage Reporting](/maintenance-ops/self-hosting/usage-reporting) and [Monitoring](/maintenance-ops/self-hosting/monitoring) for details. @@ -815,7 +792,7 @@ See [Usage Reporting](/maintenance-ops/self-hosting/usage-reporting) and [Monito Endpoint that anonymized telemetry is reported to. You typically do not need to change this. -### healthcheck +### `healthcheck` Configures how health check status is exposed. See [Health Checks](/maintenance-ops/self-hosting/healthchecks) for details on the available probes and endpoints. @@ -834,13 +811,13 @@ Configures how health check status is exposed. See [Health Checks](/maintenance- -### migrations +### `migrations` When `true`, disables automatic storage database schema migrations on startup. Migrations can then be triggered externally by altering the container `command`. -### system +### `system` Service logging configuration. @@ -848,19 +825,19 @@ Configures how health check status is exposed. See [Health Checks](/maintenance- Log level for the service logs: `silly`, `debug`, `verbose`, `http`, `info`, `warn`, or `error`. The `PS_LOG_LEVEL` environment variable takes precedence over this option. - - Log output format: `json` or `text`. Defaults to `json` when the `NODE_ENV` environment variable is set to `production`. The `PS_LOG_FORMAT` environment variable takes precedence over this option. + + Log output format: `json` or `text`. Defaults to `text`, or to `json` when the `NODE_ENV` environment variable is set to `production`. The `PS_LOG_FORMAT` environment variable takes precedence over this option. -### metadata +### `metadata` Custom metadata key-value pairs (string values) for the service. -### parameters +### `parameters` Global parameters (number, string, boolean or null values) that can be referenced in the sync configuration. From 9fb0fc65b9e00df1fc7aa634774fc66044de613f Mon Sep 17 00:00:00 2001 From: Benita Volkmann Date: Thu, 20 Aug 2026 10:23:58 +0200 Subject: [PATCH 06/16] Skills update: capitalize Service --- .claude/CLAUDE.md | 3 +++ .claude/agents/document-reviewer.md | 5 +++-- .claude/skills/doc-author/SKILL.md | 1 + 3 files changed, 7 insertions(+), 2 deletions(-) diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 02ffdb95..18e3a91b 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -154,9 +154,12 @@ Always use the left column. Never use the right. | Postgres | PostgreSQL | | partial sync | dynamic partial replication | | PowerSync Service | powersync service | +| the Service (short for the PowerSync Service) | the service | | Sync Rules | sync rules | | Sync Streams | sync streams | +When referring to the PowerSync Service in shortened form, write "the Service" (capitalized), never "the service". Generic services (a Docker Compose service, a third-party service) stay lowercase. + ## Mintlify Components ### When to Use What diff --git a/.claude/agents/document-reviewer.md b/.claude/agents/document-reviewer.md index 53ad496c..abbf3cab 100644 --- a/.claude/agents/document-reviewer.md +++ b/.claude/agents/document-reviewer.md @@ -37,8 +37,9 @@ These require judgment. Each item maps to a section of CLAUDE.md; apply the full 8. **Code examples**: language tag on every block; realistic data; no real secrets; filenames only on self-hosted examples; no SQL table aliases unless required. 9. **Links and navigation**: internal links use relative paths, never absolute URLs; new pages appear in `docs.json` navigation; moved or removed pages have redirects. 10. **Sync Streams policy**: no new content that teaches or promotes Sync Rules; where both appear side by side, the examples must return the same data with matching filters. In prose, "(or legacy Sync Rules)" is the approved pairing but only once per page or major section; later mentions omit Sync Rules. -11. **Technical accuracy**: flag claims, APIs, or examples you cannot verify. -12. **Legal and compliance content**: contractual or commercial terms may deviate from standard terminology (for example, "Synchronization Service" in the HIPAA shared-responsibility table). Don't "fix" these; outside legal contexts, the standard terms apply. +11. **"the Service" shorthand**: shortened references to the PowerSync Service are capitalized ("the Service", never "the service"). Generic services (a Docker Compose service, a third-party service) stay lowercase. Vale cannot distinguish these; judge from context. +12. **Technical accuracy**: flag claims, APIs, or examples you cannot verify. +13. **Legal and compliance content**: contractual or commercial terms may deviate from standard terminology (for example, "Synchronization Service" in the HIPAA shared-responsibility table). Don't "fix" these; outside legal contexts, the standard terms apply. ## Output Format diff --git a/.claude/skills/doc-author/SKILL.md b/.claude/skills/doc-author/SKILL.md index 9dfd5e7b..2133c075 100644 --- a/.claude/skills/doc-author/SKILL.md +++ b/.claude/skills/doc-author/SKILL.md @@ -78,6 +78,7 @@ The `description` and opening paragraph must not duplicate each other — the op | Postgres | PostgreSQL | | partial sync | dynamic partial replication | | PowerSync Service | powersync service | +| the Service (short for the PowerSync Service) | the service | | Sync Rules | sync rules | | Sync Streams | sync streams | From b6b7849ed0133fbaf22ef5d6b9f93f28dd027b83 Mon Sep 17 00:00:00 2001 From: Benita Volkmann Date: Thu, 20 Aug 2026 10:24:22 +0200 Subject: [PATCH 07/16] Use shared snippet for CLI getting started instructions --- .../powersync-service/cloud-instances.mdx | 23 ++++--------------- intro/setup-guide.mdx | 19 +++------------ snippets/create-cloud-instance-cli.mdx | 17 ++++++++++++++ 3 files changed, 24 insertions(+), 35 deletions(-) create mode 100644 snippets/create-cloud-instance-cli.mdx diff --git a/configuration/powersync-service/cloud-instances.mdx b/configuration/powersync-service/cloud-instances.mdx index a7ab378d..2e3e8db1 100644 --- a/configuration/powersync-service/cloud-instances.mdx +++ b/configuration/powersync-service/cloud-instances.mdx @@ -5,8 +5,9 @@ description: "Create and configure PowerSync Cloud instances with a database con --- import CreateCloudInstance from '/snippets/create-cloud-instance.mdx'; +import CreateCloudInstanceCli from '/snippets/create-cloud-instance-cli.mdx'; -A PowerSync instance is a running deployment of the [PowerSync Service](/architecture/powersync-service): it replicates data from your source database and streams it to clients based on your [Sync Streams](/sync/streams/overview). On PowerSync Cloud, instances are hosted and managed for you, and you create and configure them in the [PowerSync Dashboard](https://dashboard.powersync.com/) or with the [PowerSync CLI](/tools/cli). +A PowerSync instance is a running deployment of the [PowerSync Service](/architecture/powersync-service): it replicates data from your source database and streams it to clients based on your [Sync Streams](/sync/streams/overview). On PowerSync Cloud, instances are hosted and managed for you, and you create and configure them in the [PowerSync Dashboard](https://dashboard.powersync.com) or with the [PowerSync CLI](/tools/cli). ## Create a PowerSync Instance @@ -16,23 +17,7 @@ A PowerSync instance is a running deployment of the [PowerSync Service](/archite - Install the [PowerSync CLI](/tools/cli) (requires Node.js/npm), then log in and scaffold the config directory: - - ```bash - npm install -g powersync - powersync login - powersync init cloud - ``` - - This creates a `powersync/` directory with `service.yaml` (instance name, region, connection, auth) and `sync-config.yaml` (sync config). Edit `powersync/service.yaml` to set your instance name and region. - - Then create the instance and link the directory to it: - - ```bash - powersync link cloud --create --project-id= - ``` - - Find your project ID in the [PowerSync Dashboard](https://dashboard.powersync.com/) URL, or run `powersync fetch instances` after logging in. + @@ -48,6 +33,6 @@ In the Dashboard, each of these has its own view in the instance's sidebar. With Other lower-level instance options, such as compacting buckets and deprovisioning, are available in the Dashboard under the instance's Settings view. The CLI has corresponding commands for most of these operations. -For more information see: +For more information, see: - [PowerSync Dashboard](/tools/powersync-dashboard) documentation - [PowerSync CLI](/tools/cli) documentation diff --git a/intro/setup-guide.mdx b/intro/setup-guide.mdx index 9967aaab..b01f1e7e 100644 --- a/intro/setup-guide.mdx +++ b/intro/setup-guide.mdx @@ -16,6 +16,7 @@ import SwiftInstallation from '/snippets/swift/installation.mdx'; import DotnetInstallation from '/snippets/dotnet/installation.mdx'; import RustInstallation from '/snippets/rust/installation.mdx'; import DevTokenSelfHostedSteps from '/snippets/dev-token-self-hosted-steps.mdx'; +import CreateCloudInstanceCli from '/snippets/create-cloud-instance-cli.mdx'; ## 1. Configure Your Source Database @@ -198,23 +199,9 @@ PowerSync is available as a cloud-hosted service (PowerSync Cloud) or can be sel If you haven't yet, sign up for a free PowerSync Cloud account [here](https://accounts.powersync.com/portal/powersync-signup?s=docs). - Install the [PowerSync CLI](/tools/cli) (requires Node.js/npm), then log in and scaffold the config directory: + - ```bash - npm install -g powersync - powersync login - powersync init cloud - ``` - - This creates a `powersync/` directory with `service.yaml` (instance name, region, connection, auth) and `sync-config.yaml` (sync config). Edit `powersync/service.yaml` to set your instance name and region. You'll configure the database connection in the next step. - - Then create the Cloud instance: - - ```bash - powersync link cloud --create --project-id= - ``` - - Find your project ID in the [PowerSync Dashboard](https://dashboard.powersync.com) URL, or run `powersync fetch instances` after logging in. + You'll configure the database connection in the next step. diff --git a/snippets/create-cloud-instance-cli.mdx b/snippets/create-cloud-instance-cli.mdx new file mode 100644 index 00000000..c00b418d --- /dev/null +++ b/snippets/create-cloud-instance-cli.mdx @@ -0,0 +1,17 @@ +Install the [PowerSync CLI](/tools/cli) (requires Node.js/npm), then log in and scaffold the config directory: + +```bash +npm install -g powersync +powersync login +powersync init cloud +``` + +This creates a `powersync/` directory with `service.yaml` (instance name, region, connection, auth) and `sync-config.yaml` (sync config). Edit `powersync/service.yaml` to set your instance name and region. + +Then create the instance and link the directory to it: + +```bash +powersync link cloud --create --project-id= +``` + +Find your project ID in the [PowerSync Dashboard](https://dashboard.powersync.com) URL, or run `powersync fetch instances` after logging in. From 4f854143045879792d7c114fb4b810e417a9aab0 Mon Sep 17 00:00:00 2001 From: Benita Volkmann Date: Thu, 20 Aug 2026 10:32:57 +0200 Subject: [PATCH 08/16] Polish after using the reviewer skill --- .../self-hosted-instances.mdx | 123 +++++++++--------- 1 file changed, 58 insertions(+), 65 deletions(-) diff --git a/configuration/powersync-service/self-hosted-instances.mdx b/configuration/powersync-service/self-hosted-instances.mdx index f3285e91..909a4b06 100644 --- a/configuration/powersync-service/self-hosted-instances.mdx +++ b/configuration/powersync-service/self-hosted-instances.mdx @@ -4,7 +4,7 @@ description: "How to configure a self-hosted PowerSync Service instance with a c sidebarTitle: "Self-Hosted Instances" --- -A PowerSync instance is a running deployment of the [PowerSync Service](/architecture/powersync-service): it replicates data from your source database and streams it to clients based on your [Sync Streams](/sync/streams/overview). When self-hosting, you run the service in your own infrastructure and configure each instance with a config file, as described below. +A PowerSync instance is a running deployment of the [PowerSync Service](/architecture/powersync-service): it replicates data from your source database and streams it to clients based on your [Sync Streams](/sync/streams/overview). When self-hosting, you run the Service in your own infrastructure and configure each instance with a config file, as described below. ## Configure Your Instance @@ -15,7 +15,7 @@ A self-hosted instance needs four things before clients can sync: 3. Client authentication. See [Authentication Setup](/configuration/auth/overview). When getting started, you can use temporary [development tokens](/configuration/auth/development-tokens) instead of setting up a full auth provider. 4. A sync configuration defining what data syncs to which clients, written as [Sync Streams](/sync/streams/overview). -You define all of these in the service config file, along with some operational settings. The sync configuration is usually kept in a separate file that the main config references (recommended), but can also be defined inline. The skeleton below shows the most common options; the [Configuration Reference](#configuration-reference) documents all of them. +You define all of these in the main config file, along with some operational settings. We recommend keeping the sync configuration in a separate file that the main config references, though it can also be defined inline. The skeleton below shows the most common options; the [Configuration Reference](#configuration-reference) documents all of them. ```yaml service.yaml # Settings for source database replication @@ -53,8 +53,7 @@ storage: # The port which the PowerSync API server will listen on (defaults to 8080) port: 8080 -# Specify Sync Streams or legacy Sync Rules (see the sync_config section below). -# Referencing a separate file is recommended so you can edit streams/rules without nesting YAML. +# Sync configuration (see the sync_config section below) sync_config: path: sync-config.yaml @@ -80,7 +79,7 @@ telemetry: system: # Service logging configuration logging: - # Log level for the service logs + # Log level for the Service logs level: info # 'silly', 'debug', 'verbose', 'http', 'info', 'warn', 'error' format: text # 'json' or 'text' ``` @@ -148,18 +147,17 @@ The config file supports the following top-level keys, documented in the section | [`migrations`](#migrations) | Storage database schema migration behavior | | [`system`](#system) | Service logging | | [`metadata`](#metadata) | Custom metadata key-value pairs | -| [`parameters`](#parameters) | Global parameters | ### `replication` -Specify the connection to your source database in `replication.connections`. Only one connection is currently supported; multiple connection support is on the roadmap. +The `replication` section defines the source database that PowerSync replicates data from. Specify the connection details in `replication.connections`. Only one connection is currently supported; multiple connection support is on our roadmap. For instructions on preparing your source database, see [Source Database Setup](/configuration/source-db/setup). - If you are using hosted Supabase, you will need to enable IPv6 for Docker as per [the Docker docs](https://docs.docker.com/config/daemon/ipv6/) + If you are using hosted Supabase, you will need to enable IPv6 for Docker as per [the Docker docs](https://docs.docker.com/config/daemon/ipv6/). - If your host OS does not support Docker IPv6 e.g. macOS, you will need to run Supabase locally. + If your host OS does not support Docker IPv6 (e.g. macOS), run Supabase locally instead. This is because Supabase only allows direct database connections over IPv6. PowerSync cannot connect using the connection pooler. @@ -179,7 +177,7 @@ All connection types support these common options: - When enabled, allows executing queries against this connection through the service's admin API (authenticated using [`api.tokens`](#api)). + When enabled, allows executing queries against this connection through the Service's admin API (authenticated using [`api.tokens`](#api)). @@ -386,6 +384,14 @@ The remaining options depend on the connection type: The database schema to replicate from. + + CA certificate content in PEM format. + + + + Use a servername for TLS that is different from `hostname`. + + Alternative authentication configuration, instead of `username` and `password`. @@ -570,7 +576,7 @@ storage: uri: postgresql://powersync_storage_user:secure_password@storage-db:5432/postgres ``` -Postgres storage accepts the same connection options as a [Postgres replication connection](#replication): `uri`, `hostname`, `port`, `username`, `password`, `database`, `sslmode`, `cacert`, `client_certificate`, `client_private_key` and `tls_servername`. In addition, batch limits can be tuned: +Postgres storage accepts the same connection options as a [Postgres replication connection](#replication): `uri`, `hostname`, `port`, `username`, `password`, `database`, `sslmode`, `cacert`, `client_certificate`, `client_private_key`, `tls_servername`, `slot_name_prefix` and `connect_timeout`. In addition, batch limits can be tuned: Limits for batch operations during replication. Increasing these limits can improve replication performance, at the cost of higher memory usage. @@ -622,37 +628,23 @@ Separate Postgres servers are required for replication connections (i.e. source ### `port` +The `port` setting determines where clients and tools connect to your instance. Change it if the default conflicts with another service in your deployment. + The port on which the PowerSync API server will listen for connections. Can be specified as a number or string. ### `sync_config` -Your [Sync Streams](/sync/streams/overview) (or legacy [Sync Rules](/sync/rules/overview)) configuration can be in a separate file (recommended) or inline in the main config. The `sync_config:` key and its options work the same for Sync Streams and legacy Sync Rules. - - - Path to the Sync Streams/Sync Rules YAML file. Ensure the file is available at that path, e.g. in the same directory as your main config or on a mounted volume. - - - - Inline Sync Streams/Sync Rules content as a string, as an alternative to `path`. - - - - Whether to exit the process if there is an error parsing the Sync Streams/Sync Rules configuration. - - - - The top-level `sync_rules` key is a deprecated alias for `sync_config`. Use `sync_config` in new configurations. - - - - Referencing a separate file with `path:` keeps your main config tidy and makes editing Sync Streams easier. - +The `sync_config` section points the Service at your [Sync Streams](/sync/streams/overview) (or legacy [Sync Rules](/sync/rules/overview)) definition, usually a separate file referenced with `path`: -```yaml Separate File (Recommended) -# sync-config.yaml (reference from main config with sync_config: path: sync-config.yaml) +```yaml service.yaml +sync_config: + path: sync-config.yaml +``` + +```yaml sync-config.yaml config: edition: 3 streams: @@ -660,32 +652,25 @@ streams: auto_subscribe: true query: SELECT * FROM todos WHERE owner_id = auth.user_id() ``` - -```yaml Inline -sync_config: - content: | - config: - edition: 3 - streams: - todos: - auto_subscribe: true - query: SELECT * FROM todos WHERE owner_id = auth.user_id() -``` - - To verify that your Sync Streams are functioning correctly, inspect the contents of your bucket storage database. For example, if you are running MongoDB in Docker, run the following: + + Path to the sync configuration YAML file. Ensure the file is available at that path, e.g. in the same directory as your main config or on a mounted volume. + - ```bash - docker exec -it {MongoDB container name} mongosh "mongodb://{MongoDB service host}/{MongoDB database name}" --eval "db.bucket_data.find().pretty()" - # Example - docker exec -it self-host-demo-mongo-1 mongosh "mongodb://localhost:27017/powersync_demo" --eval "db.bucket_data.find().pretty()" - ``` - + + The sync configuration inline as a string, as an alternative to `path`. + + + + Whether to exit the process if there is an error parsing the sync configuration. + + +The top-level `sync_rules` key is a deprecated alias for `sync_config`. Use `sync_config` in new configurations. ### `client_auth` -Authentication of client (application end user) connections is configured in the `client_auth` section. For more details, see [Client Authentication](/configuration/auth/overview). +The `client_auth` section defines how the Service verifies your app's users when they connect to sync. Clients authenticate with JWTs, which the Service validates using the settings here. For more details, see [Client Authentication](/configuration/auth/overview). ```yaml service.yaml client_auth: @@ -748,8 +733,10 @@ client_auth: ### `api` +The `api` section protects the Service's admin API routes with access tokens, and sets limits that protect the Service from excessive load. Configure `tokens` if you use the [PowerSync CLI](/tools/cli) against this instance; the limits rarely need changing. + - Access tokens for the service's admin API routes, provided by clients as a Bearer token. Authentication of these routes is disabled if no tokens are configured. + Access tokens for the Service's admin API routes, provided by clients as a Bearer token. Authentication of these routes is disabled if no tokens are configured. @@ -762,7 +749,7 @@ client_auth: Maximum concurrency when fetching data from storage. This should not be significantly more than `storage.max_pool_size`, otherwise it would block on the pool. Increasing this can significantly increase memory usage in some cases. - Maximum number of buckets for each connection. More buckets increase latency and memory usage. While the actual number is controlled by your sync configuration, this hard limit ensures that the service errors instead of crashing when the sync configuration is misconfigured. + Maximum number of buckets for each connection. More buckets increase latency and memory usage. While the actual number is controlled by your sync configuration, this hard limit ensures that the Service errors instead of crashing when the sync configuration is misconfigured. Related to `max_buckets_per_connection`, but this limit applies directly to parameter query results, before they are converted into a unique set of buckets. @@ -778,7 +765,7 @@ client_auth: ### `telemetry` -See [Usage Reporting](/maintenance-ops/self-hosting/usage-reporting) and [Monitoring](/maintenance-ops/self-hosting/monitoring) for details. +The `telemetry` section controls the operational metrics the Service shares with PowerSync and exposes for your own monitoring. See [Usage Reporting](/maintenance-ops/self-hosting/usage-reporting) and [Monitoring](/maintenance-ops/self-hosting/monitoring) for details. When `true`, disables sharing of anonymized usage metrics with the PowerSync telemetry service. @@ -797,7 +784,7 @@ See [Usage Reporting](/maintenance-ops/self-hosting/usage-reporting) and [Monito Configures how health check status is exposed. See [Health Checks](/maintenance-ops/self-hosting/healthchecks) for details on the available probes and endpoints. - Mechanisms for exposing health check data. If this is not configured, the service defaults to legacy behavior for backwards compatibility (filesystem probes always enabled, plus HTTP probes depending on the service mode). When `probes` is configured, each mechanism requires explicit opt-in. + Mechanisms for exposing health check data. If this is not configured, the Service defaults to legacy behavior for backwards compatibility (filesystem probes always enabled, plus HTTP probes depending on the Service mode). When `probes` is configured, each mechanism requires explicit opt-in. Enables exposing health check status via filesystem files. @@ -813,17 +800,21 @@ Configures how health check status is exposed. See [Health Checks](/maintenance- ### `migrations` +The `migrations` section controls whether the Service updates its bucket storage database schema automatically when a new version starts up. Most deployments can keep the default automatic behavior. + When `true`, disables automatic storage database schema migrations on startup. Migrations can then be triggered externally by altering the container `command`. ### `system` +The `system` section configures how the Service itself runs. Currently this covers logging. + Service logging configuration. - Log level for the service logs: `silly`, `debug`, `verbose`, `http`, `info`, `warn`, or `error`. The `PS_LOG_LEVEL` environment variable takes precedence over this option. + Log level for the Service logs: `silly`, `debug`, `verbose`, `http`, `info`, `warn`, or `error`. The `PS_LOG_LEVEL` environment variable takes precedence over this option. Log output format: `json` or `text`. Defaults to `text`, or to `json` when the `NODE_ENV` environment variable is set to `production`. The `PS_LOG_FORMAT` environment variable takes precedence over this option. @@ -833,12 +824,14 @@ Configures how health check status is exposed. See [Health Checks](/maintenance- ### `metadata` - - Custom metadata key-value pairs (string values) for the service. - +Use `metadata` to attach custom labels to an instance, for example to tell your staging and production deployments apart in error reports. -### `parameters` + + Custom key-value pairs (string values) that identify this instance. When error reporting to Sentry is enabled by setting the `SENTRY_DSN` environment variable, these pairs are attached as tags to reported errors. - - Global parameters (number, string, boolean or null values) that can be referenced in the sync configuration. + ```yaml service.yaml + metadata: + environment: staging + region: eu-west-1 + ``` From ccb2f057f8c3eeaac204f5449ab21f72d8647301 Mon Sep 17 00:00:00 2001 From: Benita Volkmann Date: Thu, 20 Aug 2026 10:44:28 +0200 Subject: [PATCH 09/16] Side quest: remove old version mentions --- client-sdks/full-text-search.mdx | 2 +- client-sdks/reference/flutter.mdx | 2 +- client-sdks/usage-examples.mdx | 13 ++++--------- .../powersync-service/self-hosted-instances.mdx | 2 +- debugging/troubleshooting.mdx | 2 +- 5 files changed, 8 insertions(+), 13 deletions(-) diff --git a/client-sdks/full-text-search.mdx b/client-sdks/full-text-search.mdx index e93a3e18..86f2dd67 100644 --- a/client-sdks/full-text-search.mdx +++ b/client-sdks/full-text-search.mdx @@ -10,7 +10,7 @@ PowerSync supports full-text search using the [SQLite FTS5 extension](https://ww Full-text search has been demonstrated in the following SDKs: - [**Dart/Flutter SDK**](/client-sdks/reference/flutter): Uses the [sqlite_async](https://pub.dev/documentation/sqlite_async/latest/) package for migrations -- [**JavaScript Web SDK**](/client-sdks/reference/javascript-web): Requires version 0.5.0 or greater (including [wa-sqlite](https://github.com/powersync-ja/wa-sqlite) 0.2.0+) +- [**JavaScript Web SDK**](/client-sdks/reference/javascript-web) - [**React Native SDK**](/client-sdks/reference/react-native-and-expo): Requires additional configuration to enable FTS5, see [the README](https://www.npmjs.com/package/@powersync/react-native). - [**Swift SDK**](/client-sdks/reference/swift) diff --git a/client-sdks/reference/flutter.mdx b/client-sdks/reference/flutter.mdx index 7b7b97cd..5e7275a6 100644 --- a/client-sdks/reference/flutter.mdx +++ b/client-sdks/reference/flutter.mdx @@ -351,7 +351,7 @@ class TodosWidget extends StatelessWidget { ## Configure Logging -Since version 1.1.2 of the SDK, logging is enabled by default and outputs logs from PowerSync to the console in debug mode. +Logging is enabled by default and outputs logs from PowerSync to the console in debug mode. To disable this, or to configure logging in release-mode configurations, use the `logger` parameter on the `PowerSyncDatabase` constructor. PowerSync uses [`package:logging`](https://pub.dev/packages/logging) to emit logs. See that package for additional information. diff --git a/client-sdks/usage-examples.mdx b/client-sdks/usage-examples.mdx index f512eafa..401e77ca 100644 --- a/client-sdks/usage-examples.mdx +++ b/client-sdks/usage-examples.mdx @@ -1001,7 +1001,7 @@ import JavaScriptCallbackWatch from '/snippets/basic-watch-query-javascript-call - Use the [hasSynced](https://pub.dev/documentation/powersync/latest/powersync/SyncStatus/hasSynced.html) property (available since version 1.5.1 of the SDK) and register a listener to indicate to the user whether the initial sync is in progress. + Use the [hasSynced](https://pub.dev/documentation/powersync/latest/powersync/SyncStatus/hasSynced.html) property and register a listener to indicate to the user whether the initial sync is in progress. ```dart // Example of using hasSynced to show whether the first sync has completed @@ -1043,7 +1043,7 @@ import JavaScriptCallbackWatch from '/snippets/basic-watch-query-javascript-call - Use the [hasSynced](https://powersync-ja.github.io/powersync-js/common/interfaces/SyncStatus#hassynced) property (available since version 1.4.1 of the SDK) and register an event listener with [PowerSyncDatabase.registerListener](https://powersync-ja.github.io/powersync-js/common/interfaces/CommonPowerSyncDatabase#registerlistener) to indicate to the user whether the initial sync is in progress. + Use the [hasSynced](https://powersync-ja.github.io/powersync-js/common/interfaces/SyncStatus#hassynced) property and register an event listener with [PowerSyncDatabase.registerListener](https://powersync-ja.github.io/powersync-js/common/interfaces/CommonPowerSyncDatabase#registerlistener) to indicate to the user whether the initial sync is in progress. ```js // Example of using hasSynced to show whether the first sync has completed @@ -1067,7 +1067,7 @@ import JavaScriptCallbackWatch from '/snippets/basic-watch-query-javascript-call - Use the [hasSynced](https://powersync-ja.github.io/powersync-js/common/interfaces/SyncStatus#hassynced) property (available since version 0.4.1 of the SDK) and register an event listener with [PowerSyncDatabase.registerListener](https://powersync-ja.github.io/powersync-js/common/interfaces/CommonPowerSyncDatabase#registerlistener) to indicate to the user whether the initial sync is in progress. + Use the [hasSynced](https://powersync-ja.github.io/powersync-js/common/interfaces/SyncStatus#hassynced) property and register an event listener with [PowerSyncDatabase.registerListener](https://powersync-ja.github.io/powersync-js/common/interfaces/CommonPowerSyncDatabase#registerlistener) to indicate to the user whether the initial sync is in progress. ```js // Example of using hasSynced to show whether the first sync has completed @@ -1155,7 +1155,7 @@ import JavaScriptCallbackWatch from '/snippets/basic-watch-query-javascript-call - Use the [HasSynced](https://powersync-ja.github.io/powersync-dotnet/api/PowerSync.Common.DB.Crud.SyncStatus.HasSynced.html) property (available since version 0.0.6-alpha.1 of the SDK) to indicate to the user whether the initial sync is in progress. + Use the [HasSynced](https://powersync-ja.github.io/powersync-dotnet/api/PowerSync.Common.DB.Crud.SyncStatus.HasSynced.html) property to indicate to the user whether the initial sync is in progress. ```cs using PowerSync.Common.Client; @@ -1174,7 +1174,6 @@ import JavaScriptCallbackWatch from '/snippets/basic-watch-query-javascript-call await db.WaitForFirstSync(); // Wait for a specific priority level to complete syncing - // The priority parameter is available since version 0.0.6-alpha.1 of the SDK var prioritySyncRequest = new PowerSyncDatabase.PrioritySyncRequest{ Priority = 1 }; await db.WaitForFirstSync(request: prioritySyncRequest); ``` @@ -1458,10 +1457,6 @@ import JavaScriptCallbackWatch from '/snippets/basic-watch-query-javascript-call You can show users a progress bar when data downloads using the `DownloadProgress()` method from the [SyncStatus](https://powersync-ja.github.io/powersync-dotnet/api/PowerSync.Common.DB.Crud.SyncStatus.html) class. `DownloadProgress().DownloadedFraction` gives you a value from 0.0 to 1.0 representing the total sync progress. This is especially useful for long-running initial syncs. - - **Version compatibility**: The `DownloadProgress()` method is available since version 0.0.6-alpha.1 of the SDK. The event listener uses `db.Events.OnStatusChanged.ListenAsync` (since v0.0.11-alpha.1). - - Example: ```cs diff --git a/configuration/powersync-service/self-hosted-instances.mdx b/configuration/powersync-service/self-hosted-instances.mdx index 909a4b06..6d44b7f6 100644 --- a/configuration/powersync-service/self-hosted-instances.mdx +++ b/configuration/powersync-service/self-hosted-instances.mdx @@ -568,7 +568,7 @@ If you are rolling your own Docker environment, you can include this init script #### Postgres Storage -Available since version 1.3.8 of the [`powersync-service`](https://hub.docker.com/r/journeyapps/powersync-service), you can use Postgres as an alternative bucket storage database. +You can use Postgres as an alternative bucket storage database. ```yaml service.yaml storage: diff --git a/debugging/troubleshooting.mdx b/debugging/troubleshooting.mdx index 64e0a660..b39dc0c0 100644 --- a/debugging/troubleshooting.mdx +++ b/debugging/troubleshooting.mdx @@ -316,7 +316,7 @@ Our client SDKs support logging to troubleshoot issues. Here's how to enable log * **JavaScript-based SDKs** (Web, React Native, and Node.js) - Implement the `PowerSyncLogger` interface, or use `createConsoleLogger()`. For example: `const logger = createConsoleLogger({ minLevel: LogLevels.debug })`. Pass the logger to `PowerSyncDatabase` via the `logger` option. For the Web SDK, you can also enable the `debugMode` flag to log SQL queries on Chrome's Performance timeline. -* **Dart/Flutter SDK** - Logging is enabled by default since version 1.1.2 and outputs logs to the console in debug mode. +* **Dart/Flutter SDK** - Logging is enabled by default and outputs logs to the console in debug mode. * **Kotlin SDK** - Uses [Kermit Logger](https://kermit.touchlab.co/docs/). By default shows `Warnings` in release and `Verbose` in debug mode. From 3b7cf45fe2eecaa3a858e896404fc01b53d41845 Mon Sep 17 00:00:00 2001 From: Benita Volkmann Date: Thu, 20 Aug 2026 11:19:05 +0200 Subject: [PATCH 10/16] Undocument some internal/deprecated options; add a couple missing ones --- .../self-hosted-instances.mdx | 25 +++++++------------ 1 file changed, 9 insertions(+), 16 deletions(-) diff --git a/configuration/powersync-service/self-hosted-instances.mdx b/configuration/powersync-service/self-hosted-instances.mdx index 6d44b7f6..c26ba867 100644 --- a/configuration/powersync-service/self-hosted-instances.mdx +++ b/configuration/powersync-service/self-hosted-instances.mdx @@ -176,10 +176,6 @@ All connection types support these common options: Additional meta tag for the connection, used for categorization or grouping. - - When enabled, allows executing queries against this connection through the Service's admin API (authenticated using [`api.tokens`](#api)). - - Block connections to any of these IP ranges. Include `local` to block anything not in public unicast ranges. @@ -252,6 +248,10 @@ The remaining options depend on the connection type: Connection timeout in seconds. Takes precedence over a `connect_timeout` query parameter in the URI. + + Idle timeout in seconds for snapshot connection sockets. If the storage database cannot keep up during the initial snapshot, a storage flush can stall the snapshot for longer than this timeout, which closes the source connection mid-snapshot. This appears in the Service logs as `Socket timed out` errors during the initial snapshot. Increase the timeout if you see these errors. + + Interval in seconds between source connection heartbeats. Must be between 5 and 60. @@ -473,6 +473,10 @@ The PowerSync Service requires a storage database to store the data and metadata Block connections to any of these IP ranges. Include `local` to block anything not in public unicast ranges. + + Storage version to use when deploying a sync configuration that does not specify a storage version. You typically do not need to change this. + + #### MongoDB Storage ```yaml service.yaml @@ -723,10 +727,6 @@ client_auth: IP ranges to reject when resolving JWKS URIs. Include `local` to block anything not in public unicast ranges. - - When `true`, blocks JWKS URIs that resolve to local network addresses. Use `jwks_reject_ip_ranges` instead. - - For production environments, we recommend using JWKS with asymmetric keys (RS256, EdDSA, or ECDSA) rather than shared secrets (HS256). Asymmetric keys provide better security through public/private key separation and easier key rotation. See [Custom Authentication](/configuration/auth/custom) for more details. @@ -736,7 +736,7 @@ client_auth: The `api` section protects the Service's admin API routes with access tokens, and sets limits that protect the Service from excessive load. Configure `tokens` if you use the [PowerSync CLI](/tools/cli) against this instance; the limits rarely need changing. - Access tokens for the Service's admin API routes, provided by clients as a Bearer token. Authentication of these routes is disabled if no tokens are configured. + Access tokens for the Service's admin API routes, provided by clients as a Bearer token. If no tokens are configured, the admin API routes reject all requests. @@ -775,10 +775,6 @@ The `telemetry` section controls the operational metrics the Service shares with Port on which Prometheus metrics will be exposed. When set, metrics will be available on this port for scraping. - - Endpoint that anonymized telemetry is reported to. You typically do not need to change this. - - ### `healthcheck` Configures how health check status is exposed. See [Health Checks](/maintenance-ops/self-hosting/healthchecks) for details on the available probes and endpoints. @@ -792,9 +788,6 @@ Configures how health check status is exposed. See [Health Checks](/maintenance- Enables exposing health check status via HTTP endpoints. - - Enables the legacy behavior described above. - From c9668234f3ea0c0653d9c7caa5f7110718cae718 Mon Sep 17 00:00:00 2001 From: Benita Volkmann Date: Thu, 20 Aug 2026 11:28:03 +0200 Subject: [PATCH 11/16] Move "supplementary" materials into corresponding sections --- .../self-hosted-instances.mdx | 18 ++++++------------ 1 file changed, 6 insertions(+), 12 deletions(-) diff --git a/configuration/powersync-service/self-hosted-instances.mdx b/configuration/powersync-service/self-hosted-instances.mdx index c26ba867..da0b622b 100644 --- a/configuration/powersync-service/self-hosted-instances.mdx +++ b/configuration/powersync-service/self-hosted-instances.mdx @@ -84,6 +84,10 @@ system: format: text # 'json' or 'text' ``` + + The config used by our `self-host-demo` app. Use the demo as a working reference for your own setup. + + ## Supplying the Config File Both YAML and JSON config files are supported. The PowerSync Service can read the config in three ways: @@ -110,17 +114,9 @@ resolves to `uri: mongodb://mongo:27017/powersync`. Only environment variables with names starting with `PS_` can be substituted. -### Supplementary Resources - -These external resources supplement the [Configuration Reference](#configuration-reference) below: - - - A working config example from the `self-host-demo` app, including environment variable substitution. - +## Configuration Reference - - A machine-readable schema of the config file, published as `@powersync/service-schema`. - +A machine-readable [JSON schema](https://unpkg.com/@powersync/service-schema@latest/json-schema/powersync-config.json) of the config file is available, published as `@powersync/service-schema`. Add this comment to the top of your YAML config file to get validation and autocomplete in editors that support the [YAML language server](https://github.com/redhat-developer/yaml-language-server) (for example VS Code with the YAML extension): @@ -130,8 +126,6 @@ These external resources supplement the [Configuration Reference](#configuration ``` -## Configuration Reference - The config file supports the following top-level keys, documented in the sections below: | Key | Purpose | From def7e6987af65f710a7a01cd8d535ee16c1ae43e Mon Sep 17 00:00:00 2001 From: Benita Volkmann Date: Thu, 20 Aug 2026 11:47:39 +0200 Subject: [PATCH 12/16] Add storage version cross ref --- configuration/powersync-service/self-hosted-instances.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/configuration/powersync-service/self-hosted-instances.mdx b/configuration/powersync-service/self-hosted-instances.mdx index da0b622b..aab3a12a 100644 --- a/configuration/powersync-service/self-hosted-instances.mdx +++ b/configuration/powersync-service/self-hosted-instances.mdx @@ -468,7 +468,7 @@ The PowerSync Service requires a storage database to store the data and metadata - Storage version to use when deploying a sync configuration that does not specify a storage version. You typically do not need to change this. + Storage version to use when deploying a sync configuration that does not specify a storage version. You typically do not need to change this. See [Storage Version](/sync/advanced/compatibility#storage-version) for the available versions and how they interact with the sync configuration's `storage_version` field. #### MongoDB Storage From ae78a0c67c36fd8134d2a5e787313e443e79e2fe Mon Sep 17 00:00:00 2001 From: Benita Volkmann Date: Thu, 20 Aug 2026 12:00:44 +0200 Subject: [PATCH 13/16] Refer to heartbeat_interval_seconds from error PSYNC_S1345 --- debugging/error-codes.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/debugging/error-codes.mdx b/debugging/error-codes.mdx index 982713e3..4bcf0ea1 100644 --- a/debugging/error-codes.mdx +++ b/debugging/error-codes.mdx @@ -228,6 +228,8 @@ This reference documents PowerSync error codes organized by component, with trou This may happen if there is a significant delay on the source database in reading the change stream. If this is not resolved after retries, replication may need to be restarted from scratch. + + To help avoid this error, the Service writes periodic heartbeats to the `_powersync_checkpoints` collection when the change stream has not advanced recently. For self-hosted instances, the heartbeat frequency can be tuned with the `heartbeat_interval_seconds` [connection option](/configuration/powersync-service/self-hosted-instances#replication). - **PSYNC_S1346**: Failed to read MongoDB Change Stream. From c0ba3fc06b5289db32cdbab349b68552ea1dd634 Mon Sep 17 00:00:00 2001 From: Benita Volkmann Date: Thu, 20 Aug 2026 12:02:31 +0200 Subject: [PATCH 14/16] Add Xata to Vale accept list --- .github/vale/config/vocabularies/PowerSync/accept.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/vale/config/vocabularies/PowerSync/accept.txt b/.github/vale/config/vocabularies/PowerSync/accept.txt index 459fea47..3b9a6aa7 100644 --- a/.github/vale/config/vocabularies/PowerSync/accept.txt +++ b/.github/vale/config/vocabularies/PowerSync/accept.txt @@ -314,6 +314,7 @@ WASQLite WinForms Windsurf WorkManager +Xata Xcode Yjs Zod From 5fa851d1b41386f79c2c2032aa1326bd50cd3a5e Mon Sep 17 00:00:00 2001 From: Benita Volkmann Date: Thu, 20 Aug 2026 12:05:05 +0200 Subject: [PATCH 15/16] Claude feedback --- configuration/powersync-service/self-hosted-instances.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/configuration/powersync-service/self-hosted-instances.mdx b/configuration/powersync-service/self-hosted-instances.mdx index aab3a12a..aa65012b 100644 --- a/configuration/powersync-service/self-hosted-instances.mdx +++ b/configuration/powersync-service/self-hosted-instances.mdx @@ -235,7 +235,7 @@ The remaining options depend on the connection type: - Maximum number of connections to the source database, per service process. + Maximum number of connections to the source database, per Service process. @@ -460,7 +460,7 @@ The PowerSync Service requires a storage database to store the data and metadata - Maximum number of connections to the storage database, per service process. + Maximum number of connections to the storage database, per Service process. @@ -734,7 +734,7 @@ The `api` section protects the Service's admin API routes with access tokens, an - Performance and safety parameters for the API service. + Performance and safety parameters for the API. Maximum number of connections (HTTP streams or WebSockets) per API process. From 2ba55ab1f5b44d492f3e3fc66ec3a9dffc824430 Mon Sep 17 00:00:00 2001 From: Benita Volkmann Date: Thu, 20 Aug 2026 13:25:52 +0200 Subject: [PATCH 16/16] Document MongoDB bucket storage required permissions --- .../self-hosted-instances.mdx | 28 ++++++++++++++++++- debugging/error-codes.mdx | 2 +- 2 files changed, 28 insertions(+), 2 deletions(-) diff --git a/configuration/powersync-service/self-hosted-instances.mdx b/configuration/powersync-service/self-hosted-instances.mdx index aa65012b..3ef33202 100644 --- a/configuration/powersync-service/self-hosted-instances.mdx +++ b/configuration/powersync-service/self-hosted-instances.mdx @@ -488,7 +488,7 @@ storage: - Database username. Defaults to the username in the URI. The user should have `readWrite` and `dbAdmin` roles. + Database username. Defaults to the username in the URI. See [Required Permissions](#required-permissions) for the roles the user needs. @@ -539,6 +539,32 @@ storage: +##### Required Permissions + +The Service creates and manages all collections and indexes in the storage database itself, so no manual schema setup is needed. When authentication is enabled, the user needs the built-in `readWrite` and `dbAdmin` roles on the storage database: + +``` +readWrite@ +dbAdmin@ +``` + +No access beyond the storage database is required. The `readWrite` role covers regular operation, including creating and dropping collections and indexes. The `dbAdmin` role is additionally required for collecting storage size metrics and for dropping the database when an instance is torn down. + +Create the user with: + +```javascript +use powersync_demo +db.createUser({ + user: "powersync_storage_user", + pwd: "secure_password", + roles: ["readWrite", "dbAdmin"] +}) +``` + +MongoDB authenticates against the database where the user was created, so creating the user in the storage database itself works with the connection URI shown above. If you create the user in a different database, such as `admin`, add `authSource=admin` to the connection URI. On MongoDB Atlas, assign the same two roles restricted to the storage database. + +##### Replica Set Requirement + MongoDB requires at least one replica set node. A single node is fine for development/staging environments, but a 3-node replica set is recommended [for production](/maintenance-ops/self-hosting/deployment-architecture) deployments. [MongoDB Atlas](https://www.mongodb.com/products/platform/atlas-database) enables replica sets by default for new clusters. diff --git a/debugging/error-codes.mdx b/debugging/error-codes.mdx index 4bcf0ea1..b8e2f855 100644 --- a/debugging/error-codes.mdx +++ b/debugging/error-codes.mdx @@ -192,7 +192,7 @@ This reference documents PowerSync error codes organized by component, with trou - **PSYNC_S1307**: MongoDB authorization error. - Check that the user has the required privileges. + Check that the user has the required privileges. See the required permissions for the [MongoDB source database](/configuration/source-db/setup#permissions-required-mongodb-atlas) or the [MongoDB storage database](/configuration/powersync-service/self-hosted-instances#required-permissions), depending on which connection reported the error. - **PSYNC_S1341**: Sharded MongoDB Clusters are not supported yet.