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 }} 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 1932e34..f6a267d 100644 --- a/sqlite-cloud/_nav.ts +++ b/sqlite-cloud/_nav.ts @@ -2,88 +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: "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", @@ -565,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/_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", diff --git a/sqlite-cloud/platform/access-tokens.mdx b/sqlite-cloud/platform/access-tokens.mdx new file mode 100644 index 0000000..7ed23c1 --- /dev/null +++ b/sqlite-cloud/platform/access-tokens.mdx @@ -0,0 +1,81 @@ +--- +title: Access Tokens +description: Grant to your users, devices, tenant, access to SQLite Cloud database and services. +category: platform +status: publish +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. + +The API Documentation for the Access Tokens API can be found in the **Weblite** section in the [Dashboard](https://dashboard.sqlitecloud.io). + +--- + +## 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. + +We’ll log in with Google, grab a token, and use it to interact with SQLite Cloud Weblite APIs. Here’s how it works. + +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 +if (pathname === "/auth/callback") { + const q = query; + if (q.state !== STATE || !q.code) { + return send(res, 400, "Invalid state or missing code"); + } + + try { + // Exchange code for tokens + // Store the Google Token in the database + const googleToken = await getGoogleTokens(q.code as string); + ... +``` + +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) { + 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("https:///v2/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}`); + } + + return res.json(); +} +``` + +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("https:///v2/weblite/sql", { + method: "POST", + headers: { + Authorization: "Bearer " + sqliteCloudToken, + "Content-Type": "application/json", + }, + body: JSON.stringify({ + sql: "USE DATABASE chinook.sqlite;SELECT * FROM artists LIMIT 10;", + }), +}); +... +``` + +The result depends on the [Row Level Security](https://) you enabled for the tables. 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/offsync.mdx b/sqlite-cloud/platform/offsync.mdx new file mode 100644 index 0000000..2924156 --- /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/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. diff --git a/sqlite-cloud/platform/rls.mdx b/sqlite-cloud/platform/rls.mdx new file mode 100644 index 0000000..b1034e2 --- /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 [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. + +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 + +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 using the SQLite Cloud builtin command `SET KEY rls_mode TO `. + +#### 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. 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