docs: update docs for the new managedDatabaseId arg for cloudsync_network_init

Author: andinux

.claude/commands/stress-test-sync-sqlitecloud.md

@@ -4,17 +4,15 @@ Execute a stress test against the CloudSync server using multiple concurrent loc
 
 ## Prerequisites
 - Connection string to a sqlitecloud project
-- HTTP sync server running (default: https://cloudsync-staging-testing.fly.dev)
 - Built cloudsync extension (`make` to build `dist/cloudsync.dylib`)
-- CloudSync already enabled on the test table from the SQLiteCloud dashboard
 
 ## Test Configuration
 
 ### Step 1: Gather Parameters
 
 Ask the user for the following configuration using a single question set:
 
-1. **Sync Server URL** — propose `https://cloudsync-staging-testing.fly.dev` as default
+1. **CloudSync server address** — propose `https://cloudsync.sqlite.ai` as default (this is the built-in default). If the user provides a different address, save it as `CUSTOM_ADDRESS` and use `cloudsync_network_init_custom` instead of `cloudsync_network_init`.
 2. **SQLiteCloud connection string** — format: `sqlitecloud://<host>:<port>/<db_name>?apikey=<apikey>`. If no `<db_name>` is in the path, ask the user for one or propose `test_stress_sync`.
 3. **Scale** — offer these options:
    - Small: 1K rows, 5 iterations, 2 concurrent databases
@@ -28,14 +26,11 @@ Ask the user for the following configuration using a single question set:
    ```
 
 Save these as variables:
-- `SYNC_SERVER_URL`
+- `CUSTOM_ADDRESS` (only if the user provided a non-default address)
 - `CONNECTION_STRING` (the full sqlitecloud:// connection string)
 - `DB_NAME` (database name extracted or provided)
 - `HOST` (hostname extracted from connection string)
 - `APIKEY` (apikey extracted from connection string)
-- `PROJECT_ID` (first subdomain from the host)
-- `ORG_ID` = `org_sqlitecloud`
-- `NETWORK_CONFIG` = `'{"address":"<SYNC_SERVER_URL>","database":"<DB_NAME>","projectID":"<PROJECT_ID>","organizationID":"<ORG_ID>"}'`
 - `ROWS` (number of rows per iteration)
 - `ITERATIONS` (number of delete/insert/update cycles)
 - `NUM_DBS` (number of concurrent databases)
@@ -59,7 +54,19 @@ Connect to SQLiteCloud using `~/go/bin/sqlc` (last command must be `quit`). Note
    ```
 7. Ask the user to enable CloudSync on the table from the SQLiteCloud dashboard
 
-### Step 3: Get Auth Tokens (if RLS enabled)
+### Step 3: Get Managed Database ID
+
+Now that the database and tables are created and CloudSync is enabled on the dashboard, ask the user for:
+
+1. **Managed Database ID** — the `managedDatabaseId` returned by the CloudSync service. For SQLiteCloud projects, it can be obtained from the project's OffSync page on the dashboard after enabling CloudSync on the table.
+
+Save as `MANAGED_DB_ID`.
+
+For the network init call throughout the test, use:
+- Default address: `SELECT cloudsync_network_init('<MANAGED_DB_ID>');`
+- Custom address: `SELECT cloudsync_network_init_custom('<CUSTOM_ADDRESS>', '<MANAGED_DB_ID>');`
+
+### Step 4: Get Auth Tokens (if RLS enabled)
 
 Create tokens for the test users. Create as many users as needed for the number of concurrent databases (assign 2 databases per user, or 1 per user if NUM_DBS <= 2).
 
@@ -75,7 +82,7 @@ Save each user's `token` and `userId` from the response.
 
 If RLS is disabled, skip this step — tokens are not required.
 
-### Step 4: Run the Concurrent Stress Test
+### Step 5: Run the Concurrent Stress Test
 
 Create a bash script at `/tmp/stress_test_concurrent.sh` that:
 
@@ -113,7 +120,7 @@ Create a bash script at `/tmp/stress_test_concurrent.sh` that:
 
 Run the script with a 10-minute timeout.
 
-### Step 5: Detailed Error Analysis
+### Step 6: Detailed Error Analysis
 
 After the test completes, provide a detailed breakdown:
 
@@ -122,7 +129,7 @@ After the test completes, provide a detailed breakdown:
 3. **Timeline analysis**: do errors cluster at specific iterations or spread evenly?
 4. **Read full log files** if errors are found — show the first and last 30 lines of each log with errors
 
-### Step 6: Optional — Verify Data Integrity
+### Step 7: Optional — Verify Data Integrity
 
 If the test passes (or even if some errors occurred), verify the final state:
 

.claude/commands/test-sync-roundtrip-sqlitecloud-rls.md

@@ -4,12 +4,13 @@ Execute a full roundtrip sync test between multiple local SQLite databases and t
 
 ## Prerequisites
 - Connection string to a sqlitecloud project
-- HTTP sync server running (default: https://cloudsync-staging-testing.fly.dev)
 - Built cloudsync extension (`make` to build `dist/cloudsync.dylib`)
 
-### Step 1: Get Sync Server Address
+### Step 1: Get CloudSync Parameters
 
-Ask the user for the HTTP sync server base URL. Propose `https://cloudsync-staging-testing.fly.dev` as the default. Save this as `SYNC_SERVER_URL` for use throughout the test. The full sync endpoint will be `<SYNC_SERVER_URL>/<db_name>`.
+Ask the user for:
+
+1. **CloudSync server address** — propose `https://cloudsync.sqlite.ai` as default (this is the built-in default). If the user provides a different address, save it as `CUSTOM_ADDRESS` and use `cloudsync_network_init_custom` instead of `cloudsync_network_init`.
 
 ## Test Procedure
 
@@ -51,8 +52,7 @@ Ask the user to describe the policy in plain English.
 
 ### Step 4: Get sqlitecloud connection string from User
 
-Ask the user to provide a connection string in the form of "sqlitecloud://<host>:<port>/<db_name>?apikey=<apikey>" to be later used with the sqlitecloud cli (sqlc) with `~/go/bin/sqlc "<connection_string>"`. Save the first subdomain in the connection string address as `PROJECT_ID` for use throughout the test. Use the "org_sqlitecloud" string as `ORG_ID`. 
-Save the configuration string `'{"address":"<SYNC_SERVER_URL>","database":"<db_name>","projectID":"<PROJECT_ID>","organizationID":"<ORG_ID>"}'` as `NETWORK_CONFIG` for use throughout the test.
+Ask the user to provide a connection string in the form of "sqlitecloud://<host>:<port>/<db_name>?apikey=<apikey>" to be later used with the sqlitecloud cli (sqlc) with `~/go/bin/sqlc "<connection_string>"`.
 
 ### Step 5: Setup SQLiteCloud with RLS
 
@@ -104,7 +104,19 @@ Example for "user can only access their own rows":
    -- DELETE: User can only delete rows they own
    SET RLS DATABASE <db_name> TABLE <table_name> DELETE "auth_userid() = OLD.user_id"
    ```
-8. Ask the user to enable the table from the sqlitecloud dashboard
+8. Ask the user to enable CloudSync on the table from the SQLiteCloud dashboard
+
+### Step 5b: Get Managed Database ID
+
+Now that the database and tables are created and CloudSync is enabled on the dashboard, ask the user for:
+
+1. **Managed Database ID** — the `managedDatabaseId` returned by the CloudSync service. For SQLiteCloud projects, it can be obtained from the project's OffSync page on the dashboard after enabling CloudSync on the table.
+
+Save as `MANAGED_DB_ID`.
+
+For the network init call throughout the test, use:
+- Default address: `SELECT cloudsync_network_init('<MANAGED_DB_ID>');`
+- Custom address: `SELECT cloudsync_network_init_custom('<CUSTOM_ADDRESS>', '<MANAGED_DB_ID>');`
 
 <!-- Enable CloudSync on selected tables
 
@@ -178,7 +190,7 @@ $SQLITE_BIN /tmp/sync_test_user1_a.db
 .load dist/cloudsync.dylib
 <CREATE_TABLE_query_sqlite>
 SELECT cloudsync_init('<table_name>');
-SELECT cloudsync_network_init('<NETWORK_CONFIG>');
+SELECT cloudsync_network_init('<MANAGED_DB_ID>');  -- or cloudsync_network_init_custom('<CUSTOM_ADDRESS>', '<MANAGED_DB_ID>') if using a non-default address
 SELECT cloudsync_network_set_token('<TOKEN_USER1>');
 ```
 
@@ -190,7 +202,7 @@ $SQLITE_BIN /tmp/sync_test_user1_b.db
 .load dist/cloudsync.dylib
 <CREATE_TABLE_query_sqlite>
 SELECT cloudsync_init('<table_name>');
-SELECT cloudsync_network_init('<NETWORK_CONFIG>');
+SELECT cloudsync_network_init('<MANAGED_DB_ID>');  -- or cloudsync_network_init_custom('<CUSTOM_ADDRESS>', '<MANAGED_DB_ID>') if using a non-default address
 SELECT cloudsync_network_set_token('<TOKEN_USER1>');
 ```
 
@@ -202,7 +214,7 @@ $SQLITE_BIN /tmp/sync_test_user2_a.db
 .load dist/cloudsync.dylib
 <CREATE_TABLE_query_sqlite>
 SELECT cloudsync_init('<table_name>');
-SELECT cloudsync_network_init('<NETWORK_CONFIG>');
+SELECT cloudsync_network_init('<MANAGED_DB_ID>');  -- or cloudsync_network_init_custom('<CUSTOM_ADDRESS>', '<MANAGED_DB_ID>') if using a non-default address
 SELECT cloudsync_network_set_token('<TOKEN_USER2>');
 ```
 
@@ -214,7 +226,7 @@ $SQLITE_BIN /tmp/sync_test_user2_b.db
 .load dist/cloudsync.dylib
 <CREATE_TABLE_query_sqlite>
 SELECT cloudsync_init('<table_name>');
-SELECT cloudsync_network_init('<NETWORK_CONFIG>');
+SELECT cloudsync_network_init('<MANAGED_DB_ID>');  -- or cloudsync_network_init_custom('<CUSTOM_ADDRESS>', '<MANAGED_DB_ID>') if using a non-default address
 SELECT cloudsync_network_set_token('<TOKEN_USER2>');
 ```
 
@@ -417,14 +429,14 @@ user_id UUID NOT NULL DEFAULT '00000000-0000-0000-0000-000000000000'
 ```sql
 -- WRONG: Separate sessions won't work
 -- Session 1:
-SELECT cloudsync_network_init('<NETWORK_CONFIG>');
+SELECT cloudsync_network_init('<MANAGED_DB_ID>');  -- or cloudsync_network_init_custom('<CUSTOM_ADDRESS>', '<MANAGED_DB_ID>') if using a non-default address
 SELECT cloudsync_network_set_token('...');
 -- Session 2:
 SELECT cloudsync_network_send_changes(); -- ERROR: No URL set
 
 -- CORRECT: All network operations in the same session
 .load dist/cloudsync.dylib
-SELECT cloudsync_network_init('<NETWORK_CONFIG>');
+SELECT cloudsync_network_init('<MANAGED_DB_ID>');  -- or cloudsync_network_init_custom('<CUSTOM_ADDRESS>', '<MANAGED_DB_ID>') if using a non-default address
 SELECT cloudsync_network_set_token('...');
 SELECT cloudsync_network_send_changes();
 SELECT cloudsync_terminate();

.claude/commands/test-sync-roundtrip-supabase-rls.md

@@ -4,7 +4,6 @@ Execute a full roundtrip sync test between multiple local SQLite databases and t
 
 ## Prerequisites
 - Supabase instance running (local Docker or remote)
-- HTTP sync server running (default: https://cloudsync-staging-testing.fly.dev)
 - Built cloudsync extension (`make` to build `dist/cloudsync.dylib`)
 
 ## Test Procedure
@@ -13,7 +12,7 @@ Execute a full roundtrip sync test between multiple local SQLite databases and t
 
 Ask the user for the following parameters:
 
-1. **Sync server URL**: Propose `https://cloudsync-staging-testing.fly.dev` as default. Save as `SYNC_SERVER_URL`. The full sync endpoint will be `<SYNC_SERVER_URL>/postgres`.
+1. **CloudSync server address** — propose `https://cloudsync.sqlite.ai` as default (this is the built-in default). If the user provides a different address, save it as `CUSTOM_ADDRESS` and use `cloudsync_network_init_custom` instead of `cloudsync_network_init`.
 
 2. **PostgreSQL connection string**: Propose `postgresql://supabase_admin:postgres@127.0.0.1:54322/postgres` as default. Save as `PG_CONN`. Use this for all `psql` connections throughout the test.
 
@@ -154,6 +153,16 @@ Inside psql:
 9. Initialize cloudsync: `SELECT cloudsync_init('<table_name>');`
 10. Insert some initial test data (optional, can be done via SQLite clients)
 
+### Step 5b: Get Managed Database ID
+
+Now that the database and tables are created and cloudsync is initialized, ask the user for:
+
+1. **Managed Database ID** — the `managedDatabaseId` returned by the CloudSync service. Save as `MANAGED_DB_ID`.
+
+For the network init call throughout the test, use:
+- Default address: `SELECT cloudsync_network_init('<MANAGED_DB_ID>');`
+- Custom address: `SELECT cloudsync_network_init_custom('<CUSTOM_ADDRESS>', '<MANAGED_DB_ID>');`
+
 ### Step 6: Get JWT Tokens for Two Users
 
 Get JWT tokens for both test users by running the token script twice:
@@ -191,7 +200,7 @@ $SQLITE_BIN /tmp/sync_test_user1_a.db
 .load dist/cloudsync.dylib
 <CREATE_TABLE_query_sqlite>
 SELECT cloudsync_init('<table_name>');
-SELECT cloudsync_network_init('<SYNC_SERVER_URL>/postgres');
+SELECT cloudsync_network_init('<MANAGED_DB_ID>');  -- or cloudsync_network_init_custom('<CUSTOM_ADDRESS>', '<MANAGED_DB_ID>') if using a non-default address
 SELECT cloudsync_network_set_token('<JWT_USER1>');
 ```
 
@@ -203,7 +212,7 @@ $SQLITE_BIN /tmp/sync_test_user1_b.db
 .load dist/cloudsync.dylib
 <CREATE_TABLE_query_sqlite>
 SELECT cloudsync_init('<table_name>');
-SELECT cloudsync_network_init('<SYNC_SERVER_URL>/postgres');
+SELECT cloudsync_network_init('<MANAGED_DB_ID>');  -- or cloudsync_network_init_custom('<CUSTOM_ADDRESS>', '<MANAGED_DB_ID>') if using a non-default address
 SELECT cloudsync_network_set_token('<JWT_USER1>');
 ```
 
@@ -215,7 +224,7 @@ $SQLITE_BIN /tmp/sync_test_user2_a.db
 .load dist/cloudsync.dylib
 <CREATE_TABLE_query_sqlite>
 SELECT cloudsync_init('<table_name>');
-SELECT cloudsync_network_init('<SYNC_SERVER_URL>/postgres');
+SELECT cloudsync_network_init('<MANAGED_DB_ID>');  -- or cloudsync_network_init_custom('<CUSTOM_ADDRESS>', '<MANAGED_DB_ID>') if using a non-default address
 SELECT cloudsync_network_set_token('<JWT_USER2>');
 ```
 
@@ -227,7 +236,7 @@ $SQLITE_BIN /tmp/sync_test_user2_b.db
 .load dist/cloudsync.dylib
 <CREATE_TABLE_query_sqlite>
 SELECT cloudsync_init('<table_name>');
-SELECT cloudsync_network_init('<SYNC_SERVER_URL>/postgres');
+SELECT cloudsync_network_init('<MANAGED_DB_ID>');  -- or cloudsync_network_init_custom('<CUSTOM_ADDRESS>', '<MANAGED_DB_ID>') if using a non-default address
 SELECT cloudsync_network_set_token('<JWT_USER2>');
 ```
 
@@ -485,14 +494,14 @@ Ensure column types are compatible between SQLite and PostgreSQL:
 ```sql
 -- WRONG: Separate sessions won't work
 -- Session 1:
-SELECT cloudsync_network_init('<SYNC_SERVER_URL>/postgres');
+SELECT cloudsync_network_init('<MANAGED_DB_ID>');  -- or cloudsync_network_init_custom('<CUSTOM_ADDRESS>', '<MANAGED_DB_ID>') if using a non-default address
 SELECT cloudsync_network_set_token('...');
 -- Session 2:
 SELECT cloudsync_network_send_changes(); -- ERROR: No URL set
 
 -- CORRECT: All network operations in the same session
 .load dist/cloudsync.dylib
-SELECT cloudsync_network_init('<SYNC_SERVER_URL>/postgres');
+SELECT cloudsync_network_init('<MANAGED_DB_ID>');  -- or cloudsync_network_init_custom('<CUSTOM_ADDRESS>', '<MANAGED_DB_ID>') if using a non-default address
 SELECT cloudsync_network_set_token('...');
 SELECT cloudsync_network_send_changes();
 SELECT cloudsync_terminate();

.claude/commands/test-sync-roundtrip-supabase.md

@@ -4,7 +4,6 @@ Execute a full roundtrip sync test between a local SQLite database and the local
 
 ## Prerequisites
 - Supabase instance running (local Docker or remote)
-- HTTP sync server running (default: https://cloudsync-staging-testing.fly.dev)
 - Built cloudsync extension (`make` to build `dist/cloudsync.dylib`)
 
 ## Test Procedure
@@ -13,14 +12,15 @@ Execute a full roundtrip sync test between a local SQLite database and the local
 
 Ask the user for the following parameters:
 
-1. **Sync server URL**: Propose `https://cloudsync-staging-testing.fly.dev` as default. Save as `SYNC_SERVER_URL`. The full sync endpoint will be `<SYNC_SERVER_URL>/postgres`.
+1. **CloudSync server address** — propose `https://cloudsync.sqlite.ai` as default (this is the built-in default). If the user provides a different address, save it as `CUSTOM_ADDRESS` and use `cloudsync_network_init_custom` instead of `cloudsync_network_init`.
 
 2. **PostgreSQL connection string**: Propose `postgresql://supabase_admin:postgres@127.0.0.1:54322/postgres` as default. Save as `PG_CONN`. Use this for all `psql` connections throughout the test.
 
 3. **Supabase API key** (used for JWT token generation): Propose `sb_secret_N7UND0UgjKTVK-Uodkm0Hg_xSvEMPvz` as default. Save as `SUPABASE_APIKEY`.
 
 Derive `AUTH_URL` from the PostgreSQL connection string by extracting the host and using port `54321` (Supabase GoTrue). For example, if `PG_CONN` is `postgresql://user:pass@10.0.0.5:54322/postgres`, then `AUTH_URL` is `http://10.0.0.5:54321`. For `127.0.0.1`, use `http://127.0.0.1:54321`.
 
+
 ### Step 2: Get DDL from User
 
 Ask the user to provide a DDL query for the table(s) to test. It can be in PostgreSQL or SQLite format. Offer the following options:
@@ -95,6 +95,16 @@ Inside psql:
 5. Initialize cloudsync: `SELECT cloudsync_init('<table_name>');`
 6. Insert some test data into the table
 
+### Step 5b: Get Managed Database ID
+
+Now that the database and tables are created and cloudsync is initialized, ask the user for:
+
+1. **Managed Database ID** — the `managedDatabaseId` returned by the CloudSync service. Save as `MANAGED_DB_ID`.
+
+For the network init call throughout the test, use:
+- Default address: `SELECT cloudsync_network_init('<MANAGED_DB_ID>');`
+- Custom address: `SELECT cloudsync_network_init_custom('<CUSTOM_ADDRESS>', '<MANAGED_DB_ID>');`
+
 ### Step 6: Setup SQLite
 
 Create a temporary SQLite database using the Homebrew version (IMPORTANT: system sqlite3 cannot load extensions):
@@ -112,7 +122,7 @@ Inside sqlite3:
 -- Create table with SQLite DDL
 <CREATE_TABLE_query>
 SELECT cloudsync_init('<table_name>');
-SELECT cloudsync_network_init('<SYNC_SERVER_URL>/postgres');
+SELECT cloudsync_network_init('<MANAGED_DB_ID>');  -- or cloudsync_network_init_custom('<CUSTOM_ADDRESS>', '<MANAGED_DB_ID>') if using a non-default address
 SELECT cloudsync_network_set_token('<jwt_token>');
 -- Insert test data (different from PostgreSQL to test merge)
 <INSERT_statements>

API.md

@@ -20,7 +20,7 @@ This document provides a reference for the SQLite functions provided by the `sql
   - [`cloudsync_begin_alter()`](#cloudsync_begin_altertable_name)
   - [`cloudsync_commit_alter()`](#cloudsync_commit_altertable_name)
 - [Network Functions](#network-functions)
-  - [`cloudsync_network_init()`](#cloudsync_network_initconnection_string)
+  - [`cloudsync_network_init()`](#cloudsync_network_initmanageddatabaseid)
   - [`cloudsync_network_cleanup()`](#cloudsync_network_cleanup)
   - [`cloudsync_network_set_token()`](#cloudsync_network_set_tokentoken)
   - [`cloudsync_network_set_apikey()`](#cloudsync_network_set_apikeyapikey)
@@ -287,20 +287,20 @@ SELECT cloudsync_commit_alter('my_table');
 
 ## Network Functions
 
-### `cloudsync_network_init(connection_string)`
+### `cloudsync_network_init(managedDatabaseId)`
 
-**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.
+**Description:** Initializes the `sqlite-sync` network component. This function configures the endpoints for the CloudSync service 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>`.
+- `managedDatabaseId` (TEXT): The managed database identifier returned by the CloudSync service when a new database is registered for sync. For SQLiteCloud projects, this value can be obtained from the project's OffSync page on the dashboard.
 
 **Returns:** None.
 
 **Example:**
 
 ```sql
-SELECT cloudsync_network_init('<projectid>.sqlite.cloud/<db>.sqlite');
+SELECT cloudsync_network_init('your-managed-database-id');
 ```
 
 ---

CHANGELOG.md

@@ -13,7 +13,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ### Changed
 
-- **BREAKING: `cloudsync_network_init` now accepts JSON instead of a URL string.** The new format adds `projectID` and `organizationID` fields for multi-organization CloudSync support. An `X-CloudSync-Org` header is automatically sent with every request.
+- **BREAKING: `cloudsync_network_init` now accepts a `managedDatabaseId` instead of a connection string.** The `managedDatabaseId` is returned by the CloudSync service when a new database is registered for sync. For SQLiteCloud projects, it can be obtained from the project's OffSync page on the dashboard.
 
   Before:
   ```sql
@@ -22,7 +22,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
   After:
   ```sql
-  SELECT cloudsync_network_init('{"address":"https://myproject.sqlite.cloud:443","database":"mydb.sqlite","projectID":"abc123","organizationID":"org456","apikey":"KEY"}');
+  SELECT cloudsync_network_init('your-managed-database-id');
   ```
 
 - **BREAKING: Sync functions now return structured JSON.** `cloudsync_network_send_changes`, `cloudsync_network_check_changes`, and `cloudsync_network_sync` return a JSON object instead of a plain integer. This provides richer status information including sync state, version numbers, row counts, and affected table names.