powersync-ja · bean1352 · Jun 3, 2026 · Jun 3, 2026 · Jun 4, 2026 · Jun 4, 2026
diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md
@@ -151,6 +151,8 @@ Always use the left column. Never use the right.
 | Sync Rules | sync rules |
 | Sync Streams | sync streams |
 
+Capitalize **Service** whenever it refers to the PowerSync Service, including when it stands alone without the "PowerSync" prefix (for example, "the Service recovers on its own" or "depending on Service version"). Lowercase "service" alone is ambiguous and can refer to many things. Leave casing unchanged inside literal log output, code, field names, or identifiers (for example, the `service closing stream` log value or the `is_service_error` field).
+
 ## Mintlify Components
 
 ### When to Use What

diff --git a/.claude/skills/doc-author/SKILL.md b/.claude/skills/doc-author/SKILL.md
@@ -81,6 +81,8 @@ The `description` and opening paragraph must not duplicate each other — the op
 | Sync Rules | sync rules |
 | Sync Streams | sync streams |
 
+Capitalize **Service** whenever it refers to the PowerSync Service, including when it stands alone without the "PowerSync" prefix (for example, "the Service recovers on its own"). Lowercase "service" alone is ambiguous. Leave casing unchanged inside literal log output, code, field names, or identifiers.
+
 ### Tone
 
 - No promotional language: "powerful," "seamless," "breathtaking," "stands as a testament"

diff --git a/.github/vale/config/vocabularies/PowerSync/accept.txt b/.github/vale/config/vocabularies/PowerSync/accept.txt
@@ -5,12 +5,15 @@ addons
 agnostically
 allowlisting
 autoscaling
+backfill
+backfills
 backpressure
 baz
 binlog
 bitwise
 bundler
 bundlers
+bursty
 cardinalities
 cardinality
 changetables
@@ -43,6 +46,7 @@ deserializer
 deserializers
 dev
 dotnet
+errored
 failover
 geo
 geospatial
@@ -67,6 +71,7 @@ nameservers
 namespace
 nullable
 offline-first
+oplog
 orgs
 pdf
 performant
@@ -85,6 +90,7 @@ realtime
 repo
 repos
 replication
+replicator
 requeue
 requeues
 resync
@@ -106,6 +112,7 @@ sidecar
 signups
 slidable
 snapshotted
+snapshotter
 subqueries
 subquery
 subnet
@@ -157,10 +164,13 @@ DAO
 DAOs
 DAU
 DAUs
+DBs
 ECDSA
 E2EE
 ECS
 EdDSA
+GTID
+GTIDs
 HA
 HS256
 IDE
@@ -209,7 +219,9 @@ YAML
 bytea
 cacert
 client_auth
+close_reason
 clusterTime
+current_data
 datetime
 DBPointer
 inet
@@ -218,6 +230,7 @@ json_extract
 jwks_uri
 listitem
 macaddr
+op_id
 plpgsql
 replicaset
 subsec

diff --git a/configuration/source-db/postgres-maintenance.mdx b/configuration/source-db/postgres-maintenance.mdx
@@ -56,7 +56,7 @@ Replace `powersync_1_xxxx` with the actual slot name from the error message.
 
 3. Restart the PowerSync Service. It will create a new replication slot and begin replication from scratch.
 
-<Note>If the slot was invalidated during the initial snapshot (before it completed), the PowerSync Service will not automatically retry. You must drop the invalidated slot manually before the service can recover.</Note>
+<Note>If the slot was invalidated during initial replication (before it completed), the PowerSync Service will not automatically retry. You must drop the invalidated slot manually before the Service can recover.</Note>
 
 If the invalidation reason is `idle_timeout` (Postgres 18+), the slot was invalidated due to inactivity. In this case, increase `idle_replication_slot_timeout` on the source database instead.
 

diff --git a/debugging/log-reference.mdx b/debugging/log-reference.mdx
diff --git a/docs.json b/docs.json
@@ -413,6 +413,7 @@
                 "pages": [
                   "debugging/troubleshooting",
                   "debugging/error-codes",
+                  "debugging/log-reference",
                   "tools/diagnostics-client",
                   "maintenance-ops/client-database-diagnostics"
                 ]

