Merge pull request #132 from sqlitecloud/docs/sqlite-sync

docs: update sqlite sync docs

Author: damlayildiz

.github/workflows/aisearch.yaml

@@ -16,7 +16,7 @@ jobs:
 
     steps:
       - uses: actions/checkout@v4
-      
+
       - uses: sqliteai/sqlite-aisearch-action@v1
         with:
           connection_string: ${{ secrets.PROJECT_STRING }}

sqlite-cloud/_nav.ts

@@ -7,7 +7,41 @@ const sidebarNav: SidebarNavStruct = [
   { title: "Overview", filePath: "ai-overview", type: "inner", level: 0 },
   { title: "SQLite-AI", filePath: "sqlite-ai", type: "inner", level: 0 },
   { title: "SQLite-JS", filePath: "sqlite-js", type: "inner", level: 0 },
-  { title: "SQLite-Sync", filePath: "sqlite-sync", type: "inner", level: 0 },
+  { title: "SQLite-Sync", type: "inner", level: 0 },
+	  { title: "Introduction", filePath: "sqlite-sync-introduction", type: "inner", level: 1 },
+	  { title: "Getting Started", filePath: "sqlite-sync-getting-started", type: "inner", level: 1 },
+	  { title: "Best Practices", filePath: "sqlite-sync-best-practices", type: "inner", level: 1 },
+	  { title: "Quick Starts", type: "inner", level: 1 },
+    	  { title: "Android", filePath: "sqlite-sync-quick-start-android", type: "inner", level: 2 },
+	  	  { title: "iOS", filePath: "sqlite-sync-quick-start-ios", type: "inner", level: 2 },
+	  	  { title: "Linux", filePath: "sqlite-sync-quick-start-linux", type: "inner", level: 2 },
+        { title: "macOS", filePath: "sqlite-sync-quick-start-macos", type: "inner", level: 2 },
+        { title: "React Native Expo", filePath: "sqlite-sync-quick-start-expo", type: "inner", level: 2 },
+	  	  { title: "WASM", filePath: "sqlite-sync-quick-start-wasm", type: "inner", level: 2 },
+	  	  { title: "Windows", filePath: "sqlite-sync-quick-start-windows", type: "inner", level: 2 },
+	  { title: "API Reference", type: "inner", level: 1 },
+	      { title: "cloudsync_init", filePath: "sqlite-sync-api-cloudsync-init", type: "inner", level: 2 },
+	      { title: "cloudsync_enable", filePath: "sqlite-sync-api-cloudsync-enable", type: "inner", level: 2 },
+	      { title: "cloudsync_disable", filePath: "sqlite-sync-api-cloudsync-disable", type: "inner", level: 2 },
+	      { title: "cloudsync_is_enabled", filePath: "sqlite-sync-api-cloudsync-is-enabled", type: "inner", level: 2 },
+	      { title: "cloudsync_cleanup", filePath: "sqlite-sync-api-cloudsync-cleanup", type: "inner", level: 2 },
+	      { title: "cloudsync_terminate", filePath: "sqlite-sync-api-cloudsync-terminate", type: "inner", level: 2 },
+	      { title: "cloudsync_version", filePath: "sqlite-sync-api-cloudsync-version", type: "inner", level: 2 },
+	      { title: "cloudsync_siteid", filePath: "sqlite-sync-api-cloudsync-siteid", type: "inner", level: 2 },
+	      { title: "cloudsync_db_version", filePath: "sqlite-sync-api-cloudsync-db-version", type: "inner", level: 2 },
+	      { title: "cloudsync_uuid", filePath: "sqlite-sync-api-cloudsync-uuid", type: "inner", level: 2 },
+	      { title: "cloudsync_begin_alter", filePath: "sqlite-sync-api-cloudsync-begin-alter", type: "inner", level: 2 },
+	      { title: "cloudsync_commit_alter", filePath: "sqlite-sync-api-cloudsync-commit-alter", type: "inner", level: 2 },
+	      { title: "cloudsync_network_init", filePath: "sqlite-sync-api-cloudsync-network-init", type: "inner", level: 2 },
+	      { title: "cloudsync_network_cleanup", filePath: "sqlite-sync-api-cloudsync-network-cleanup", type: "inner", level: 2 },
+	      { title: "cloudsync_network_set_token", filePath: "sqlite-sync-api-cloudsync-network-set-token", type: "inner", level: 2 },
+	      { title: "cloudsync_network_set_apikey", filePath: "sqlite-sync-api-cloudsync-network-set-apikey", type: "inner", level: 2 },
+	      { title: "cloudsync_network_has_unsent_changes", filePath: "sqlite-sync-api-cloudsync-network-has-unsent-changes", type: "inner", level: 2 },
+	      { title: "cloudsync_network_send_changes", filePath: "sqlite-sync-api-cloudsync-network-send-changes", type: "inner", level: 2 },
+	      { title: "cloudsync_network_check_changes", filePath: "sqlite-sync-api-cloudsync-network-check-changes", type: "inner", level: 2 },
+	      { title: "cloudsync_network_sync", filePath: "sqlite-sync-api-cloudsync-network-sync", type: "inner", level: 2 },
+	      { title: "cloudsync_network_reset_sync_version", filePath: "sqlite-sync-api-cloudsync-network-reset-sync-version", type: "inner", level: 2 },
+	      { title: "cloudsync_network_logout", filePath: "sqlite-sync-api-cloudsync-network-logout", type: "inner", level: 2 },
   { title: "SQLite-Vector", filePath: "sqlite-vector", type: "inner", level: 0 },
   { title: "MCP (Model Context Protocol)", filePath: "mcp-server", type: "inner", level: 0 },
 

sqlite-cloud/sqlite-ai/sqlite-sync.mdx

@@ -0,0 +1,25 @@
+---
+title: "cloudsync_begin_alter(table_name)"
+description: SQLite Sync is a multi-platform extension that brings a true local-first experience to your applications with minimal effort.
+category: platform
+status: publish
+slug: sqlite-sync-api-cloudsync-begin-alter
+---
+
+**Description:** Prepares a synchronized table for schema changes. This function must be called before altering the table. Failure to use `cloudsync_begin_alter` and `cloudsync_commit_alter` can lead to synchronization errors and data divergence.
+
+**Parameters:**
+
+- `table_name` (TEXT): The name of the table that will be altered.
+
+**Returns:** None.
+
+**Example:**
+
+```sql
+SELECT cloudsync_init('my_table');
+-- ... later
+SELECT cloudsync_begin_alter('my_table');
+ALTER TABLE my_table ADD COLUMN new_column TEXT;
+SELECT cloudsync_commit_alter('my_table');
+```

sqlite-cloud/sqlite-ai/sqlite-sync/api-reference/cloudsync_begin_alter.md

@@ -0,0 +1,23 @@
+---
+title: "cloudsync_cleanup(table_name)"
+description: SQLite Sync is a multi-platform extension that brings a true local-first experience to your applications with minimal effort.
+category: platform
+status: publish
+slug: sqlite-sync-api-cloudsync-cleanup
+---
+
+**Description:** Removes the `sqlite-sync` synchronization mechanism from a specified table or all tables. This operation drops the associated `_cloudsync` metadata table and removes triggers from the target table(s). Use this function when synchronization is no longer desired for a table.
+
+**Parameters:**
+
+- `table_name` (TEXT): The name of the table to clean up.
+
+**Returns:** None.
+
+**Example:**
+
+```sql
+-- Clean up a single table
+SELECT cloudsync_cleanup('my_table');
+
+```

sqlite-cloud/sqlite-ai/sqlite-sync/api-reference/cloudsync_cleanup.md

@@ -0,0 +1,25 @@
+---
+title: "cloudsync_commit_alter(table_name)"
+description: SQLite Sync is a multi-platform extension that brings a true local-first experience to your applications with minimal effort.
+category: platform
+status: publish
+slug: sqlite-sync-api-cloudsync-commit-alter
+---
+
+**Description:** Finalizes schema changes for a synchronized table. This function must be called after altering the table's schema, completing the process initiated by `cloudsync_begin_alter` and ensuring CRDT data consistency.
+
+**Parameters:**
+
+- `table_name` (TEXT): The name of the table that was altered.
+
+**Returns:** None.
+
+**Example:**
+
+```sql
+SELECT cloudsync_init('my_table');
+-- ... later
+SELECT cloudsync_begin_alter('my_type');
+ALTER TABLE my_table ADD COLUMN new_column TEXT;
+SELECT cloudsync_commit_alter('my_table');
+```

sqlite-cloud/sqlite-ai/sqlite-sync/api-reference/cloudsync_commit_alter.md

@@ -0,0 +1,19 @@
+---
+title: "cloudsync_db_version()"
+description: SQLite Sync is a multi-platform extension that brings a true local-first experience to your applications with minimal effort.
+category: platform
+status: publish
+slug: sqlite-sync-api-cloudsync-db-version
+---
+
+**Description:** Returns the current database version.
+
+**Parameters:** None.
+
+**Returns:** The database version as an INTEGER.
+
+**Example:**
+
+```sql
+SELECT cloudsync_db_version();
+```

sqlite-cloud/sqlite-ai/sqlite-sync/api-reference/cloudsync_db_version.md

@@ -0,0 +1,21 @@
+---
+title: "cloudsync_disable(table_name)"
+description: SQLite Sync is a multi-platform extension that brings a true local-first experience to your applications with minimal effort.
+category: platform
+status: publish
+slug: sqlite-sync-api-cloudsync-disable
+---
+
+**Description:** Disables synchronization for the specified table.
+
+**Parameters:**
+
+- `table_name` (TEXT): The name of the table to disable.
+
+**Returns:** None.
+
+**Example:**
+
+```sql
+SELECT cloudsync_disable('my_table');
+```

sqlite-cloud/sqlite-ai/sqlite-sync/api-reference/cloudsync_disable.md

@@ -0,0 +1,21 @@
+---
+title: "cloudsync_enable(table_name)"
+description: SQLite Sync is a multi-platform extension that brings a true local-first experience to your applications with minimal effort.
+category: platform
+status: publish
+slug: sqlite-sync-api-cloudsync-enable
+---
+
+**Description:** Enables synchronization for the specified table.
+
+**Parameters:**
+
+- `table_name` (TEXT): The name of the table to enable.
+
+**Returns:** None.
+
+**Example:**
+
+```sql
+SELECT cloudsync_enable('my_table');
+```

sqlite-cloud/sqlite-ai/sqlite-sync/api-reference/cloudsync_enable.md

@@ -0,0 +1,52 @@
+---
+title: "cloudsync_init(table_name, [crdt_algo], [force])"
+description: SQLite Sync is a multi-platform extension that brings a true local-first experience to your applications with minimal effort.
+category: platform
+status: publish
+slug: sqlite-sync-api-cloudsync-init
+---
+
+**Description:** Initializes a table for `sqlite-sync` synchronization. This function is idempotent and needs to be called only once per table on each site; configurations are stored in the database and automatically loaded with the extension.
+
+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.
+
+**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](/docs/sqlite-sync-best-practices) section.
+
+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').
+- `cloudsync_init(table_name, crdt_algo, force)`: Specifies an algorithm and, if `force` is `true` (or `1`), skips the integer primary key check (use with caution, GUIDs are strongly recommended).
+
+**Parameters:**
+
+- `table_name` (TEXT): The name of the table to initialize.
+- `crdt_algo` (TEXT, optional): The CRDT algorithm to use. Can be "cls", "dws", "aws", "gos". Defaults to "cls".
+- `force` (BOOLEAN, optional): If `true` (or `1`), it skips the check that prevents the use of a single-column INTEGER primary key. Defaults to `false`. It is strongly recommended to use globally unique primary keys instead of integers.
+
+**Returns:** None.
+
+**Example:**
+
+```sql
+-- Initialize a single table for synchronization with the Causal-Length Set (CLS) Algorithm (default)
+SELECT cloudsync_init('my_table');
+
+-- Initialize a single table for synchronization with a different algorithm Delete-Wins Set (DWS)
+SELECT cloudsync_init('my_table', 'dws');
+
+```