From 792d458b59f3fbdeff65aba13aefdf8dd67ef4da Mon Sep 17 00:00:00 2001
From: Dylan MacKenzie <ecstaticmorse@gmail.com>
Date: Tue, 19 Aug 2025 11:19:02 -0700
Subject: [PATCH] Add a note explaining the consequences of ID aliases when
 uploading

---
 usage/sync-rules/client-id.mdx | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/usage/sync-rules/client-id.mdx b/usage/sync-rules/client-id.mdx
index 2c5d2c9d..06004e2e 100644
--- a/usage/sync-rules/client-id.mdx
+++ b/usage/sync-rules/client-id.mdx
@@ -22,6 +22,10 @@ Custom transformations could also be used for the ID, for example:
 SELECT org_id || '.' || record_id as id FROM my_data
 ```
 
+<Warning>
+    If you want to upload data to a table with a custom record ID, ensure that `uploadData()` isn't blindly using a field named `id` when handling CRUD operations. See the [Sequential ID mapping tutorial](/tutorials/client/data/sequential-id-mapping#update-client-to-use-uuids) for an example where the record ID is aliased to `uuid` on the backend.
+</Warning>
+
 PowerSync does not perform any validation that IDs are unique. Duplicate IDs on a client could occur in any of these scenarios:
 
 1. A non-unique column is used for the ID.