docs: add Database Schema Recommendations

Author: andinux

API.md

@@ -44,6 +44,18 @@ Before initialization, `cloudsync_init` performs schema sanity checks to ensure
 - All primary key columns must be `NOT NULL`.
 - All non-primary key `NOT NULL` columns must have a `DEFAULT` value.
 
+**Schema Design Considerations:**
+
+When designing your database schema for SQLite Sync, follow these essential requirements:
+
+- **Primary Keys**: Use TEXT primary keys with `cloudsync_uuid()` for globally unique identifiers. Avoid auto-incrementing integers.
+- **Column Constraints**: All NOT NULL columns (except primary keys) must have DEFAULT values to prevent synchronization errors.
+- **UNIQUE Constraints**: In multi-tenant scenarios, use composite UNIQUE constraints (e.g., `UNIQUE(tenant_id, email)`) instead of global uniqueness.
+- **Foreign Key Compatibility**: Be aware of potential conflicts during CRDT merge operations and RLS policy interactions.
+- **Trigger Compatibility**: Triggers may cause duplicate operations or be called multiple times due to column-by-column processing.
+
+For comprehensive guidelines, see the [Database Schema Recommendations](../README.md#database-schema-recommendations) section in the README.
+
 The function supports three overloads:
 - `cloudsync_init(table_name)`: Uses the default 'cls' CRDT algorithm.
 - `cloudsync_init(table_name, crdt_algo)`: Specifies a CRDT algorithm ('cls', 'dws', 'aws', 'gos').
@@ -373,6 +385,8 @@ SELECT cloudsync_network_has_unsent_changes();
 
 **Returns:** None.
 
+**Errors:** See [Network Errors](#network-errors) for common error conditions.
+
 **Example:**
 
 ```sql
@@ -397,6 +411,8 @@ On success, it returns `SQLITE_OK`, and the return value indicates how many chan
 
 **Returns:** The number of changes downloaded. Errors are reported via the SQLite return code.
 
+**Errors:** See [Network Errors](#network-errors) for common error conditions.
+
 **Example:**
 
 ```sql
@@ -419,6 +435,8 @@ SELECT cloudsync_network_check_changes();
 
 **Returns:** The number of changes downloaded. Errors are reported via the SQLite return code.
 
+**Errors:** See [Network Errors](#network-errors) for common error conditions.
+
 **Example:**
 
 ```sql
@@ -460,3 +478,21 @@ SELECT cloudsync_network_reset_sync_version();
 ```sql
 SELECT cloudsync_network_logout();
 ```
+
+---
+
+### Network Errors
+
+Network functions may encounter specific errors during synchronization:
+
+#### Device Limit Exceeded
+
+If the device limit for your current plan on the cloud node is exceeded, network functions return error code `SQLITE_ERROR` (1) with the error message:
+
+```
+403 Device limit reached: You've already registered the maximum number of <n> devices allowed by your current plan.
+```
+
+**Resolution:** To resolve this error, you can:
+- [Upgrade to a higher plan](https://www.sqlite.ai/pricing) to increase your device limit
+- Remove unused devices from the OffSync section of your database in the [SQLite Cloud dashboard](https://dashboard.sqlitecloud.io/)

README.md

@@ -20,6 +20,12 @@ In simple terms, CRDTs make it possible for multiple users to **edit shared data
 - [Documentation](#documentation)
 - [Installation](#installation)
 - [Getting Started](#getting-started)
+- [Database Schema Recommendations](#database-schema-recommendations)
+  - [Primary Key Requirements](#primary-key-requirements)
+  - [Column Constraint Guidelines](#column-constraint-guidelines)
+  - [UNIQUE Constraint Considerations](#unique-constraint-considerations)
+  - [Foreign Key Compatibility](#foreign-key-compatibility)
+  - [Trigger Compatibility](#trigger-compatibility)
 - [License](#license)
 
 ## Key Features
@@ -251,6 +257,113 @@ Use SQLite-AI alongside:
 * **[SQLite-Vector](https://github.com/sqliteai/sqlite-vector)** – vector search from SQL
 * **[SQLite-JS](https://github.com/sqliteai/sqlite-js)** – define SQLite functions in JavaScript
 
+## Database Schema Recommendations
+
+When designing your database schema for SQLite Sync, follow these best practices to ensure optimal CRDT performance and conflict resolution:
+
+### Primary Key Requirements
+
+- **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`**.
+
+```sql
+-- ✅ Recommended: Globally unique TEXT primary key
+CREATE TABLE users (
+    id TEXT PRIMARY KEY NOT NULL,          -- Use cloudsync_uuid()
+    name TEXT NOT NULL,
+    email TEXT UNIQUE NOT NULL
+);
+
+-- ❌ Avoid: Auto-incrementing integer primary key
+CREATE TABLE users (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,  -- Causes conflicts
+    name TEXT NOT NULL,
+    email TEXT UNIQUE NOT NULL
+);
+```
+
+### Column Constraint Guidelines
+
+- **Provide DEFAULT values**: All `NOT NULL` columns (except primary keys) must have `DEFAULT` values
+- **Consider nullable columns**: For optional data, use nullable columns instead of empty strings
+
+```sql
+-- ✅ Recommended: Proper constraints and defaults
+CREATE TABLE tasks (
+    id TEXT PRIMARY KEY,
+    title TEXT NOT NULL DEFAULT '',
+    status TEXT NOT NULL DEFAULT 'pending',
+    priority INTEGER NOT NULL DEFAULT 1,
+    created_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now')),
+    assigned_to TEXT                       -- Nullable for optional assignment
+);
+```
+
+### UNIQUE Constraint Considerations
+
+When converting from single-tenant to multi-tenant database schemas with Row-Level Security, **UNIQUE constraints must be globally unique** across all tenants in the cloud database. For columns that should only be unique within a tenant, use composite UNIQUE constraints.
+
+```sql
+-- ❌ Single-tenant: Unique email per database
+CREATE TABLE users (
+    id TEXT PRIMARY KEY,
+    email TEXT UNIQUE NOT NULL  -- Problem: Not unique across tenants
+);
+
+-- ✅ Multi-tenant: Composite unique constraint
+CREATE TABLE users (
+    id TEXT PRIMARY KEY,
+    tenant_id TEXT NOT NULL,
+    email TEXT NOT NULL,
+    UNIQUE(tenant_id, email)    -- Unique email per tenant
+);
+```
+
+### Foreign Key Compatibility
+
+When using foreign key constraints with SQLite Sync, be aware that interactions with the CRDT merge algorithm and Row-Level Security policies may cause constraint violations. 
+
+#### Potential Conflicts
+
+**CRDT Merge Algorithm and DEFAULT Values**
+
+- CRDT changes are applied column-by-column during synchronization
+- Columns may be temporarily assigned DEFAULT values during the merge process
+- If a foreign key column has a DEFAULT value, that value must exist in the referenced table
+
+**Row-Level Security and CASCADE Actions**
+- RLS policies may block operations required for maintaining referential integrity
+- CASCADE DELETE/UPDATE operations may fail if RLS prevents access to related rows
+
+#### Recommendations
+
+**Database Design Patterns**
+- Prefer application-level cascade logic over database-level CASCADE actions
+- Design RLS policies to accommodate referential integrity operations
+- Use nullable foreign keys where appropriate to avoid DEFAULT value issues
+- Alternatively, ensure DEFAULT values for foreign key columns exist in their referenced tables
+
+**Testing and Validation**
+- Test synchronization scenarios with foreign key constraints enabled
+- Monitor for constraint violations during sync operations in development
+
+### Trigger Compatibility
+
+Be aware that certain types of triggers can cause errors during synchronization due to SQLite Sync's merge logic.
+
+**Duplicate Operations**
+- If a trigger modifies a table that is also synchronized with SQLite Sync, changes performed by the trigger may be applied twice during the merge operation
+- This can lead to constraint violations or unexpected data states depending on the table's constraints
+
+**Column-by-Column Processing**
+- SQLite Sync applies changes column-by-column during synchronization
+- UPDATE triggers may be called multiple times for a single row as each column is processed
+- This can result in unexpected trigger behavior
+
+
+
 ## License
 
 This project is licensed under the [Elastic License 2.0](./LICENSE.md). You can use, copy, modify, and distribute it under the terms of the license for non-production use. For production or managed service use, please [contact SQLite Cloud, Inc](mailto:[email protected]) for a commercial license.