> ## Documentation Index
> Fetch the complete documentation index at: https://powersync-attachment-transport.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Self-Hosted Instance Configuration
> Configuration methods, file structure, and a reference of all available config file options for self-hosted PowerSync Service deployments.
## Configuration Methods
The PowerSync Service is configured using key/value pairs in a config file, and supports the following configuration methods:
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)
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 theme={null}
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.
```yaml service.yaml theme={null}
# 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
# The connection URI or individual parameters can be specified.
uri: postgresql://postgres:mypassword@pg-db:5432/postgres
# 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
# 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 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_config:
path: sync-config.yaml
# Settings for client authentication
client_auth:
# Enable this if using Supabase Auth
# supabase: true
# supabase_jwt_secret: your-secret
# JWKS URIs can be specified here.
jwks_uri: http://demo-backend:6060/api/auth/keys
# 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
# System-level configuration options
system:
# Service logging configuration
logging:
# Log level for the service logs
level: info # 'silly', 'debug', 'verbose', 'http', 'info', 'warn', 'error'
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 theme={null}
# 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:
| 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 |
### replication
Specify the connection to your source database in `replication.connections`. Only one connection is currently supported; multiple connection support is on the 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 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.
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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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.
Block connections to any of these IP ranges. Include `local` to block anything not in public unicast ranges.
#### MongoDB Storage
```yaml service.yaml theme={null}
storage:
type: mongodb
uri: mongodb://mongo:27017/powersync_demo
```
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.
[MongoDB Atlas](https://www.mongodb.com/products/platform/atlas-database) enables replica sets by default for new clusters.
However, if you're using your own environment you can enable this manually by running:
```bash theme={null}
mongosh "mongodb+srv://powersync.abcdef.mongodb.net/" --apiVersion 1 --username myuser --eval 'try{rs.status().ok && quit(0)} catch {} rs.initiate({_id: "rs0", version: 1, members: [{ _id: 0, host : "mongo:27017" }]})'
```
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 theme={null}
# Initializes the MongoDB replica set. This service will not usually be actively running
mongo-rs-init:
image: mongo:7.0
depends_on:
- mongo
restart: "no"
entrypoint:
- bash
- -c
- '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
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.
```yaml service.yaml theme={null}
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:
1. Let PowerSync create the schema (recommended):
```sql theme={null}
CREATE USER powersync_storage_user WITH PASSWORD 'secure_password';
-- The user should only have access to the schema it created
GRANT CREATE ON DATABASE postgres TO powersync_storage_user;
```
2. Or manually create the schema:
```sql theme={null}
CREATE USER powersync_storage_user WITH PASSWORD 'secure_password';
CREATE SCHEMA IF NOT EXISTS powersync AUTHORIZATION powersync_storage_user;
GRANT CONNECT ON DATABASE postgres TO powersync_storage_user;
GRANT USAGE ON SCHEMA powersync TO powersync_storage_user;
GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA powersync TO powersync_storage_user;
```
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
Separate Postgres servers are required for replication connections (i.e. source database) and bucket storage **if using Postgres versions below 14**.
| Postgres Version | Server configuration |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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
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.
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 easier.
```yaml Sync Streams — Separate File (Recommended) theme={null}
# sync-config.yaml (reference from main config with sync_config: path: sync-config.yaml)
config:
edition: 3
streams:
todos:
auto_subscribe: true
query: SELECT * FROM todos WHERE owner_id = auth.user_id()
```
```yaml Sync Streams — Inline theme={null}
sync_config:
content: |
config:
edition: 3
streams:
todos:
auto_subscribe: true
query: SELECT * FROM todos WHERE owner_id = auth.user_id()
```
```yaml Sync Rules — Separate File (Legacy) theme={null}
# 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) theme={null}
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:
```bash theme={null}
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
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 theme={null}
client_auth:
# Enable this if using Supabase Auth
# supabase: true
# supabase_jwt_secret: your-secret
# Option 1: JWKS URI endpoint
jwks_uri: http://demo-backend:6060/api/auth/keys
# Option 2: Static collection of public keys for JWT verification
# jwks:
# keys:
# - kty: 'RSA'
# n: '[rsa-modulus]'
# e: '[rsa-exponent]'
# alg: 'RS256'
# kid: '[key-id]'
# JWKS audience
audience: ['powersync-dev', 'powersync']
```
URI or array of URIs pointing to JWKS endpoints, used to fetch public keys for JWT verification.
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.
Enables Supabase authentication integration. JWKS details are derived from the Supabase connection. See [Supabase Auth](/configuration/auth/supabase-auth).
Legacy JWT secret for Supabase authentication (HS256 shared secret).
Valid audiences for JWT validation.
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.
### 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.