[Proposal] Replication config - config.edition: 2

[rkistner]

Background

The replication process on PowerSync has a couple of "quirks" due to how it was implemented initially. Since we aim to keep backwards-compatibility as far as possible, we cannot directly change these. Instead, we propose adding a config section to sync rule files to specify the behavior.

Status

2025-09-23:

1. These options are available on the stable channel for hosted PowerSync services, and are documented on our website.

2025-09-01:

1. Support for timestamps_iso8601, versioned_bucket_ids and fixed_json_extract are released in v1.15.x.
2. custom_postgres_types is going through final testing, and will also be enabled by default with edition: 2.

Proposal

Sync rule files gain a new config key, that can be used to specify an "edition" as a short-hand for all config values, or fine-grained config.

Example using the new defaults:

config:
  edition: 2

Alternatively, specify each option individually:

config:
  timestamps_iso8601: true
  versioned_bucket_ids: true
  fixed_json_extract: true
  custom_postgres_types: true

The specific config changes are:

timestamps_iso8601

Enabled by default in edition: 2

Previously, timestamps from Postgres and MongoDB were replicated in the SQLite-compatible format YYYY-MM-DD HH:MM:SS[.sss]Z. This is supported by most ISO8601-compatible parsers, but does not strictly conform to the spec.

Additionally, for Postgres, and trailing 0's were not included, which could cause default sort order to be broken.

Setting this option to true changes it to:

• Postgres: YYYY-MM-DDTHH:MM:SS.ssssssZ. We use microsecond-precision to match the maximum precision supported by Postgres.
• MongoDB: YYYY-MM-DDTHH:MM:SS.sssZ. We use millisecond-precision to match MongoDB's precision.

MySQL is unchanged: YYYY-MM-DDTHH:MM:SS.sssZ

Details: #331

versioned_bucket_ids

Enabled by default in edition: 2

When deploying sync rule changes, buckets are re-created from scratch. Clients would then sync new data; detect checksum mismatches; then re-download the new bucket data. This could cause new data to be downloaded twice, and confusing progress indicators due to that.

This config option adds the sync rules version number as a prefix to each bucket name, allowing clients to detect the change earlier, and avoid downloading the new data twice.

Details: #333

fixed_json_extract

Enabled by default in edition: 2

This brings the json_extract function and -> and ->> operators in line with the current SQLite version's behavior, specifically in how it relates to dots in keys.

Specifically:

1. When using a key starting with $, it is interpreted as a JSON path. For example, '{"a": {"b": 1}}' ->> '$.a.b' gives 1.
2. When the key does not start with $, it is treated as a direct key. For example: '{"https://mydomain.net": 1}' ->> 'https://mydomain.net' gives 1. This form is sometimes used in JWT claims.

Details: #335

custom_postgres_types

Will be enabled by default in edition: 2 (when released)

Previously, custom Postgres types had no special handling in PowerSync, syncing the raw text representation as-is. This config option enables support for parsing these custom types as JSON.

Specifically, this supports:

• Domain types, which wrap an underlying type and add constraints. We don't add any custom parsing here, but now treat these the same as the underlying type.
• Composite types, which group multiple named values. We now convert these to JSON.
• Range and multirange types are also converted to JSON.

Details: #339

[benitav]

Has since been released, see https://docs.powersync.com/usage/sync-rules/compatibility