Merge branch 'main' into codex/chunked-payloads-network

andinux · web-flow · commit 83aea31fa2ff · 2026-07-06T17:09:39.000-06:00
diff --git a/README.md b/README.md
@@ -5,7 +5,7 @@
 
   <h1>SQLite-Sync</h1>
   <p><strong>Offline-first sync for SQLite, powered by CRDTs.</strong><br>
-  Local writes, conflict-free merges, real-time collaboration across devices. Sync to SQLite Cloud, PostgreSQL, or Supabase — no central coordinator required.</p>
+  Local writes, conflict-free merges, real-time collaboration across devices. Sync to SQLite Cloud, <a href="./docs/postgresql/quickstarts/postgres.md">PostgreSQL</a>, or <a href="./docs/postgresql/quickstarts/supabase-self-hosted.md">Supabase</a> — no central coordinator required.</p>
 
   <p>
     <a href="https://dashboard.sqlitecloud.io/auth/sign-in"><strong>Free managed instance →</strong></a> ·
@@ -32,15 +32,15 @@
 
 <br>
 
-> **Need a sync backend?** Plug into any PostgreSQL or Supabase instance, or use **[SQLite Cloud CloudSync](https://www.sqlite.ai/pricing)** — managed device sync with auth, ACL, and a free tier for up to 3 devices.
+> **Need a sync backend?** Plug into any [PostgreSQL](./docs/postgresql/quickstarts/postgres.md) or [self-hosted Supabase](./docs/postgresql/quickstarts/supabase-self-hosted.md) instance, or use **[SQLite Cloud CloudSync](https://www.sqlite.ai/pricing)**
 
 ---
 
 # SQLite Sync
 
 [![sqlite-sync coverage](https://img.shields.io/badge/dynamic/regex?url=https%3A%2F%2Fsqliteai.github.io%2Fsqlite-sync%2F&search=Functions%3A%3C%5C%2Ftd%3E%5Cs*%3Ctd%20class%3D%22headerCovTableEntry(?:Hi|Med|Lo)%22%3E(%5B%5Cd.%5D%2B)%26nbsp%3B%25&replace=%241%25&label=coverage&labelColor=rgb(85%2C%2085%2C%2085)%3B&color=rgb(167%2C%20252%2C%20157)%3B&link=https%3A%2F%2Fsqliteai.github.io%2Fsqlite-sync%2F)](https://sqliteai.github.io/sqlite-sync/)
 
-**SQLite Sync** is a multi-platform extension that turns any SQLite database into a **conflict-free, offline-first replica** that syncs automatically with **[SQLite Cloud](https://sqlitecloud.io/)** nodes, **PostgreSQL** servers, and **Supabase** instances. One function call is all it takes: no backend to build, no sync protocol to implement.
+**SQLite Sync** is a multi-platform extension that turns any SQLite database into a **conflict-free, offline-first replica** that syncs automatically with **[SQLite Cloud](https://sqlitecloud.io/)** nodes, **[PostgreSQL](./docs/postgresql/quickstarts/postgres.md)** servers, and **[Supabase](./docs/postgresql/quickstarts/supabase-self-hosted.md)** instances. One function call is all it takes: no backend to build, no sync protocol to implement.
 
 Built on **CRDT** (Conflict-free Replicated Data Types), it guarantees:
 
@@ -91,7 +91,7 @@ Built on **CRDT** (Conflict-free Replicated Data Types), it guarantees:
 
 ### 1. Install
 
-Download a pre-built binary from the [Releases](https://github.com/sqliteai/sqlite-sync/releases) page, or install a platform package (see [full installation guide](./docs/INSTALLATION.md) for platform-specific code examples):
+Download a pre-built binary from the [Releases](https://github.com/sqliteai/sqlite-sync/releases) page, or install a platform package (see [full installation guide](./docs/installation.md) for platform-specific code examples):
 
 | Platform | Install |
 |----------|---------|
@@ -131,6 +131,8 @@ SELECT * FROM tasks;
 
 ### 4. Sync with the cloud
 
+The example below uses SQLite Cloud CloudSync. If you are wiring up a self-hosted backend instead, use the [PostgreSQL quick start](./docs/postgresql/quickstarts/postgres.md) or the [self-hosted Supabase quick start](./docs/postgresql/quickstarts/supabase-self-hosted.md).
+
 ```sql
 -- Connect to your SQLite Cloud managed database
 -- (get the managed database ID from the OffSync page on the SQLite Cloud dashboard)
@@ -188,7 +190,7 @@ SELECT cloudsync_terminate();
 
 Back on Device A, calling `cloudsync_network_sync()` will pull Device B's changes. The CRDT engine ensures all devices converge to the same data, automatically, with no conflicts.
 
-> **Note:** every device participating in the same sync must create **the same set of tables with the same structure** and initialize each one with `cloudsync_init()`. sqlite-sync derives a schema hash from the synced tables, and the server rejects payloads whose hash it does not recognize. For multi-tenant setups where each client should see only a subset of rows, use a shared schema with a tenant/scope column and enforce isolation with [Row-Level Security](./docs/row-level-security.md) — do not give each client a different table.
+> **Note:** every device participating in the same sync must create **the same set of tables with the same structure** and initialize each one with `cloudsync_init()`. sqlite-sync derives a schema hash from the synced tables, and the server rejects payloads whose hash it does not recognize. For multi-tenant setups where each client should see only a subset of rows, use a shared schema with a tenant/scope column and enforce isolation with [RLS Overview](./docs/rls-overview.md) — do not give each client a different table.
 
 ## Block-Level LWW
 
@@ -214,21 +216,25 @@ With SQLite Cloud's RLS, a single shared cloud database serves all users while e
 - One database, multiple tenants, no per-user database provisioning.
 - Each client syncs only authorized rows, minimal bandwidth and storage.
 
-See the full guide: **[Row-Level Security Documentation](./docs/row-level-security.md)**.
+See the full guide: **[RLS Overview](./docs/rls-overview.md)**.
 
 ## Documentation
 
 - **[API Reference](./API.md)**: all functions, parameters, and examples
 - **[Performance & Overhead](./PERFORMANCE.md)**: sync cost model, payload chunking, and large-value memory notes
 - **[Installation Guide](./docs/installation.md)**: platform-specific setup (Swift, Android, Expo, React Native, Flutter, WASM)
 - **[Block-Level LWW Guide](./docs/block-lww.md)**: line-level text merge for markdown and documents
-- **[Row-Level Security Guide](./docs/row-level-security.md)**: multi-tenant access control with server-enforced policies
+- **[RLS Overview](./docs/rls-overview.md)**: conceptual guide to multi-tenant access control with server-enforced policies
+- **[Self-Hosted PostgreSQL Quick Start](./docs/postgresql/quickstarts/postgres.md)**: run CloudSync against your own PostgreSQL instance
+- **[Self-Hosted Supabase Quick Start](./docs/postgresql/quickstarts/supabase-self-hosted.md)**: run CloudSync against your own Supabase deployment
 - **[Database Schema Recommendations](./docs/schema.md)**: primary keys, constraints, foreign keys, triggers
 - **[Custom Network Layer](./docs/internal/network.md)**: replace the built-in libcurl networking
 - **[Examples](./examples/)**: complete walkthroughs (todo app, sport tracker, Swift multiplatform)
 
 ## SQLite Cloud Setup
 
+If you are not using SQLite Cloud as the sync backend, see the [self-hosted PostgreSQL quick start](./docs/postgresql/quickstarts/postgres.md) or the [self-hosted Supabase quick start](./docs/postgresql/quickstarts/supabase-self-hosted.md).
+
 1. Sign up at [SQLite Cloud](https://sqlitecloud.io/) and create a project.
 2. Create a database and your tables in the [dashboard](https://dashboard.sqlitecloud.io/).
 3. Enable synchronization: click **"OffSync"** for your database and select the tables to sync.
diff --git a/docs/block-lww.md b/docs/block-lww.md
diff --git a/docs/installation.md b/docs/installation.md
@@ -2,9 +2,9 @@
 
 Download the appropriate pre-built binary for your platform from the official [Releases](https://github.com/sqliteai/sqlite-sync/releases) page:
 
-- Linux: x86 and ARM
-- macOS: x86 and ARM
-- Windows: x86
+- Linux: x86_64 and arm64 (glibc and musl)
+- macOS: x86_64 and arm64
+- Windows: x86_64
 - Android
 - iOS
 
@@ -34,7 +34,7 @@ var stmt: OpaquePointer?
 sqlite3_prepare_v2(db, "SELECT cloudsync_version()", -1, &stmt, nil)
 defer { sqlite3_finalize(stmt) }
 sqlite3_step(stmt)
-log("cloudsync_version(): \(String(cString: sqlite3_column_text(stmt, 0)))")
+print("cloudsync_version(): \(String(cString: sqlite3_column_text(stmt, 0)))")
 sqlite3_close(db)
 ```
 
@@ -43,7 +43,7 @@ sqlite3_close(db)
 Add the [following](https://central.sonatype.com/artifact/ai.sqlite/sync) to your Gradle dependencies:
 
 ```gradle
-implementation 'ai.sqlite:sync:1.0.0'
+implementation 'ai.sqlite:sync:<latest-version>'
 ```
 
 ```java
@@ -121,6 +121,8 @@ flutter pub add sqlite_sync  # Flutter projects
 dart pub add sqlite_sync     # Dart projects
 ```
 
+Requires Dart 3.10+ / Flutter 3.38+.
+
 ```dart
 import 'package:sqlite3/sqlite3.dart';
 import 'package:sqlite_sync/sqlite_sync.dart';
diff --git a/docs/internal/postgres-flyio.md b/docs/internal/postgres-flyio.md
@@ -836,6 +836,108 @@ docker compose pull db
 docker compose up -d db
 ```
 
+### Update CloudSync from a GitHub Actions PostgreSQL artifact
+
+If you already run the Dockerized PostgreSQL setup from this guide and want to test a newer CloudSync PostgreSQL build without rebuilding and pushing a custom image, you can copy the packaged extension files into the running `db` container.
+
+1. Confirm the running PostgreSQL major version and current CloudSync version:
+
+```bash
+cd /data/cloudsync-postgres
+docker compose exec db pg_config --version
+docker compose exec db psql -U postgres -d postgres -c "SELECT cloudsync_version();"
+docker compose exec db psql -U postgres -d postgres -c "SELECT name, default_version, installed_version FROM pg_available_extensions WHERE name = 'cloudsync';"
+uname -m
+```
+
+For a standard Fly Ubuntu VM running PostgreSQL 17 on x86_64, download the artifact named:
+
+```text
+cloudsync-postgresql17-linux-x86_64
+```
+
+2. Download the artifact from the GitHub Actions run on your local machine while signed into GitHub, then upload the zip to the VM:
+
+```bash
+fly ssh sftp shell --app <your-app-name>
+```
+
+At the SFTP prompt:
+
+```text
+cd /data
+put /absolute/path/to/cloudsync-postgresql17-linux-x86_64.zip cloudsync-postgresql17-linux-x86_64.zip
+```
+
+3. SSH back into the VM, extract the package, and verify the files:
+
+```bash
+fly ssh console --app <your-app-name>
+
+apt-get update
+apt-get install -y unzip
+
+cd /data
+mkdir -p cloudsync-package
+cd cloudsync-package
+cp ../cloudsync-postgresql17-linux-x86_64.zip .
+unzip -o cloudsync-postgresql17-linux-x86_64.zip
+ls -1
+```
+
+The extracted package should contain:
+
+- `cloudsync.so`
+- `cloudsync.control`
+- `cloudsync--<version>.sql`
+- any `cloudsync--<from>--<to>.sql` upgrade scripts
+
+4. Copy those files into the running PostgreSQL container:
+
+```bash
+docker cp cloudsync.so cloudsync-postgres:/tmp/
+docker cp cloudsync.control cloudsync-postgres:/tmp/
+for f in cloudsync--*.sql; do
+  docker cp "$f" cloudsync-postgres:/tmp/
+done
+```
+
+5. Install the files into PostgreSQL's extension directories inside the container and restart it:
+
+```bash
+docker exec cloudsync-postgres sh -lc 'cp /tmp/cloudsync.so "$(pg_config --pkglibdir)/"'
+docker exec cloudsync-postgres sh -lc 'cp /tmp/cloudsync.control /tmp/cloudsync--*.sql "$(pg_config --sharedir)/extension/"'
+docker restart cloudsync-postgres
+```
+
+6. Verify the new binary version:
+
+```bash
+docker exec cloudsync-postgres psql -U postgres -d postgres -c "SELECT cloudsync_version();"
+docker exec cloudsync-postgres psql -U postgres -d postgres -c "SELECT name, default_version, installed_version FROM pg_available_extensions WHERE name = 'cloudsync';"
+```
+
+If `installed_version` is behind `default_version`, apply the PostgreSQL extension upgrade:
+
+```bash
+docker exec cloudsync-postgres psql -U postgres -d postgres -c "ALTER EXTENSION cloudsync UPDATE;"
+```
+
+Then verify again:
+
+```bash
+docker exec cloudsync-postgres psql -U postgres -d postgres -c "SELECT cloudsync_version();"
+docker exec cloudsync-postgres psql -U postgres -d postgres -c "SELECT name, default_version, installed_version FROM pg_available_extensions WHERE name = 'cloudsync';"
+```
+
+For example, after a successful `1.0.16 -> 1.1.0` upgrade you should see:
+
+- `cloudsync_version()` returns `1.1.0`
+- `default_version = 1.1`
+- `installed_version = 1.1`
+
+> **Important:** this is an in-place container modification. It survives a container restart, but it does **not** survive recreating the container from the original image. If you later run `docker compose pull`, change the image tag, or recreate `db`, you will lose the manually copied files unless the image itself already includes that newer CloudSync build.
+
 ### View logs
 
 ```bash
@@ -852,10 +954,12 @@ docker compose logs -f auth   # Auth server only
 |---------|----------|
 | `fractional_indexing.h: No such file or directory` | Run `git submodule update --init --recursive` before building |
 | `cloudsync_version()` not found | Init scripts only run on first start. Run `CREATE EXTENSION IF NOT EXISTS cloudsync;` manually |
+| `unzip: command not found` | Install it on the Fly VM first: `apt-get update && apt-get install -y unzip` |
 | Auth server won't start | Check `docker compose logs auth`. Ensure `npm install` was run in `auth-server/` |
 | Token verification fails (HS256) | Ensure `JWT_SECRET` matches exactly — CloudSync uses the raw string, not base64-decoded |
 | Token verification fails (JWKS) | Ensure CloudSync can reach the JWKS endpoint and `JWT_ISSUER` matches the `ISSUER` env var |
 | JWKS keys lost after restart | The JWKS server generates new keys on each start. For production, persist keys to a volume |
 | Docker commands not found after VM restart | Run `/data/startup.sh` — Fly VM root filesystem resets on stop/start |
 | `fuse-overlayfs` not working | Install it: `apt-get install -y fuse-overlayfs` |
+| Manual artifact upgrade disappears after `docker compose up` recreation | This method only patches the running container. Rebuild or switch to an image that already contains the new CloudSync build for a durable upgrade. |
 | Can't connect to Postgres from outside Fly | Use `fly proxy 5432:5432 -a <your-app-name>` |
diff --git a/docs/postgresql/README.md b/docs/postgresql/README.md
@@ -98,5 +98,6 @@ The PostgreSQL integration is actively evolving. Current limitations include:
 
 # Next
 * [CLIENT](client.md) installation and setup
-* [SUPABASE](integrations/supabase.md) configuration and setup
-* [SPORT-TRACKER APP](examples/sport-app-supabase.md) demo web app based on SQLite Sync WASM
+* [POSTGRES QUICK START](quickstarts/postgres.md) configuration and setup
+* [SUPABASE QUICK START](quickstarts/supabase-self-hosted.md) configuration and setup
+* [SPORT-TRACKER APP](examples/sport-tracker-app-supabase.md) demo web app based on SQLite Sync WASM
diff --git a/docs/postgresql/client.md b/docs/postgresql/client.md
diff --git a/docs/postgresql/examples/sport-tracker-app-supabase.md b/docs/postgresql/examples/sport-tracker-app-supabase.md
@@ -4,7 +4,7 @@ A Vite/React demonstration app showcasing [**SQLite Sync**](https://github.com/s
 
 > This app uses the packed WASM version of SQLite with the [SQLite Sync extension enabled](https://www.npmjs.com/package/@sqliteai/sqlite-wasm).
 
-**The source code is located in [examples/sport-tracker-app](../../examples/sport-tracker-app/)**
+**The source code is located in [examples/sport-tracker-app](../../../examples/sport-tracker-app/)**
 
 ## Setup Instructions
 
@@ -13,7 +13,7 @@ A Vite/React demonstration app showcasing [**SQLite Sync**](https://github.com/s
 
 ### 2. Database Setup
 1. Create database
-2. Execute the schema with [sport-tracker-schema-postgres.sql](../../examples/sport-tracker-app/sport-tracker-schema-postgres.sql).  
+2. Execute the schema with [sport-tracker-schema-postgres.sql](../../../examples/sport-tracker-app/sport-tracker-schema-postgres.sql).  
 3. Enable CloudSync for all tables on the remote database with:
     ```sql
     CREATE EXTENSION IF NOT EXISTS cloudsync;
@@ -40,4 +40,4 @@ npm run dev
 
 ### Demo
 
-Continue reading on the official [README](https://github.com/sqliteai/sqlite-sync/blob/main/examples/sport-tracker-app/README.md#demo-use-case-multi-user-sync-scenario). 
+Continue reading on the official [README](https://github.com/sqliteai/sqlite-sync/blob/main/examples/sport-tracker-app/README.md#demo-use-case-multi-user-sync-scenario). 
diff --git a/docs/postgresql/examples/todo-app-postgres.md b/docs/postgresql/examples/todo-app-postgres.md
@@ -16,7 +16,7 @@ cd MyApp
 
 ### 2. Setup
 
-1. Execute the exact schema from [`to-do-app.sql`](../../examples/to-do-app/to-do-app.sql).
+1. Execute the exact schema from [`to-do-app.sql`](../../../examples/to-do-app/to-do-app.sql).
 2. Enable CloudSync for all tables on the remote database with:
     ```sql
     CREATE EXTENSION IF NOT EXISTS cloudsync;
@@ -61,4 +61,3 @@ npm run ios # or android
 - **Dropdown Menu** - Select categories for tasks from a predefined list.
 - **Cross-Platform** - Works on iOS and Android
 - **Offline Support** - Works offline, syncs when connection returns
-
diff --git a/docs/rls-overview.md b/docs/rls-overview.md
@@ -1,7 +1,9 @@
-# Row-Level Security
+# RLS Overview
 
 SQLite Sync supports **Row-Level Security (RLS)** through the underlying [SQLite Cloud](https://sqlitecloud.io/) infrastructure. RLS allows you to use a **single shared cloud database** while each client only sees and modifies its own data. Policies are enforced on the server, so the security boundary is at the database level, not in application code.
 
+> **Using self-hosted PostgreSQL or Supabase?** Start with the backend-specific [RLS Reference](./postgresql/reference/rls.md) for CloudSync apply behavior, PostgreSQL roles and grants, Supabase notes, and troubleshooting.
+
 ## How It Works
 
 - Control not just who can read or write a table, but **which specific rows** they can access.
@@ -44,6 +46,6 @@ CREATE TABLE users (
 );
 ```
 
-For more schema guidelines, see [Database Schema Recommendations](./schema.md).
+For more schema guidelines, see [Database Schema Recommendations](./schema.md). If you are running a self-hosted backend, also see the PostgreSQL/Supabase [RLS Reference](./postgresql/reference/rls.md).
 
 For full RLS documentation, see the [SQLite Cloud RLS documentation](https://docs.sqlitecloud.io/docs/rls).
diff --git a/docs/schema.md b/docs/schema.md
@@ -16,7 +16,7 @@ sqlite-sync computes a **schema hash** from the synced tables and includes it in
 cloudsync operation failed: Cannot apply the received payload because the schema hash is unknown <hash>
 ```
 
-If you need different clients to see different subsets of data (for example, per-tenant or per-workspace isolation), do **not** give each client a different table. Instead, use a single shared schema and scope the data with a column such as `tenant_id` or `workspace_id`, then enforce isolation server-side with [Row-Level Security](./row-level-security.md).
+If you need different clients to see different subsets of data (for example, per-tenant or per-workspace isolation), do **not** give each client a different table. Instead, use a single shared schema and scope the data with a column such as `tenant_id` or `workspace_id`, then enforce isolation server-side with [RLS Overview](./rls-overview.md).
 
 ## Primary Key Requirements
 
diff --git a/packages/flutter/README.md b/packages/flutter/README.md
@@ -67,4 +67,4 @@ See the full [sqlite-sync API documentation](https://github.com/sqliteai/sqlite-
 
 ## License
 
-See [LICENSE](LICENSE).
+See [LICENSE](../../LICENSE.md).
