From 3b61b8dc2030aca821d708f5c20683177a29b71f Mon Sep 17 00:00:00 2001 From: Kobie Botha Date: Wed, 12 Aug 2026 14:57:38 -0600 Subject: [PATCH 1/6] polish/conflicts --- handling-writes/custom-conflict-resolution.mdx | 2 +- handling-writes/handling-update-conflicts.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/handling-writes/custom-conflict-resolution.mdx b/handling-writes/custom-conflict-resolution.mdx index 6ea65c7b..9889d3c3 100644 --- a/handling-writes/custom-conflict-resolution.mdx +++ b/handling-writes/custom-conflict-resolution.mdx @@ -3,7 +3,7 @@ title: "Custom Conflict Resolution" description: "Implement custom conflict resolution in PowerSync for concurrent updates from multiple offline clients." --- -The default behavior is "**last write wins per field**". Updates to different fields on the same record don't conflict with each other. The server processes operations in the order received, so if two users modify the *same* field, the last update to reach the server wins. +PowerSync uses server-authoritative reconciliation to settle conflicts and decide which state clients converge to. The default behavior is "**last write wins per field**". Updates to different fields on the same record don't conflict with each other. The server processes operations in the order received, so if two users modify the *same* field, the last update to reach the server wins. For most apps, this works fine. But some scenarios demand more complex conflict resolution strategies. diff --git a/handling-writes/handling-update-conflicts.mdx b/handling-writes/handling-update-conflicts.mdx index 447caaf9..d234431b 100644 --- a/handling-writes/handling-update-conflicts.mdx +++ b/handling-writes/handling-update-conflicts.mdx @@ -3,7 +3,7 @@ title: "Handling Update Conflicts" description: "Understand how PowerSync resolves conflicts when multiple users update the same records while offline." --- -**The default behavior is essentially "last write wins", but this can be** [**customized by the developer**](/handling-writes/custom-conflict-resolution)**.** +PowerSync uses server-authoritative reconciliation to settle conflicts and decide which state clients converge to. The developer's existing app backend dictates how mutations from clients are processed. In the simplest backend implementation, the behavior of the overall system will be per-field LWW, however this can be** [**customized**](/handling-writes/custom-conflict-resolution)**.** The upload queue on the client stores three types of operations: From de6f4f59b3feefa67d52e029454183874727a106 Mon Sep 17 00:00:00 2001 From: Kobie Botha Date: Wed, 12 Aug 2026 14:57:38 -0600 Subject: [PATCH 2/6] polish/conflicts From 38c2b1336599ea0c2bcce6f4e3583fae9696828c Mon Sep 17 00:00:00 2001 From: Kobie Botha Date: Tue, 18 Aug 2026 10:13:10 -0600 Subject: [PATCH 3/6] change description and rework intro paragraph --- handling-writes/handling-update-conflicts.mdx | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/handling-writes/handling-update-conflicts.mdx b/handling-writes/handling-update-conflicts.mdx index d234431b..d095856b 100644 --- a/handling-writes/handling-update-conflicts.mdx +++ b/handling-writes/handling-update-conflicts.mdx @@ -1,9 +1,11 @@ --- title: "Handling Update Conflicts" -description: "Understand how PowerSync resolves conflicts when multiple users update the same records while offline." +description: "Understand what happens when multiple users update the same records while offline." --- -PowerSync uses server-authoritative reconciliation to settle conflicts and decide which state clients converge to. The developer's existing app backend dictates how mutations from clients are processed. In the simplest backend implementation, the behavior of the overall system will be per-field LWW, however this can be** [**customized**](/handling-writes/custom-conflict-resolution)**.** +By design PowerSync is unopinionated when it comes to handling conflicts on the backend. On the client, mutations are stored in an "upload queue" - an ordered log of mutations. This upload queue must be sequentially drained against backend API endpoints configured by the developer. The developer's app backend therefore dictates how mutations from clients are processed and applied against the source database. PowerSync then replicates and syncs those mutations back to the client. This is known as server-authoritative reconcilliation. + +In the simplest backend implementation, the behavior of the overall system will be per-field LWW, however this can be** [**customized**](/handling-writes/custom-conflict-resolution)**.** The upload queue on the client stores three types of operations: @@ -17,7 +19,7 @@ The operations must be idempotent — i.e. the backend may receive the same oper * A per-client incrementing operation ID is included with each operation that can be used to deduplicate operations, and/or the backend can implement the operations in an idempotent way (e.g. ignore DELETE on a row that is already deleted). -A conflict may arise when two clients update the same record before seeing the other client’s update, or one client deletes the record while the other updates it. +A conflict may arise when two clients update the same column on the same record before seeing the other client’s update, or one client deletes the record while the other updates it. Typically, the backend should be implemented to handle writes as follows: From 995d0723956209aa0463da21a650eb71c051a8e5 Mon Sep 17 00:00:00 2001 From: Kobie Botha Date: Tue, 18 Aug 2026 10:22:32 -0600 Subject: [PATCH 4/6] simplify intro for custom conflict strategies page --- handling-writes/custom-conflict-resolution.mdx | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/handling-writes/custom-conflict-resolution.mdx b/handling-writes/custom-conflict-resolution.mdx index 9889d3c3..ce369b90 100644 --- a/handling-writes/custom-conflict-resolution.mdx +++ b/handling-writes/custom-conflict-resolution.mdx @@ -3,9 +3,7 @@ title: "Custom Conflict Resolution" description: "Implement custom conflict resolution in PowerSync for concurrent updates from multiple offline clients." --- -PowerSync uses server-authoritative reconciliation to settle conflicts and decide which state clients converge to. The default behavior is "**last write wins per field**". Updates to different fields on the same record don't conflict with each other. The server processes operations in the order received, so if two users modify the *same* field, the last update to reach the server wins. - -For most apps, this works fine. But some scenarios demand more complex conflict resolution strategies. +See [Handling Update Conflicts](/handling-writes/handling-update-conflicts) for basic guidance on how to handle conflicts. For most apps, the approaches documented there are fine. But some scenarios demand more complex conflict resolution strategies. ## When You Might Need Custom Conflict Resolution From 21f80eb034c4a202c42020591c2e1502ed9c411a Mon Sep 17 00:00:00 2001 From: Kobie Botha Date: Fri, 21 Aug 2026 08:24:34 -0600 Subject: [PATCH 5/6] fix formatting issue --- handling-writes/handling-update-conflicts.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/handling-writes/handling-update-conflicts.mdx b/handling-writes/handling-update-conflicts.mdx index d095856b..420fb540 100644 --- a/handling-writes/handling-update-conflicts.mdx +++ b/handling-writes/handling-update-conflicts.mdx @@ -5,7 +5,7 @@ description: "Understand what happens when multiple users update the same record By design PowerSync is unopinionated when it comes to handling conflicts on the backend. On the client, mutations are stored in an "upload queue" - an ordered log of mutations. This upload queue must be sequentially drained against backend API endpoints configured by the developer. The developer's app backend therefore dictates how mutations from clients are processed and applied against the source database. PowerSync then replicates and syncs those mutations back to the client. This is known as server-authoritative reconcilliation. -In the simplest backend implementation, the behavior of the overall system will be per-field LWW, however this can be** [**customized**](/handling-writes/custom-conflict-resolution)**.** +In the simplest backend implementation, the behavior of the overall system will be per-field Last-Write-Wins (LWW), however this can be [**customized**](/handling-writes/custom-conflict-resolution). The upload queue on the client stores three types of operations: From 6a859c172f51aa80beb269e8e76b6019fb99554a Mon Sep 17 00:00:00 2001 From: Kobie Botha Date: Fri, 21 Aug 2026 09:26:17 -0600 Subject: [PATCH 6/6] claude feedback --- handling-writes/handling-update-conflicts.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/handling-writes/handling-update-conflicts.mdx b/handling-writes/handling-update-conflicts.mdx index 420fb540..208976e4 100644 --- a/handling-writes/handling-update-conflicts.mdx +++ b/handling-writes/handling-update-conflicts.mdx @@ -5,7 +5,7 @@ description: "Understand what happens when multiple users update the same record By design PowerSync is unopinionated when it comes to handling conflicts on the backend. On the client, mutations are stored in an "upload queue" - an ordered log of mutations. This upload queue must be sequentially drained against backend API endpoints configured by the developer. The developer's app backend therefore dictates how mutations from clients are processed and applied against the source database. PowerSync then replicates and syncs those mutations back to the client. This is known as server-authoritative reconcilliation. -In the simplest backend implementation, the behavior of the overall system will be per-field Last-Write-Wins (LWW), however this can be [**customized**](/handling-writes/custom-conflict-resolution). +In the simplest backend implementation, the behavior of the overall system will be per-field Last-Write-Wins (LWW). However, this can be [customized](/handling-writes/custom-conflict-resolution). The upload queue on the client stores three types of operations: @@ -19,7 +19,7 @@ The operations must be idempotent — i.e. the backend may receive the same oper * A per-client incrementing operation ID is included with each operation that can be used to deduplicate operations, and/or the backend can implement the operations in an idempotent way (e.g. ignore DELETE on a row that is already deleted). -A conflict may arise when two clients update the same column on the same record before seeing the other client’s update, or one client deletes the record while the other updates it. +A conflict may arise when two clients update the same field on the same record before seeing the other client’s update, or one client deletes the record while the other updates it. Typically, the backend should be implemented to handle writes as follows: