Added new init_flags to the cloudsync_init function

Author: marcobambini

API.md

@@ -5,10 +5,12 @@ This document provides a reference for the SQLite functions provided by the `sql
 ## Index
 
 - [Configuration Functions](#configuration-functions)
-  - [`cloudsync_init()`](#cloudsync_inittable_name-crdt_algo-force)
+  - [`cloudsync_init()`](#cloudsync_inittable_name-crdt_algo-init_flags)
   - [`cloudsync_enable()`](#cloudsync_enabletable_name)
   - [`cloudsync_disable()`](#cloudsync_disabletable_name)
   - [`cloudsync_is_enabled()`](#cloudsync_is_enabledtable_name)
+  - [`cloudsync_set_filter()`](#cloudsync_set_filtertable_name-filter_expr)
+  - [`cloudsync_clear_filter()`](#cloudsync_clear_filtertable_name)
   - [`cloudsync_cleanup()`](#cloudsync_cleanuptable_name)
   - [`cloudsync_terminate()`](#cloudsync_terminate)
 - [Block-Level LWW Functions](#block-level-lww-functions)
@@ -38,7 +40,7 @@ This document provides a reference for the SQLite functions provided by the `sql
 
 ## Configuration Functions
 
-### `cloudsync_init(table_name, [crdt_algo], [force])`
+### `cloudsync_init(table_name, [crdt_algo], [init_flags])`
 
 **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.
 
@@ -62,25 +64,32 @@ For comprehensive guidelines, see the [Database Schema Recommendations](docs/sch
 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).
+- `cloudsync_init(table_name, crdt_algo, init_flags)`: Specifies an algorithm and a bitmask of initialization flags to control which schema sanity checks are skipped.
 
 **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.
+- `crdt_algo` (TEXT, optional): The CRDT algorithm to use. Can be `"cls"`, `"dws"`, `"aws"`, `"gos"`. Defaults to `"cls"`.
+- `init_flags` (INTEGER, optional): A bitmask of flags that control initialization behavior. Defaults to `0` (no flags). Available flags:
+  - `0` — No flags; all sanity checks are performed (default).
+  - `1` (`CLOUDSYNC_INIT_FLAG_SKIP_INT_PK_CHECK`) — Skip the check that prevents the use of a single-column INTEGER primary key. Use with caution; globally unique primary keys (UUID/ULID) are strongly recommended.
+  - `2` (`CLOUDSYNC_INIT_FLAG_SKIP_NOT_NULL_DEFAULT_CHECK`) — Skip the check that requires all NOT NULL non-PK columns to have a DEFAULT value.
+  - `4` (`CLOUDSYNC_INIT_FLAG_SKIP_NOT_NULL_PRIKEYS_CHECK`) — Skip the check that rejects NULL primary key values.
+  - Flags can be combined with bitwise OR (e.g., `3` skips both the integer PK check and the NOT NULL default check).
 
 **Returns:** None.
 
 **Example:**
 
 ```sql
--- Initialize a single table for synchronization with the Causal-Length Set (CLS) Algorithm (default)
+-- Initialize a table with the default CLS algorithm
 SELECT cloudsync_init('my_table');
 
--- Initialize a single table for synchronization with a different algorithm Delete-Wins Set (DWS)
+-- Initialize a table with the Delete-Wins Set algorithm
 SELECT cloudsync_init('my_table', 'dws');
 
+-- Initialize a table with an integer primary key (skip the integer PK check)
+SELECT cloudsync_init('my_table', 'cls', 1);
 ```
 
 ---
@@ -139,6 +148,56 @@ SELECT cloudsync_is_enabled('my_table');
 
 ---
 
