From c0e069f795e3ca85c4160bb1a2291fabb05a59dc Mon Sep 17 00:00:00 2001 From: Benita Volkmann Date: Wed, 25 Feb 2026 17:38:43 +0200 Subject: [PATCH] Polish the yaml templates --- cli/templates/cloud/powersync/service.yaml | 97 ++++------- .../self-hosted/base/powersync/service.yaml | 164 ++++++++---------- 2 files changed, 104 insertions(+), 157 deletions(-) diff --git a/cli/templates/cloud/powersync/service.yaml b/cli/templates/cloud/powersync/service.yaml index 9453277..8f64871 100644 --- a/cli/templates/cloud/powersync/service.yaml +++ b/cli/templates/cloud/powersync/service.yaml @@ -7,7 +7,7 @@ # ----------------------------------------------------------------------------- _type: cloud -name: My instance +name: my-cli-instance # region (required): deployment region, e.g. us # Note: This cannot be changed after the initial deployment @@ -26,124 +26,104 @@ region: us # replication: # connections: # - type: postgresql +# # Connection string (recommended). Omit and use hostname/port/database/username/password instead if you prefer. # # [optional] -# uri: string +# uri: postgresql://user:pass@host:5432/dbname # password: # secret: !env POWERSYNC_DATABASE_PASSWORD -# # [optional] +# # [optional] Alternative to uri: individual connection parameters. # hostname: example.com -# # [optional] +# port: 5432 # database: one -# # [optional] # username: postgres -# # [optional] -# port: 5432 -# # [optional] +# # [optional] Connection identifiers. # name: string -# # [optional] # id: string -# # [optional] # tag: string -# # [optional] Options: verify-full | verify-ca +# # [optional] TLS mode. Options: verify-full | verify-ca. Default: verify-full. Use verify-full for production. # sslmode: verify-full -# # [optional] +# # [optional] TLS certificates (PEM). Required for verify-ca; optional for verify-full. # cacert: string -# # [optional] # client_certificate: string -# # [optional] # client_private_key: # secret: !env POWERSYNC_DATABASE_CLIENT_KEY -# # [optional] +# # [optional] Cloud VPC endpoint hostname. # vpc_endpoint_hostname: string # ------------------------------------------------------------------------- -# MongoDB – uncomment this entire block to use (comment out PostgreSQL above) +# MongoDB – uncomment this entire block to use (comment out PostgreSQL above). # uri is required for MongoDB; other fields are optional. # ------------------------------------------------------------------------- # replication: # connections: # - type: mongodb +# # Connection string (required for MongoDB). # uri: mongodb+srv://user:pass@host/db # password: # secret: !env POWERSYNC_MONGODB_PASSWORD -# # [optional] +# # [optional] Connection parameters (if not in URI). +# username: string +# database: string +# # [optional] Connection identifiers. # name: string -# # [optional] # id: string -# # [optional] # tag: string -# # [optional] -# username: string -# # [optional] -# database: string -# # [optional] Options: off | auto_configure | read_only +# # [optional] Change-data-capture mode. Options: off | auto_configure | read_only. Default: off. # post_images: off -# # [optional] +# # [optional] Cloud VPC endpoint hostname. # vpc_endpoint_hostname: string # ------------------------------------------------------------------------- -# MySQL – uncomment this entire block to use (comment out PostgreSQL above) +# MySQL – uncomment this entire block to use (comment out PostgreSQL above). # ------------------------------------------------------------------------- # replication: # connections: # - type: mysql -# # [optional] +# # [optional] Connection string. Omit and use hostname/port/database/username/password instead if you prefer. # uri: string # password: # secret: !env POWERSYNC_MYSQL_PASSWORD -# # [optional] +# # [optional] Alternative to uri: individual connection parameters. # hostname: db.example.com -# # [optional] # port: 3306 -# # [optional] # database: mydb -# # [optional] # username: sync -# # [optional] +# # [optional] Connection identifiers. # name: string -# # [optional] # id: string -# # [optional] # tag: string -# # [optional] +# # [optional] TLS client certificate and key (PEM). # client_certificate: string -# # [optional] # client_private_key: # secret: !env POWERSYNC_MYSQL_CLIENT_KEY # ------------------------------------------------------------------------- -# MSSQL – uncomment this entire block to use (comment out PostgreSQL above) +# MSSQL – uncomment this entire block to use (comment out PostgreSQL above). # ------------------------------------------------------------------------- # replication: # connections: # - type: mssql -# # [optional] +# # [optional] Connection string. Omit and use hostname/port/database/schema/username/password instead if you prefer. # uri: string # password: # secret: !env POWERSYNC_MSSQL_PASSWORD -# # [optional] +# # [optional] Alternative to uri: individual connection parameters. # hostname: sql.example.com -# # [optional] # port: 1433 -# # [optional] # database: mydb -# # [optional] # schema: dbo -# # [optional] # username: sync -# # [optional] +# # [optional] Connection identifiers. # name: string -# # [optional] # id: string -# # [optional] # tag: string -# # [optional] Options: default | azure-active-directory-password | azure-active-directory-service-principal-secret +# # [optional] Auth type. Options: default | azure-active-directory-password | azure-active-directory-service-principal-secret. # authentication: # type: default # options: # password: # secret: !env POWERSYNC_MSSQL_PASSWORD -# # [optional] +# # [optional] Polling and TLS options. # additionalConfig: # pollingIntervalMs: 5000 # pollingBatchSize: 1000 @@ -153,23 +133,14 @@ region: us # CLIENT AUTH (optional) – uncomment this entire block to enable # ----------------------------------------------------------------------------- # client_auth: - -# # [optional] PowerSync will use the same JWT secret as Supabase. +# # [optional] Use the same JWT secret as Supabase. Default: false. # supabase: false - -# # [optional] Legacy: If your Supabase project does not use the new JWT signing keys, you must provide your project's legacy JWT secret to use Supabase Auth. Get it from your project's API settings in the Supabase Dashboard. +# # [optional] Legacy: provide your Supabase project's legacy JWT secret from API settings in the Supabase Dashboard if not using new JWT signing keys. # supabase_jwt_secret: # secret: !env POWERSYNC_SUPABASE_JWT_SECRET - -# # [optional] Additional audiences to accept when validating incoming JWT tokens (the instance domain is always accepted) -# additional_audiences: [] - -# # [optional] Enables development tokens to be generated and accepted by the instance -# allow_temporary_tokens: false - -# # [optional] URL to a JSON Web Key Set (JWKS) endpoint; the instance fetches public keys from this URL to verify JWT signatures from clients. +# # [optional] JWKS URL; instance fetches public keys to verify JWT signatures. # jwks_uri: https://example.com/jwks.json -# # [optional] Inline JSON Web Key Set; provide keys directly instead of (or in addition to) jwks_uri to verify JWT signatures. +# # [optional] Inline JWKS; provide keys directly instead of or in addition to jwks_uri. # jwks: # keys: # HMAC (symmetric) – Options: HS256 | HS384 | HS512 @@ -197,3 +168,7 @@ region: us # crv: Ed25519 # x: "" # alg: EdDSA +# # [optional] Additional audiences to accept (instance domain is always accepted). Default: []. +# additional_audiences: [] +# # [optional] Allow development/temporary tokens. Default: false. +# allow_temporary_tokens: false diff --git a/cli/templates/self-hosted/base/powersync/service.yaml b/cli/templates/self-hosted/base/powersync/service.yaml index 673e6fb..fc2bc59 100644 --- a/cli/templates/self-hosted/base/powersync/service.yaml +++ b/cli/templates/self-hosted/base/powersync/service.yaml @@ -9,9 +9,9 @@ _type: self-hosted # ----------------------------------------------------------------------------- # See https://docs.powersync.com/self-hosting/telemetry telemetry: - # When true, disables sharing of anonymized telemetry data + # When true, disables sharing of anonymized telemetry data. Default: false. disable_telemetry_sharing: false -# # [optional] Port on which Prometheus metrics will be exposed. When set, metrics will be available on this port for scraping. +# # [optional] Port for Prometheus metrics; when set, metrics are exposed for scraping. # prometheus_port: 9090 # ----------------------------------------------------------------------------- @@ -26,145 +26,122 @@ replication: # ------------------------------------------------------------------------- # connections: # - type: postgresql +# # Connection string (recommended). Omit and use hostname/port/database/username/password instead if you prefer. # # [optional] # uri: !env PS_DATA_SOURCE_URI # password: !env PS_DATABASE_PASSWORD -# # [optional] -# id: string -# # [optional] -# tag: string -# # [optional] +# # [optional] Alternative to uri: individual connection parameters. # hostname: string -# # [optional] -# port: number | string -# # [optional] -# username: string -# # [optional] +# port: 5432 # database: string -# # [optional] Options: verify-full | verify-ca | disable +# username: string +# # [optional] Connection identifiers. +# id: string +# tag: string +# # [optional] TLS mode. Options: verify-full | verify-ca | disable. Default: verify-full for production; disable is for local/private networks only. # sslmode: disable -# # [optional] +# # [optional] TLS certificates (PEM). Required for verify-ca; optional for verify-full. # cacert: string -# # [optional] # client_certificate: string -# # [optional] # client_private_key: string -# # [optional] +# # [optional] TLS SNI when connecting. # tls_servername: string -# # [optional] +# # [optional] IP ranges to reject for this connection. # reject_ip_ranges: [ string ] -# # [optional] +# # [optional] Replication slot name prefix. # slot_name_prefix: string -# # [optional] +# # [optional] Maximum connection pool size. # max_pool_size: number # ------------------------------------------------------------------------- -# MongoDB – uncomment this entire block to use (comment out PostgreSQL above) +# MongoDB – uncomment this entire block to use (comment out PostgreSQL above). # uri is required for MongoDB; other fields are optional. # ------------------------------------------------------------------------- # connections: # - type: mongodb +# # Connection string (required for MongoDB). # uri: !env PS_MONGODB_URI # password: !env PS_MONGODB_PASSWORD -# # [optional] -# database: string -# # [optional] +# # [optional] Connection parameters (if not in URI). # username: string -# # [optional] +# database: string +# # [optional] Connection identifiers. # id: string -# # [optional] # tag: string -# # [optional] +# # [optional] IP ranges to reject for this connection. # reject_ip_ranges: [] -# # [optional] Options: off | auto_configure | read_only +# # [optional] Change-data-capture mode. Options: off | auto_configure | read_only. Default: off. # post_images: off # ------------------------------------------------------------------------- -# MySQL – uncomment this entire block to use (comment out PostgreSQL above) +# MySQL – uncomment this entire block to use (comment out PostgreSQL above). # ------------------------------------------------------------------------- # connections: # - type: mysql -# # [optional] +# # [optional] Connection string. Omit and use hostname/port/database/username/password instead if you prefer. # uri: !env PS_MYSQL_URI # password: !env PS_MYSQL_PASSWORD -# # [optional] +# # [optional] Alternative to uri: individual connection parameters. # hostname: db.example.com -# # [optional] # port: 3306 -# # [optional] # database: mydb -# # [optional] # username: sync -# # [optional] +# # [optional] Connection identifiers. # id: string -# # [optional] # tag: string -# # [optional] +# # [optional] MySQL server ID for replication. # server_id: number -# # [optional] +# # [optional] TLS: CA cert and client cert/key (PEM). # cacert: string -# # [optional] # client_certificate: string -# # [optional] # client_private_key: string -# # [optional] +# # [optional] IP ranges to reject for this connection. # reject_ip_ranges: [] -# # [optional] +# # [optional] Binlog queue memory limit. # binlog_queue_memory_limit: number # ----------------------------------------------------------------------------- -# STORAGE – configuration for the storage backend (sync bucket storage). Required for self-hosted. +# MongoDB storage – configuration for the storage backend (sync bucket storage). Also see PostgreSQL storage below. # ----------------------------------------------------------------------------- # storage: # type: mongodb +# # Connection string (required for MongoDB storage). # uri: !env PS_MONGO_URI -# # [optional] database +# # [optional] Connection parameters (if not in URI). # database: string -# # [optional] username # username: string -# # [optional] password # password: !env PS_MONGO_PASSWORD -# # [optional] reject_ip_ranges +# # [optional] IP ranges to reject for this connection. # reject_ip_ranges: [] # ----------------------------------------------------------------------------- -# PostgreSQL storage – uncomment this block and comment out the MongoDB storage block above to use PostgreSQL +# PostgreSQL storage – uncomment this block and comment out the MongoDB storage block above to use PostgreSQL. # ----------------------------------------------------------------------------- # storage: # type: postgresql -# # [optional] uri +# # [optional] Connection string. Omit and use hostname/port/database/username/password instead if you prefer. # uri: !env PS_STORAGE_URI -# # [optional] id -# id: string -# # [optional] tag -# tag: string -# # [optional] hostname +# # [optional] Alternative to uri: individual connection parameters. # hostname: string -# # [optional] port # port: 5432 -# # [optional] username # username: string -# # [optional] password # password: !env PS_STORAGE_PASSWORD -# # [optional] database # database: string -# # [optional] Options: verify-full | verify-ca | disable +# # [optional] Connection identifiers. +# id: string +# tag: string +# # [optional] TLS mode. Options: verify-full | verify-ca | disable. Default: verify-full for production. # sslmode: verify-full -# # [optional] cacert +# # [optional] TLS certificates (PEM). # cacert: string -# # [optional] client_certificate # client_certificate: string -# # [optional] client_private_key # client_private_key: string -# # [optional] tls_servername +# # [optional] TLS SNI, IP rejection, slot prefix, pool size. # tls_servername: string -# # [optional] reject_ip_ranges # reject_ip_ranges: [] -# # [optional] slot_name_prefix # slot_name_prefix: string -# # [optional] max_pool_size # max_pool_size: 8 -# # [optional] batch_limits +# # [optional] Batch size limits. # batch_limits: # max_estimated_size: number # max_record_count: number @@ -176,29 +153,29 @@ replication: # port: !env PS_PORT # ----------------------------------------------------------------------------- -# SYNC CONFIG – configuration for synchronization rules that define data access patterns +# SYNC CONFIG – configuration for Sync Streams/Sync Rules that define which data is synced to each user. # ----------------------------------------------------------------------------- -# One of path or content is supported. path is used in this example. +# One of path or content is supported. path is the most common (file reference). sync_config: - # [optional] Path to the sync config YAML file. + # Path to the sync config YAML file (sync rules). path: sync-config.yaml -# # [optional] Inline sync config content as a string (use this or path, not both). +# # [optional] Inline sync config content as a string; use this or path, not both. # content: string -# # [optional] Whether to exit the process if there is an error parsing sync config. -# exit_on_error: boolean +# # [optional] When true, exit the process if sync config fails to parse. Default: false. +# exit_on_error: false # ----------------------------------------------------------------------------- # CLIENT AUTH (optional) – configuration for client authentication mechanisms # ----------------------------------------------------------------------------- # client_auth: -# # [optional] PowerSync will use the same JWT secret as Supabase. +# # [optional] Use the same JWT secret as Supabase. Default: false. # supabase: false -# # [optional] Legacy: If your Supabase project does not use the new JWT signing keys, you must provide your project's legacy JWT secret to use Supabase Auth. Get it from your project's API settings in the Supabase Dashboard. +# # [optional] Legacy: provide your Supabase project's legacy JWT secret from API settings in the Supabase Dashboard if not using new JWT signing keys. # supabase_jwt_secret: !env PS_SUPABASE_JWT_SECRET -# # [optional] URI or array of URIs pointing to JWKS endpoints for client authentication; instance fetches public keys to verify JWT signatures. +# # [optional] JWKS URL or array of URLs; instance fetches public keys to verify JWT signatures. Often used with custom auth. # jwks_uri: https://example.com/jwks.json -# # [optional] Inline JWKS configuration; provide keys directly instead of (or in addition to) jwks_uri to verify JWT signatures. +# # [optional] Inline JWKS; provide keys directly instead of or in addition to jwks_uri. # jwks: # keys: # HMAC (symmetric) – Options: HS256 | HS384 | HS512 @@ -225,47 +202,42 @@ sync_config: # crv: Ed25519 # x: "" # alg: EdDSA -# # [optional] When true, blocks JWKS URIs that resolve to local network addresses. +# # [optional] Valid audiences for JWT validation. Example: ['authenticated']. +# audience: ['authenticated'] +# # [optional] When true, block JWKS URIs that resolve to local network addresses. Default: false. # block_local_jwks: false -# # [optional] IP ranges to reject when validating JWKS URIs. +# # [optional] IP ranges to reject when resolving JWKS URIs. Default: []. # jwks_reject_ip_ranges: [] -# # [optional] Valid audiences for JWT validation. -# audience: ['authenticated'] # ----------------------------------------------------------------------------- # [optional] API – API service configuration and parameters # ----------------------------------------------------------------------------- api: - # [optional] API access tokens for administrative operations. + # API access tokens for administrative operations (e.g. CLI link). Use a strong token in production. tokens: - use_a_better_token_in_production -# # [optional] Performance and safety parameters for the API service. +# # [optional] Performance and safety parameters. Defaults shown. # parameters: -# # [optional] Maximum number of connections (http streams or websockets) per API process. Default of 200. -# max_concurrent_connections: 200 -# # [optional] Should not be significantly more than storage.max_pool_size, otherwise it would block on the pool. Default of 10. -# max_data_fetch_concurrency: 10 -# # [optional] Maximum number of buckets for each connection; hard limit so the service errors instead of crashing when a sync rule is misconfigured. Default of 1000. -# max_buckets_per_connection: 1000 -# # [optional] Limit on parameter query results before converting to a unique set. Default of 1000. -# max_parameter_query_results: 1000 +# max_concurrent_connections: 200 # Max connections (HTTP/websocket) per API process. +# max_data_fetch_concurrency: 10 # Should not exceed storage.max_pool_size. Default: 10. +# max_buckets_per_connection: 1000 # Hard limit; service errors if exceeded. Default: 1000. +# max_parameter_query_results: 1000 # Limit before converting to unique set. Default: 1000. # ----------------------------------------------------------------------------- # [optional] HEALTHCHECK – mechanisms for exposing health check data # ----------------------------------------------------------------------------- # healthcheck: # probes: -# # [optional] Enables exposing healthcheck status via filesystem files. +# # [optional] Expose healthcheck status via filesystem files. # use_filesystem: boolean -# # [optional] Enables exposing healthcheck status via HTTP endpoints. +# # [optional] Expose healthcheck status via HTTP endpoints. # use_http: boolean -# # [optional] Deprecated. Enables HTTP probes for both API and UNIFIED service modes. FileSystem probes are always enabled. +# # [optional] Deprecated. HTTP probes for API and UNIFIED; filesystem probes are always enabled. # use_legacy: boolean # ----------------------------------------------------------------------------- # [optional] MIGRATIONS – configuration for database schema migrations # ----------------------------------------------------------------------------- # migrations: -# # [optional] When true, disables automatic storage database schema migrations. -# # Migrations need to manually be started by the consuming application. +# # When true, disables automatic storage schema migrations; start them manually. Default: false. # disable_auto_migration: false