docs: update sqlite sync docs

Author: damlayildiz

.github/workflows/aisearch.yaml

@@ -2,17 +2,24 @@ name: Process docs for SQLite AI Search
 
 on:
   workflow_dispatch:
-  
+  push:
+    branches:
+      - main
+      - stage
+
 jobs:
-  docsearch:
+  aisearch:
     runs-on: ubuntu-latest
     environment: ${{ github.ref_name }}
+    permissions:
+      contents: read
 
     steps:
       - uses: actions/checkout@v4
-      
-      # - uses: sqlitecloud/sqlite-ai-action@v1
-      #   with:
-      #     project-string: ${{ secrets.PROJECT_STRING }}
-      #     base-url: ${{ vars.BASE_URL }}
-      #     database: documentation_ai.sqlite
+
+      - uses: sqliteai/sqlite-aisearch-action@v1
+        with:
+          connection_string: ${{ secrets.PROJECT_STRING }}
+          base_url: ${{ vars.BASE_URL }}
+          database_name: documentation_ai.sqlite
+          source_files: ./

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

@@ -0,0 +1,19 @@
+### `cloudsync_begin_alter(table_name)`
+
+**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,17 @@
+### `cloudsync_cleanup(table_name)`
+
+**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,19 @@
+### `cloudsync_commit_alter(table_name)`
+
+**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,13 @@
+### `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,15 @@
+### `cloudsync_disable(table_name)`
+
+**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,15 @@
+### `cloudsync_enable(table_name)`
+
+**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,46 @@
+### `cloudsync_init(table_name, [crdt_algo], [force])`
+
+**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](https://github.com/sqliteai/sqlite-sync/blob/main/README.md#database-schema-recommendations) 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_init.md

@@ -0,0 +1,15 @@
+### `cloudsync_is_enabled(table_name)`
+
+**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');
+```