+### `cloudsync_set_filter(table_name, filter_expr)`
+
+**Description:** Sets a row-level filter expression on a synchronized table. Only rows that match the filter are tracked by the sync triggers; changes to rows that do not satisfy the expression are ignored and never replicated.
+
+The filter expression is a standard SQL boolean expression written using bare column names (without a table or alias prefix). The extension automatically rewrites it with `NEW.` for INSERT/UPDATE triggers and `OLD.` for DELETE triggers. The expression is evaluated inside the trigger `WHEN` clause.
+
+This function stores the filter in the table's settings and immediately recreates the sync triggers to apply it. The filter persists across database reopens. Use [`cloudsync_clear_filter()`](#cloudsync_clear_filtertable_name) to remove it.
+
+**Parameters:**
+
+- `table_name` (TEXT): The name of the synchronized table.
+- `filter_expr` (TEXT): A SQL boolean expression referencing column names of the table. Only rows for which this expression evaluates to true are tracked for sync.
+
+**Returns:** `1` on success.
+
+**Example:**
+
+```sql
+-- Only sync tasks that are not marked as drafts
+SELECT cloudsync_set_filter('tasks', "is_draft = 0");
+
+-- Only sync rows belonging to a specific tenant
+SELECT cloudsync_set_filter('orders', "tenant_id = 'acme'");
+
+-- Combine conditions
+SELECT cloudsync_set_filter('messages', "deleted = 0 AND type != 'ephemeral'");
+```
+
+---
+
+### `cloudsync_clear_filter(table_name)`
+
+**Description:** Removes the row-level filter previously set with [`cloudsync_set_filter()`](#cloudsync_set_filtertable_name-filter_expr). After clearing, all row changes in the table are tracked and replicated regardless of column values.
+
+This function updates the stored settings and immediately recreates the sync triggers without a filter condition.
+
+**Parameters:**
+
+- `table_name` (TEXT): The name of the synchronized table.
+
+**Returns:** `1` on success.
+
+**Example:**
+
+```sql
+SELECT cloudsync_clear_filter('tasks');
+```
+
+---
+
 ### `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.

CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
+## [1.0.9] - 2026-04-08
+
+### Changed
+
+- **cloudsync_init**: Replaced the `force` boolean parameter with an `init_flags` integer bitmask (`CLOUDSYNC_INIT_FLAG`), allowing fine-grained control over which schema sanity checks are skipped. Existing callers passing `0`/`false` or `1`/`true` remain compatible.
+- **API**: Updated `cloudsync_init` SQL signature (PostgreSQL) to accept `integer` instead of `boolean` for the third argument, enabling flag combinations via bitwise OR.
+
+### Added
+
+- `CLOUDSYNC_INIT_FLAG_NONE` (0), `CLOUDSYNC_INIT_FLAG_SKIP_INT_PK_CHECK` (1), `CLOUDSYNC_INIT_FLAG_SKIP_NOT_NULL_DEFAULT_CHECK` (2), `CLOUDSYNC_INIT_FLAG_SKIP_NOT_NULL_PRIKEYS_CHECK` (4) enum values.
+- Documentation for `cloudsync_set_filter` and `cloudsync_clear_filter` in API.md.
+
 ## [1.0.8] - 2026-04-03
 
 ### Changed

src/cloudsync.c

@@ -2429,7 +2429,7 @@ int cloudsync_commit_alter (cloudsync_context *data, const char *table_name) {
     // init again cloudsync for the table
     table_algo algo_current = dbutils_table_settings_get_algo(data, table_name);
     if (algo_current == table_algo_none) algo_current = dbutils_table_settings_get_algo(data, "*");
-    rc = cloudsync_init_table(data, table_name, cloudsync_algo_name(algo_current), true);
+    rc = cloudsync_init_table(data, table_name, cloudsync_algo_name(algo_current), CLOUDSYNC_INIT_FLAG_SKIP_INT_PK_CHECK);
     if (rc != DBRES_OK) goto rollback_finalize_alter;
 
     return DBRES_OK;
@@ -3278,7 +3278,7 @@ int cloudsync_payload_save (cloudsync_context *data, const char *payload_path, i
 
 // MARK: - Core -
 
-int cloudsync_table_sanity_check (cloudsync_context *data, const char *name, bool skip_int_pk_check) {
+int cloudsync_table_sanity_check (cloudsync_context *data, const char *name, CLOUDSYNC_INIT_FLAG init_flags) {
     DEBUG_DBFUNCTION("cloudsync_table_sanity_check %s", name);
     char buffer[2048];
 
@@ -3317,7 +3317,8 @@ int cloudsync_table_sanity_check (cloudsync_context *data, const char *name, boo
         return cloudsync_set_error(data, buffer, DBRES_ERROR);
     }
     #endif
-        
+    
+    bool skip_int_pk_check = (init_flags & CLOUDSYNC_INIT_FLAG_SKIP_INT_PK_CHECK) != 0;
     if (!skip_int_pk_check) {
         if (npri_keys == 1) {
             // the affinity of a column is determined by the declared type of the column,
@@ -3335,23 +3336,29 @@ int cloudsync_table_sanity_check (cloudsync_context *data, const char *name, boo
 
     // if user declared explicit primary key(s) then make sure they are all declared as NOT NULL
     #if CLOUDSYNC_CHECK_NOTNULL_PRIKEYS
-    if (npri_keys > 0) {
-        int npri_keys_notnull = database_count_pk(data, name, true, cloudsync_schema(data));
-        if (npri_keys_notnull < 0) return cloudsync_set_dberror(data);
-        if (npri_keys != npri_keys_notnull) {
-            snprintf(buffer, sizeof(buffer), "All primary keys must be explicitly declared as NOT NULL (table %s)", name);
-            return cloudsync_set_error(data, buffer, DBRES_ERROR);
+    bool skip_notnull_prikeys_check = (init_flags & CLOUDSYNC_INIT_FLAG_SKIP_NOT_NULL_PRIKEYS_CHECK) != 0;
+    if (!skip_notnull_prikeys_check) {
+        if (npri_keys > 0) {
+            int npri_keys_notnull = database_count_pk(data, name, true, cloudsync_schema(data));
+            if (npri_keys_notnull < 0) return cloudsync_set_dberror(data);
+            if (npri_keys != npri_keys_notnull) {
+                snprintf(buffer, sizeof(buffer), "All primary keys must be explicitly declared as NOT NULL (table %s)", name);
+                return cloudsync_set_error(data, buffer, DBRES_ERROR);
+            }
         }
     }
     #endif
 
     // check for columns declared as NOT NULL without a DEFAULT value.
     // Otherwise, col_merge_stmt would fail if changes to other columns are inserted first.
-    int n_notnull_nodefault = database_count_notnull_without_default(data, name, cloudsync_schema(data));
-    if (n_notnull_nodefault < 0) return cloudsync_set_dberror(data);
-    if (n_notnull_nodefault > 0) {
-        snprintf(buffer, sizeof(buffer), "All non-primary key columns declared as NOT NULL must have a DEFAULT value. (table %s)", name);
-        return cloudsync_set_error(data, buffer, DBRES_ERROR);
+    bool skip_notnull_default_check = (init_flags & CLOUDSYNC_INIT_FLAG_SKIP_NOT_NULL_DEFAULT_CHECK) != 0;
+    if (!skip_notnull_default_check) {
+        int n_notnull_nodefault = database_count_notnull_without_default(data, name, cloudsync_schema(data));
+        if (n_notnull_nodefault < 0) return cloudsync_set_dberror(data);
+        if (n_notnull_nodefault > 0) {
+            snprintf(buffer, sizeof(buffer), "All non-primary key columns declared as NOT NULL must have a DEFAULT value. (table %s)", name);
+            return cloudsync_set_error(data, buffer, DBRES_ERROR);
+        }
     }
 
     return DBRES_OK;
@@ -3440,9 +3447,9 @@ int cloudsync_terminate (cloudsync_context *data) {
     return 1;
 }
 
-int cloudsync_init_table (cloudsync_context *data, const char *table_name, const char *algo_name, bool skip_int_pk_check) {
+int cloudsync_init_table (cloudsync_context *data, const char *table_name, const char *algo_name, CLOUDSYNC_INIT_FLAG init_flags) {
     // sanity check table and its primary key(s)
-    int rc = cloudsync_table_sanity_check(data, table_name, skip_int_pk_check);
+    int rc = cloudsync_table_sanity_check(data, table_name, init_flags);
     if (rc != DBRES_OK) return rc;
 
     // init cloudsync_settings

src/cloudsync.h

@@ -18,7 +18,7 @@
 extern "C" {
 #endif
 
-#define CLOUDSYNC_VERSION                       "1.0.8"
+#define CLOUDSYNC_VERSION                       "1.0.9"
 #define CLOUDSYNC_MAX_TABLENAME_LEN             512
 
 #define CLOUDSYNC_VALUE_NOTSET                  -1
@@ -29,6 +29,13 @@ extern "C" {
 
 #define CLOUDSYNC_CHANGES_NCOLS                 9
 
+typedef enum {
+    CLOUDSYNC_INIT_FLAG_NONE                        = 0,
+    CLOUDSYNC_INIT_FLAG_SKIP_INT_PK_CHECK           = 1 << 0, // 1
+    CLOUDSYNC_INIT_FLAG_SKIP_NOT_NULL_DEFAULT_CHECK = 1 << 1, // 2
+    CLOUDSYNC_INIT_FLAG_SKIP_NOT_NULL_PRIKEYS_CHECK = 1 << 2  // 4
+} CLOUDSYNC_INIT_FLAG;
+
 // CRDT Algos
 table_algo cloudsync_algo_from_name (const char *algo_name);
 const char *cloudsync_algo_name (table_algo algo);
@@ -43,7 +50,7 @@ const char *cloudsync_context_init (cloudsync_context *data);
 void cloudsync_context_free (void *ctx);
 
 // CloudSync global
-int cloudsync_init_table (cloudsync_context *data, const char *table_name, const char *algo_name, bool skip_int_pk_check);
+int cloudsync_init_table (cloudsync_context *data, const char *table_name, const char *algo_name, CLOUDSYNC_INIT_FLAG init_flags);
 int cloudsync_cleanup (cloudsync_context *data, const char *table_name);
 int cloudsync_cleanup_all (cloudsync_context *data);
 int cloudsync_terminate (cloudsync_context *data);

src/postgresql/cloudsync--1.0.sql

@@ -55,7 +55,7 @@ RETURNS bytea
 AS 'MODULE_PATHNAME', 'cloudsync_init'
 LANGUAGE C VOLATILE;
 
-CREATE OR REPLACE FUNCTION cloudsync_init(table_name text, algo text, skip_int_pk_check boolean)
+CREATE OR REPLACE FUNCTION cloudsync_init(table_name text, algo text, init_flags integer)
 RETURNS bytea
 AS 'MODULE_PATHNAME', 'cloudsync_init'
 LANGUAGE C VOLATILE;

src/postgresql/cloudsync_postgresql.c

@@ -272,7 +272,7 @@ Datum cloudsync_db_version_next (PG_FUNCTION_ARGS) {
 
 // Internal helper for cloudsync_init - replicates dbsync_init logic from SQLite
 // Returns site_id as bytea on success, raises error on failure
-static bytea *cloudsync_init_internal (cloudsync_context *data, const char *table, const char *algo, bool skip_int_pk_check) {
+static bytea *cloudsync_init_internal (cloudsync_context *data, const char *table, const char *algo, CLOUDSYNC_INIT_FLAG init_flags) {
     bytea *result = NULL;
 
     // Connect SPI for database operations
@@ -290,7 +290,7 @@ static bytea *cloudsync_init_internal (cloudsync_context *data, const char *tabl
         }
 
         // Initialize table for sync
-        rc = cloudsync_init_table(data, table, algo, skip_int_pk_check);
+        rc = cloudsync_init_table(data, table, algo, init_flags);
         ereport(DEBUG1, (errmsg("cloudsync_init_internal cloudsync_init_table %d", rc)));
 
         if (rc == DBRES_OK) {
@@ -332,8 +332,8 @@ static bytea *cloudsync_init_internal (cloudsync_context *data, const char *tabl
     return result;
 }
 
-// cloudsync_init(table_name, [algo], [skip_int_pk_check]) - Initialize table for sync
-// Supports 1-3 arguments with defaults: algo=NULL, skip_int_pk_check=false
+// cloudsync_init(table_name, [algo], [init_flags]) - Initialize table for sync
+// Supports 1-3 arguments with defaults: algo=NULL, init_flags=CLOUDSYNC_INIT_FLAG_NONE
 PG_FUNCTION_INFO_V1(cloudsync_init);
 Datum cloudsync_init (PG_FUNCTION_ARGS) {
     if (PG_ARGISNULL(0)) {
@@ -344,7 +344,7 @@ Datum cloudsync_init (PG_FUNCTION_ARGS) {
 
     // Default values
     const char *algo = NULL;
-    bool skip_int_pk_check = false;
+    int init_flags = CLOUDSYNC_INIT_FLAG_NONE;
 
     // Handle optional arguments
     int nargs = PG_NARGS();
@@ -354,13 +354,13 @@ Datum cloudsync_init (PG_FUNCTION_ARGS) {
     }
 
     if (nargs >= 3 && !PG_ARGISNULL(2)) {
-        skip_int_pk_check = PG_GETARG_BOOL(2);
+        init_flags = PG_GETARG_INT32(2);
     }
 
     cloudsync_context *data = get_cloudsync_context();
 
     // Call internal helper and return site_id as bytea
-    bytea *result = cloudsync_init_internal(data, table, algo, skip_int_pk_check);
+    bytea *result = cloudsync_init_internal(data, table, algo, init_flags);
     PG_RETURN_BYTEA_P(result);
 }
 

src/sqlite/cloudsync_sqlite.c

@@ -858,7 +858,7 @@ void dbsync_terminate (sqlite3_context *context, int argc, sqlite3_value **argv)
 
 // MARK: -
 
-void dbsync_init (sqlite3_context *context, const char *table, const char *algo, bool skip_int_pk_check) {
+void dbsync_init (sqlite3_context *context, const char *table, const char *algo, CLOUDSYNC_INIT_FLAG init_flags) {
     cloudsync_context *data = (cloudsync_context *)sqlite3_user_data(context);
 
     int rc = database_begin_savepoint(data, "cloudsync_init");
@@ -868,7 +868,7 @@ void dbsync_init (sqlite3_context *context, const char *table, const char *algo,
         return;
     }
 
-    rc = cloudsync_init_table(data, table, algo, skip_int_pk_check);
+    rc = cloudsync_init_table(data, table, algo, init_flags);
     if (rc == SQLITE_OK) {
         rc = database_commit_savepoint(data, "cloudsync_init");
         if (rc != SQLITE_OK) {
@@ -896,23 +896,23 @@ void dbsync_init3 (sqlite3_context *context, int argc, sqlite3_value **argv) {
 
     const char *table = (const char *)database_value_text(argv[0]);
     const char *algo = (const char *)database_value_text(argv[1]);
-    bool skip_int_pk_check = (bool)database_value_int(argv[2]);
-    dbsync_init(context, table, algo, skip_int_pk_check);
+    int init_flags = database_value_int(argv[2]);
+    dbsync_init(context, table, algo, init_flags);
 }
 
 void dbsync_init2 (sqlite3_context *context, int argc, sqlite3_value **argv) {
     DEBUG_FUNCTION("cloudsync_init2");
 
     const char *table = (const char *)database_value_text(argv[0]);
     const char *algo = (const char *)database_value_text(argv[1]);
-    dbsync_init(context, table, algo, false);
+    dbsync_init(context, table, algo, CLOUDSYNC_INIT_FLAG_NONE);
 }
 
 void dbsync_init1 (sqlite3_context *context, int argc, sqlite3_value **argv) {
     DEBUG_FUNCTION("cloudsync_init1");
 
     const char *table = (const char *)database_value_text(argv[0]);
-    dbsync_init(context, table, NULL, false);
+    dbsync_init(context, table, NULL, CLOUDSYNC_INIT_FLAG_NONE);
 }
 
 // MARK: -