From ab10858bd4f098aa8b8801842cc6ba4c59ef34b0 Mon Sep 17 00:00:00 2001 From: Daniele Briggi Date: Thu, 24 Apr 2025 12:58:10 +0200 Subject: [PATCH 01/17] feat(accessTokens): first draft --- sqlite-cloud/platform/access-tokens.mdx | 238 ++++++++++++++++++++++++ 1 file changed, 238 insertions(+) create mode 100644 sqlite-cloud/platform/access-tokens.mdx diff --git a/sqlite-cloud/platform/access-tokens.mdx b/sqlite-cloud/platform/access-tokens.mdx new file mode 100644 index 0000000..859da93 --- /dev/null +++ b/sqlite-cloud/platform/access-tokens.mdx @@ -0,0 +1,238 @@ +--- +title: Access Tokens +description: Grant to your users, devices, tenant, access to SQLite Cloud services. +category: platform +status: publish +slug: access-tokens +--- + +# Access Token API + +Access Tokens let backend systems securely grant users, devices, tenants, etc. access to SQLite Cloud services (SQLite Sync, Weblite, etc.). These endpoints enable full token lifecycle management: creation, inspection, validation, update, and revocation. +All endpoints require authentication. Use an **API Key** or an **Access Token** via the `Authorization` header. + +--- + +## Create a New Access Token + +### `POST /v2/tokens` + +Creates a new Access Token for a specific entity. +The `entityId` refers to any kind of resource you want to associate the Access Token with. It must be a unique ID in your system. +The `expiresAt` is a date time value to set an expiration, or `null` if it doesn't expire. + +>[!note] Store the Access Token securely. It will not be shown again. + +- **Authentication**: API Key + +#### Example + +```bash +curl -X 'POST' \ + 'https://.sqlite.cloud:443/v2/tokens' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer sqlitecloud://.sqlite.cloud:8860?apikey=' \ + -d '{ + "entityId": "0195fc5b-96a6-7000-8b17-fd2420499c2c", + "name": "user-token", + "expiresAt": "2023-10-01 10:11:12" + }' +``` + +#### Example Response + +```json +{ + "data": { + "token": "134|sqla_abcdeabcdeabcdeabcdeabcdeabcde", + "access_token_id": 134, + "entityId": "0195fc5b-96a6-7000-8b17-fd2420499c2c", + "name": "user-token", + "expiresAt": "2023-10-01 10:11:12", + "createdAt": "2023-09-01 10:11:12" + } +} +``` + +--- + +## Get Current Token Details (Access Token Only) + +### `GET /v2/tokens/details` + +Retrieves metadata about the token used to authenticate the request. + +- **Authentication**: Access Token + +#### Example + +```bash +curl -X 'GET' \ + 'https://.sqlite.cloud:443/v2/tokens/details' \ + -H 'accept: application/json' \ + -H 'Authorization: Bearer 134|sqla_abcdeabcdeabcdeabcdeabcdeabcde' +``` + +#### Example Response + +```json +{ + "data": { + "access_token_id": 134, + "entityId": "0195fc5b-96a6-7000-8b17-fd2420499c2c", + "name": "user-token", + "expiresAt": "2023-10-01 10:11:12", + "createdAt": "2023-09-01 10:11:12" + } +} +``` + +--- + +## Get Token Details (Using API Key) + +### `POST /v2/tokens/details` + +Lets you inspect an Access Token using your API Key. + +- **Authentication**: API Key + +#### Example + +```bash +curl -X 'POST' \ + 'https://.sqlite.cloud:443/v2/tokens/details' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer sqlitecloud://.sqlite.cloud:8860?apikey=' \ + -d '{ + "token": "134|sqla_abcdeabcdeabcdeabcdeabcdeabcde" + }' +``` + +#### Example Response + +```json +{ + "data": { + "access_token_id": 134, + "entityId": "0195fc5b-96a6-7000-8b17-fd2420499c2c", + "name": "user-token", + "expiresAt": "2023-10-01 10:11:12", + "createdAt": "2023-09-01 10:11:12" + } +} +``` + +--- + +## Check Token Validity + +### `GET /v2/tokens/authorized` + +Checks whether the provided Access Token is valid and not expired. + +- **Authentication**: API Key or Access Token + +#### Example + +```bash +curl -X 'GET' \ + 'https://.sqlite.cloud:443/v2/tokens/authorized' \ + -H 'accept: application/json' \ + -H 'Authorization: Bearer 134|sqla_abcdeabcdeabcdeabcdeabcdeabcde' +``` + +--- + +## Update an Access Token + +### `PATCH /v2/tokens` + +Updates information of an Access Token. +The The `token` field is required; it specifies the Access Token to update. +Fields that can be updated: +- `name`. +- `expiresAt`: date time value or `null` to set no expiration. + +- **Authentication**: API Key + +#### Example + +```bash +curl -X 'PATCH' \ + 'https://.sqlite.cloud:443/v2/tokens' \ + -H 'accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer sqlitecloud://.sqlite.cloud:8860?apikey=' \ + -d '{ + "token": "134|sqla_abcdeabcdeabcdeabcdeabcdeabcde", + "name": "updated-user-token", + "expiresAt": "2024-12-31T23:59:59" + }' +``` + +--- + +## Revoke a Token + +### `DELETE /v2/tokens` + +Revokes the given token, making it immediately unusable. + +- **Authentication**: API Key, Access Token + +The `token` in the request is optional when the Access Token is used for the authentication. + +#### Example + +```bash +curl -X 'DELETE' \ + 'https://.sqlite.cloud:443/v2/tokens' \ + -H 'accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer sqlitecloud://.sqlite.cloud:8860?apikey=' \ + -d '{ + "token": "134|sqla_abcdeabcdeabcdeabcdeabcdeabcde" + }' +``` + +--- + +## List Tokens by Entity + +### `GET /v2/tokens/entities/{entityId}` + +Returns all non-expired tokens associated with the specified entity. + +- **Authentication**: API Key +- **Path Parameter**: `entityId` + +#### Example + +```bash +curl -X 'GET' \ + 'https://.sqlite.cloud:443/v2/tokens/entities/0195fc5b-96a6-7000-8b17-fd2420499c2c' \ + -H 'accept: application/json' \ + -H 'Authorization: Bearer sqlitecloud://.sqlite.cloud:8860?apikey=' +``` + +#### Example Response + +```json +{ + "data": [ + { + "name": "sqlitesync-user", + "expiresAt": "2024-11-01 00:00:00", + "createdAt": "2024-10-01 10:11:12" + }, + { + "name": "sqlitesync-user", + "expiresAt": null, + "createdAt": "2024-09-01 10:11:12" + } + ] +} +``` + +--- \ No newline at end of file From e566c1630939bb7adf50382df82dd0c9a1991797 Mon Sep 17 00:00:00 2001 From: Daniele Briggi Date: Thu, 22 May 2025 16:13:36 +0200 Subject: [PATCH 02/17] fix(tokens): minor changes --- sqlite-cloud/platform/access-tokens.mdx | 60 ++++++++++++++----------- 1 file changed, 34 insertions(+), 26 deletions(-) diff --git a/sqlite-cloud/platform/access-tokens.mdx b/sqlite-cloud/platform/access-tokens.mdx index 859da93..ec6c35c 100644 --- a/sqlite-cloud/platform/access-tokens.mdx +++ b/sqlite-cloud/platform/access-tokens.mdx @@ -1,6 +1,6 @@ --- title: Access Tokens -description: Grant to your users, devices, tenant, access to SQLite Cloud services. +description: Grant to your users, devices, tenant, access to SQLite Cloud database and services. category: platform status: publish slug: access-tokens @@ -8,7 +8,7 @@ slug: access-tokens # Access Token API -Access Tokens let backend systems securely grant users, devices, tenants, etc. access to SQLite Cloud services (SQLite Sync, Weblite, etc.). These endpoints enable full token lifecycle management: creation, inspection, validation, update, and revocation. +Access Tokens let backend systems securely grant users, devices, tenants, etc. access to SQLite Cloud database and services (SQLite Sync, Weblite, etc.). These endpoints enable full token lifecycle management: creation, inspection, validation, update, and revocation. All endpoints require authentication. Use an **API Key** or an **Access Token** via the `Authorization` header. --- @@ -17,9 +17,9 @@ All endpoints require authentication. Use an **API Key** or an **Access Token** ### `POST /v2/tokens` -Creates a new Access Token for a specific entity. -The `entityId` refers to any kind of resource you want to associate the Access Token with. It must be a unique ID in your system. -The `expiresAt` is a date time value to set an expiration, or `null` if it doesn't expire. +Creates a new Access Token for a specific user. +The `userId` refers to your user's id or any kind of resource you want to associate the Access Token to. It must be a unique ID in your system. +The `expiresAt` is a date time value to set expiration, or `null` if it doesn't expire. >[!note] Store the Access Token securely. It will not be shown again. @@ -29,12 +29,13 @@ The `expiresAt` is a date time value to set an expiration, or `null` if it doesn ```bash curl -X 'POST' \ - 'https://.sqlite.cloud:443/v2/tokens' \ + 'https://.sqlite.cloud/v2/tokens' \ -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer sqlitecloud://.sqlite.cloud:8860?apikey=' \ + -H 'Authorization: Bearer ' \ -d '{ - "entityId": "0195fc5b-96a6-7000-8b17-fd2420499c2c", + "userId": "0195fc5b-96a6-7000-8b17-fd2420499c2c", "name": "user-token", + "attributes": "{\"role\":\"myrole\"}", "expiresAt": "2023-10-01 10:11:12" }' ``` @@ -46,8 +47,9 @@ curl -X 'POST' \ "data": { "token": "134|sqla_abcdeabcdeabcdeabcdeabcdeabcde", "access_token_id": 134, - "entityId": "0195fc5b-96a6-7000-8b17-fd2420499c2c", + "userId": "0195fc5b-96a6-7000-8b17-fd2420499c2c", "name": "user-token", + "attributes": "{\"role\":\"myrole\"}", "expiresAt": "2023-10-01 10:11:12", "createdAt": "2023-09-01 10:11:12" } @@ -68,7 +70,7 @@ Retrieves metadata about the token used to authenticate the request. ```bash curl -X 'GET' \ - 'https://.sqlite.cloud:443/v2/tokens/details' \ + 'https://.sqlite.cloud/v2/tokens/details' \ -H 'accept: application/json' \ -H 'Authorization: Bearer 134|sqla_abcdeabcdeabcdeabcdeabcdeabcde' ``` @@ -79,8 +81,9 @@ curl -X 'GET' \ { "data": { "access_token_id": 134, - "entityId": "0195fc5b-96a6-7000-8b17-fd2420499c2c", + "userId": "0195fc5b-96a6-7000-8b17-fd2420499c2c", "name": "user-token", + "attributes": null, "expiresAt": "2023-10-01 10:11:12", "createdAt": "2023-09-01 10:11:12" } @@ -101,9 +104,9 @@ Lets you inspect an Access Token using your API Key. ```bash curl -X 'POST' \ - 'https://.sqlite.cloud:443/v2/tokens/details' \ + 'https://.sqlite.cloud/v2/tokens/details' \ -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer sqlitecloud://.sqlite.cloud:8860?apikey=' \ + -H 'Authorization: Bearer ' \ -d '{ "token": "134|sqla_abcdeabcdeabcdeabcdeabcdeabcde" }' @@ -115,8 +118,9 @@ curl -X 'POST' \ { "data": { "access_token_id": 134, - "entityId": "0195fc5b-96a6-7000-8b17-fd2420499c2c", + "userId": "0195fc5b-96a6-7000-8b17-fd2420499c2c", "name": "user-token", + "attributes": null, "expiresAt": "2023-10-01 10:11:12", "createdAt": "2023-09-01 10:11:12" } @@ -137,11 +141,15 @@ Checks whether the provided Access Token is valid and not expired. ```bash curl -X 'GET' \ - 'https://.sqlite.cloud:443/v2/tokens/authorized' \ + 'https://.sqlite.cloud/v2/tokens/authorized' \ -H 'accept: application/json' \ -H 'Authorization: Bearer 134|sqla_abcdeabcdeabcdeabcdeabcdeabcde' ``` +#### Example Response + +HTTP Status **204** or **401** if not valid or expired. + --- ## Update an Access Token @@ -149,7 +157,7 @@ curl -X 'GET' \ ### `PATCH /v2/tokens` Updates information of an Access Token. -The The `token` field is required; it specifies the Access Token to update. +The `token` field is required, it specifies the Access Token to update. Fields that can be updated: - `name`. - `expiresAt`: date time value or `null` to set no expiration. @@ -160,10 +168,10 @@ Fields that can be updated: ```bash curl -X 'PATCH' \ - 'https://.sqlite.cloud:443/v2/tokens' \ + 'https://.sqlite.cloud/v2/tokens' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer sqlitecloud://.sqlite.cloud:8860?apikey=' \ + -H 'Authorization: Bearer ' \ -d '{ "token": "134|sqla_abcdeabcdeabcdeabcdeabcdeabcde", "name": "updated-user-token", @@ -187,10 +195,10 @@ The `token` in the request is optional when the Access Token is used for the aut ```bash curl -X 'DELETE' \ - 'https://.sqlite.cloud:443/v2/tokens' \ + 'https://.sqlite.cloud/v2/tokens' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer sqlitecloud://.sqlite.cloud:8860?apikey=' \ + -H 'Authorization: Bearer ' \ -d '{ "token": "134|sqla_abcdeabcdeabcdeabcdeabcdeabcde" }' @@ -198,22 +206,22 @@ curl -X 'DELETE' \ --- -## List Tokens by Entity +## List Tokens by User -### `GET /v2/tokens/entities/{entityId}` +### `GET /v2/tokens/users/{userId}` -Returns all non-expired tokens associated with the specified entity. +Returns all non-expired tokens associated with the specified user. - **Authentication**: API Key -- **Path Parameter**: `entityId` +- **Path Parameter**: `userId` #### Example ```bash curl -X 'GET' \ - 'https://.sqlite.cloud:443/v2/tokens/entities/0195fc5b-96a6-7000-8b17-fd2420499c2c' \ + 'https://.sqlite.cloud/v2/tokens/users/0195fc5b-96a6-7000-8b17-fd2420499c2c' \ -H 'accept: application/json' \ - -H 'Authorization: Bearer sqlitecloud://.sqlite.cloud:8860?apikey=' + -H 'Authorization: Bearer ' ``` #### Example Response From 4c64125fc7073de23f56948b726a4c923de0b394 Mon Sep 17 00:00:00 2001 From: Daniele Briggi Date: Mon, 26 May 2025 11:59:42 +0200 Subject: [PATCH 03/17] feat(accessTokens): explain the access tokens example --- sqlite-cloud/platform/access-tokens.mdx | 273 +++++------------------- 1 file changed, 55 insertions(+), 218 deletions(-) diff --git a/sqlite-cloud/platform/access-tokens.mdx b/sqlite-cloud/platform/access-tokens.mdx index ec6c35c..cca2b33 100644 --- a/sqlite-cloud/platform/access-tokens.mdx +++ b/sqlite-cloud/platform/access-tokens.mdx @@ -8,239 +8,76 @@ slug: access-tokens # Access Token API -Access Tokens let backend systems securely grant users, devices, tenants, etc. access to SQLite Cloud database and services (SQLite Sync, Weblite, etc.). These endpoints enable full token lifecycle management: creation, inspection, validation, update, and revocation. -All endpoints require authentication. Use an **API Key** or an **Access Token** via the `Authorization` header. +Access Tokens let backend systems securely grant users, devices, tenants, etc. access to SQLite Cloud database and services (SQLite Sync, Weblite, etc.). These endpoints enable full token lifecycle management: creation, inspection, validation, update, and revocation. All endpoints require authentication. Use an **API Key** or an **Access Token** via the `Authorization` header. ---- - -## Create a New Access Token - -### `POST /v2/tokens` - -Creates a new Access Token for a specific user. -The `userId` refers to your user's id or any kind of resource you want to associate the Access Token to. It must be a unique ID in your system. -The `expiresAt` is a date time value to set expiration, or `null` if it doesn't expire. - ->[!note] Store the Access Token securely. It will not be shown again. - -- **Authentication**: API Key - -#### Example - -```bash -curl -X 'POST' \ - 'https://.sqlite.cloud/v2/tokens' \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer ' \ - -d '{ - "userId": "0195fc5b-96a6-7000-8b17-fd2420499c2c", - "name": "user-token", - "attributes": "{\"role\":\"myrole\"}", - "expiresAt": "2023-10-01 10:11:12" - }' -``` - -#### Example Response - -```json -{ - "data": { - "token": "134|sqla_abcdeabcdeabcdeabcdeabcdeabcde", - "access_token_id": 134, - "userId": "0195fc5b-96a6-7000-8b17-fd2420499c2c", - "name": "user-token", - "attributes": "{\"role\":\"myrole\"}", - "expiresAt": "2023-10-01 10:11:12", - "createdAt": "2023-09-01 10:11:12" - } -} -``` +API Documentation can be found in the **Weblite** section in the [Dashboard](https://dashboard.sqlitecloud.io). --- -## Get Current Token Details (Access Token Only) - -### `GET /v2/tokens/details` +In the repository on GitHub [sqlitecloud/examples](https://github.com/sqlitecloud/examples), we created a simple app to demonstrate how to generate and use Access Tokens. -Retrieves metadata about the token used to authenticate the request. +We’ll log in with Google, grab a token, and use it to interact with SQLite Cloud Weblite APIs. Here’s how it works. -- **Authentication**: Access Token +## Generate a new Access Token -#### Example +In the snippet below, we handle the Google Login callback when the user has completed the login on Google. Here, you can exchange the `code` with the Google Access Token and then decide what to do with it as needed. -```bash -curl -X 'GET' \ - 'https://.sqlite.cloud/v2/tokens/details' \ - -H 'accept: application/json' \ - -H 'Authorization: Bearer 134|sqla_abcdeabcdeabcdeabcdeabcdeabcde' -``` - -#### Example Response - -```json -{ - "data": { - "access_token_id": 134, - "userId": "0195fc5b-96a6-7000-8b17-fd2420499c2c", - "name": "user-token", - "attributes": null, - "expiresAt": "2023-10-01 10:11:12", - "createdAt": "2023-09-01 10:11:12" +```typescript +if (pathname === "/auth/callback") { + const q = query; + if (q.state !== STATE || !q.code) { + return send(res, 400, "Invalid state or missing code"); } -} -``` ---- - -## Get Token Details (Using API Key) - -### `POST /v2/tokens/details` - -Lets you inspect an Access Token using your API Key. - -- **Authentication**: API Key - -#### Example - -```bash -curl -X 'POST' \ - 'https://.sqlite.cloud/v2/tokens/details' \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer ' \ - -d '{ - "token": "134|sqla_abcdeabcdeabcdeabcdeabcdeabcde" - }' + try { + // Exchange code for tokens + // Store the Google Token in the database + const googleToken = await getGoogleTokens(q.code as string); + ... ``` -#### Example Response - -```json -{ - "data": { - "access_token_id": 134, - "userId": "0195fc5b-96a6-7000-8b17-fd2420499c2c", - "name": "user-token", - "attributes": null, - "expiresAt": "2023-10-01 10:11:12", - "createdAt": "2023-09-01 10:11:12" +Now we have authenticated the user, we are ready to request SQLite Cloud to create a new SQLite Cloud Access Token to assign to the this user. + +```typescript +async function getSQLiteCloudToken(userId: string) { + const payload = { + name: "test-user-token", // A name for the token, can be anything you want + userId, + expiresAt: new Date(Date.now() + 1000 * 60 * 60 * 24).toISOString(), // expires in 24 hours + }; + + const res = await fetch(SQLITE_CLOUD_API_TOKENS, { + method: "POST", + headers: { + Authorization: `Bearer ${SQLITE_CLOUD_API_KEY}`, + "Content-Type": "application/json", + }, + body: JSON.stringify(payload), + }); + if (!res.ok) { + throw new Error(`Failed to create SQLite Cloud token: ${res.statusText}`); } -} -``` - ---- - -## Check Token Validity - -### `GET /v2/tokens/authorized` - -Checks whether the provided Access Token is valid and not expired. - -- **Authentication**: API Key or Access Token - -#### Example -```bash -curl -X 'GET' \ - 'https://.sqlite.cloud/v2/tokens/authorized' \ - -H 'accept: application/json' \ - -H 'Authorization: Bearer 134|sqla_abcdeabcdeabcdeabcdeabcdeabcde' -``` - -#### Example Response - -HTTP Status **204** or **401** if not valid or expired. - ---- - -## Update an Access Token - -### `PATCH /v2/tokens` - -Updates information of an Access Token. -The `token` field is required, it specifies the Access Token to update. -Fields that can be updated: -- `name`. -- `expiresAt`: date time value or `null` to set no expiration. - -- **Authentication**: API Key - -#### Example - -```bash -curl -X 'PATCH' \ - 'https://.sqlite.cloud/v2/tokens' \ - -H 'accept: application/json' \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer ' \ - -d '{ - "token": "134|sqla_abcdeabcdeabcdeabcdeabcdeabcde", - "name": "updated-user-token", - "expiresAt": "2024-12-31T23:59:59" - }' -``` - ---- - -## Revoke a Token - -### `DELETE /v2/tokens` - -Revokes the given token, making it immediately unusable. - -- **Authentication**: API Key, Access Token - -The `token` in the request is optional when the Access Token is used for the authentication. - -#### Example - -```bash -curl -X 'DELETE' \ - 'https://.sqlite.cloud/v2/tokens' \ - -H 'accept: application/json' \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer ' \ - -d '{ - "token": "134|sqla_abcdeabcdeabcdeabcdeabcdeabcde" - }' -``` - ---- - -## List Tokens by User - -### `GET /v2/tokens/users/{userId}` - -Returns all non-expired tokens associated with the specified user. - -- **Authentication**: API Key -- **Path Parameter**: `userId` - -#### Example - -```bash -curl -X 'GET' \ - 'https://.sqlite.cloud/v2/tokens/users/0195fc5b-96a6-7000-8b17-fd2420499c2c' \ - -H 'accept: application/json' \ - -H 'Authorization: Bearer ' + return res.json(); +} ``` -#### Example Response - -```json -{ - "data": [ - { - "name": "sqlitesync-user", - "expiresAt": "2024-11-01 00:00:00", - "createdAt": "2024-10-01 10:11:12" - }, - { - "name": "sqlitesync-user", - "expiresAt": null, - "createdAt": "2024-09-01 10:11:12" - } - ] -} +In the response JSON, the `data.token` field contains the Access Token. + +Finally, the user is authorized to securely access SQLite Cloud services like the Weblite API to perform a query on the database: + +```typescript +const res = await fetch(sqliteCloudApiQuery, { + method: "POST", + headers: { + Authorization: "Bearer " + sqliteCloudToken, + "Content-Type": "application/json", + }, + body: JSON.stringify({ + sql: "USE DATABASE chinook.sqlite;SELECT * FROM artists LIMIT 10;", + }), +}); +... ``` ---- \ No newline at end of file +The results depend on the [Row Level Security](https://) you enabled for the tables. From 1e5e1f2219f44b8444100952d1d3f8c439bc2b42 Mon Sep 17 00:00:00 2001 From: Daniele Briggi Date: Mon, 26 May 2025 12:18:57 +0200 Subject: [PATCH 04/17] fix(accessTokens): missing nav reference --- sqlite-cloud/_nav.ts | 6 ++++++ sqlite-cloud/platform/access-tokens.mdx | 2 -- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/sqlite-cloud/_nav.ts b/sqlite-cloud/_nav.ts index 1c4f14b..7a3e559 100644 --- a/sqlite-cloud/_nav.ts +++ b/sqlite-cloud/_nav.ts @@ -77,6 +77,12 @@ const sidebarNav: SidebarNavStruct = [ type: "inner", level: 0, }, + { + title: "Access Tokens", + filePath: "access-tokens", + type: "inner", + level: 0, + }, { title: "Backups", filePath: "backups", type: "inner", level: 0 }, { title: "Query Analyzer", filePath: "analyzer", type: "inner", level: 0 }, { title: "Extensions", filePath: "extensions", type: "inner", level: 0 }, diff --git a/sqlite-cloud/platform/access-tokens.mdx b/sqlite-cloud/platform/access-tokens.mdx index cca2b33..e7850d9 100644 --- a/sqlite-cloud/platform/access-tokens.mdx +++ b/sqlite-cloud/platform/access-tokens.mdx @@ -6,8 +6,6 @@ status: publish slug: access-tokens --- -# Access Token API - Access Tokens let backend systems securely grant users, devices, tenants, etc. access to SQLite Cloud database and services (SQLite Sync, Weblite, etc.). These endpoints enable full token lifecycle management: creation, inspection, validation, update, and revocation. All endpoints require authentication. Use an **API Key** or an **Access Token** via the `Authorization` header. API Documentation can be found in the **Weblite** section in the [Dashboard](https://dashboard.sqlitecloud.io). From fd5da604a9783d38d2f0f8cc4edae4ae005f1d0c Mon Sep 17 00:00:00 2001 From: Daniele Briggi Date: Mon, 26 May 2025 12:32:15 +0200 Subject: [PATCH 05/17] fix(accessTokens): typos --- sqlite-cloud/platform/access-tokens.mdx | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/sqlite-cloud/platform/access-tokens.mdx b/sqlite-cloud/platform/access-tokens.mdx index e7850d9..d46f390 100644 --- a/sqlite-cloud/platform/access-tokens.mdx +++ b/sqlite-cloud/platform/access-tokens.mdx @@ -8,16 +8,16 @@ slug: access-tokens Access Tokens let backend systems securely grant users, devices, tenants, etc. access to SQLite Cloud database and services (SQLite Sync, Weblite, etc.). These endpoints enable full token lifecycle management: creation, inspection, validation, update, and revocation. All endpoints require authentication. Use an **API Key** or an **Access Token** via the `Authorization` header. -API Documentation can be found in the **Weblite** section in the [Dashboard](https://dashboard.sqlitecloud.io). +The API Documentation for the Access Tokens API can be found in the **Weblite** section in the [Dashboard](https://dashboard.sqlitecloud.io). --- +## Example App + In the repository on GitHub [sqlitecloud/examples](https://github.com/sqlitecloud/examples), we created a simple app to demonstrate how to generate and use Access Tokens. We’ll log in with Google, grab a token, and use it to interact with SQLite Cloud Weblite APIs. Here’s how it works. -## Generate a new Access Token - In the snippet below, we handle the Google Login callback when the user has completed the login on Google. Here, you can exchange the `code` with the Google Access Token and then decide what to do with it as needed. ```typescript @@ -34,7 +34,7 @@ if (pathname === "/auth/callback") { ... ``` -Now we have authenticated the user, we are ready to request SQLite Cloud to create a new SQLite Cloud Access Token to assign to the this user. +Now we have authenticated the user, we are ready to request SQLite Cloud to create a new SQLite Cloud Access Token assigned to this user. ```typescript async function getSQLiteCloudToken(userId: string) { @@ -44,7 +44,7 @@ async function getSQLiteCloudToken(userId: string) { expiresAt: new Date(Date.now() + 1000 * 60 * 60 * 24).toISOString(), // expires in 24 hours }; - const res = await fetch(SQLITE_CLOUD_API_TOKENS, { + const res = await fetch("https:///v2/tokens", { method: "POST", headers: { Authorization: `Bearer ${SQLITE_CLOUD_API_KEY}`, @@ -65,7 +65,7 @@ In the response JSON, the `data.token` field contains the Access Token. Finally, the user is authorized to securely access SQLite Cloud services like the Weblite API to perform a query on the database: ```typescript -const res = await fetch(sqliteCloudApiQuery, { +const res = await fetch("https:///v2/weblite/sql", { method: "POST", headers: { Authorization: "Bearer " + sqliteCloudToken, @@ -78,4 +78,4 @@ const res = await fetch(sqliteCloudApiQuery, { ... ``` -The results depend on the [Row Level Security](https://) you enabled for the tables. +The result depends on the [Row Level Security](https://) you enabled for the tables. From ed7b1f4cd63942b3dd9c17753b95f36311a9412e Mon Sep 17 00:00:00 2001 From: Daniele Briggi Date: Mon, 26 May 2025 12:38:19 +0200 Subject: [PATCH 06/17] fix(accessTokens): typos --- sqlite-cloud/platform/access-tokens.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sqlite-cloud/platform/access-tokens.mdx b/sqlite-cloud/platform/access-tokens.mdx index d46f390..7ed23c1 100644 --- a/sqlite-cloud/platform/access-tokens.mdx +++ b/sqlite-cloud/platform/access-tokens.mdx @@ -12,7 +12,7 @@ The API Documentation for the Access Tokens API can be found in the **Weblite** --- -## Example App +## Example Using SQLite Cloud Access Tokens with Google Login In the repository on GitHub [sqlitecloud/examples](https://github.com/sqlitecloud/examples), we created a simple app to demonstrate how to generate and use Access Tokens. From 591fab0a94179131a0db49893e1eb682c743c7c8 Mon Sep 17 00:00:00 2001 From: Andrea Donetti Date: Mon, 14 Jul 2025 10:34:01 +0200 Subject: [PATCH 07/17] add new docs page for RLS --- sqlite-cloud/_nav.ts | 6 + sqlite-cloud/platform/rls.mdx | 228 ++++++++++++++++++++++++++++++++++ 2 files changed, 234 insertions(+) create mode 100644 sqlite-cloud/platform/rls.mdx diff --git a/sqlite-cloud/_nav.ts b/sqlite-cloud/_nav.ts index bc3d317..de07b69 100644 --- a/sqlite-cloud/_nav.ts +++ b/sqlite-cloud/_nav.ts @@ -77,6 +77,12 @@ const sidebarNav: SidebarNavStruct = [ type: "inner", level: 0, }, + { + title: "Row-Level Security", + filePath: "rls", + type: "inner", + level: 0, + }, { title: "Access Tokens", filePath: "access-tokens", diff --git a/sqlite-cloud/platform/rls.mdx b/sqlite-cloud/platform/rls.mdx new file mode 100644 index 0000000..8fd6ee6 --- /dev/null +++ b/sqlite-cloud/platform/rls.mdx @@ -0,0 +1,228 @@ +--- +title: Row-Level Security +description: Configure fine-grained access control policies to determine which rows in a table a user can access. +category: platform +status: publish +slug: rls +--- + +import Callout from "@commons-components/Information/Callout.astro"; + +Row-Level Security (RLS) allows you to define fine-grained access control policies that determine which rows in a table a user can access. This ensures that users can only view or modify data they are authorized to see, enhancing data security and privacy. + + +RLS rules only affect users who are authenticated using tokens. Admins, APIKEYs, or other non-token users are not restricted by RLS. + + +RLS is a powerful feature for building secure, multi-tenant applications. When combined with [SQLite Sync](https://github.com/sqliteai/sqlite-sync), it enables you to create robust **local-first apps** where user data is stored on the device for offline availability and superior performance. + +This architecture simplifies development by allowing your application to interact with a local database while SQLite Cloud transparently handles the synchronization with a central database. RLS ensures that each user's data is securely isolated during this process. The centralized database can then be used for powerful business analytics and reporting across all tenants, without compromising individual data privacy. + +## Policy Enforcement + +RLS in SQLite Cloud operates based on the following principles: + +Access is denied by default. + +Unless explicitly allowed by RLS rules, access is blocked. Specifically: + +- If RLS is enabled and rules are defined, only permitted operations will succeed. +- If RLS is enabled but a rule is missing for an operation (e.g., `SELECT`), that operation will be denied. +- If RLS is not enabled or not configured for a table, token-authenticated users won't see any rows at all. + +To make data accessible to token-authenticated users, you must both enable RLS for the table and define rules for the desired operations (like `SELECT`, `INSERT`, etc.). + +Otherwise, they will be blocked from accessing any rows. + +## Configuring RLS + +You can configure RLS policies for your databases through the SQLite Cloud dashboard. + +1. **Navigate to the Databases Page**: From the main dashboard, go to the "Databases" page. +2. **Select the RLS Column**: In the list of your databases, click on the button in the "RLS" column for the desired database. + + ![Dashboard Databases Page](@docs-website-assets/introduction/rls-1.png) + +3. **Configure RLS Settings**: On the RLS settings page, you can define the policies for each table. + + ![Dashboard RLS Settings Page](@docs-website-assets/introduction/rls-2.png) + + For each table, you can specify the following RLS policies: + + - **SELECT**: A SQL expression that determines which rows a user can `SELECT`. + - **INSERT**: A SQL expression that determines if a user can `INSERT` a new row. + - **UPDATE**: A SQL expression that determines which rows a user can `UPDATE`. + - **DELETE**: A SQL expression that determines which rows a user can `DELETE`. + + + The SQL expressions can be any valid SQLite expression that returns a boolean value. You can use built-in SQLite functions, and even custom functions to define your policies. + + +### User Information Functions + +To help you create dynamic RLS policies, SQLite Cloud provides two functions to retrieve information about the current authenticated user: + +- `auth_userid()`: Returns the `userid` of the current token-authenticated user. +- `auth_json()`: Returns a JSON object with all the details of the current token-authenticated user, including `user_id`, `name`, `attributes`, `created_at`, and `expires_at`. + +These functions are particularly useful for creating policies that are based on user attributes. + +For more information on Access Tokens, see the [Access Tokens documentation](/docs/access-tokens). The API Documentation for the Access Tokens API can be found in the Weblite section in the [Dashboard](https://dashboard.sqlitecloud.io/). + +### OLD and NEW References + +Your RLS policies for `INSERT`, `UPDATE`, and `DELETE` operations can reference column values as they are being changed. This is done using the special `OLD.column` and `NEW.column` identifiers. Their availability and meaning depend on the operation being performed: + +| Operation | `OLD.column` Reference | `NEW.column` Reference | +| :--- | :--- | :--- | +| `INSERT` | Not available | The value for the new row. | +| `UPDATE` | The value of the row *before* the update. | The value of the row *after* the update. | +| `DELETE` | The value of the row being deleted. | Not available | + +## Example + +Suppose you have a `tasks` table with the following schema: + +```sql +CREATE TABLE tasks ( + id INTEGER PRIMARY KEY, + title TEXT, + owner_id INTEGER, + status TEXT +); +``` + +Here are a few examples of RLS policies you can create: + +**1. Users can only see their own tasks.** + +```sql +-- SELECT policy +owner_id = auth_userid() +``` + +**2. Users can only insert tasks for themselves.** + +```sql +-- INSERT policy +NEW.owner_id = auth_userid() +``` + +**3. Users can only update the status of their own tasks.** + +```sql +-- UPDATE policy +OLD.owner_id = auth_userid() +``` + +**4. Users with the 'admin' group can see all tasks.** + +```sql +-- SELECT policy +json_extract(auth_json(), '$.attributes.group') = 'admin' +``` + +**5. Role-Based Access within a Tenancy** + +```sql +-- SELECT policy +org_id = json_extract(auth_json(), '$.attributes.org_id') AND +(json_extract(auth_json(), '$.attributes.role') = 'admin' OR owner_id = auth_userid()) +``` + +**6. Access via a Membership Linking Table** + +```sql +-- SELECT policy +EXISTS ( + SELECT 1 FROM project_members + WHERE project_members.project_id = tasks.project_id + AND project_members.user_id = auth_userid() +) +``` + +**7. Public vs. Private Record Visibility** + +```sql +-- SELECT policy +visibility = 'public' OR owner_id = auth_userid() +``` + +With these policies, when a user executes a query, SQLite Cloud will automatically enforce the defined RLS rules, ensuring data security and compliance. + +### Additional Real-World Examples + +Here are a few more examples to illustrate how you can use RLS policies to solve common security challenges. + +#### 1. Team-Based Access (Multi-Tenancy) + +**Use Case:** A user should only be able to see documents that belong to their organization or team. This is a classic multi-tenancy scenario. + +**Assumptions:** +* Your `documents` table has an `org_id` column. +* The user's access token contains their organization ID in the JSON attributes (e.g., `{"org_id": "acme_corp"}`). + +**RLS Policy (`SELECT`):** +```sql +-- On the 'documents' table +org_id = json_extract(auth_json(), '$.attributes.org_id') +``` + +**Explanation:** +This policy ensures that the `org_id` in the document row must match the `org_id` stored in the authenticated user's token. This effectively isolates data between different organizations. + +--- + +#### 2. Content Publishing Workflow + +**Use Case:** In a simple CMS or blog, any user (even anonymous ones, if applicable) can see articles with a `published` status. However, only the original author can see their own articles when they are in the `draft` status. + +**Assumptions:** +* Your `articles` table has a `status` column (`'draft'` or `'published'`) and an `author_id` column. + +**RLS Policy (`SELECT`):** +```sql +-- On the 'articles' table +status = 'published' OR (status = 'draft' AND author_id = auth_userid()) +``` + +**Explanation:** +This policy uses a boolean `OR` to combine two conditions. A user can see a row if: +1. The article's status is `published`, OR +2. The article's status is `draft` AND the user is the author. + +--- + +#### 3. Making Records Read-Only + +**Use Case:** Once an invoice has been marked as `paid`, it should become immutable. No user should be able to update it. + +**Assumptions:** +* Your `invoices` table has a `status` column (`'pending'`, `'paid'`, etc.). + +**RLS Policy (`UPDATE`):** +```sql +-- On the 'invoices' table +OLD.status <> 'paid' +``` + +**Explanation:** +This policy uses the `OLD` reference to check the value of the `status` column *before* the update is applied. If the status is already `'paid'`, the condition `OLD.status <> 'paid'` will be false, and the `UPDATE` operation will be denied. This effectively makes paid invoices read-only. + +### Advanced: RLS and SQLite Sync + +When using RLS in conjunction with [SQLite Sync](https://github.com/sqliteai/sqlite-sync), it's important to understand how they interact. The Sync protocol applies changes on a column-by-column basis, which can affect how `INSERT` and `UPDATE` policies are evaluated. + +To accommodate this, SQLite Cloud offers two modes for handling RLS during sync operations, configurable via the `rls_mode` server setting. + +#### Default Mode (`rls_mode = 1`) + +To simplify policy creation for the most common use cases, the default mode does **not** enforce `INSERT` and `UPDATE` policies while applying changes from SQLite Sync. + +Instead, after the sync operation is complete, the `SELECT` policy is used to validate the final state of the row. If the user does not have permission to view the resulting row, the entire transaction is rolled back. This ensures that users cannot introduce changes that they are not allowed to see. + +#### Manual Policy Mode (`rls_mode = 0`) + +For more complex scenarios, such as implementing separate read/write permissions or restricting write access to specific columns, you can set `rls_mode` to `0`. + +In this mode, your `INSERT` and `UPDATE` policies are enforced for every incremental change applied by SQLite Sync. Because of Sync's column-by-column operation, your policies must be written to permit intermediate states. This means the policies must allow `NEW` values for non-primary key columns to be temporarily set to their default values during the sync process. From 65460dd93ec1af9f1bfe2c3851b9c86b1919316b Mon Sep 17 00:00:00 2001 From: TizianoT Date: Mon, 14 Jul 2025 11:12:32 +0200 Subject: [PATCH 08/17] removed readme from build --- README.md => _README.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename README.md => _README.md (100%) diff --git a/README.md b/_README.md similarity index 100% rename from README.md rename to _README.md From a2e991bc6ecd29064f6858ff7aa7b3a1bc193dbb Mon Sep 17 00:00:00 2001 From: TizianoT Date: Mon, 14 Jul 2025 11:16:00 +0200 Subject: [PATCH 09/17] trigger build --- _README.md => README.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename _README.md => README.md (100%) diff --git a/_README.md b/README.md similarity index 100% rename from _README.md rename to README.md From 38ea40a3de1f7b1460355a897f65b5ffe3c28f72 Mon Sep 17 00:00:00 2001 From: TizianoT Date: Mon, 14 Jul 2025 11:25:55 +0200 Subject: [PATCH 10/17] trigger build --- sqlite-cloud/platform/_wip-index-with-card.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/sqlite-cloud/platform/_wip-index-with-card.mdx b/sqlite-cloud/platform/_wip-index-with-card.mdx index 875df1e..3aba1f5 100644 --- a/sqlite-cloud/platform/_wip-index-with-card.mdx +++ b/sqlite-cloud/platform/_wip-index-with-card.mdx @@ -11,6 +11,8 @@ import IndexPage from "@docs-website-components/Docs/IndexPage.astro" export const introduction = "SQLite Cloud is a distributed relational database system built on top of the SQLite database engine. It has been specifically designed from the ground up to ensure the strong consistency of your data across all nodes in a cluster while simultaneously managing the technical aspects of scaling, security, and data distribution." + + export const sections = [ { icon: "puzzle", From 7d41d138bb3e55ea085370a380332b86edee8650 Mon Sep 17 00:00:00 2001 From: Andrea Donetti Date: Mon, 14 Jul 2025 14:26:10 +0200 Subject: [PATCH 11/17] Update rls.mdx --- sqlite-cloud/platform/rls.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sqlite-cloud/platform/rls.mdx b/sqlite-cloud/platform/rls.mdx index 8fd6ee6..75bcba3 100644 --- a/sqlite-cloud/platform/rls.mdx +++ b/sqlite-cloud/platform/rls.mdx @@ -11,7 +11,7 @@ import Callout from "@commons-components/Information/Callout.astro"; Row-Level Security (RLS) allows you to define fine-grained access control policies that determine which rows in a table a user can access. This ensures that users can only view or modify data they are authorized to see, enhancing data security and privacy. -RLS rules only affect users who are authenticated using tokens. Admins, APIKEYs, or other non-token users are not restricted by RLS. +RLS rules only affect users who are authenticated using [Access Tokens](/docs/access-tokens). Admins, APIKEYs, or other non-token users are not restricted by RLS. RLS is a powerful feature for building secure, multi-tenant applications. When combined with [SQLite Sync](https://github.com/sqliteai/sqlite-sync), it enables you to create robust **local-first apps** where user data is stored on the device for offline availability and superior performance. @@ -213,7 +213,7 @@ This policy uses the `OLD` reference to check the value of the `status` column * When using RLS in conjunction with [SQLite Sync](https://github.com/sqliteai/sqlite-sync), it's important to understand how they interact. The Sync protocol applies changes on a column-by-column basis, which can affect how `INSERT` and `UPDATE` policies are evaluated. -To accommodate this, SQLite Cloud offers two modes for handling RLS during sync operations, configurable via the `rls_mode` server setting. +To accommodate this, SQLite Cloud offers two modes for handling RLS during sync operations, configurable via the `rls_mode` server setting using the SQLite Cloud builtin command `SET KEY rls_mode TO `. #### Default Mode (`rls_mode = 1`) From 172d78d1cb39d48c5a91f732ae3bd4e250b4d4da Mon Sep 17 00:00:00 2001 From: Andrea Donetti Date: Wed, 16 Jul 2025 15:24:50 +0200 Subject: [PATCH 12/17] add offsync doc --- sqlite-cloud/_nav.ts | 1 + sqlite-cloud/platform/offsync.mdx | 42 +++++++++++++++++++++++++++++++ 2 files changed, 43 insertions(+) create mode 100644 sqlite-cloud/platform/offsync.mdx diff --git a/sqlite-cloud/_nav.ts b/sqlite-cloud/_nav.ts index de07b69..68e3b77 100644 --- a/sqlite-cloud/_nav.ts +++ b/sqlite-cloud/_nav.ts @@ -83,6 +83,7 @@ const sidebarNav: SidebarNavStruct = [ type: "inner", level: 0, }, + { title: "Offsync", filePath: "offsync", type: "inner", level: 0 }, { title: "Access Tokens", filePath: "access-tokens", diff --git a/sqlite-cloud/platform/offsync.mdx b/sqlite-cloud/platform/offsync.mdx new file mode 100644 index 0000000..f63b6d7 --- /dev/null +++ b/sqlite-cloud/platform/offsync.mdx @@ -0,0 +1,42 @@ +--- +title: Offsync +description: Enable local-first applications with automatic data synchronization between edge devices and SQLite Cloud. +category: platform +status: publish +slug: offsync +--- + +import Callout from "@commons-components/Information/Callout.astro"; + +Offsync is a powerful SQLite Cloud feature that enables true **local-first** data synchronization for your applications. Powered by the [SQLite Sync](https://github.com/sqliteai/sqlite-sync) extension, it allows you to build robust, offline-capable applications where data is stored and processed on edge devices and seamlessly synchronized with a central SQLite Cloud database. + +This architecture is ideal for mobile apps, IoT devices, and any application requiring high availability and low latency, even with intermittent network connectivity. By leveraging Conflict-free Replicated Data Types (CRDTs), Offsync ensures that changes made offline are merged automatically and without conflicts when the device reconnects. + +## How It Works + +Offsync extends standard SQLite tables with built-in support for offline work and automatic synchronization. This allows multiple devices to operate independently and then seamlessly merge their changes. + +- **Offline-First by Design**: Applications work seamlessly even when devices are offline. Changes are queued locally and synced automatically when connectivity is restored. +- **CRDT-Based Conflict Resolution**: Merges updates deterministically and efficiently, ensuring eventual consistency across all replicas without complex merge logic. +- **Seamless Integration**: The sync layer is tightly integrated with SQLite Cloud, enabling secure data sharing across devices, users, and platforms. + +When combined with [Row-Level Security (RLS)](/docs/sqlite-cloud/platform/rls), Offsync allows you to build secure, multi-tenant applications where each user's data is safely isolated, both on the edge and in the cloud. + +## Configuring Offsync + +You can enable and manage Offsync for your databases directly from the SQLite Cloud dashboard. + +1. **Navigate to the Databases Page**: From the main dashboard, go to the "Databases" page. +2. **Select the Offsync Column**: In the list of your databases, click on the button in the "Offsync" column for the desired database. + + ![Dashboard Databases Page](@docs-website-assets/introduction/offsync-1.png) + +3. **Enable Tables for Synchronization**: On the Offsync settings page, you will see a list of all tables in your database. Toggle the switch next to each table you want to enable for synchronization. + + ![Dashboard Offsync Settings Page](@docs-website-assets/introduction/offsync-2.png) + + +For Offsync to work correctly, the list of tables configured for synchronization—and their corresponding schemas—must be identical in both your local SQLite database and your SQLite Cloud database. + + +Once enabled, any changes made to the selected tables via the SQLite Sync extension will be automatically synchronized with your SQLite Cloud database. From 5a4dcac386a9471c47c4f78b6d3eadb62acc09ec Mon Sep 17 00:00:00 2001 From: Andrea Donetti Date: Wed, 16 Jul 2025 15:31:09 +0200 Subject: [PATCH 13/17] add a link to offsync doc --- sqlite-cloud/platform/rls.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sqlite-cloud/platform/rls.mdx b/sqlite-cloud/platform/rls.mdx index 75bcba3..b1034e2 100644 --- a/sqlite-cloud/platform/rls.mdx +++ b/sqlite-cloud/platform/rls.mdx @@ -16,7 +16,7 @@ RLS rules only affect users who are authenticated using [Access Tokens](/docs/ac RLS is a powerful feature for building secure, multi-tenant applications. When combined with [SQLite Sync](https://github.com/sqliteai/sqlite-sync), it enables you to create robust **local-first apps** where user data is stored on the device for offline availability and superior performance. -This architecture simplifies development by allowing your application to interact with a local database while SQLite Cloud transparently handles the synchronization with a central database. RLS ensures that each user's data is securely isolated during this process. The centralized database can then be used for powerful business analytics and reporting across all tenants, without compromising individual data privacy. +This architecture simplifies development by allowing your application to interact with a local database while SQLite Cloud [OffSync](/docs/offsync) transparently handles the synchronization with a central database. RLS ensures that each user's data is securely isolated during this process. The centralized database can then be used for powerful business analytics and reporting across all tenants, without compromising individual data privacy. ## Policy Enforcement From 2a1ad8ebef045ad2c8e5be1c8ca9183444cf15a6 Mon Sep 17 00:00:00 2001 From: Andrea Donetti Date: Wed, 16 Jul 2025 15:31:25 +0200 Subject: [PATCH 14/17] fix rls link --- sqlite-cloud/platform/offsync.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sqlite-cloud/platform/offsync.mdx b/sqlite-cloud/platform/offsync.mdx index f63b6d7..584a61a 100644 --- a/sqlite-cloud/platform/offsync.mdx +++ b/sqlite-cloud/platform/offsync.mdx @@ -20,7 +20,7 @@ Offsync extends standard SQLite tables with built-in support for offline work an - **CRDT-Based Conflict Resolution**: Merges updates deterministically and efficiently, ensuring eventual consistency across all replicas without complex merge logic. - **Seamless Integration**: The sync layer is tightly integrated with SQLite Cloud, enabling secure data sharing across devices, users, and platforms. -When combined with [Row-Level Security (RLS)](/docs/sqlite-cloud/platform/rls), Offsync allows you to build secure, multi-tenant applications where each user's data is safely isolated, both on the edge and in the cloud. +When combined with [Row-Level Security (RLS)](/docs/rls), Offsync allows you to build secure, multi-tenant applications where each user's data is safely isolated, both on the edge and in the cloud. ## Configuring Offsync From 6c7ee4f7c327b326d39583b07308d47a4bececf4 Mon Sep 17 00:00:00 2001 From: Andrea Donetti Date: Wed, 16 Jul 2025 15:43:13 +0200 Subject: [PATCH 15/17] fix: use the correct casing for OffSync --- sqlite-cloud/_nav.ts | 2 +- sqlite-cloud/platform/offsync.mdx | 16 ++++++++-------- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/sqlite-cloud/_nav.ts b/sqlite-cloud/_nav.ts index 68e3b77..074c2cc 100644 --- a/sqlite-cloud/_nav.ts +++ b/sqlite-cloud/_nav.ts @@ -83,7 +83,7 @@ const sidebarNav: SidebarNavStruct = [ type: "inner", level: 0, }, - { title: "Offsync", filePath: "offsync", type: "inner", level: 0 }, + { title: "OffSync", filePath: "offsync", type: "inner", level: 0 }, { title: "Access Tokens", filePath: "access-tokens", diff --git a/sqlite-cloud/platform/offsync.mdx b/sqlite-cloud/platform/offsync.mdx index 584a61a..2924156 100644 --- a/sqlite-cloud/platform/offsync.mdx +++ b/sqlite-cloud/platform/offsync.mdx @@ -1,5 +1,5 @@ --- -title: Offsync +title: OffSync description: Enable local-first applications with automatic data synchronization between edge devices and SQLite Cloud. category: platform status: publish @@ -8,23 +8,23 @@ slug: offsync import Callout from "@commons-components/Information/Callout.astro"; -Offsync is a powerful SQLite Cloud feature that enables true **local-first** data synchronization for your applications. Powered by the [SQLite Sync](https://github.com/sqliteai/sqlite-sync) extension, it allows you to build robust, offline-capable applications where data is stored and processed on edge devices and seamlessly synchronized with a central SQLite Cloud database. +OffSync is a powerful SQLite Cloud feature that enables true **local-first** data synchronization for your applications. Powered by the [SQLite Sync](https://github.com/sqliteai/sqlite-sync) extension, it allows you to build robust, offline-capable applications where data is stored and processed on edge devices and seamlessly synchronized with a central SQLite Cloud database. -This architecture is ideal for mobile apps, IoT devices, and any application requiring high availability and low latency, even with intermittent network connectivity. By leveraging Conflict-free Replicated Data Types (CRDTs), Offsync ensures that changes made offline are merged automatically and without conflicts when the device reconnects. +This architecture is ideal for mobile apps, IoT devices, and any application requiring high availability and low latency, even with intermittent network connectivity. By leveraging Conflict-free Replicated Data Types (CRDTs), OffSync ensures that changes made offline are merged automatically and without conflicts when the device reconnects. ## How It Works -Offsync extends standard SQLite tables with built-in support for offline work and automatic synchronization. This allows multiple devices to operate independently and then seamlessly merge their changes. +OffSync extends standard SQLite tables with built-in support for offline work and automatic synchronization. This allows multiple devices to operate independently and then seamlessly merge their changes. - **Offline-First by Design**: Applications work seamlessly even when devices are offline. Changes are queued locally and synced automatically when connectivity is restored. - **CRDT-Based Conflict Resolution**: Merges updates deterministically and efficiently, ensuring eventual consistency across all replicas without complex merge logic. - **Seamless Integration**: The sync layer is tightly integrated with SQLite Cloud, enabling secure data sharing across devices, users, and platforms. -When combined with [Row-Level Security (RLS)](/docs/rls), Offsync allows you to build secure, multi-tenant applications where each user's data is safely isolated, both on the edge and in the cloud. +When combined with [Row-Level Security (RLS)](/docs/rls), OffSync allows you to build secure, multi-tenant applications where each user's data is safely isolated, both on the edge and in the cloud. -## Configuring Offsync +## Configuring OffSync -You can enable and manage Offsync for your databases directly from the SQLite Cloud dashboard. +You can enable and manage OffSync for your databases directly from the SQLite Cloud dashboard. 1. **Navigate to the Databases Page**: From the main dashboard, go to the "Databases" page. 2. **Select the Offsync Column**: In the list of your databases, click on the button in the "Offsync" column for the desired database. @@ -36,7 +36,7 @@ You can enable and manage Offsync for your databases directly from the SQLite Cl ![Dashboard Offsync Settings Page](@docs-website-assets/introduction/offsync-2.png) -For Offsync to work correctly, the list of tables configured for synchronization—and their corresponding schemas—must be identical in both your local SQLite database and your SQLite Cloud database. +For OffSync to work correctly, the list of tables configured for synchronization—and their corresponding schemas—must be identical in both your local SQLite database and your SQLite Cloud database. Once enabled, any changes made to the selected tables via the SQLite Sync extension will be automatically synchronized with your SQLite Cloud database. From 188e71a09dff142255b78799868555c621066264 Mon Sep 17 00:00:00 2001 From: Andrea Donetti Date: Wed, 16 Jul 2025 18:02:22 +0200 Subject: [PATCH 16/17] Update search.yml to use docsearch-action@v6 --- .github/workflows/search.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/search.yml b/.github/workflows/search.yml index 903abdf..2c48cf0 100644 --- a/.github/workflows/search.yml +++ b/.github/workflows/search.yml @@ -13,7 +13,7 @@ jobs: steps: - uses: actions/checkout@v4 - - uses: sqlitecloud/docsearch-action@v5 + - uses: sqlitecloud/docsearch-action@v6 with: project-string: ${{ secrets.PROJECT_STRING }} base-url: ${{ vars.BASE_URL }} From 6e6c458c8a6d7aa69b634287e34af45c27ea738f Mon Sep 17 00:00:00 2001 From: Marco Bambini Date: Mon, 21 Jul 2025 12:35:24 +0200 Subject: [PATCH 17/17] Updated documentation --- .gitignore | 1 + sqlite-cloud/_nav.ts | 134 ++++++------------ sqlite-cloud/{platform => }/architecture.mdx | 0 .../platform/{vector.mdx => _vector.mdx} | 0 sqlite-cloud/platform/apikey.mdx | 20 +++ sqlite-cloud/platform/extensions.mdx | 9 +- sqlite-cloud/platform/security.mdx | 14 +- .../quick-start-apollo-graphql.mdx | 0 .../{ => quickstart}/quick-start-cdn.mdx | 0 .../{ => quickstart}/quick-start-django.mdx | 0 .../{ => quickstart}/quick-start-flask.mdx | 0 .../{ => quickstart}/quick-start-gin.mdx | 0 .../quick-start-knex.mdx} | 2 +- .../quick-start-laravel.mdx} | 0 .../{ => quickstart}/quick-start-next.mdx | 0 .../{ => quickstart}/quick-start-node.mdx | 0 .../{ => quickstart}/quick-start-prisma.mdx | 0 .../quick-start-react-native.mdx | 0 .../{ => quickstart}/quick-start-react.mdx | 0 .../quick-start-sqlalchemy-orm.mdx | 0 .../quick-start-streamlit.mdx | 0 sqlite-cloud/sqlite-ai/ai-overview.mdx | 37 +++++ .../{platform => sqlite-ai}/mcp-server.mdx | 0 sqlite-cloud/sqlite-ai/sqlite-ai.mdx | 13 ++ sqlite-cloud/sqlite-ai/sqlite-js.mdx | 13 ++ sqlite-cloud/sqlite-ai/sqlite-sync.mdx | 15 ++ sqlite-cloud/sqlite-ai/sqlite-vector.mdx | 13 ++ .../{ => tutorials}/tutorial-geopoly.mdx | 0 28 files changed, 166 insertions(+), 105 deletions(-) create mode 100644 .gitignore rename sqlite-cloud/{platform => }/architecture.mdx (100%) rename sqlite-cloud/platform/{vector.mdx => _vector.mdx} (100%) create mode 100644 sqlite-cloud/platform/apikey.mdx rename sqlite-cloud/{ => quickstart}/quick-start-apollo-graphql.mdx (100%) rename sqlite-cloud/{ => quickstart}/quick-start-cdn.mdx (100%) rename sqlite-cloud/{ => quickstart}/quick-start-django.mdx (100%) rename sqlite-cloud/{ => quickstart}/quick-start-flask.mdx (100%) rename sqlite-cloud/{ => quickstart}/quick-start-gin.mdx (100%) rename sqlite-cloud/{knex-integration.mdx => quickstart/quick-start-knex.mdx} (99%) rename sqlite-cloud/{quick-start-php-laravel.mdx => quickstart/quick-start-laravel.mdx} (100%) rename sqlite-cloud/{ => quickstart}/quick-start-next.mdx (100%) rename sqlite-cloud/{ => quickstart}/quick-start-node.mdx (100%) rename sqlite-cloud/{ => quickstart}/quick-start-prisma.mdx (100%) rename sqlite-cloud/{ => quickstart}/quick-start-react-native.mdx (100%) rename sqlite-cloud/{ => quickstart}/quick-start-react.mdx (100%) rename sqlite-cloud/{ => quickstart}/quick-start-sqlalchemy-orm.mdx (100%) rename sqlite-cloud/{ => quickstart}/quick-start-streamlit.mdx (100%) create mode 100644 sqlite-cloud/sqlite-ai/ai-overview.mdx rename sqlite-cloud/{platform => sqlite-ai}/mcp-server.mdx (100%) create mode 100644 sqlite-cloud/sqlite-ai/sqlite-ai.mdx create mode 100644 sqlite-cloud/sqlite-ai/sqlite-js.mdx create mode 100644 sqlite-cloud/sqlite-ai/sqlite-sync.mdx create mode 100644 sqlite-cloud/sqlite-ai/sqlite-vector.mdx rename sqlite-cloud/{ => tutorials}/tutorial-geopoly.mdx (100%) diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..e43b0f9 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +.DS_Store diff --git a/sqlite-cloud/_nav.ts b/sqlite-cloud/_nav.ts index 074c2cc..f6a267d 100644 --- a/sqlite-cloud/_nav.ts +++ b/sqlite-cloud/_nav.ts @@ -2,101 +2,56 @@ import type { SidebarNavStruct } from "@docs-website/types/sidebar-navigation"; const sidebarNav: SidebarNavStruct = [ { title: "", type: "primary" }, - { - title: "Introduction", - type: "secondary", - icon: "docs-star", - }, + // ### AI ### + { title: "AI", type: "secondary", icon: "docs-star",}, + { 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-Vector", filePath: "sqlite-vector", type: "inner", level: 0 }, + { title: "MCP (Model Context Protocol)", filePath: "mcp-server", type: "inner", level: 0 }, + + // ### CLOUD ### + { title: "Cloud", type: "secondary", icon: "docs-star",}, { title: "Overview", filePath: "overview", type: "inner", level: 0 }, + { title: "Scaling", filePath: "architecture", type: "inner", level: 0 }, { title: "Getting Started", type: "inner", level: 0 }, - { title: "Connecting", filePath: "connect-cluster", type: "inner", level: 1 }, - { - title: "Creating a database", - filePath: "create-database", - type: "inner", - level: 1, - }, - { title: "Writing data", filePath: "write-data", type: "inner", level: 1 }, + { title: "Connecting", filePath: "connect-cluster", type: "inner", level: 1 }, + { title: "Creating a database", filePath: "create-database", type: "inner", level: 1 }, + { title: "Writing data", filePath: "write-data", type: "inner", level: 1 }, { title: "Quick Start Guides", type: "inner", level: 0 }, - { title: "CDN", filePath: "quick-start-cdn", type: "inner", level: 1 }, - { title: "Node.js", filePath: "quick-start-node", type: "inner", level: 1 }, - { title: "React", filePath: "quick-start-react", type: "inner", level: 1 }, - { - title: "React Native", - filePath: "quick-start-react-native", - type: "inner", - level: 1, - }, - { - title: "Apollo / GraphQL", - filePath: "quick-start-apollo-graphql", - type: "inner", - level: 1, - }, - { title: "Next.js", filePath: "quick-start-next", type: "inner", level: 1 }, - { title: "Django", filePath: "quick-start-django", type: "inner", level: 1 }, - { title: "Flask", filePath: "quick-start-flask", type: "inner", level: 1 }, - { - title: "SQLAlchemy", - filePath: "quick-start-sqlalchemy-orm", - type: "inner", - level: 1, - }, - { - title: "Streamlit", - filePath: "quick-start-streamlit", - type: "inner", - level: 1, - }, - { - title: "PHP / Laravel", - filePath: "quick-start-php-laravel", - type: "inner", - level: 1, - }, - { title: "Gin", filePath: "quick-start-gin", type: "inner", level: 1 }, - { title: "Tutorials", type: "inner", level: 0 }, - { title: "Geopoly", filePath: "tutorial-geopoly", type: "inner", level: 1 }, - { title: "Integrations", type: "inner", level: 0 }, - { title: "Knex.js", filePath: "knex-integration", type: "inner", level: 1 }, + { title: "CDN", filePath: "quick-start-cdn", type: "inner", level: 1 }, + { title: "Node.js", filePath: "quick-start-node", type: "inner", level: 1 }, + { title: "React", filePath: "quick-start-react", type: "inner", level: 1 }, + { title: "React Native", filePath: "quick-start-react-native", type: "inner", level: 1 }, + { title: "Apollo / GraphQL", filePath: "quick-start-apollo-graphql", type: "inner", level: 1 }, + { title: "Next.js", filePath: "quick-start-next", type: "inner", level: 1 }, + { title: "Django", filePath: "quick-start-django", type: "inner", level: 1 }, + { title: "Flask", filePath: "quick-start-flask", type: "inner", level: 1 }, + { title: "SQLAlchemy", filePath: "quick-start-sqlalchemy-orm", type: "inner", level: 1 }, + { title: "Streamlit", filePath: "quick-start-streamlit", type: "inner", level: 1 }, + { title: "PHP / Laravel", filePath: "quick-start-php-laravel", type: "inner", level: 1 }, + { title: "Gin", filePath: "quick-start-gin", type: "inner", level: 1 }, + { title: "Knex.js", filePath: "quick-start-knex", type: "inner", level: 1 }, + // ### PLATFORM ### { title: "Platform", type: "secondary", icon: "docs-plat" }, - { - title: "Edge Functions", - filePath: "edge-functions", - type: "inner", - level: 0, - }, - { title: "Webhooks", filePath: "webhooks", type: "inner", level: 0 }, - { title: "Pub/Sub", filePath: "pub-sub", type: "inner", level: 0 }, - { title: "Vector", filePath: "vector", type: "inner", level: 0 }, - { title: "Scaling", type: "inner", filePath: "architecture", level: 0 }, - { - title: "Security and Access Control", - filePath: "security", - type: "inner", - level: 0, - }, - { - title: "Row-Level Security", - filePath: "rls", - type: "inner", - level: 0, - }, - { title: "OffSync", filePath: "offsync", type: "inner", level: 0 }, - { - title: "Access Tokens", - filePath: "access-tokens", - type: "inner", - level: 0, - }, - { title: "Backups", filePath: "backups", type: "inner", level: 0 }, - { title: "Query Analyzer", filePath: "analyzer", type: "inner", level: 0 }, - { title: "Extensions", filePath: "extensions", type: "inner", level: 0 }, - { title: "Weblite", filePath: "weblite", type: "inner", level: 0 }, - { title: "AI - Model Context Protocol (MCP)", filePath: "mcp-server", type: "inner", level: 0 }, + { title: "Edge Functions", filePath: "edge-functions", type: "inner", level: 0 }, + { title: "Webhooks", filePath: "webhooks", type: "inner", level: 0 }, + { title: "Pub/Sub", filePath: "pub-sub", type: "inner", level: 0 }, + //{ title: "Vector", filePath: "vector", type: "inner", level: 0 }, + { title: "Users and Roles", filePath: "security", type: "inner", level: 0 }, + { title: "API Keys", filePath: "apikey", type: "inner", level: 0 }, + { title: "Row-Level Security", filePath: "rls", type: "inner", level: 0}, + { title: "OffSync", filePath: "offsync", type: "inner", level: 0 }, + { title: "Access Tokens", filePath: "access-tokens", type: "inner", level: 0 }, + { title: "Backups", filePath: "backups", type: "inner", level: 0 }, + { title: "Query Analyzer", filePath: "analyzer", type: "inner", level: 0 }, + { title: "Extensions", filePath: "extensions", type: "inner", level: 0 }, + { title: "Weblite (REST API)", filePath: "weblite", type: "inner", level: 0 }, - { title: "SDKs", type: "secondary", icon: "docs-sdk" }, + // ### CLOUD SDK ### + { title: "Cloud SDK", type: "secondary", icon: "docs-sdk" }, { title: "C/C++", type: "inner", level: 0 }, { title: "Introduction", @@ -578,6 +533,7 @@ const sidebarNav: SidebarNavStruct = [ level: 1, }, + // ### REFERENCE ### { title: "Reference", type: "secondary", icon: "docs-ref" }, { title: "Server-side Commands", type: "inner", level: 0 }, { diff --git a/sqlite-cloud/platform/architecture.mdx b/sqlite-cloud/architecture.mdx similarity index 100% rename from sqlite-cloud/platform/architecture.mdx rename to sqlite-cloud/architecture.mdx diff --git a/sqlite-cloud/platform/vector.mdx b/sqlite-cloud/platform/_vector.mdx similarity index 100% rename from sqlite-cloud/platform/vector.mdx rename to sqlite-cloud/platform/_vector.mdx diff --git a/sqlite-cloud/platform/apikey.mdx b/sqlite-cloud/platform/apikey.mdx new file mode 100644 index 0000000..ee08944 --- /dev/null +++ b/sqlite-cloud/platform/apikey.mdx @@ -0,0 +1,20 @@ +--- +title: Security and Access Control +description: SQLite Cloud provides secure access to resources through role-based authorization, which ensures user isolation and enhances security and manageability. +category: platform +status: publish +slug: apikey +--- + +## API KEYs + +API KEYs can be used as an alternative authentication mechanism. +Authentication through API keys ensures the same privileges as the user to which they are associated. +API KEYs are recommended for all server-to-server authentication cases and are necessary for using the REST APIs and the SDKs that uses the WebSocket APIs. + +To create an API key for a user, click on the **Create API KEY** button. + +![Dashboard Create APIKEY](@docs-website-assets/introduction/dashboard_create_apikey.png) + +The resulting table will display all the API keys associated with each user, along with their name and restrictions. +![Dashboard List APIKEY](@docs-website-assets/introduction/dashboard_list_apikey.png) diff --git a/sqlite-cloud/platform/extensions.mdx b/sqlite-cloud/platform/extensions.mdx index 3b9931d..6a958ea 100644 --- a/sqlite-cloud/platform/extensions.mdx +++ b/sqlite-cloud/platform/extensions.mdx @@ -6,14 +6,17 @@ status: publish slug: extensions --- -SQLite Cloud comes with the following pre-installed SQLite extensions. These extensions are available for use in your SQLite Cloud databases. +SQLite Cloud comes with the following pre-installed SQLite extensions. +These extensions are available for use in your SQLite Cloud databases. ## Extensions +- **[SQLite-Vector](sqlite-vector)**: High performance vector storage extension for similarity search. +- **[SQLite-Sync](sqlite-sync)**: Local-first extension for true local-first data synchronization for your applications. +- **[SQLite-JS](sqlite-js)**: Enables JavaScript integration in SQLite for executing server-side logic. - **[Full-text Search 5](https://www.sqlite.org/fts5.html)**: Full-text search engine that allows you to search for text in a database. - **[JSON1](https://www.sqlite.org/json1.html)**: Allows you to easily store, query, and manipulate JSON data. - **[Math](https://www.sqlite.org/lang_mathfunc.html)**: Mathematical functions. - **[RTree](https://www.sqlite.org/rtree.html)**: R-Tree index for storing and querying spatial data. -- **[Geopoly](https://www.sqlite.org/geopoly.html)**: Functions for working with geospatial data. -- **[sqlite-vec](/docs/vector)**: Vector storage extension for similarity search. +- **[Geopoly](https://www.sqlite.org/geopoly.html)**: A set of functions for working with geospatial data. For a complete guide, see the [comprehensive tutorial here](tutorial-geopoly). In the future, we plan to allow users to install their own extensions. If you have a specific extension you would like to use, please let us know by [adding to this issue](https://github.com/sqlitecloud/docs/issues/34). \ No newline at end of file diff --git a/sqlite-cloud/platform/security.mdx b/sqlite-cloud/platform/security.mdx index 5677f15..3cd63e5 100644 --- a/sqlite-cloud/platform/security.mdx +++ b/sqlite-cloud/platform/security.mdx @@ -148,7 +148,7 @@ A role can contains any combination of privileges. -----------------| ``` - +{/* ## IP Restrictions The IP Restrictions panel enables the restriction of access for a role or user by allowing only specific IP addresses or ranges in [CIDR notation](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing) (for example 10.10.10.0/24). Both IPv4 and IPv6 addresses are supported. @@ -159,14 +159,4 @@ To add a new IP restriction to a user or role, click on the **Add IP** button. The IP Restrictions table will display all current IP restrictions for the selected user or role. ![Dashboard List IP Restrictions](@docs-website-assets/introduction/dashboard_list_ip.png) - -## API KEYs - -API KEYs can be used as an alternative authentication mechanism. Authentication through API keys ensures the same privileges as the user to which they are associated. API KEYs are recommended for all server-to-server authentication cases and are necessary for using the REST APIs and the SDKs that uses the WebSocket APIs. - -To create an API key for a user, click on the **Create API KEY** button. - -![Dashboard Create APIKEY](@docs-website-assets/introduction/dashboard_create_apikey.png) - -The resulting table will display all the API keys associated with each user, along with their name and restrictions. -![Dashboard List APIKEY](@docs-website-assets/introduction/dashboard_list_apikey.png) +*/} \ No newline at end of file diff --git a/sqlite-cloud/quick-start-apollo-graphql.mdx b/sqlite-cloud/quickstart/quick-start-apollo-graphql.mdx similarity index 100% rename from sqlite-cloud/quick-start-apollo-graphql.mdx rename to sqlite-cloud/quickstart/quick-start-apollo-graphql.mdx diff --git a/sqlite-cloud/quick-start-cdn.mdx b/sqlite-cloud/quickstart/quick-start-cdn.mdx similarity index 100% rename from sqlite-cloud/quick-start-cdn.mdx rename to sqlite-cloud/quickstart/quick-start-cdn.mdx diff --git a/sqlite-cloud/quick-start-django.mdx b/sqlite-cloud/quickstart/quick-start-django.mdx similarity index 100% rename from sqlite-cloud/quick-start-django.mdx rename to sqlite-cloud/quickstart/quick-start-django.mdx diff --git a/sqlite-cloud/quick-start-flask.mdx b/sqlite-cloud/quickstart/quick-start-flask.mdx similarity index 100% rename from sqlite-cloud/quick-start-flask.mdx rename to sqlite-cloud/quickstart/quick-start-flask.mdx diff --git a/sqlite-cloud/quick-start-gin.mdx b/sqlite-cloud/quickstart/quick-start-gin.mdx similarity index 100% rename from sqlite-cloud/quick-start-gin.mdx rename to sqlite-cloud/quickstart/quick-start-gin.mdx diff --git a/sqlite-cloud/knex-integration.mdx b/sqlite-cloud/quickstart/quick-start-knex.mdx similarity index 99% rename from sqlite-cloud/knex-integration.mdx rename to sqlite-cloud/quickstart/quick-start-knex.mdx index 8407ed1..d421d4d 100644 --- a/sqlite-cloud/knex-integration.mdx +++ b/sqlite-cloud/quickstart/quick-start-knex.mdx @@ -3,7 +3,7 @@ title: Knex.js Integration description: Integrate SQLite Cloud with Knex.js, a popular SQL query builder. category: getting-started status: publish -slug: knex-integration +slug: quick-start-knex --- In this tutorial, we'll show you how to connect your TypeScript application to a SQLite Cloud database using the popular SQL builder, [Knex.js](https://knexjs.org/). diff --git a/sqlite-cloud/quick-start-php-laravel.mdx b/sqlite-cloud/quickstart/quick-start-laravel.mdx similarity index 100% rename from sqlite-cloud/quick-start-php-laravel.mdx rename to sqlite-cloud/quickstart/quick-start-laravel.mdx diff --git a/sqlite-cloud/quick-start-next.mdx b/sqlite-cloud/quickstart/quick-start-next.mdx similarity index 100% rename from sqlite-cloud/quick-start-next.mdx rename to sqlite-cloud/quickstart/quick-start-next.mdx diff --git a/sqlite-cloud/quick-start-node.mdx b/sqlite-cloud/quickstart/quick-start-node.mdx similarity index 100% rename from sqlite-cloud/quick-start-node.mdx rename to sqlite-cloud/quickstart/quick-start-node.mdx diff --git a/sqlite-cloud/quick-start-prisma.mdx b/sqlite-cloud/quickstart/quick-start-prisma.mdx similarity index 100% rename from sqlite-cloud/quick-start-prisma.mdx rename to sqlite-cloud/quickstart/quick-start-prisma.mdx diff --git a/sqlite-cloud/quick-start-react-native.mdx b/sqlite-cloud/quickstart/quick-start-react-native.mdx similarity index 100% rename from sqlite-cloud/quick-start-react-native.mdx rename to sqlite-cloud/quickstart/quick-start-react-native.mdx diff --git a/sqlite-cloud/quick-start-react.mdx b/sqlite-cloud/quickstart/quick-start-react.mdx similarity index 100% rename from sqlite-cloud/quick-start-react.mdx rename to sqlite-cloud/quickstart/quick-start-react.mdx diff --git a/sqlite-cloud/quick-start-sqlalchemy-orm.mdx b/sqlite-cloud/quickstart/quick-start-sqlalchemy-orm.mdx similarity index 100% rename from sqlite-cloud/quick-start-sqlalchemy-orm.mdx rename to sqlite-cloud/quickstart/quick-start-sqlalchemy-orm.mdx diff --git a/sqlite-cloud/quick-start-streamlit.mdx b/sqlite-cloud/quickstart/quick-start-streamlit.mdx similarity index 100% rename from sqlite-cloud/quick-start-streamlit.mdx rename to sqlite-cloud/quickstart/quick-start-streamlit.mdx diff --git a/sqlite-cloud/sqlite-ai/ai-overview.mdx b/sqlite-cloud/sqlite-ai/ai-overview.mdx new file mode 100644 index 0000000..4bd7530 --- /dev/null +++ b/sqlite-cloud/sqlite-ai/ai-overview.mdx @@ -0,0 +1,37 @@ +--- +title: Getting Started with SQLite AI +description: SQLite Cloud is a distributed relational database system built on top of the SQLite database engine. +category: getting-started +status: publish +slug: ai-overview +--- + +## Overview + +**SQLite AI** is an advanced extension of SQLite designed to bring AI capabilities directly to the edge. It transforms the world’s most deployed database into a powerful, intelligent local database engine capable of powering modern, AI-driven applications, from mobile apps to embedded systems, IoT devices, and robotics. + +At the core of the project is a belief that **AI should run where the data is** — locally, privately, and efficiently — without always relying on the cloud. + +### Key Extensions + +SQLite AI is built around several modular extensions: + +1. **SQLite-AI** + Integrates on-device AI capabilities (e.g., LLM inference, audio transcription with Whisper) directly into SQLite using extensions that wrap C-based AI libraries such as `llama.cpp`, `whisper.cpp`, and more. + +2. **SQLite-Vector** + Adds native vector search to SQLite using optimized in-database structures and distance functions (L2, cosine, dot, etc.), with support for multiple vector formats (Float32, Int8, etc.). Ideal for on-device semantic search and AI retrieval. + +3. **SQLite-Sync** + A local-first sync layer that keeps SQLite databases synchronized across devices and users, with support for CRDTs, delta-based replication, and efficient cloud coordination. + +4. **SQLite-JS** + Embed JavaScript directly into SQLite using a lightweight interpreter (e.g., QuickJS), allowing developers to define SQLite functions and logic in JavaScript for increased flexibility and expressiveness. + + +### Features + +* **Works offline-first**: No need for a server to run advanced queries or AI models. +* **Cross-platform**: Runs on iOS, Android, Windows, Linux, macOS, and WebAssembly. +* **Minimal footprint**: Optimized for constrained devices. +* **Modular and open**: Built in C with clean, embeddable APIs and no heavy dependencies. diff --git a/sqlite-cloud/platform/mcp-server.mdx b/sqlite-cloud/sqlite-ai/mcp-server.mdx similarity index 100% rename from sqlite-cloud/platform/mcp-server.mdx rename to sqlite-cloud/sqlite-ai/mcp-server.mdx diff --git a/sqlite-cloud/sqlite-ai/sqlite-ai.mdx b/sqlite-cloud/sqlite-ai/sqlite-ai.mdx new file mode 100644 index 0000000..7d43c74 --- /dev/null +++ b/sqlite-cloud/sqlite-ai/sqlite-ai.mdx @@ -0,0 +1,13 @@ +--- +title: SQLite-AI +description: SQLite Cloud is a distributed relational database system built on top of the SQLite database engine. +category: platform +status: publish +slug: sqlite-ai +--- + +[SQLite-AI](https://website-stage.sqlitecloud.io/sqlite-ai) is a groundbreaking extension that brings powerful AI capabilities directly into SQLite. By embedding llama and whisper, it enables local LLM inference, text generation, embedding creation, speech recognition, translation, and even multimodal support, all from within the database itself. + +With a simple SQL interface, you can chat with a model, stream tokens in real time, generate high-quality embeddings, or transcribe and translate audio using Whisper. Multimodal features allow image processing and embedding, making SQLite-AI a versatile foundation for modern AI applications. + +**SQLite-AI** is an open-source project available on [GitHub](https://github.com/sqliteai/sqlite-ai). \ No newline at end of file diff --git a/sqlite-cloud/sqlite-ai/sqlite-js.mdx b/sqlite-cloud/sqlite-ai/sqlite-js.mdx new file mode 100644 index 0000000..0456e2c --- /dev/null +++ b/sqlite-cloud/sqlite-ai/sqlite-js.mdx @@ -0,0 +1,13 @@ +--- +title: SQLite-JS +description: SQLite Cloud is a distributed relational database system built on top of the SQLite database engine. +category: platform +status: publish +slug: sqlite-js +--- + +[SQLite-JS](https://website-stage.sqlitecloud.io/sqlite-js) is a powerful extension that lets you write custom cross-platform logic directly in your SQLite database using JavaScript. With support for scalar, aggregate, window functions, and collation sequences, you can express complex operations with ease, all using familiar SQL syntax. + +By integrating SQLite-JS with [SQLite-Sync](sqlite-sync), your user-defined JavaScript functions are automatically synchronized across all clients connected to your cluster, keeping logic consistent everywhere, even offline, for a truly consistent offline-first server-side logic distribution. + +**SQLite-JS** is an open-source project available on [GitHub](https://github.com/sqliteai/sqlite-js). \ No newline at end of file diff --git a/sqlite-cloud/sqlite-ai/sqlite-sync.mdx b/sqlite-cloud/sqlite-ai/sqlite-sync.mdx new file mode 100644 index 0000000..5815c48 --- /dev/null +++ b/sqlite-cloud/sqlite-ai/sqlite-sync.mdx @@ -0,0 +1,15 @@ +--- +title: SQLite-Sync +description: SQLite Cloud is a distributed relational database system built on top of the SQLite database engine. +category: platform +status: publish +slug: sqlite-sync +--- + +[SQLite-Sync](https://website-stage.sqlitecloud.io/sqlite-sync) is a cross-platform extension that adds built-in offline support and automatic synchronization to standard SQLite databases, enabling a **true local-first experience with zero latency**. Applications can operate fully offline, with each device maintaining its own copy of the database + +When reconnected, all changes are seamlessly synchronized across devices. Developers can continue using the familiar simplicity and performance of SQLite while easily building distributed, collaborative applications without complex infrastructure. + +SQLite Sync is powered by CRDTs (Conflict-free Replicated Data Types), a class of algorithms designed for real-time collaboration and distributed systems. CRDTs ensure that changes made on different devices are merged automatically and without conflicts, even when made offline. This means no data loss, no overwrites, and no need for manual conflict resolution. Whether it's a multi-user app or a fleet of devices operating in the field, SQLite Sync keeps everything consistent and in sync automatically. + +**SQLite-Sync** is an open-source project available on [GitHub](https://github.com/sqliteai/sqlite-sync). \ No newline at end of file diff --git a/sqlite-cloud/sqlite-ai/sqlite-vector.mdx b/sqlite-cloud/sqlite-ai/sqlite-vector.mdx new file mode 100644 index 0000000..4a0fd31 --- /dev/null +++ b/sqlite-cloud/sqlite-ai/sqlite-vector.mdx @@ -0,0 +1,13 @@ +--- +title: SQLite-Vector +description: SQLite Cloud is a distributed relational database system built on top of the SQLite database engine. +category: platform +status: publish +slug: sqlite-vector +--- + +[SQLite-Vector](https://website-stage.sqlitecloud.io/sqlite-vector) is a cross-platform, ultra-efficient SQLite extension that brings vector search capabilities directly into your embedded database + +Whether you're dealing with **millions of high-dimensional vectors** or operating on resource-constrained edge devices, SQLite-Vector delivers **lightning-fast performance** with a **tiny memory footprint**. + +**SQLite-Vector** is an open-source project available on [GitHub](https://github.com/sqliteai/sqlite-vector). \ No newline at end of file diff --git a/sqlite-cloud/tutorial-geopoly.mdx b/sqlite-cloud/tutorials/tutorial-geopoly.mdx similarity index 100% rename from sqlite-cloud/tutorial-geopoly.mdx rename to sqlite-cloud/tutorials/tutorial-geopoly.mdx