diff --git a/maintenance-ops/implementing-schema-changes.mdx b/maintenance-ops/implementing-schema-changes.mdx
@@ -145,7 +145,7 @@ Due to a limitation in the replication process, dropping a collection does not i
 
 Renaming a synced collection to a name that _is not included_ in Sync Streams (or legacy Sync Rules) has the same effect as dropping the collection.
 
-Renaming an unsynced collection to a name that is included in your Sync/Streams/Sync Rules triggers an initial snapshot replication. The time required for this process depends on the collection size.
+Renaming an unsynced collection to a name that is included in your Sync Streams/Sync Rules triggers an initial snapshot replication. The time required for this process depends on the collection size.
 
 Circular renames (e.g., renaming `todos` → `todos_old` → `todos`) are not directly supported. To reprocess the database after such changes, a Sync Streams/Sync Rules update must be deployed.
 

diff --git a/maintenance-ops/monitoring-and-alerting.mdx b/maintenance-ops/monitoring-and-alerting.mdx
@@ -78,6 +78,8 @@ You can review logs for your PowerSync instance(s) to troubleshoot replication o
 
 * **Replicator logs**: Reflect replication activity from your source database to the PowerSync Service.
 
+See the [Log Reference](/debugging/log-reference) for what each log line means and which ones the service recovers from on its own.
+
 <Note>
   **Availability**
 
@@ -199,6 +201,33 @@ checkpoint sync user_id:123 checkpoint:>=1224
 
 This matches entries containing both `checkpoint` and `sync` in the message, with `user_id` equal to `123` and a `checkpoint` property greater than or equal to `1224`.
 
+#### Example Queries
+
+Common queries for Sync & API logs:
+
+```
+user_id:<user-id>                             # one user
+rid:<request-id>                              # both ends of one session
+close_reason:"stream error"                   # errored sessions
+error:PSYNC_S2403                             # a specific error code
+user_id:<user-id> close_reason:"stream error" # errored sessions for one user
+operations_synced:>=10000                     # high-volume sync sessions
+```
+
+Common queries for Replication logs:
+
+```
+lag:>=10                       # flushes with significant lag
+"Replicating" "public.orders"  # snapshot progress for a specific table
+"Replication error"            # non-fatal retries
+"Replication failed"           # pod restarts
+"Created replication slot"     # Postgres slot recreation events
+"Processing schema change"     # MySQL DDL
+"System started"               # pod restart points
+```
+
+For what each of these events and fields means, see the [Log Reference](/debugging/log-reference).
+
 ### Export Logs
 
 Click the **Download** button on the right side of the toolbar to export the currently visible log entries to a CSV file. The export reflects the active log type, time range, log levels, and search query, so you can narrow the result set before downloading.

diff --git a/maintenance-ops/replication-lag.mdx b/maintenance-ops/replication-lag.mdx
@@ -60,7 +60,7 @@ The causes below are grouped into ones that apply to any source, and ones that a
 
 When you first connect a source database, or when you deploy Sync Config changes that trigger reprocessing, the PowerSync Service replicates the full set of matching rows. During this period:
 
-* Replication lag will be elevated until the initial snapshot completes.
+* Replication lag will be elevated until initial replication completes.
 * The source-side replication buffer (WAL on Postgres, oplog on MongoDB, binlog on MySQL, CDC change tables on SQL Server) grows because the service has not yet acknowledged those changes.
 
 This is expected. Plan for it by sizing the relevant retention setting appropriately (see the source-specific sections below) and by coordinating large Sync Config changes during lower-traffic windows.

diff --git a/maintenance-ops/self-hosting/diagnostics.mdx b/maintenance-ops/self-hosting/diagnostics.mdx
@@ -54,7 +54,7 @@ Each connection in `active_sync_rules.connections[]` includes:
 | Field | Description |
 | --- | --- |
 | `slot_name` | The name of the Postgres replication slot used by this sync rules version. |
-| `initial_replication_done` | Whether the initial snapshot has completed. |
+| `initial_replication_done` | Whether initial replication has completed. |
 | `replication_lag_bytes` | Replication lag in bytes. |
 | `wal_status` | The WAL status of the replication slot (`reserved`, `extended`, `unreserved`, or `lost`). |
 | `safe_wal_size` | Remaining WAL budget in bytes before the slot risks invalidation. |