docs: update sqlite sync docs

.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/api-reference/cloudsync_begin_alter.md

@@ -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_cleanup.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_commit_alter.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_db_version.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_disable.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_enable.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_init.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');
+
+```

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

@@ -0,0 +1,21 @@
+---
+title: "cloudsync_is_enabled(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-is-enabled
+---
+
+**Description:** Checks if synchronization is enabled for the specified table.
+
+**Parameters:**
+
+- `table_name` (TEXT): The name of the table to check.
+
+**Returns:** 1 if enabled, 0 otherwise.
+
+**Example:**
+
+```sql
+SELECT cloudsync_is_enabled('my_table');
+```

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

@@ -0,0 +1,29 @@
+---
+title: "cloudsync_network_check_changes()"
+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-network-check-changes
+---
+
+**Description:** Checks the remote server for new changes and applies them to the local database.
+
+If a package of new changes is already available for the local site, the server returns it immediately, and the changes are applied. If no package is ready, the server returns an empty response and starts an asynchronous process to prepare a new package. This new package can be retrieved with a subsequent call to this function.
+
+This function is designed to be called periodically to keep the local database in sync.
+To force an update and wait for changes (with a timeout), use `cloudsync_network_sync(wait_ms, max_retries)`.
+
+If the network is misconfigured or the remote server is unreachable, the function returns an error.
+On success, it returns `SQLITE_OK`, and the return value indicates how many changes were downloaded and applied.
+
+**Parameters:** None.
+
+**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
+SELECT cloudsync_network_check_changes();
+```

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

@@ -0,0 +1,19 @@
+---
+title: "cloudsync_network_cleanup()"
+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-network-cleanup
+---
+
+**Description:** Cleans up the `sqlite-sync` network component, releasing all resources allocated by `cloudsync_network_init` (memory, cURL handles).
+
+**Parameters:** None.
+
+**Returns:** None.
+
+**Example:**
+
+```sql
+SELECT cloudsync_network_cleanup();
+```

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

@@ -0,0 +1,19 @@
+---
+title: "cloudsync_network_has_unsent_changes()"
+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-network-has-unsent-changes
+---
+
+**Description:** Checks if there are any local changes that have not yet been sent to the remote server.
+
+**Parameters:** None.
+
+**Returns:** 1 if there are unsent changes, 0 otherwise.
+
+**Example:**
+
+```sql
+SELECT cloudsync_network_has_unsent_changes();
+```

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

@@ -0,0 +1,21 @@
+---
+title: "cloudsync_network_init(connection_string)"
+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-network-init
+---
+
+**Description:** Initializes the `sqlite-sync` network component. This function parses the connection string to configure change checking and upload endpoints, and initializes the cURL library.
+
+**Parameters:**
+
+- `connection_string` (TEXT): The connection string for the remote synchronization server. The format is `sqlitecloud://<host>:<port>/<database>?<options>`.
+
+**Returns:** None.
+
+**Example:**
+
+```sql
+SELECT cloudsync_network_init('<projectid>.sqlite.cloud/<db>.sqlite');
+```

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

@@ -0,0 +1,19 @@
+---
+title: "cloudsync_network_logout()"
+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-network-logout
+---
+
+**Description:** Logs out the current user and cleans up all local data from synchronized tables. This function deletes and then re-initializes synchronized tables, useful for switching users or resetting the local database. **Warning:** This function deletes all data from synchronized tables. Use with caution.
+
+**Parameters:** None.
+
+**Returns:** None.
+
+**Example:**
+
+```sql
+SELECT cloudsync_network_logout();
+```