Self-Hosted Instance Configuration

Configuration Methods

The PowerSync Service is configured using key/value pairs in a config file, and supports the following configuration methods:

Inject config as an environment variable (which contains the Base64 encoding of a config file)
Use a config file mounted on a volume
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 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

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 for all available options.

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

      # 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 below:

Example service.yaml with detailed comments

A working config example from the self-host-demo app, including environment variable substitution.

Config file JSON schema

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 (for example VS Code with the YAML extension):

# 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`	Source database connection(s) to replicate from
`storage`	Bucket storage database connection
`port`	Port for the PowerSync API server
`sync_config`	Sync Streams (or legacy Sync Rules) definition
`client_auth`	JWT authentication for client connections
`api`	Admin API tokens and performance/safety limits
`telemetry`	Telemetry sharing and Prometheus metrics
`healthcheck`	Health check probe mechanisms
`migrations`	Storage database schema migration behavior
`system`	Service logging
`metadata`	Custom metadata key-value pairs
`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.

If you are using hosted Supabase, you will need to enable IPv6 for Docker as per the Docker docsIf 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:

string

required

The connection type. One of postgresql, mongodb, mysql, mssql, or convex.

string

default:"default"

Unique identifier for the connection. Optional when only a single connection is present.

string

default:"default"

Additional meta tag for the connection, used for categorization or grouping.

boolean

default:"false"

When enabled, allows executing queries against this connection through the service’s admin API (authenticated using api.tokens).

string[]

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:

Postgres connection options

service.yaml

replication:
  connections:
    - type: postgresql
      uri: postgresql://postgres:mypassword@pg-db:5432/postgres
      sslmode: verify-full

string

Connection URI in the format postgresql://user:password@hostname:5432/database. Individual connection parameters take precedence over values in the URI.

string

Database hostname. Required if not specified in uri.

number

default:"5432"

Database port.

string

Database username. Required if not specified in uri.

string

Database password. Required if not specified in uri.

string

Database name. Required if not specified in uri.

string

default:"verify-full"

SSL mode: verify-full, verify-ca, or disable. disable is only suitable for local/private networks, not for public networks.

string

CA certificate content in PEM format. Required for verify-ca, optional for verify-full.

string

Client certificate content in PEM format, for TLS client authentication.

string

Client private key content in PEM format, for TLS client authentication.

string

Use a servername for TLS that is different from hostname.

string

default:"powersync_"

Prefix for Postgres logical replication slot names and replication stream names.

number

default:"8"

Maximum number of connections to the source database, per service process.

number

Connection timeout in seconds. Takes precedence over a connect_timeout query parameter in the URI.

number

default:"60"

Interval in seconds between source connection heartbeats. Must be between 5 and 60.

MongoDB connection options

service.yaml

replication:
  connections:
    - type: mongodb
      uri: mongodb+srv://myuser:mypassword@cluster0.abcde.mongodb.net/mydatabase
      post_images: auto_configure

string

required

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.

string

Database name. Defaults to the database in the URI path.

string

Database username. Defaults to the username in the URI.

string

Database password. Defaults to the password in the URI.

string

default:"off"

Controls how change stream post-images are used: off, auto_configure, or read_only. auto_configure is recommended for new instances. See Post Images for details on each option.

number

default:"60"

Interval in seconds between source connection heartbeats. Must be between 5 and 60.

MySQL connection options

MySQL support is currently in a Beta release.

service.yaml

replication:
  connections:
    - type: mysql
      uri: mysql://repl_user:mypassword@mysql-db:3306/inventory

string

Connection URI in the format mysql://user:password@hostname:3306/database. Individual connection parameters take precedence over values in the URI.

string

Database hostname. Required if not specified in uri.

number

default:"3306"

Database port.

string

Database username. Required if not specified in uri.

string

Database password. Required if not specified in uri.

string

Database name. Required if not specified in uri.

number

default:"1"

Server ID used when connecting as a replication client.

string

CA certificate content in PEM format.

string

Client certificate content in PEM format, for TLS client authentication.

string

Client private key content in PEM format, for TLS client authentication.

number

default:"50"

The combined size in MB of binlog events that can be queued in memory before throttling is applied.

SQL Server connection options

SQL Server support is currently in a Beta release. Also see SQL Server Additional Configuration.

service.yaml

replication:
  connections:
    - type: mssql
      uri: mssql://powersync_user:mypassword@mssql-db:1433/inventory

string

Connection URI in the format mssql://user:password@hostname:1433/database. Individual connection parameters take precedence over values in the URI.

string

Database hostname. Required if not specified in uri.

number

default:"1433"

Database port.

string

Database username. Required if not specified in uri or authentication.

string

Database password. Required if not specified in uri or authentication.

string

Database name. Required if not specified in uri.

string

The database schema to replicate from.

object

Alternative authentication configuration, instead of username and password.

Show properties

string

required

Authentication method: default (SQL Server login) or azure-active-directory-service-principal-secret.

object

required

For default: userName and password. For azure-active-directory-service-principal-secret: clientId, clientSecret and tenantId from your registered Azure application.

object

Additional replication settings.

Show properties

number

default:"1000"

Interval in milliseconds to wait between CDC polling cycles.

number

default:"10"

Maximum number of transactions to poll per polling cycle.

boolean

default:"false"

Whether to trust the server certificate. Set to true for local development and self-signed certificates.

number

default:"60"

Interval in seconds between source connection heartbeats. Must be between 5 and 60.

Convex connection options

The Convex replicator is currently released as an experimental feature. See Convex source database setup.

service.yaml

replication:
  connections:
    - type: convex
      deployment_url: https://happy-animal-123.convex.cloud
      deploy_key: !env PS_CONVEX_DEPLOY_KEY

string

required

The URL of your Convex deployment.

string

required

A deploy key for the Convex deployment, used to authenticate against the Convex Streaming Export API.

number

default:"1000"

Interval in milliseconds between polling for new changes.

number

default:"60000"

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. You can use either MongoDB or Postgres for this purpose.

The bucket storage database is separate from your source database.

string

required

The storage backend type: mongodb or postgresql.

number

default:"8"

Maximum number of connections to the storage database, per service process.

string[]

Block connections to any of these IP ranges. Include local to block anything not in public unicast ranges.

MongoDB Storage

service.yaml

storage:
  type: mongodb
  uri: mongodb://mongo:27017/powersync_demo

string

required

string

Database name. Defaults to the database in the URI path.

string

Database username. Defaults to the username in the URI. The user should have readWrite and dbAdmin roles.

string

Database password. Defaults to the password in the URI.

number

default:"0.2"

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.

string

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.

object

Experimental support for storing large bucket data chunks in S3-compatible object storage instead of MongoDB.

Show properties

string

required

Must be s3.

string

required

Name of the S3 bucket.

string

Region of the S3 bucket.

string

Key prefix for stored objects.

string

Custom endpoint, for S3-compatible object storage providers.

boolean

Use path-style addressing, required by some S3-compatible providers.

string

Access key ID for authentication.

string

Secret access key for authentication.

number

Maximum number of concurrent object storage requests.

number

default:"1024"

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 deployments. MongoDB Atlas enables replica sets by default for new clusters. However, if you’re using your own environment you can enable this manually by running:

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:

  # 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, you can use Postgres as an alternative bucket storage database.

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: uri, hostname, port, username, password, database, sslmode, cacert, client_certificate, client_private_key and tls_servername. In addition, batch limits can be tuned:

object

Limits for batch operations during replication. Increasing these limits can improve replication performance, at the cost of higher memory usage.

Show properties

number

default:"5000000"

Maximum estimated byte size of operations written in a single transaction.

number

default:"2000"

Maximum number of records written in a single transaction.

number

default:"50000000"

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:

Let PowerSync create the schema (recommended):

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;

Or manually create the schema:

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.

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

number

default:"8080"

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

string

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.

string

Inline Sync Streams/Sync Rules content as a string, as an alternative to path.

boolean

default:"true"

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.

# 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()

sync_config:
  content: |
    config:
      edition: 3
    streams:
      todos:
        auto_subscribe: true
        query: SELECT * FROM todos WHERE owner_id = auth.user_id()

# sync-config.yaml (reference from main config with sync_config: path: sync-config.yaml)
bucket_definitions:
  global:
    data:
      - SELECT * FROM lists
      - SELECT * FROM todos

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:

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.

service.yaml

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']

string | string[]

URI or array of URIs pointing to JWKS endpoints, used to fetch public keys for JWT verification.

object

Inline JWKS configuration, as an alternative or in addition to jwks_uri.

Show properties

object[]

required

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 for details.

boolean

default:"false"

Enables Supabase authentication integration. JWKS details are derived from the Supabase connection. See Supabase Auth.

string

Legacy JWT secret for Supabase authentication (HS256 shared secret).

string[]

Valid audiences for JWT validation.

string[]

IP ranges to reject when resolving JWKS URIs. Include local to block anything not in public unicast ranges.

boolean

deprecated

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 for more details.

api

string[]

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.

object

Performance and safety parameters for the API service.

Show properties

number

default:"200"

Maximum number of connections (HTTP streams or WebSockets) per API process.

number

default:"10"

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.

number

default:"1000"

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.

number

default:"1000"

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

default:"60"

Number of minutes to keep client-requested write checkpoint records. Expired records are removed by the compact job. Must be a positive integer.

number

default:"60"

How long to keep cached bucket counts before refreshing them, in minutes. Bucket counts may be affected by compacting.

telemetry

See Usage Reporting and Monitoring for details.

When true, disables sharing of anonymized usage metrics with the PowerSync telemetry service.

number

Port on which Prometheus metrics will be exposed. When set, metrics will be available on this port for scraping.

string

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 for details on the available probes and endpoints.

object

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.

Show properties

boolean

default:"false"

Enables exposing health check status via filesystem files.

boolean

default:"false"

Enables exposing health check status via HTTP endpoints.

boolean

default:"false"

deprecated

Enables the legacy behavior described above.

migrations

boolean

default:"false"

When true, disables automatic storage database schema migrations on startup. Migrations can then be triggered externally by altering the container command.

system

object

Service logging configuration.

Show properties

string

default:"info"

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.

string

default:"text"

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

object

Custom metadata key-value pairs (string values) for the service.

parameters

object

Global parameters (number, string, boolean or null values) that can be referenced in the sync configuration.

Get Started

Configuration Details

Sync Streams & Rules

Client SDKs

Handling Writes

Maintenance & Ops

Integrations

Tools

Resources

Self-Hosted Instance Configuration

Configuration Methods

Environment Variable Substitution

Configuration File Structure

Supplementary Resources

Example service.yaml with detailed comments

Config file JSON schema

Configuration Reference

replication

storage

MongoDB Storage

Postgres Storage

Database Setup

Postgres Version Requirements

port

sync_config

MongoDB Example

client_auth

api

telemetry

healthcheck

migrations

system

metadata

parameters

​Configuration Methods

​Environment Variable Substitution

​Configuration File Structure

​Supplementary Resources

Example service.yaml with detailed comments

Config file JSON schema

​Configuration Reference

​replication

​storage

​MongoDB Storage

​Postgres Storage

Database Setup

Postgres Version Requirements

​port

​sync_config

​MongoDB Example

​client_auth

​api

​telemetry

​healthcheck

​migrations

​system

​metadata

​parameters

Configuration Methods

Environment Variable Substitution

Configuration File Structure

Supplementary Resources

Configuration Reference

replication

storage

MongoDB Storage

Postgres Storage

port

sync_config

MongoDB Example

client_auth

api

telemetry

healthcheck

migrations

system

metadata

parameters