Update "Conversion Between SQLite and PostgreSQL Tables" in docs/postgresql/CLIENT.md

Author: andinux

docs/postgresql/CLIENT.md

@@ -33,9 +33,114 @@ Under the hood, SQLite Sync uses advanced **CRDT (Conflict-free Replicated Data
 
 ## Conversion Between SQLite and PostgreSQL Tables
 
-- In this version, make sure to **manually create** the same tables in the PostgreSQL database as used in the SQLite client.
-- Follow the Database Schema Recommendations:  
-  https://github.com/sqliteai/sqlite-sync-dev?tab=readme-ov-file#database-schema-recommendations
+In this version, make sure to **manually create** the same tables in the PostgreSQL database as used in the SQLite client.
+
+This guide shows how to manually convert a SQLite table definition to PostgreSQL
+so CloudSync can sync between a PostgreSQL server and SQLite clients.
+
+### 1) Primary Keys
+
+- Use **TEXT NOT NULL** primary keys only (UUIDs as text).
+- Generate IDs with `cloudsync_uuid()` on both sides.
+- Avoid INTEGER auto-increment PKs.
+
+SQLite:
+```sql
+id TEXT PRIMARY KEY NOT NULL
+```
+
+PostgreSQL:
+```sql
+id TEXT PRIMARY KEY NOT NULL
+```
+
+### 2) NOT NULL Columns Must Have DEFAULTs
+
+CloudSync merges column-by-column. Any NOT NULL (non-PK) column needs a DEFAULT
+to avoid constraint failures during merges.
+
+Example:
+```sql
+title TEXT NOT NULL DEFAULT ''
+count INTEGER NOT NULL DEFAULT 0
+```
+
+### 3) Safe Type Mapping
+
+Use types that map cleanly to CloudSync's DBTYPEs:
+
+- INTEGER → `INTEGER` (SQLite) / `INTEGER` (Postgres)
+- FLOAT → `REAL` / `DOUBLE` (SQLite) / `DOUBLE PRECISION` (Postgres)
+- TEXT → `TEXT` (both)
+- BLOB → `BLOB` (SQLite) / `BYTEA` (Postgres)
+
+Avoid: JSON/JSONB, UUID, INET, CIDR, RANGE, ARRAY unless you accept text-cast
+behavior.
+
+### 4) Defaults That Match Semantics
+
+Use defaults that serialize the same on both sides:
+
+- TEXT: `DEFAULT ''`
+- INTEGER: `DEFAULT 0`
+- FLOAT: `DEFAULT 0.0`
+- BLOB: `DEFAULT X'00'` (SQLite) vs `DEFAULT E'\\x00'` (Postgres)
+
+### 5) Foreign Keys and Triggers
+
+- Foreign keys can cause merge conflicts; test carefully.
+- Application triggers will fire during merge; keep them idempotent or disable
+  in synced tables.
+
+### 6) Example Conversion
+
+SQLite:
+```sql
+CREATE TABLE notes (
+  id TEXT PRIMARY KEY NOT NULL,
+  title TEXT NOT NULL DEFAULT '',
+  body TEXT DEFAULT '',
+  views INTEGER NOT NULL DEFAULT 0,
+  rating REAL DEFAULT 0.0,
+  data BLOB
+);
+```
+
+PostgreSQL:
+```sql
+CREATE TABLE notes (
+  id TEXT PRIMARY KEY NOT NULL,
+  title TEXT NOT NULL DEFAULT '',
+  body TEXT DEFAULT '',
+  views INTEGER NOT NULL DEFAULT 0,
+  rating DOUBLE PRECISION DEFAULT 0.0,
+  data BYTEA
+);
+```
+
+### 7) Enable CloudSync
+
+SQLite:
+```sql
+.load dist/cloudsync.dylib
+SELECT cloudsync_init('notes');
+```
+
+PostgreSQL:
+```sql
+CREATE EXTENSION cloudsync;
+SELECT cloudsync_init('notes');
+```
+
+### Checklist
+
+- [ ] PKs are TEXT + NOT NULL
+- [ ] All NOT NULL columns have DEFAULT
+- [ ] Only INTEGER/FLOAT/TEXT/BLOB-compatible types
+- [ ] Same column names and order
+- [ ] Same defaults (semantic match)
+
+Database Schema Recommendations: https://github.com/sqliteai/sqlite-sync-dev?tab=readme-ov-file#database-schema-recommendations
 
 ---