docs: remove NOT NULL requirement from primary key definitions

The extension now enforces NULL primary key rejection at runtime, so
the explicit NOT NULL constraint on PK columns is no longer a schema
requirement. Replace the "must be NOT NULL" guidance with a note about
runtime enforcement.

Author: andinux

.claude/commands/test-sync-roundtrip-postgres-local.md

@@ -16,7 +16,7 @@ Ask the user to provide a DDL query for the table(s) to test. It can be in Postg
 **Option 1: Simple TEXT primary key**
 ```sql
 CREATE TABLE test_sync (
-    id TEXT PRIMARY KEY NOT NULL,
+    id TEXT PRIMARY KEY,
     name TEXT,
     value INTEGER
 );
@@ -34,13 +34,13 @@ CREATE TABLE test_uuid (
 **Option 3: Two tables scenario (tests multi-table sync)**
 ```sql
 CREATE TABLE authors (
-    id TEXT PRIMARY KEY NOT NULL,
+    id TEXT PRIMARY KEY,
     name TEXT,
     email TEXT
 );
 
 CREATE TABLE books (
-    id TEXT PRIMARY KEY NOT NULL,
+    id TEXT PRIMARY KEY,
     title TEXT,
     author_id TEXT,
     published_year INTEGER

.claude/commands/test-sync-roundtrip-postrges-local-rls.md

@@ -16,7 +16,7 @@ Ask the user to provide a DDL query for the table(s) to test. It can be in Postg
 **Option 1: Simple TEXT primary key with user_id for RLS**
 ```sql
 CREATE TABLE test_sync (
-    id TEXT PRIMARY KEY NOT NULL,
+    id TEXT PRIMARY KEY,
     user_id UUID NOT NULL,
     name TEXT,
     value INTEGER
@@ -36,14 +36,14 @@ CREATE TABLE test_uuid (
 **Option 3: Two tables scenario with user ownership**
 ```sql
 CREATE TABLE authors (
-    id TEXT PRIMARY KEY NOT NULL,
+    id TEXT PRIMARY KEY,
     user_id UUID NOT NULL,
     name TEXT,
     email TEXT
 );
 
 CREATE TABLE books (
-    id TEXT PRIMARY KEY NOT NULL,
+    id TEXT PRIMARY KEY,
     user_id UUID NOT NULL,
     title TEXT,
     author_id TEXT,

.claude/commands/test-sync-roundtrip-sqlitecloud-rls.md

@@ -16,7 +16,7 @@ Ask the user to provide a DDL query for the table(s) to test. It can be in Postg
 **Option 1: Simple TEXT primary key with user_id for RLS**
 ```sql
 CREATE TABLE test_sync (
-    id TEXT PRIMARY KEY NOT NULL,
+    id TEXT PRIMARY KEY,
     user_id TEXT NOT NULL,
     name TEXT,
     value INTEGER
@@ -26,14 +26,14 @@ CREATE TABLE test_sync (
 **Option 2: Two tables scenario with user ownership**
 ```sql
 CREATE TABLE authors (
-    id TEXT PRIMARY KEY NOT NULL,
+    id TEXT PRIMARY KEY,
     user_id TEXT NOT NULL,
     name TEXT,
     email TEXT
 );
 
 CREATE TABLE books (
-    id TEXT PRIMARY KEY NOT NULL,
+    id TEXT PRIMARY KEY,
     user_id TEXT NOT NULL,
     title TEXT,
     author_id TEXT,

API.md

@@ -41,8 +41,8 @@ This document provides a reference for the SQLite functions provided by the `sql
 
 Before initialization, `cloudsync_init` performs schema sanity checks to ensure compatibility with CRDT requirements and best practices. These checks include:
 - Primary keys should not be auto-incrementing integers; GUIDs (UUIDs, ULIDs) are highly recommended to prevent multi-node collisions.
-- All primary key columns must be `NOT NULL`.
 - All non-primary key `NOT NULL` columns must have a `DEFAULT` value.
+- **Note:** Any write operation that includes a NULL value for a primary key column will be rejected with an error, even if SQLite would normally allow it due to a legacy behavior.
 
 **Schema Design Considerations:**
 

README.md

@@ -264,7 +264,7 @@ sqlite3 myapp.db
 
 -- Create a table (primary key MUST be TEXT for global uniqueness)
 CREATE TABLE IF NOT EXISTS my_data (
-    id TEXT PRIMARY KEY NOT NULL,
+    id TEXT PRIMARY KEY,
     value TEXT NOT NULL DEFAULT '',
     created_at TEXT DEFAULT CURRENT_TIMESTAMP
 );
@@ -313,7 +313,7 @@ SELECT cloudsync_terminate();
 -- Load extension and create identical table structure
 .load ./cloudsync
 CREATE TABLE IF NOT EXISTS my_data (
-    id TEXT PRIMARY KEY NOT NULL,
+    id TEXT PRIMARY KEY,
     value TEXT NOT NULL DEFAULT '',
     created_at TEXT DEFAULT CURRENT_TIMESTAMP
 );
@@ -372,12 +372,12 @@ When designing your database schema for SQLite Sync, follow these best practices
 - **Use globally unique identifiers**: Always use TEXT primary keys with UUIDs, ULIDs, or similar globally unique identifiers
 - **Avoid auto-incrementing integers**: Integer primary keys can cause conflicts across multiple devices
 - **Use `cloudsync_uuid()`**: The built-in function generates UUIDv7 identifiers optimized for distributed systems
-- **All primary keys must be explicitly declared as `NOT NULL`**.
+- **Note:** Any write operation that includes a NULL value for a primary key column will be rejected with an error, even if SQLite would normally allow it due to a legacy behavior.
 
 ```sql
 -- ✅ Recommended: Globally unique TEXT primary key
 CREATE TABLE users (
-    id TEXT PRIMARY KEY NOT NULL,          -- Use cloudsync_uuid()
+    id TEXT PRIMARY KEY,                    -- Use cloudsync_uuid()
     name TEXT NOT NULL,
     email TEXT UNIQUE NOT NULL
 );

docs/postgresql/CLIENT.md

@@ -34,26 +34,26 @@ so CloudSync can sync between a PostgreSQL server and SQLite clients.
 
 ### 1) Primary Keys
 
-- Use **TEXT NOT NULL** primary keys in SQLite.
-- PostgreSQL primary keys can be **TEXT NOT NULL** or **UUID**. If the PK type
+- Use **TEXT** primary keys in SQLite.
+- PostgreSQL primary keys can be **TEXT** or **UUID**. If the PK type
   isn't explicitly mapped to a DBTYPE (like UUID), it will be converted to TEXT
   in the payload so it remains compatible with the SQLite extension.
 - Generate IDs with `cloudsync_uuid()` on both sides.
 - Avoid INTEGER auto-increment PKs.
 
 SQLite:
 ```sql
-id TEXT PRIMARY KEY NOT NULL
+id TEXT PRIMARY KEY
 ```
 
 PostgreSQL:
 ```sql
-id TEXT PRIMARY KEY NOT NULL
+id TEXT PRIMARY KEY
 ```
 
 PostgreSQL (UUID):
 ```sql
-id UUID PRIMARY KEY NOT NULL
+id UUID PRIMARY KEY
 ```
 
 ### 2) NOT NULL Columns Must Have DEFAULTs
@@ -99,7 +99,7 @@ Use defaults that serialize the same on both sides:
 SQLite:
 ```sql
 CREATE TABLE notes (
-  id TEXT PRIMARY KEY NOT NULL,
+  id TEXT PRIMARY KEY,
   title TEXT NOT NULL DEFAULT '',
   body TEXT DEFAULT '',
   views INTEGER NOT NULL DEFAULT 0,
@@ -111,7 +111,7 @@ CREATE TABLE notes (
 PostgreSQL:
 ```sql
 CREATE TABLE notes (
-  id TEXT PRIMARY KEY NOT NULL,
+  id TEXT PRIMARY KEY,
   title TEXT NOT NULL DEFAULT '',
   body TEXT DEFAULT '',
   views INTEGER NOT NULL DEFAULT 0,
@@ -136,7 +136,7 @@ SELECT cloudsync_init('notes');
 
 ### Checklist
 
-- [ ] PKs are TEXT + NOT NULL
+- [ ] PKs are TEXT (or UUID in PostgreSQL)
 - [ ] All NOT NULL columns have DEFAULT
 - [ ] Only INTEGER/FLOAT/TEXT/BLOB-compatible types
 - [ ] Same column names and order

docs/postgresql/RLS.md

@@ -31,7 +31,7 @@ Given a table with an ownership column (`user_id`):
 
 ```sql
 CREATE TABLE documents (
-    id      TEXT PRIMARY KEY NOT NULL,
+    id      TEXT PRIMARY KEY,
     user_id UUID,
     title   TEXT,
     content TEXT
@@ -68,13 +68,13 @@ This example shows the complete flow of syncing data between two databases where
 ```sql
 -- Source database (DB A) — no RLS, represents the sync server
 CREATE TABLE documents (
-    id TEXT PRIMARY KEY NOT NULL, user_id UUID, title TEXT, content TEXT
+    id TEXT PRIMARY KEY, user_id UUID, title TEXT, content TEXT
 );
 SELECT cloudsync_init('documents');
 
 -- Target database (DB B) — RLS enforced
 CREATE TABLE documents (
-    id TEXT PRIMARY KEY NOT NULL, user_id UUID, title TEXT, content TEXT
+    id TEXT PRIMARY KEY, user_id UUID, title TEXT, content TEXT
 );
 SELECT cloudsync_init('documents');
 ALTER TABLE documents ENABLE ROW LEVEL SECURITY;

docs/postgresql/SUPABASE.md

@@ -76,7 +76,7 @@ SELECT cloudsync_version();
 
 ```sql
 CREATE TABLE notes (
-  id TEXT PRIMARY KEY NOT NULL,
+  id TEXT PRIMARY KEY,
   body TEXT DEFAULT ''
 );
 

examples/simple-todo-db/README.md

@@ -59,7 +59,7 @@ Tables must be created on both the local database and SQLite Cloud with identica
 -- Create the main tasks table
 -- Note: Primary key MUST be TEXT (not INTEGER) for global uniqueness
 CREATE TABLE IF NOT EXISTS tasks (
-    id TEXT PRIMARY KEY NOT NULL,
+    id TEXT PRIMARY KEY,
     userid TEXT NOT NULL DEFAULT '',
     title TEXT NOT NULL DEFAULT '',
     description TEXT DEFAULT '',
@@ -84,7 +84,7 @@ SELECT cloudsync_is_enabled('tasks');
    - Execute the same CREATE TABLE statement:
    ```sql
    CREATE TABLE IF NOT EXISTS tasks (
-       id TEXT PRIMARY KEY NOT NULL,
+       id TEXT PRIMARY KEY,
        userid TEXT NOT NULL DEFAULT '',
        title TEXT NOT NULL DEFAULT '',
        description TEXT DEFAULT '',
@@ -149,7 +149,7 @@ sqlite3 todo_device_b.db
 ```sql
 -- Create identical table structure
 CREATE TABLE IF NOT EXISTS tasks (
-    id TEXT PRIMARY KEY NOT NULL,
+    id TEXT PRIMARY KEY,
     userid TEXT NOT NULL DEFAULT '',
     title TEXT NOT NULL DEFAULT '',
     description TEXT DEFAULT '',