├── .github ├── ISSUE_TEMPLATE │ ├── .github │ │ └── ISSUE_TEMPLATE │ │ │ └── ---01-documentation.yml │ └── config.yml └── cover.png ├── .gitignore ├── CONTRIBUTING.md ├── LICENSE ├── README.md ├── _snippets ├── akamai-logo.svg ├── all-sdks.mdx ├── configure-libsql-client-ts.mdx ├── embedded-replicas-warning.mdx ├── encryption-at-rest-flutter.mdx ├── encryption-at-rest-golang.mdx ├── encryption-at-rest-python.mdx ├── encryption-at-rest-ruby.mdx ├── encryption-at-rest-rust.mdx ├── encryption-at-rest-typescript.mdx ├── fly-logo.svg ├── global-cli-flags.mdx ├── http-sdk.mdx ├── install-libsql-client-ts.mdx ├── install-libsql-extension-php.mdx ├── koyeb-logo.svg ├── mobile-secrets-warning.mdx ├── official-sdks.mdx ├── platform-api-links.mdx ├── railway-logo.svg ├── render-logo.svg ├── retrieve-database-credentials.mdx └── technical-preview-banner.mdx ├── api-reference ├── audit-logs │ └── list.mdx ├── authentication.mdx ├── databases │ ├── configuration.mdx │ ├── create-token.mdx │ ├── create.mdx │ ├── delete.mdx │ ├── invalidate-tokens.mdx │ ├── list-instances.mdx │ ├── list.mdx │ ├── retrieve-instance.mdx │ ├── retrieve.mdx │ ├── stats.mdx │ ├── update-configuration.mdx │ └── usage.mdx ├── groups │ ├── configuration.mdx │ ├── create-token.mdx │ ├── create.mdx │ ├── delete.mdx │ ├── invalidate-tokens.mdx │ ├── list.mdx │ ├── retrieve.mdx │ ├── transfer.mdx │ ├── unarchive.mdx │ └── update-configuration.mdx ├── introduction.mdx ├── locations │ ├── closest-region.mdx │ └── list.mdx ├── oauth.mdx ├── openapi.json ├── organizations │ ├── invites │ │ ├── create.mdx │ │ ├── delete.mdx │ │ └── list.mdx │ ├── invoices.mdx │ ├── list.mdx │ ├── members │ │ ├── add.mdx │ │ ├── list.mdx │ │ ├── remove.mdx │ │ ├── retrieve.mdx │ │ └── update.mdx │ ├── plans.mdx │ ├── retrieve.mdx │ ├── subscription.mdx │ ├── update.mdx │ └── usage.mdx ├── quickstart.mdx ├── response-codes.mdx ├── tokens │ ├── create.mdx │ ├── list.mdx │ ├── revoke.mdx │ └── validate.mdx └── versioning.mdx ├── cli ├── auth │ ├── api-tokens │ │ ├── list.mdx │ │ ├── mint.mdx │ │ └── revoke.mdx │ ├── login.mdx │ ├── logout.mdx │ ├── signup.mdx │ ├── token.mdx │ └── whoami.mdx ├── authentication.mdx ├── contact │ ├── bookmeeting.mdx │ └── feedback.mdx ├── db │ ├── create.mdx │ ├── destroy.mdx │ ├── import.mdx │ ├── inspect.mdx │ ├── list.mdx │ ├── locations.mdx │ ├── shell.mdx │ ├── show.mdx │ ├── tokens │ │ ├── create.mdx │ │ └── invalidate.mdx │ └── wakeup.mdx ├── dev.mdx ├── group │ ├── aws-migration │ │ ├── abort.mdx │ │ ├── info.mdx │ │ └── start.mdx │ ├── create.mdx │ ├── destroy.mdx │ ├── list.mdx │ ├── locations │ │ ├── add.mdx │ │ └── remove.mdx │ ├── tokens │ │ ├── create.mdx │ │ └── invalidate.mdx │ ├── transfer.mdx │ ├── unarchive.mdx │ └── update.mdx ├── headless-mode.mdx ├── help.mdx ├── installation.mdx ├── introduction.mdx ├── org │ ├── billing.mdx │ ├── create.mdx │ ├── destroy.mdx │ ├── list.mdx │ ├── members │ │ ├── add.mdx │ │ ├── invite.mdx │ │ ├── list.mdx │ │ └── rm.mdx │ └── switch.mdx ├── plan │ ├── overages │ │ ├── disable.mdx │ │ └── enable.mdx │ ├── select.mdx │ ├── show.mdx │ └── upgrade.mdx └── upgrading.mdx ├── cloud ├── durability.mdx ├── migrate-to-turso.mdx └── private-endpoints.mdx ├── data-and-connections.mdx ├── docs.json ├── favicon.svg ├── features ├── ai-and-embeddings.mdx ├── attach-database.mdx ├── branching.mdx ├── data-edge.mdx ├── embedded-replicas │ ├── introduction.mdx │ ├── read-your-writes.png │ ├── rust │ │ └── railway.mdx │ ├── with-akamai.mdx │ ├── with-fly.mdx │ ├── with-koyeb.mdx │ ├── with-railway.mdx │ └── with-render.mdx ├── multi-db-schemas.mdx ├── platform-api.mdx ├── point-in-time-recovery.mdx ├── scale-to-zero.mdx └── sqlite-extensions.mdx ├── help └── usage-and-billing.mdx ├── images ├── cloud │ └── import.png ├── concepts │ └── database-group.png ├── guides │ ├── actix-banner.png │ ├── astro-banner.png │ ├── axum-banner.png │ ├── doctrine-dbal-banner.png │ ├── drizzle-banner.png │ ├── elysia-banner.png │ ├── flask-banner.png │ ├── flutter-banner.png │ ├── hono-banner.png │ ├── laravel-banner.png │ ├── nextjs-banner.png │ ├── nuxt-banner.png │ ├── prisma-banner.png │ ├── quasar-banner.png │ ├── qwik-banner.png │ ├── remix-banner.png │ ├── rocket-banner.png │ ├── sqlalchemy-banner.png │ ├── svelte-banner.png │ └── tauri-banner.png ├── platforms │ ├── akamai-banner.png │ ├── fly-banner.png │ ├── koyeb-banner.png │ ├── koyeb-env-variables.png │ ├── railway-banner.png │ ├── render-banner.png │ └── render-env-vars.png └── turso-banner.png ├── integrations └── cloudflare.mdx ├── introduction.mdx ├── libsql.mdx ├── local-development.mdx ├── logo ├── turso-dark.svg └── turso-light.svg ├── package-lock.json ├── package.json ├── quickstart.mdx ├── sdk ├── activerecord │ ├── guides │ │ └── rails.mdx │ └── quickstart.mdx ├── authentication.mdx ├── c │ ├── examples.mdx │ ├── quickstart.mdx │ └── reference.mdx ├── flutter │ ├── examples.mdx │ ├── integrations │ │ └── drift.mdx │ ├── quickstart.mdx │ └── reference.mdx ├── go │ ├── examples.mdx │ ├── quickstart.mdx │ └── reference.mdx ├── http │ ├── guides │ │ └── flutter.mdx │ ├── quickstart.mdx │ └── reference.mdx ├── introduction.mdx ├── java │ ├── quickstart.mdx │ └── reference.mdx ├── kotlin │ ├── quickstart.mdx │ └── reference.mdx ├── php │ ├── examples.mdx │ ├── guides │ │ └── laravel.mdx │ ├── orm │ │ └── doctrine-dbal.mdx │ ├── quickstart.mdx │ └── reference.mdx ├── python │ ├── examples.mdx │ ├── guides │ │ └── flask.mdx │ ├── orm │ │ └── sqlalchemy.mdx │ ├── quickstart.mdx │ └── reference.mdx ├── ruby │ ├── examples.mdx │ └── quickstart.mdx ├── rust │ ├── examples.mdx │ ├── guides │ │ ├── actix.mdx │ │ ├── axum.mdx │ │ ├── rocket.mdx │ │ └── tauri.mdx │ ├── quickstart.mdx │ └── reference.mdx ├── swift │ ├── quickstart.mdx │ └── reference.mdx └── ts │ ├── examples.mdx │ ├── guides │ ├── astro.mdx │ ├── elysia.mdx │ ├── hono.mdx │ ├── nextjs.mdx │ ├── nuxt.mdx │ ├── quasar.mdx │ ├── qwik.mdx │ ├── remix.mdx │ └── sveltekit.mdx │ ├── integrations │ └── sentry.mdx │ ├── orm │ ├── drizzle.mdx │ └── prisma.mdx │ ├── quickstart.mdx │ └── reference.mdx └── support.mdx /.github/ISSUE_TEMPLATE/.github/ISSUE_TEMPLATE/---01-documentation.yml: -------------------------------------------------------------------------------- 1 | name: "📘 Documentation Issue" 2 | description: Missing, incorrect or outdated documentation? Let us know, or open a PR. 3 | labels: [] 4 | assignees: [] 5 | body: 6 | - type: dropdown 7 | id: section 8 | attributes: 9 | label: What part of the documentation is this issue about? 10 | multiple: true 11 | options: 12 | - CLI 13 | - Client SDKs 14 | - Platform API 15 | - Everything else 16 | - type: textarea 17 | id: suggestion 18 | attributes: 19 | label: Suggestion 20 | description: What could be improved, or what's missing? 21 | render: block 22 | validations: 23 | required: true 24 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/config.yml: -------------------------------------------------------------------------------- 1 | blank_issues_enabled: false 2 | contact_links: 3 | - name: 💁 Support 4 | url: https://tur.so/ghdiscord 5 | about: Get help and chat with us on Discord. 6 | - name: 💡 Feedback & Feature Requests 7 | url: https://tur.so/ghdiscord 8 | about: Share your feedback, and request new features on Discord! 9 | -------------------------------------------------------------------------------- /.github/cover.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/tursodatabase/turso-docs/60e72d978353bcb8d5c5d0ff6cb68a822844cad4/.github/cover.png -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Dependencies 2 | /node_modules 3 | 4 | # Production 5 | /build 6 | 7 | # Generated files 8 | .docusaurus 9 | .cache-loader 10 | 11 | # Misc 12 | .DS_Store 13 | .env.local 14 | .env.development.local 15 | .env.test.local 16 | .env.production.local 17 | 18 | npm-debug.log* 19 | yarn-debug.log* 20 | yarn-error.log* 21 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Contributor Manual 2 | 3 | Turso welcomes contributions from the community. Make sure to [join us on Discord](https://tur.so/discord-php) — to discuss your ideas and get help. 4 | 5 | 1. Clone the repository 6 | 2. Run `npm install` 7 | 3. Run `npm run dev` 8 | 4. Make changes 🙏 9 | 5. Open Pull Request 10 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2023 ChiselStrike 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 |

2 | 3 | 4 | Turso 5 | 6 | 7 |

Turso Documentation

8 |

9 | 10 |

11 | Databases for multi-tenant AI Apps. 12 |

13 | 14 |

15 | Turso · 16 | Docs · 17 | Quickstart · 18 | Blog & Tutorials 19 |

20 | 21 |

22 | 23 | 24 | MIT License 25 | 26 | 27 | 28 | 29 | Discord 30 | 31 | 32 | 33 | 34 | Contributors 35 | 36 | 37 |

38 | 39 | ## Support 40 | 41 | Join us [on Discord](https://tur.so/discord-c) to get help using this SDK. Report security issues [via email](mailto:security@turso.tech). 42 | 43 | ## Contributors 44 | 45 | See the [contributing guide](CONTRIBUTING.md) to learn how to get involved. 46 | 47 | ![Contributors](https://contrib.nn.ci/api?repo=tursodatabase/turso-docs) 48 | 49 | 50 | 51 | good first issue 52 | 53 | 54 | -------------------------------------------------------------------------------- /_snippets/all-sdks.mdx: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | -------------------------------------------------------------------------------- /_snippets/configure-libsql-client-ts.mdx: -------------------------------------------------------------------------------- 1 | 2 | 3 | ```ts Node.js 4 | import { createClient } from "@libsql/client"; 5 | 6 | export const turso = createClient({ 7 | url: process.env.TURSO_DATABASE_URL, 8 | authToken: process.env.TURSO_AUTH_TOKEN, 9 | }); 10 | ``` 11 | 12 | ```ts Edge Runtimes 13 | import { createClient } from "@libsql/client/web"; 14 | 15 | export const turso = createClient({ 16 | url: process.env.TURSO_DATABASE_URL, 17 | authToken: process.env.TURSO_AUTH_TOKEN, 18 | }); 19 | ``` 20 | 21 | ```ts Deno 22 | import { createClient } from "https://esm.sh/@libsql/client@0.6.0/web"; 23 | 24 | export const turso = createClient({ 25 | url: Deno.env.get("TURSO_DATABASE_URL"), 26 | authToken: Deno.env.get("TURSO_AUTH_TOKEN"), 27 | }); 28 | ``` 29 | 30 | 31 | -------------------------------------------------------------------------------- /_snippets/embedded-replicas-warning.mdx: -------------------------------------------------------------------------------- 1 | 2 | 3 | Embedded Replicas only works where you have access to the file system. 4 | 5 | -------------------------------------------------------------------------------- /_snippets/encryption-at-rest-flutter.mdx: -------------------------------------------------------------------------------- 1 | ```dart Flutter 2 | final dir = await getApplicationCacheDirectory(); 3 | final path = '${dir.path}/local.db'; 4 | 5 | final client = LibsqlClient(path)..encryptionKey = ''; 6 | ``` 7 | -------------------------------------------------------------------------------- /_snippets/encryption-at-rest-golang.mdx: -------------------------------------------------------------------------------- 1 | ```go Go 2 | package main 3 | 4 | import ( 5 | "database/sql" 6 | "fmt" 7 | "os" 8 | "path/filepath" 9 | 10 | "github.com/tursodatabase/go-libsql" 11 | ) 12 | 13 | func main() { 14 | dbName := "local.db" 15 | primaryUrl := "libsql://[DATABASE].turso.io" 16 | authToken := "..." 17 | encryptionKey := "SuperSecretKey" 18 | 19 | dir, err := os.MkdirTemp("", "libsql-*") 20 | if err != nil { 21 | fmt.Println("Error creating temporary directory:", err) 22 | os.Exit(1) 23 | } 24 | defer os.RemoveAll(dir) 25 | 26 | dbPath := filepath.Join(dir, dbName) 27 | 28 | connector, err := NewEmbeddedReplicaConnector(dbPath, primaryUrl, 29 | WithAuthToken(authToken), 30 | WithEncryption(encryptionKey), 31 | ) 32 | if err != nil { 33 | fmt.Println("Error creating connector:", err) 34 | os.Exit(1) 35 | } 36 | defer connector.Close() 37 | 38 | db := sql.OpenDB(connector) 39 | defer db.Close() 40 | } 41 | ``` 42 | -------------------------------------------------------------------------------- /_snippets/encryption-at-rest-python.mdx: -------------------------------------------------------------------------------- 1 | ```py Python 2 | import os 3 | 4 | import libsql_experimental as libsql 5 | 6 | conn = libsql.connect("encrypted.db", sync_url=os.getenv("LIBSQL_URL"), 7 | auth_token=os.getenv("LIBSQL_AUTH_TOKEN"), 8 | encryption_key=os.getenv("ENCRYPTION_KEY")) 9 | ``` 10 | -------------------------------------------------------------------------------- /_snippets/encryption-at-rest-ruby.mdx: -------------------------------------------------------------------------------- 1 | ```ruby Ruby 2 | db = 3 | Libsql::Database.new( 4 | path: 'encrypted.db', 5 | encryption_key: 'my-safe-encryption-key' 6 | ) 7 | ``` 8 | -------------------------------------------------------------------------------- /_snippets/encryption-at-rest-rust.mdx: -------------------------------------------------------------------------------- 1 | ```rust Rust 2 | use libsql::Builder; 3 | use bytes::Bytes; 4 | 5 | let url = env::var("LIBSQL_URL").expect("LIBSQL_URL must be set"); 6 | let token = env::var("LIBSQL_AUTH_TOKEN").unwrap_or_default(); 7 | 8 | let cipher = Cipher::YourChosenCipher; 9 | let encryption_key_bytes = Bytes::from("your_secure_encryption_key_here"); 10 | 11 | let encryption_config = EncryptionConfig { 12 | cipher, 13 | encryption_key: encryption_key_bytes, 14 | }; 15 | 16 | let mut db = Builder::new_remote_replica("local.db", &url, &token) 17 | .encryption_config(encryption_config) // Apply encryption configuration 18 | .build() 19 | .await 20 | .unwrap(); 21 | 22 | let conn = db.connect().unwrap(); 23 | ``` 24 | -------------------------------------------------------------------------------- /_snippets/encryption-at-rest-typescript.mdx: -------------------------------------------------------------------------------- 1 | ```ts TypeScript {5} 2 | import { createClient } from "@libsql/client"; 3 | 4 | const db = createClient({ 5 | url: "file:encrypted.db", 6 | encryptionKey: process.env.ENCRYPTION_KEY, 7 | }); 8 | ``` 9 | -------------------------------------------------------------------------------- /_snippets/global-cli-flags.mdx: -------------------------------------------------------------------------------- 1 | ## Global Flags 2 | 3 | | Flag | Description | 4 | | ------------------------------------- | ----------------------------------------------- | 5 | | `-c`, `--config-path` | Path to the directory with the config file. | 6 | | `--no-multiple-token-sources-warning` | Don't warn about multiple access token sources. | 7 | -------------------------------------------------------------------------------- /_snippets/http-sdk.mdx: -------------------------------------------------------------------------------- 1 | 6 | 13 | 17 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | } 32 | href="/sdk/http/quickstart" 33 | /> 34 | -------------------------------------------------------------------------------- /_snippets/install-libsql-client-ts.mdx: -------------------------------------------------------------------------------- 1 | Begin by installing the `@libsql/client` dependency in your project: 2 | 3 | 4 | 5 | ```bash npm 6 | npm install @libsql/client 7 | ``` 8 | 9 | ```bash pnpm 10 | pnpm install @libsql/client 11 | ``` 12 | 13 | ```bash yarn 14 | yarn add @libsql/client 15 | ``` 16 | 17 | ```bash deno 18 | deno add npm:@libsql/client 19 | ``` 20 | 21 | 22 | -------------------------------------------------------------------------------- /_snippets/install-libsql-extension-php.mdx: -------------------------------------------------------------------------------- 1 | Download the latest build extension/driver binary you can see at [Release](https://github.com/tursodatabase/turso-client-php/releases) page. It's available for: 2 | 3 | - Linux 4 | - Mac/Darwin 5 | - Windows (WSL) / [Devcontainer](https://github.com/darkterminal/turso-docker-php) 6 | 7 | 8 | 9 | Get the installer: 10 | 11 | ```bash 12 | curl --proto '=https' --tlsv1.2 -sSf "https://darkterminal.github.io/turso-php-installer/dist/turso-php-installer.phar" 13 | ./turso-php-installer.phar 14 | ``` 15 | 16 | Add as a global executable script: 17 | 18 | ```bash 19 | sudo mv turso-php-installer.phar /usr/local/bin/turso-php-installer 20 | ``` 21 | 22 | **Usage** 23 | 24 | Install Turso Client PHP / libSQL Extension: 25 | 26 | ```bash 27 | turso-php-installer install 28 | ``` 29 | 30 | Check on your console/terminal 31 | 32 | ```shell 33 | $ php --m | grep libsql 34 | liblibsql_php 35 | ``` 36 | 37 | Update Turso Client PHP / libSQL Extension: 38 | 39 | ```bash 40 | turso-php-installer update 41 | ``` 42 | 43 | Uninstall Turso Client PHP / libSQL Extension: 44 | 45 | ```bash 46 | turso-php-installer uninstall 47 | ``` 48 | 49 | 50 | - 📦 Extract the archive 51 | - 🗃 Locate somewhere in your machine 52 | - 💽 Copy a relative path that address that extension/driver 53 | - 📂 Open `php.ini` search `;extension` if you using nano (ctrl+w) then searching for it 54 | - 📝 add in the next-line `extension=liblibsql_php.so` (in Linux) without `;` at the begining 55 | 56 | Check on your console/terminal 57 | 58 | ```shell 59 | $ php --m | grep libsql 60 | liblibsql_php 61 | ``` 62 | 63 | 64 | 65 | 66 | Now, `LibSQL` class is available in your PHP environment! You can use it everywhere in your PHP project 🎉 67 | -------------------------------------------------------------------------------- /_snippets/koyeb-logo.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | -------------------------------------------------------------------------------- /_snippets/mobile-secrets-warning.mdx: -------------------------------------------------------------------------------- 1 | You will want to make sure to handle database tokens securely. 2 | -------------------------------------------------------------------------------- /_snippets/platform-api-links.mdx: -------------------------------------------------------------------------------- 1 | 2 | 3 | Create and manage where your database is located. 4 | 5 | 6 | Create, manage and generate auth tokens for databases. 7 | 8 | 13 | Fetch all available locations where your database group can be located. 14 | 15 | 20 | Manage your organization, it's members and invites. 21 | 22 | 23 | Create, validate and revoke API keys that can be used to access the API. 24 | 25 | 26 | Monitor logs of what's happening in your organization. 27 | 28 | 29 | -------------------------------------------------------------------------------- /_snippets/railway-logo.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | -------------------------------------------------------------------------------- /_snippets/render-logo.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | -------------------------------------------------------------------------------- /_snippets/retrieve-database-credentials.mdx: -------------------------------------------------------------------------------- 1 | Get the database URL: 2 | 3 | ```bash 4 | turso db show --url 5 | ``` 6 | 7 | Get the database authentication token: 8 | 9 | ```bash 10 | turso db tokens create 11 | ``` 12 | 13 | Assign credentials to the environment variables inside `.env`. 14 | 15 | ```bash 16 | TURSO_DATABASE_URL= 17 | TURSO_AUTH_TOKEN= 18 | ``` 19 | -------------------------------------------------------------------------------- /_snippets/technical-preview-banner.mdx: -------------------------------------------------------------------------------- 1 | 2 | 3 | This is currently in technical preview. [Join us in Discord](https://discord.gg/turso) to report any issues. 4 | 5 | 6 | -------------------------------------------------------------------------------- /api-reference/audit-logs/list.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | sidebarTitle: List 3 | openapi: "GET /v1/organizations/{organizationSlug}/audit-logs" 4 | --- 5 | 6 | Audit Logs are limited to paid plans. 7 | 8 | 9 | 10 | ```bash cURL 11 | curl -L https://api.turso.tech/v1/organizations/{organizationSlug}/audit-logs \ 12 | -H 'Authorization: Bearer TOKEN' 13 | ``` 14 | 15 | 16 | -------------------------------------------------------------------------------- /api-reference/authentication.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Authentication 3 | description: 4 | --- 5 | 6 | The Turso API uses API tokens to authenticate requests. You can create and revoke API tokens using the [Turso CLI](/cli) and [Authentication API](/api-reference/tokens/create). 7 | 8 | API tokens allow access to manage all API resources, including creating and destroying database. 9 | 10 | - Use environment variables when working with API tokens. 11 | - Never share your API token in public, including repositories, and CI/CD Actions. 12 | 13 | Turso uses Bearer authentication, and requires your API token to be passed with all protected requests in the `Authorization` header: 14 | 15 | ```bash 16 | Authorization: Bearer TOKEN 17 | ``` 18 | 19 | ## Base URL 20 | 21 | The Turso API is located at the following URL: 22 | 23 | ```bash 24 | https://api.turso.tech 25 | ``` 26 | -------------------------------------------------------------------------------- /api-reference/databases/configuration.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | sidebarTitle: Retrieve Configuration 3 | openapi: "GET /v1/organizations/{organizationSlug}/databases/{databaseName}/configuration" 4 | --- 5 | 6 | 7 | 8 | ```bash cURL 9 | curl -L -X GET 'https://api.turso.tech/v1/organizations/{organizationSlug}/databases/{databaseName}/configuration' \ 10 | -H 'Authorization: Bearer TOKEN' 11 | ``` 12 | 13 | 14 | -------------------------------------------------------------------------------- /api-reference/databases/create-token.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | sidebarTitle: Create Token 3 | openapi: "POST /v1/organizations/{organizationSlug}/databases/{databaseName}/auth/tokens" 4 | --- 5 | 6 | 7 | 8 | ```bash cURL 9 | curl -L -X POST 'https://api.turso.tech/v1/organizations/{organizationSlug}/databases/{databaseName}/auth/tokens?expiration=2w&authorization=full-access' \ 10 | -H 'Authorization: Bearer TOKEN' 11 | ``` 12 | 13 | ```ts Node.js 14 | import { createClient } from "@tursodatabase/api"; 15 | 16 | const turso = createClient({ 17 | org: "...", 18 | token: "", 19 | }); 20 | 21 | const token = await turso.databases.createToken("my-db", { 22 | expiration: "2w", 23 | authorization: "full-access", 24 | }); 25 | ``` 26 | 27 | 28 | 29 | 30 | 31 | ```json 32 | { 33 | "jwt": "TOKEN" 34 | } 35 | ``` 36 | 37 | 38 | -------------------------------------------------------------------------------- /api-reference/databases/create.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | sidebarTitle: Create 3 | openapi: "POST /v1/organizations/{organizationSlug}/databases" 4 | --- 5 | 6 | 7 | 8 | ```bash cURL 9 | curl -L -X POST 'https://api.turso.tech/v1/organizations/{organizationSlug}/databases' \ 10 | -H 'Authorization: Bearer TOKEN' \ 11 | -H 'Content-Type: application/json' \ 12 | -d '{ 13 | "name": "new-database", 14 | "group": "default" 15 | }' 16 | ``` 17 | 18 | ```ts Node.js 19 | import { createClient } from "@tursodatabase/api"; 20 | 21 | const turso = createClient({ 22 | org: "...", 23 | token: "", 24 | }); 25 | 26 | const database = await turso.databases.create("new-database", { 27 | group: "default", 28 | }); 29 | ``` 30 | 31 | 32 | -------------------------------------------------------------------------------- /api-reference/databases/delete.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | sidebarTitle: Delete 3 | openapi: "DELETE /v1/organizations/{organizationSlug}/databases/{databaseName}" 4 | --- 5 | 6 | 7 | 8 | ```bash cURL 9 | curl -L -X DELETE 'https://api.turso.tech/v1/organizations/{organizationSlug}/databases/{databaseName}' \ 10 | -H 'Authorization: Bearer TOKEN' 11 | ``` 12 | 13 | ```ts Node.js 14 | import { createClient } from "@tursodatabase/api"; 15 | 16 | const turso = createClient({ 17 | org: "...", 18 | token: "", 19 | }); 20 | 21 | const database = await turso.databases.delete("my-db"); 22 | ``` 23 | 24 | 25 | -------------------------------------------------------------------------------- /api-reference/databases/invalidate-tokens.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | sidebarTitle: Invalidate Tokens 3 | openapi: "POST /v1/organizations/{organizationSlug}/databases/{databaseName}/auth/rotate" 4 | --- 5 | 6 | 7 | 8 | A short downtime is required to complete the changes. 9 | 10 | 11 | 12 | 13 | 14 | ```bash cURL 15 | curl -L -X POST 'https://api.turso.tech/v1/organizations/{organizationSlug}/databases/{databaseName}/auth/rotate' \ 16 | -H 'Authorization: Bearer TOKEN' 17 | ``` 18 | 19 | ```ts Node.js 20 | import { createClient } from "@tursodatabase/api"; 21 | 22 | const turso = createClient({ 23 | org: "...", 24 | token: "", 25 | }); 26 | 27 | const response = await turso.databases.rotateTokens("my-db"); 28 | ``` 29 | 30 | 31 | -------------------------------------------------------------------------------- /api-reference/databases/list-instances.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | sidebarTitle: List Instances 3 | openapi: "GET /v1/organizations/{organizationSlug}/databases/{databaseName}/instances" 4 | --- 5 | 6 | 7 | 8 | ```bash cURL 9 | curl -L https://api.turso.tech/v1/organizations/{organizationSlug}/databases/{databaseName}/instances \ 10 | -H 'Authorization: Bearer TOKEN' 11 | ``` 12 | 13 | ```ts Node.js 14 | import { createClient } from "@tursodatabase/api"; 15 | 16 | const turso = createClient({ 17 | org: "...", 18 | token: "", 19 | }); 20 | 21 | const instances = await turso.databases.listInstances("my-db"); 22 | ``` 23 | 24 | 25 | -------------------------------------------------------------------------------- /api-reference/databases/list.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | sidebarTitle: List 3 | openapi: "GET /v1/organizations/{organizationSlug}/databases" 4 | --- 5 | 6 | 7 | 8 | ```bash cURL 9 | curl -L https://api.turso.tech/v1/organizations/{organizationSlug}/databases \ 10 | -H 'Authorization: Bearer TOKEN' 11 | ``` 12 | 13 | ```ts Node.js 14 | import { createClient } from "@tursodatabase/api"; 15 | 16 | const turso = createClient({ 17 | org: "...", 18 | token: "", 19 | }); 20 | 21 | const databases = await turso.databases.list(); 22 | ``` 23 | 24 | 25 | -------------------------------------------------------------------------------- /api-reference/databases/retrieve-instance.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | sidebarTitle: Retrieve Instance 3 | openapi: "GET /v1/organizations/{organizationSlug}/databases/{databaseName}/instances/{instanceName}" 4 | --- 5 | 6 | 7 | 8 | ```bash cURL 9 | curl -L https://api.turso.tech/v1/organizations/{organizationSlug}/databases/{databaseName}/instances/{instanceName} \ 10 | -H 'Authorization: Bearer TOKEN' 11 | ``` 12 | 13 | ```ts Node.js 14 | import { createClient } from "@tursodatabase/api"; 15 | 16 | const turso = createClient({ 17 | org: "...", 18 | token: "", 19 | }); 20 | 21 | const instance = await turso.databases.retrieveInstance( 22 | "my-db", 23 | "instanceName", 24 | ); 25 | ``` 26 | 27 | 28 | -------------------------------------------------------------------------------- /api-reference/databases/retrieve.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | sidebarTitle: Retrieve 3 | openapi: "GET /v1/organizations/{organizationSlug}/databases/{databaseName}" 4 | --- 5 | 6 | 7 | 8 | ```bash cURL 9 | curl -L 'https://api.turso.tech/v1/organizations/{organizationSlug}/databases/{databaseName}' \ 10 | -H 'Authorization: Bearer TOKEN' 11 | ``` 12 | 13 | ```ts Node.js 14 | import { createClient } from "@tursodatabase/api"; 15 | 16 | const turso = createClient({ 17 | org: "...", 18 | token: "", 19 | }); 20 | 21 | const database = await turso.databases.retrieve("my-db"); 22 | ``` 23 | 24 | 25 | -------------------------------------------------------------------------------- /api-reference/databases/stats.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | sidebarTitle: Stats 3 | openapi: "GET /v1/organizations/{organizationSlug}/databases/{databaseName}/stats" 4 | --- 5 | 6 | 7 | 8 | ```bash cURL 9 | curl -L -X GET 'https://api.turso.tech/v1/organizations/{organizationSlug}/databases/{databaseName}/stats' \ 10 | -H 'Authorization: Bearer TOKEN' 11 | ``` 12 | 13 | 14 | -------------------------------------------------------------------------------- /api-reference/databases/update-configuration.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | sidebarTitle: Update Configuration 3 | openapi: "PATCH /v1/organizations/{organizationSlug}/databases/{databaseName}/configuration" 4 | --- 5 | 6 | 7 | 8 | ```bash cURL 9 | curl -L -X PATCH 'https://api.turso.tech/v1/organizations/{organizationSlug}/databases/{databaseName}/configuration' \ 10 | -H 'Authorization: Bearer TOKEN' \ 11 | -H 'Content-Type: application/json' \ 12 | -d '{ 13 | "size_limit": "500mb", 14 | "delete_protection": true, 15 | "block_reads": false, 16 | "block_writes": false 17 | }' 18 | ``` 19 | 20 | 21 | -------------------------------------------------------------------------------- /api-reference/databases/usage.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | sidebarTitle: Usage 3 | openapi: "GET /v1/organizations/{organizationSlug}/databases/{databaseName}/usage" 4 | --- 5 | 6 | 7 | 8 | ```bash cURL 9 | curl -L -X GET 'https://api.turso.tech/v1/organizations/{organizationSlug}/databases/{databaseName}/usage?from=2023-01-01T00:00:00Z&to=2023-02-01T00:00:00Z' \ 10 | -H 'Authorization: Bearer TOKEN' 11 | ``` 12 | 13 | ```ts Node.js 14 | import { createClient } from "@tursodatabase/api"; 15 | 16 | const turso = createClient({ 17 | org: "...", 18 | token: "", 19 | }); 20 | 21 | const usageStatsWithDate = await turso.databases.usage("my-db"); 22 | 23 | const usageStatsWithDate = await turso.databases.usage("my-db", { 24 | from: new Date("2023-01-01"), 25 | to: new Date("2023-02-01"), 26 | }); 27 | 28 | const usageStatsWithString = await turso.databases.usage("my-db", { 29 | from: "2023-01-01T00:00:00Z", 30 | to: "2023-02-01T00:00:00Z", 31 | }); 32 | ``` 33 | 34 | 35 | -------------------------------------------------------------------------------- /api-reference/groups/configuration.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | sidebarTitle: Retrieve Configuration 3 | openapi: "GET /v1/organizations/{organizationSlug}/groups/{groupName}/configuration" 4 | --- 5 | 6 | 7 | 8 | ```bash cURL 9 | curl -L -X GET 'https://api.turso.tech/v1/organizations/{organizationSlug}/groups/{groupName}/configuration' \ 10 | -H 'Authorization: Bearer TOKEN' 11 | ``` 12 | 13 | 14 | -------------------------------------------------------------------------------- /api-reference/groups/create-token.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | sidebarTitle: Create Token 3 | openapi: "POST /v1/organizations/{organizationSlug}/groups/{groupName}/auth/tokens" 4 | --- 5 | 6 | 7 | 8 | Tokens cannot be retrieved once created, and cannot be revoked individually. 9 | 10 | 11 | 12 | 13 | 14 | ```bash cURL 15 | curl -L -X POST 'https://api.turso.tech/v1/organizations/{organizationSlug}/groups/{groupName}/auth/tokens?expiration=2w&authorization=full-access' \ 16 | -H 'Authorization: Bearer TOKEN' 17 | ``` 18 | 19 | ```ts Node.js 20 | import { createClient } from "@tursodatabase/api"; 21 | 22 | const turso = createClient({ 23 | org: "...", 24 | token: "", 25 | }); 26 | 27 | const token = await turso.groups.createToken("default", { 28 | expiration: "2w", 29 | authorization: "full-access", 30 | }); 31 | ``` 32 | 33 | 34 | 35 | 36 | 37 | ```json 38 | { 39 | "jwt": "TOKEN" 40 | } 41 | ``` 42 | 43 | 44 | -------------------------------------------------------------------------------- /api-reference/groups/create.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | sidebarTitle: Create 3 | openapi: "POST /v1/organizations/{organizationSlug}/groups" 4 | --- 5 | 6 | 7 | Creating more than one group is limited to Scaler, Pro and Enterprise plans. 8 | 9 | 10 | 11 | 12 | ```bash cURL 13 | curl -L -X POST 'https://api.turso.tech/v1/organizations/{organizationSlug}/groups' \ 14 | -H 'Authorization: Bearer TOKEN' \ 15 | -H 'Content-Type: application/json' \ 16 | -d '{ 17 | "name": "new-group", 18 | "location": "lhr" 19 | }' 20 | ``` 21 | 22 | ```ts Node.js 23 | import { createClient } from "@tursodatabase/api"; 24 | 25 | const turso = createClient({ 26 | org: "...", 27 | token: "", 28 | }); 29 | 30 | const group = await turso.groups.create("new-group", { 31 | location: "lhr", 32 | extensions: ["vector", "uuid"], // 'all' 33 | }); 34 | ``` 35 | 36 | 37 | -------------------------------------------------------------------------------- /api-reference/groups/delete.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | sidebarTitle: Delete 3 | openapi: "DELETE /v1/organizations/{organizationSlug}/groups/{groupName}" 4 | --- 5 | 6 | 7 | 8 | ```bash cURL 9 | curl -L -X DELETE 'https://api.turso.tech/v1/organizations/{organizationSlug}/groups/{groupName}' \ 10 | -H 'Authorization: Bearer TOKEN' 11 | ``` 12 | 13 | ```ts Node.js 14 | import { createClient } from "@tursodatabase/api"; 15 | 16 | const turso = createClient({ 17 | org: "...", 18 | token: "", 19 | }); 20 | 21 | const group = await turso.groups.delete("new-group"); 22 | ``` 23 | 24 | 25 | -------------------------------------------------------------------------------- /api-reference/groups/invalidate-tokens.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | sidebarTitle: Invalidate Tokens 3 | openapi: "POST /v1/organizations/{organizationSlug}/groups/{groupName}/auth/rotate" 4 | --- 5 | 6 | 7 | 8 | ```bash cURL 9 | curl -L -X POST 'https://api.turso.tech/v1/organizations/{organizationSlug}/groups/{groupName}/auth/rotate' \ 10 | -H 'Authorization: Bearer TOKEN' 11 | ``` 12 | 13 | ```ts Node.js 14 | import { createClient } from "@tursodatabase/api"; 15 | 16 | const turso = createClient({ 17 | org: "...", 18 | token: "", 19 | }); 20 | 21 | const response = await turso.groups.invalidateTokens("default"); 22 | ``` 23 | 24 | 25 | -------------------------------------------------------------------------------- /api-reference/groups/list.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | sidebarTitle: List 3 | openapi: "GET /v1/organizations/{organizationSlug}/groups" 4 | --- 5 | 6 | 7 | 8 | ```bash cURL 9 | curl -L https://api.turso.tech/v1/organizations/{organizationSlug}/groups \ 10 | -H 'Authorization: Bearer TOKEN' 11 | ``` 12 | 13 | ```ts Node.js 14 | import { createClient } from "@tursodatabase/api"; 15 | 16 | const turso = createClient({ 17 | org: "...", 18 | token: "", 19 | }); 20 | 21 | const groups = await turso.groups.list(); 22 | ``` 23 | 24 | 25 | -------------------------------------------------------------------------------- /api-reference/groups/retrieve.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | sidebarTitle: Retrieve 3 | openapi: "GET /v1/organizations/{organizationSlug}/groups/{groupName}" 4 | --- 5 | 6 | 7 | 8 | ```bash cURL 9 | curl -L 'https://api.turso.tech/v1/organizations/{organizationSlug}/groups/{groupName}' \ 10 | -H 'Authorization: Bearer TOKEN' 11 | ``` 12 | 13 | ```ts Node.js 14 | import { createClient } from "@tursodatabase/api"; 15 | 16 | const turso = createClient({ 17 | org: "...", 18 | token: "", 19 | }); 20 | 21 | const group = await turso.groups.retrieve("default"); 22 | ``` 23 | 24 | 25 | -------------------------------------------------------------------------------- /api-reference/groups/transfer.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | sidebarTitle: Transfer 3 | openapi: "POST /v1/organizations/{organizationSlug}/groups/{groupName}/transfer" 4 | --- 5 | 6 | 7 | 8 | You can only transfer groups to organizations you own or are an admin. 9 | 10 | 11 | 12 | 13 | 14 | Existing database URL and tokens will continue to work, but should update your application to use the new URL and token as soon as possible. 15 | 16 | 17 | 18 | 19 | 20 | ```bash cURL 21 | curl -L -X POST 'https://api.turso.tech/v1/organizations/{organizationSlug}/groups/{groupName}/transfer' \ 22 | -H 'Authorization: Bearer TOKEN' \ 23 | -d '{ 24 | "organization": "new-organization-slug" 25 | }' 26 | ``` 27 | 28 | 29 | -------------------------------------------------------------------------------- /api-reference/groups/unarchive.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | sidebarTitle: Unarchive 3 | openapi: "POST /v1/organizations/{organizationSlug}/groups/{groupName}/unarchive" 4 | --- 5 | 6 | 7 | 8 | Databases get archived after 10 days of inactivity for users on a free plan — [learn more](/features/scale-to-zero). You can unarchive inactive groups using the API. 9 | 10 | 11 | 12 | 13 | 14 | ```bash cURL 15 | curl -L -X POST 'https://api.turso.tech/v1/organizations/{organizationSlug}/groups/{groupName}/unarchive' \ 16 | -H 'Authorization: Bearer TOKEN' \ 17 | ``` 18 | 19 | 20 | -------------------------------------------------------------------------------- /api-reference/groups/update-configuration.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | sidebarTitle: Update Configuration 3 | openapi: "PATCH /v1/organizations/{organizationSlug}/groups/{groupName}/configuration" 4 | --- 5 | 6 | 7 | 8 | ```bash cURL 9 | curl -L -X PATCH 'https://api.turso.tech/v1/organizations/{organizationSlug}/groups/{groupName}/configuration' \ 10 | -H 'Authorization: Bearer TOKEN' \ 11 | -H 'Content-Type: application/json' \ 12 | -d '{ 13 | "delete_protection": true 14 | }' 15 | ``` 16 | 17 | 18 | -------------------------------------------------------------------------------- /api-reference/introduction.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | sidebarTitle: Introduction 3 | title: Turso Platform API 4 | description: 5 | --- 6 | 7 | The Turso API gives you everything needed to manage your organization and its members, groups, databases, and API tokens. 8 | 9 | If you want to programatically create and manage databases, either for building a platform where you provide SQLite databases to your users or have a per-user SQLite database architecture, this is the API to do that. 10 | 11 | 12 | 13 | 14 | Get started with the Turso API to create your first database. 15 | 16 | 17 | 18 | 19 | ## API Resources 20 | 21 | Start integrating the Turso API with your platform in a few simple steps. 22 | 23 | 24 | -------------------------------------------------------------------------------- /api-reference/locations/closest-region.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Closest Region 3 | description: Returns the closest region to the user's location. 4 | sidebarTitle: Closest Region 5 | api: "GET https://region.turso.io" 6 | --- 7 | 8 | #### Response 9 | 10 | 11 | The location code for the server responding. 12 | 13 | 14 | 15 | The location code for the client request. 16 | 17 | 18 | 19 | 20 | ```bash cURL 21 | curl https://region.turso.io 22 | ``` 23 | 24 | ```ts Node.js 25 | import { createClient } from "@tursodatabase/api"; 26 | 27 | const turso = createClient({ 28 | org: "...", 29 | token: "", 30 | }); 31 | 32 | const { server, client } = await turso.locations.closest(); 33 | ``` 34 | 35 | 36 | 37 | 38 | 39 | ```json 200 40 | { 41 | "server": "lhr", 42 | "client": "lhr" 43 | } 44 | ``` 45 | 46 | 47 | -------------------------------------------------------------------------------- /api-reference/locations/list.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | sidebarTitle: List 3 | openapi: "GET /v1/locations" 4 | --- 5 | 6 | 7 | 8 | ```bash cURL 9 | curl -L https://api.turso.tech/v1/locations \ 10 | -H 'Authorization: Bearer TOKEN' 11 | ``` 12 | 13 | ```ts Node.js 14 | import { createClient } from "@tursodatabase/api"; 15 | 16 | const turso = createClient({ 17 | org: "...", 18 | token: "", 19 | }); 20 | 21 | const locations = await turso.locations.list(); 22 | ``` 23 | 24 | 25 | -------------------------------------------------------------------------------- /api-reference/organizations/invites/create.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Create Invite 3 | openapi: "POST /v1/organizations/{organizationSlug}/invites" 4 | --- 5 | 6 | 7 | 8 | If you want to invite someone who is already a registered Turso user, you can [add them](/api-reference/organizations/members/add) instead. 9 | 10 | 11 | 12 | 13 | 14 | You must be an `owner` or `admin` to invite other users. **You can only invite users to a team and not your personal account.** 15 | 16 | 17 | -------------------------------------------------------------------------------- /api-reference/organizations/invites/delete.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | sidebarTitle: Delete Invite 3 | openapi: "DELETE /v1/organizations/{organizationSlug}/invites/{email}" 4 | --- 5 | 6 | 7 | 8 | ```bash cURL 9 | curl -L -X DELETE https://api.turso.tech/v1/organizations/{organizationSlug}/invites/{email} \ 10 | -H 'Authorization: Bearer TOKEN' 11 | ``` 12 | 13 | 14 | -------------------------------------------------------------------------------- /api-reference/organizations/invites/list.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | sidebarTitle: List 3 | openapi: "GET /v1/organizations/{organizationSlug}/invites" 4 | --- 5 | 6 | 7 | 8 | ```bash cURL 9 | curl -L https://api.turso.tech/v1/organizations/{organizationSlug}/invites \ 10 | -H 'Authorization: Bearer TOKEN' 11 | ``` 12 | 13 | ```ts Node.js 14 | import { createClient } from "@tursodatabase/api"; 15 | 16 | const turso = createClient({ 17 | org: "...", 18 | token: "", 19 | }); 20 | 21 | const invites = await turso.organizations.invites("mycompany"); 22 | ``` 23 | 24 | 25 | -------------------------------------------------------------------------------- /api-reference/organizations/invoices.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | sidebarTitle: Invoices 3 | openapi: "GET /v1/organizations/{organizationSlug}/invoices" 4 | --- 5 | 6 | 7 | 8 | ```bash cURL 9 | curl -L https://api.turso.tech/v1/organizations/{organizationSlug}/invoices \ 10 | -H 'Authorization: Bearer TOKEN' 11 | ``` 12 | 13 | 14 | -------------------------------------------------------------------------------- /api-reference/organizations/list.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | sidebarTitle: List 3 | openapi: "GET /v1/organizations" 4 | --- 5 | 6 | 7 | 8 | ```bash cURL 9 | curl -L https://api.turso.tech/v1/organizations \ 10 | -H 'Authorization: Bearer TOKEN' 11 | ``` 12 | 13 | ```ts Node.js 14 | import { createClient } from "@tursodatabase/api"; 15 | 16 | const turso = createClient({ 17 | org: "...", 18 | token: "", 19 | }); 20 | 21 | const organizations = await turso.organizations.list(); 22 | ``` 23 | 24 | 25 | -------------------------------------------------------------------------------- /api-reference/organizations/members/add.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | sidebarTitle: Add 3 | openapi: "POST /v1/organizations/{organizationSlug}/members" 4 | --- 5 | 6 | 7 | 8 | If you want to add someone who is not a registered Turso user, you can [create an invite](/api-reference/organizations/invites/create) instead. 9 | 10 | 11 | 12 | 13 | 14 | You must be an `owner` or `admin` to add other members. **You can only add users to a team and not your personal account.** 15 | 16 | 17 | -------------------------------------------------------------------------------- /api-reference/organizations/members/list.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | sidebarTitle: List 3 | openapi: "GET /v1/organizations/{organizationSlug}/members" 4 | --- 5 | 6 | 7 | 8 | ```bash cURL 9 | curl -L https://api.turso.tech/v1/organizations/{organizationSlug}/members \ 10 | -H 'Authorization: Bearer TOKEN' 11 | ``` 12 | 13 | ```ts Node.js 14 | import { createClient } from "@tursodatabase/api"; 15 | 16 | const turso = createClient({ 17 | org: "...", 18 | token: "", 19 | }); 20 | 21 | const members = await turso.organizations.members("mycompany"); 22 | ``` 23 | 24 | 25 | -------------------------------------------------------------------------------- /api-reference/organizations/members/remove.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | sidebarTitle: Remove 3 | openapi: "DELETE /v1/organizations/{organizationSlug}/members/{username}" 4 | --- 5 | 6 | 7 | 8 | ```bash cURL 9 | curl -L -X DELETE https://api.turso.tech/v1/organizations/{organizationSlug}/members/{username} \ 10 | -H 'Authorization: Bearer TOKEN' 11 | ``` 12 | 13 | ```ts Node.js 14 | import { createClient } from "@tursodatabase/api"; 15 | 16 | const turso = createClient({ 17 | org: "...", 18 | token: "", 19 | }); 20 | 21 | const member = await turso.organizations.removeMember("mycompany", "iku"); 22 | ``` 23 | 24 | 25 | -------------------------------------------------------------------------------- /api-reference/organizations/members/retrieve.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | sidebarTitle: Retrieve 3 | openapi: "GET /v1/organizations/{organizationSlug}/members/{username}" 4 | --- 5 | 6 | 7 | 8 | ```bash 9 | curl -L https://api.turso.tech/v1/organizations/{organizationSlug}/members/{username} \ 10 | -H 'Authorization: Bearer TOKEN' 11 | ``` 12 | 13 | 14 | -------------------------------------------------------------------------------- /api-reference/organizations/members/update.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | sidebarTitle: Update 3 | openapi: "PATCH /v1/organizations/{organizationSlug}/members/{username}" 4 | --- 5 | 6 | 7 | 8 | ```bash 9 | curl -L -X PATCH https://api.turso.tech/v1/organizations/{organizationSlug}/members/{username} \ 10 | -H 'Authorization: Bearer TOKEN' \ 11 | -H 'Content-Type: application/json' \ 12 | -d '{ 13 | "role": "member" 14 | }' 15 | ``` 16 | 17 | 18 | -------------------------------------------------------------------------------- /api-reference/organizations/plans.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | sidebarTitle: Plans 3 | openapi: "GET /v1/organizations/{organizationSlug}/plans" 4 | --- 5 | 6 | 7 | 8 | ```bash cURL 9 | curl -L https://api.turso.tech/v1/organizations/{organizationSlug}/plans \ 10 | -H 'Authorization: Bearer TOKEN' 11 | ``` 12 | 13 | 14 | -------------------------------------------------------------------------------- /api-reference/organizations/retrieve.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | sidebarTitle: Retrieve 3 | openapi: "GET /v1/organizations/{organizationSlug}" 4 | --- 5 | 6 | 7 | 8 | ```bash 9 | curl -L https://api.turso.tech/v1/organizations/{organizationSlug} \ 10 | -H 'Authorization: Bearer TOKEN' 11 | ``` 12 | 13 | 14 | -------------------------------------------------------------------------------- /api-reference/organizations/subscription.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | sidebarTitle: Current Subscription 3 | openapi: "GET /v1/organizations/{organizationSlug}/subscription" 4 | --- 5 | 6 | 7 | 8 | ```bash cURL 9 | curl -L https://api.turso.tech/v1/organizations/{organizationSlug}/subscription \ 10 | -H 'Authorization: Bearer TOKEN' 11 | ``` 12 | 13 | 14 | -------------------------------------------------------------------------------- /api-reference/organizations/update.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | sidebarTitle: Update 3 | openapi: "PATCH /v1/organizations/{organizationSlug}" 4 | --- 5 | 6 | 7 | 8 | ```bash cURL 9 | curl -L -X PATCH https://api.turso.tech/v1/organizations/{organizationSlug} \ 10 | -H 'Authorization: Bearer TOKEN' \ 11 | -H 'Content-Type: application/json' \ 12 | -d '{ 13 | "overages": true 14 | }' 15 | ``` 16 | 17 | ```ts Node.js 18 | import { createClient } from "@tursodatabase/api"; 19 | 20 | const turso = createClient({ 21 | org: "...", 22 | token: "", 23 | }); 24 | 25 | const organization = await turso.organizations.update("mycompany", { 26 | overages: true, 27 | }); 28 | ``` 29 | 30 | 31 | -------------------------------------------------------------------------------- /api-reference/organizations/usage.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | sidebarTitle: Current Usage 3 | openapi: "GET /v1/organizations/{organizationSlug}/usage" 4 | --- 5 | 6 | 7 | 8 | ```bash cURL 9 | curl -L https://api.turso.tech/v1/organizations/{organizationSlug}/usage \ 10 | -H 'Authorization: Bearer TOKEN' 11 | ``` 12 | 13 | 14 | -------------------------------------------------------------------------------- /api-reference/quickstart.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Quickstart 3 | description: Get started with Turso API in a few easy steps. 4 | --- 5 | 6 | 7 | 8 | 9 | 10 | Make sure to [install the Turso CLI](/cli/installation) if you haven't 11 | already. 12 | 13 | 14 | 15 | ```bash Signup 16 | turso auth signup 17 | ``` 18 | 19 | ```bash Login 20 | turso auth login 21 | ``` 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | The Platform API can be used with your personal account or with an organization. You'll need the obtain the `slug` of your account or organization using using the Turso CLI: 30 | 31 | ```bash 32 | turso org list 33 | ``` 34 | 35 | 36 | 37 | 38 | 39 | Now create a new API Token using the Turso CLI: 40 | 41 | ```bash 42 | turso auth api-tokens mint quickstart 43 | ``` 44 | 45 | 46 | 47 | Make sure to save the token somewhere safe. We'll need it next. 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | Before we can create a group or database in a specific region, we'll need to fetch the list of available regions: 56 | 57 | 58 | 59 | ```bash cURL 60 | curl -L 'https://api.turso.tech/v1/locations' \ 61 | -H 'Authorization: Bearer TOKEN' \ 62 | ``` 63 | 64 | ```ts Node.js 65 | import { createClient } from "@tursodatabase/api"; 66 | 67 | const turso = createClient({ 68 | org: "...", 69 | token: "", 70 | }); 71 | 72 | const locations = await turso.locations.list(); 73 | ``` 74 | 75 | 76 | 77 |
78 | 79 | 80 | 81 | The `organizationSlug` is the name of your organization or personal account. 82 | 83 | 84 | 85 | 86 | 87 | 88 | 89 | All databases belong to a group that can exist in one or more locations. 90 | 91 | Begin by creating a group, giving it a `name` and primary `location`: 92 | 93 | 94 | 95 | ```bash cURL 96 | curl -L -X POST 'https://api.turso.tech/v1/organizations/{organizationSlug}/groups' \ 97 | -H 'Authorization: Bearer TOKEN' \ 98 | -H 'Content-Type: application/json' \ 99 | -d '{ 100 | "name": "default", 101 | "location": "lhr" 102 | }' 103 | ``` 104 | 105 | ```ts Node.js 106 | import { createClient } from "@tursodatabase/api"; 107 | 108 | const turso = createClient({ 109 | org: "...", 110 | token: "", 111 | }); 112 | 113 | const group = await turso.groups.addLocation("default", "lhr"); 114 | ``` 115 | 116 | 117 | 118 | 119 | 120 | 121 | 122 | Now create your first database in the group you created above: 123 | 124 | 125 | 126 | ```bash cURL 127 | curl -L -X POST 'https://api.turso.tech/v1/organizations/{organizationSlug}/databases' \ 128 | -H 'Authorization: Bearer TOKEN' \ 129 | -H 'Content-Type: application/json' \ 130 | -d '{ 131 | "name": "my-db", 132 | "group": "default" 133 | }' 134 | ``` 135 | 136 | ```ts Node.js 137 | import { createClient } from "@tursodatabase/api"; 138 | 139 | const turso = createClient({ 140 | org: "...", 141 | token: "", 142 | }); 143 | 144 | const database = await turso.databases.create("my-db", "ams"); 145 | ``` 146 | 147 | 148 | 149 | 150 | 151 | 152 | 153 | You now have a database, distributed across multiple regions that you can connect to using one of the official or experimental SDKs: 154 | 155 | 156 | 157 | 158 | 159 | 160 | -------------------------------------------------------------------------------- /api-reference/response-codes.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Errors 3 | description: 4 | --- 5 | 6 | The Turso API will respond with an HTTP status code, and in the event of an error, return an error message in the response body. 7 | 8 | | Code | Description | 9 | | ----- | ---------------------------------------------------------------------- | 10 | | `200` | `OK` — Successful request | 11 | | `401` | `Unauthorized` — Invalid or expired auth token | 12 | | `402` | `Payment required` — Check you have an active subscription | 13 | | `403` | `Forbidden` — You do not have permission to access this resource | 14 | | `409` | `Conflict` — Resource already exists | 15 | -------------------------------------------------------------------------------- /api-reference/tokens/create.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | sidebarTitle: Create 3 | openapi: "POST /v1/auth/api-tokens/{tokenName}" 4 | --- 5 | 6 | 7 | 8 | The `token` in the response is never revealed again. Store this somewhere safe, and never share or commit it to source control. 9 | 10 | 11 | 12 | 13 | 14 | ```bash cURL 15 | curl -L -X POST https://api.turso.tech/v1/auth/api-tokens/{tokenName} \ 16 | -H 'Authorization: Bearer TOKEN' 17 | ``` 18 | 19 | ```ts Node.js 20 | import { createClient } from "@tursodatabase/api"; 21 | 22 | const turso = createClient({ 23 | org: "...", 24 | token: "", 25 | }); 26 | 27 | const apiToken = await turso.apiTokens.create("my-token"); 28 | ``` 29 | 30 | 31 | -------------------------------------------------------------------------------- /api-reference/tokens/list.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | sidebarTitle: List 3 | openapi: "GET /v1/auth/api-tokens" 4 | --- 5 | 6 | 7 | 8 | ```bash cURL 9 | curl -L https://api.turso.tech/v1/auth/api-tokens \ 10 | -H 'Authorization: Bearer TOKEN' 11 | ``` 12 | 13 | ```ts Node.js 14 | import { createClient } from "@tursodatabase/api"; 15 | 16 | const turso = createClient({ 17 | org: "...", 18 | token: "", 19 | }); 20 | 21 | const apiTokens = await turso.apiTokens.list(); 22 | ``` 23 | 24 | 25 | -------------------------------------------------------------------------------- /api-reference/tokens/revoke.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | sidebarTitle: Revoke 3 | openapi: "DELETE /v1/auth/api-tokens/{tokenName}" 4 | --- 5 | 6 | 7 | 8 | ```bash cURL 9 | curl -L -X DELETE 'https://api.turso.tech/v1/auth/api-tokens/{tokenName}' \ 10 | -H 'Authorization: Bearer TOKEN' 11 | ``` 12 | 13 | ```ts Node.js 14 | import { createClient } from "@tursodatabase/api"; 15 | 16 | const turso = createClient({ 17 | org: "...", 18 | token: "", 19 | }); 20 | 21 | const response = await turso.apiTokens.revoke("my-token"); 22 | ``` 23 | 24 | 25 | -------------------------------------------------------------------------------- /api-reference/tokens/validate.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | sidebarTitle: Validate 3 | openapi: "GET /v1/auth/validate" 4 | --- 5 | 6 | 7 | 8 | ```bash cURL 9 | curl -L 'https://api.turso.tech/v1/auth/validate' \ 10 | -H 'Authorization: Bearer TOKEN' 11 | ``` 12 | 13 | ```ts Node.js 14 | import { createClient } from "@tursodatabase/api"; 15 | 16 | const turso = createClient({ 17 | org: "...", 18 | token: "", 19 | }); 20 | 21 | const response = await turso.apiTokens.validate("..."); 22 | ``` 23 | 24 | 25 | -------------------------------------------------------------------------------- /api-reference/versioning.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Versioning 3 | description: 4 | --- 5 | -------------------------------------------------------------------------------- /cli/auth/api-tokens/list.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: auth api-tokens list 3 | sidebarTitle: list 4 | --- 5 | 6 | To list all API tokens for the current organization, run the following command: 7 | 8 | ```bash 9 | turso auth api-tokens list 10 | ``` 11 | -------------------------------------------------------------------------------- /cli/auth/api-tokens/mint.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: auth api-tokens mint 3 | sidebarTitle: mint 4 | --- 5 | 6 | To create a new API token for the current organization, run the following command: 7 | 8 | ```bash 9 | turso auth api-tokens mint 10 | ``` 11 | -------------------------------------------------------------------------------- /cli/auth/api-tokens/revoke.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: auth api-tokens revoke 3 | sidebarTitle: revoke 4 | --- 5 | 6 | To revoke an API token for the current organization, run the following command: 7 | 8 | ```bash 9 | turso auth api-tokens revoke 10 | ``` 11 | -------------------------------------------------------------------------------- /cli/auth/login.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: auth login 3 | sidebarTitle: login 4 | --- 5 | 6 | To authenticate the Turso CLI with your account, run the following command: 7 | 8 | ```bash 9 | turso auth login 10 | ``` 11 | 12 | 13 | 14 | If you're using Windows with WSL or a remote CI/CD environment, pass the --headless flag. 15 | 16 | 17 | 18 | ## Flags 19 | 20 | | Flag | Description | 21 | | ------------ | ----------------------------------------------------------------- | 22 | | `--headless` | Useful when the CLI can't interact with the system's web browser. | 23 | -------------------------------------------------------------------------------- /cli/auth/logout.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: auth logout 3 | sidebarTitle: logout 4 | --- 5 | 6 | To logout of the Turso CLI, run the following command: 7 | 8 | ```bash 9 | turso auth logout 10 | ``` 11 | 12 | ## Flags 13 | 14 | | Flag | Description | 15 | | ----------- | --------------------------------------------- | 16 | | `-a, --all` | Invalidate all sessions for the current user. | 17 | -------------------------------------------------------------------------------- /cli/auth/signup.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: auth signup 3 | sidebarTitle: signup 4 | --- 5 | 6 | To sign up for a new Turso account using the CLI, run the following command: 7 | 8 | ```bash 9 | turso auth signup 10 | ``` 11 | 12 | 13 | 14 | If you're using Windows with WSL or a remote CI/CD environment, pass the --headless flag. 15 | 16 | 17 | 18 | ## Flags 19 | 20 | | Flag | Description | 21 | | ------------ | ----------------------------------------------------------------- | 22 | | `--headless` | Useful when the CLI can't interact with the system's web browser. | 23 | -------------------------------------------------------------------------------- /cli/auth/token.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: auth token 3 | sidebarTitle: token 4 | --- 5 | 6 | You can obtain your current API token that is used to authenticate with the Turso Platform API by running the following command: 7 | 8 | ```bash 9 | turso auth token 10 | ``` 11 | -------------------------------------------------------------------------------- /cli/auth/whoami.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: auth whoami 3 | sidebarTitle: whoami 4 | --- 5 | 6 | You can obtain the username for the currently logged in user by running the following command: 7 | 8 | ```bash 9 | turso auth whoami 10 | ``` 11 | -------------------------------------------------------------------------------- /cli/authentication.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Authentication 3 | --- 4 | 5 | ## `login` 6 | 7 | The Turso CLI uses an access token to authenticate with Turso. You can login using the command: 8 | 9 | ```bash 10 | turso auth login 11 | ``` 12 | 13 | This will open a browser window, asking you to log into your account with GitHub. 14 | 15 | 16 | 17 | If you're using Windows with WSL or a remote CI/CD environment, pass the `--headless` flag. 18 | 19 | 20 | 21 | Once you're logged in, you can manage your account and databases. You can explore all of the commands via the docs, or by using the `--help` flag for each subcommand: 22 | 23 | ```bash 24 | turso 25 | ``` 26 | 27 | 28 | 29 | The Turso CLI requires you to reauthenticate after one week. Don't share your token. 30 | 31 | 32 | 33 | ## `signup` 34 | 35 | If you're new to Turso, you can create an account using the Turso CLI: 36 | 37 | ```bash 38 | turso auth signup 39 | ``` 40 | 41 | ## `logout` 42 | 43 | You can logout of the Turso CLI using the `logout` command: 44 | 45 | ```bash 46 | turso auth logout 47 | ``` 48 | -------------------------------------------------------------------------------- /cli/contact/bookmeeting.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: contact bookmeeting 3 | sidebarTitle: bookmeeting 4 | --- 5 | 6 | You can book a meeting with the Turso team to discuss your project and requirements using the following command: 7 | 8 | ```bash 9 | turso contact bookmeeting 10 | ``` 11 | 12 | 13 | 14 | You will be redirected to a webpage where you can select a date and time for the meeting. 15 | 16 | 17 | -------------------------------------------------------------------------------- /cli/contact/feedback.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: contact feedback 3 | sidebarTitle: feedback 4 | --- 5 | 6 | You can send feedback to the Turso team by using the following command: 7 | 8 | ```bash 9 | turso contact feedback 10 | ``` 11 | -------------------------------------------------------------------------------- /cli/db/destroy.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: db destroy 3 | sidebarTitle: destroy 4 | --- 5 | 6 | You can destroy a database by using the following command: 7 | 8 | ```bash 9 | turso db destroy [flags] 10 | ``` 11 | 12 | ## Flags 13 | 14 | | Flag | Description | 15 | | ------------- | -------------------------------------- | 16 | | `-y`, `--yes` | Confirms the destruction the database. | 17 | -------------------------------------------------------------------------------- /cli/db/import.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: db import 3 | sidebarTitle: import 4 | --- 5 | 6 | You can import an existing SQLite file to Turso Cloud using the following command: 7 | 8 | ```bash 9 | turso db import ~/path/to/database.db 10 | ``` 11 | 12 | 13 | 14 | Make sure the SQLite file has WAL journal mode enabled. 15 | 16 | 17 | 18 | 19 | 20 | If you have more than one group, you will need to pass the `--group` flag. 21 | 22 | 23 | 24 | ## Flags 25 | 26 | | Flag | Description | 27 | | -------------- | ------------------------------------------- | 28 | | `--group` | Import the database in the specified group. | 29 | | `-h`, `--help` | Get help for import. | 30 | -------------------------------------------------------------------------------- /cli/db/inspect.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: db inspect 3 | sidebarTitle: inspect 4 | --- 5 | 6 | You can inspect the usage of a database, including the total space used, rows read and written with the following command: 7 | 8 | ```bash 9 | turso db inspect 10 | ``` 11 | 12 | ## Flags 13 | 14 | | Flag | Description | 15 | | ----------- | -------------------------------------------------------------------- | 16 | | `--queries` | Show database query statistics. | 17 | | `--verbose` | Show detailed information, including the location and instance type. | 18 | 19 | ## Examples 20 | 21 | ### Top Queries 22 | 23 | You can fetch the most executed, resource-intensive SQL statements that have been run against your database using the Turso CLI: 24 | 25 | 26 | 27 | ```bash Command 28 | turso db inspect --queries 29 | ``` 30 | 31 | ```bash Response 32 | SELECT * FROM Orders WHERE Status = 'Pending'; 33 | SELECT COUNT(*), CustomerID FROM Orders GROUP BY CustomerID HAVING COUNT(*) > 5; 34 | SELECT Orders.OrderID, Customers.CustomerName FROM Orders INNER JOIN Customers ON Orders.CustomerID = Customers.CustomerID; 35 | UPDATE Products SET Price = Price * 1.10 WHERE Category = 'Electronics'; 36 | ``` 37 | 38 | 39 | -------------------------------------------------------------------------------- /cli/db/list.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: db list 3 | sidebarTitle: list 4 | --- 5 | 6 | You can obtain a list of all databases for the current user or organization by running the following command: 7 | 8 | ```bash 9 | turso db list 10 | ``` 11 | 12 | ## Flags 13 | 14 | | Flag | Description | 15 | | ---------------------- | -------------------------- | 16 | | `--group ` | Filter databases by group. | 17 | -------------------------------------------------------------------------------- /cli/db/locations.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: db locations 3 | sidebarTitle: locations 4 | --- 5 | 6 | You can fetch a list of supported locations where databases can be located by running the following command: 7 | 8 | ```bash 9 | turso db locations 10 | ``` 11 | 12 | ## Flags 13 | 14 | | Flag | Description | 15 | | ------------------------ | ------------------------------------------------------------------------- | 16 | | `-l`, `--show-latencies` | Display latencies from your current location to each of Turso's locations | 17 | -------------------------------------------------------------------------------- /cli/db/shell.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: db shell 3 | sidebarTitle: shell 4 | --- 5 | 6 | You can connect directly to a Turso database by using the following command: 7 | 8 | ```bash 9 | turso db shell [sql] [flags] 10 | ``` 11 | 12 | ## Flags 13 | 14 | | Flag | Description | 15 | | ---------------------------- | -------------------------------------------------- | 16 | | `--instance ` | Connect to the specified database instance. | 17 | | `--location ` | Connect to the database at the specified location. | 18 | | `--proxy ` | The proxy to use when connecting to the database. | 19 | 20 | ## Examples 21 | 22 | ### Execute SQL 23 | 24 | You can execute SQL directly against a database using the shell: 25 | 26 | ```bash 27 | turso db shell "SELECT * FROM users" 28 | ``` 29 | 30 | ### Database dump 31 | 32 | You can dump the contents of a Turso database using the following command: 33 | 34 | ```bash 35 | turso db shell .dump > dump.sql 36 | ``` 37 | 38 | 39 | 40 | The `.dump` can be used to rebuild a database and doesn't contain any libSQL or SQLite internal tables. 41 | 42 | 43 | 44 | ### Load from dump 45 | 46 | You can load a dump file into a new database using the following command: 47 | 48 | ```bash 49 | turso db shell < dump.sql 50 | ``` 51 | 52 | ### Shell with libSQL server 53 | 54 | If you're using `turso dev` locally, you can use the shell by providing the URL to your database: 55 | 56 | ```bash 57 | turso db shell http://127.0.0.1:8080 58 | ``` 59 | -------------------------------------------------------------------------------- /cli/db/show.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: db show 3 | sidebarTitle: show 4 | --- 5 | 6 | You can obtain details about the database, including the name, ID, libSQL server version, group, size and location. 7 | 8 | ```bash 9 | turso db show [flags] 10 | ``` 11 | 12 | You can also obtain the different URLs for the database using the following: 13 | 14 | ## Flags 15 | 16 | | Flag | Description | 17 | | ------------ | ---------------------------------------- | 18 | | `--url` | Show URL for the database HTTP API. | 19 | | `--http-url` | Show HTTP URL for the database HTTP API. | 20 | -------------------------------------------------------------------------------- /cli/db/tokens/create.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: db tokens create 3 | sidebarTitle: create 4 | --- 5 | 6 | You can create a new token that can be used to connect to one database using the command: 7 | 8 | ```bash 9 | turso db tokens create [flags] 10 | ``` 11 | 12 | ## Flags 13 | 14 | | Flag | Description | 15 | | -------------------- | ------------------------------------------------------------------------------- | 16 | | `-e`, `--expiration` | The expiration time for a token, can be `never` or a value in days, e.g. `7d` . | 17 | | `-r`, `--read-only` | Restrict the token to read only access. | 18 | 19 | ## Examples 20 | 21 | The examples below outline the most common use cases for the `db tokens create` command. 22 | 23 | ### Create a token with read only access 24 | 25 | You can create a token with read only access to a database using the following command: 26 | 27 | ```bash 28 | turso db tokens create --read-only 29 | ``` 30 | 31 | ### Create a token with a specific expiration time 32 | 33 | You can create a token with a specific expiration time using the following command: 34 | 35 | ```bash 36 | turso db tokens create --expiration 7d3h2m1s 37 | ``` 38 | -------------------------------------------------------------------------------- /cli/db/tokens/invalidate.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: db tokens invalidate 3 | sidebarTitle: invalidate 4 | --- 5 | 6 | You can invalidate all tokens for a database by running the following command: 7 | 8 | ```bash 9 | turso db tokens invalidate [flags] 10 | ``` 11 | 12 | ## Flags 13 | 14 | | Flag | Description | 15 | | ------------- | ---------------------------------------------------- | 16 | | `-y`, `--yes` | Confirms the invalidation of all existing db tokens. | 17 | 18 | 19 | 20 | All tokens in the group that provided database belongs will also be invalidated. This means that all existing tokens will no longer be valid and will need to be regenerated. 21 | 22 | 23 | -------------------------------------------------------------------------------- /cli/db/wakeup.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: db unarchive 3 | sidebarTitle: unarchive 4 | --- 5 | 6 | You can unarchive inactive databases by running the following command: 7 | 8 | ```bash 9 | turso db unarchive 10 | ``` 11 | 12 | 13 | 14 | Databases get archived after 10 days of inactivity for users on a free plan — [learn more](/features/scale-to-zero). 15 | 16 | 17 | -------------------------------------------------------------------------------- /cli/dev.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: dev 3 | url: /local-development#turso-cli 4 | --- 5 | -------------------------------------------------------------------------------- /cli/group/aws-migration/abort.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: group aws-migration abort 3 | sidebarTitle: abort 4 | --- 5 | 6 | You can abort the AWS migration process by using the following command: 7 | 8 | ```bash 9 | turso group aws-migration abort 10 | ``` 11 | -------------------------------------------------------------------------------- /cli/group/aws-migration/info.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: group aws-migration info 3 | sidebarTitle: info 4 | --- 5 | 6 | You can check the AWS migration details by using the following command: 7 | 8 | ```bash 9 | turso group aws-migration info 10 | ``` 11 | -------------------------------------------------------------------------------- /cli/group/aws-migration/start.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: group aws-migration start 3 | sidebarTitle: start 4 | --- 5 | 6 | You can start the AWS migration process by using the following command: 7 | 8 | ```bash 9 | turso group aws-migration start 10 | ``` 11 | -------------------------------------------------------------------------------- /cli/group/create.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: group create 3 | sidebarTitle: create 4 | --- 5 | 6 | You can create a new group of databases. Groups belong to a primary region. 7 | 8 | ```bash 9 | turso group create [flags] 10 | ``` 11 | 12 | 13 | Creating more than one group is limited to Scaler, Pro and Enterprise plans. 14 | 15 | 16 | 17 | 18 | Turso will automatically detect the closest region and use that as the primary region. You can override this by specifying the `--location` flag. 19 | 20 | 21 | 22 | ## Flags 23 | 24 | | Flag | Description | 25 | | -------------- | --------------------------------------------------------------------------- | 26 | | `--canary` | Use database canary build. | 27 | | `--location` | Create the group in the specified priary location using a three-digit code. | 28 | | `-w`, `--wait` | Wait for group to be ready before exiting. | 29 | -------------------------------------------------------------------------------- /cli/group/destroy.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: group destroy 3 | sidebarTitle: destroy 4 | --- 5 | 6 | You can destroy a group and all of its databases using the following command: 7 | 8 | ```bash 9 | turso group destroy [flags] 10 | ``` 11 | 12 | ## Flags 13 | 14 | | Flag | Description | 15 | | ------------- | ---------------------------------------------------------------- | 16 | | `-y`, `--yes` | Confirms destroying the group, with all locations and databases. | 17 | -------------------------------------------------------------------------------- /cli/group/list.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: group list 3 | sidebarTitle: list 4 | --- 5 | 6 | You can obtain a list of all groups by using the following command: 7 | 8 | ```bash 9 | turso group list 10 | ``` 11 | -------------------------------------------------------------------------------- /cli/group/locations/add.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: group locations add 3 | sidebarTitle: add 4 | --- 5 | 6 | You can replicate databases globally by adding locations to a group using the following command: 7 | 8 | ```bash 9 | turso group locations add [flags] 10 | ``` 11 | 12 | ## Flags 13 | 14 | | Flag | Description | 15 | | -------------- | ------------------------------------------ | 16 | | `-w`, `--wait` | Wait for group to be ready before exiting. | 17 | -------------------------------------------------------------------------------- /cli/group/locations/remove.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: group locations remove 3 | sidebarTitle: remove 4 | --- 5 | 6 | You can remove locations from a group using the command below: 7 | 8 | ```bash 9 | turso group locations remove <...location-codes> 10 | ``` 11 | 12 | 13 | 14 | All database replicas belonging to the provided group will be immediately removed from the locations. 15 | 16 | 17 | -------------------------------------------------------------------------------- /cli/group/tokens/create.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: group tokens create 3 | sidebarTitle: create 4 | --- 5 | 6 | You can create a new token that can be used to connect to any database in the group using the command: 7 | 8 | ```bash 9 | turso group tokens create [flags] 10 | ``` 11 | 12 | ## Flags 13 | 14 | | Flag | Description | 15 | | -------------------- | ------------------------------------------------------------------------------- | 16 | | `-e`, `--expiration` | The expiration time for a token, can be `never` or a value in days, e.g. `7d` . | 17 | | `-r`, `--read-only` | Restrict the token to read only access. | 18 | 19 | ## Examples 20 | 21 | The examples below outline the most common use cases for the `group tokens create` command. 22 | 23 | ### Create a token with read only access 24 | 25 | You can create a token with read only access using the command: 26 | 27 | ```bash 28 | turso group tokens create --read-only 29 | ``` 30 | 31 | ### Create a token with a specific expiration time 32 | 33 | You can create a token with a specific expiration time using the command: 34 | 35 | ```bash 36 | turso group tokens create --expiration 7d 37 | ``` 38 | -------------------------------------------------------------------------------- /cli/group/tokens/invalidate.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: group tokens invalidate 3 | sidebarTitle: invalidate 4 | --- 5 | 6 | You can invalidate all tokens for a group by running the command: 7 | 8 | ```bash 9 | turso group tokens invalidate [flags] 10 | ``` 11 | 12 | ## Flags 13 | 14 | | Flag | Description | 15 | | ------------- | ------------------------------------------------------- | 16 | | `-y`, `--yes` | Confirms the invalidation of all existing group tokens. | 17 | -------------------------------------------------------------------------------- /cli/group/transfer.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: group transfer 3 | sidebarTitle: transfer 4 | --- 5 | 6 | You can transfer a group (including its databases) to an organization you're an admin or owner of using the following command: 7 | 8 | ```bash 9 | turso group transfer [flags] 10 | ``` 11 | 12 | 13 | 14 | Existing database URL and tokens will continue to work, but should update your application to use the new URL and token as soon as possible. 15 | 16 | 17 | 18 | ## Flags 19 | 20 | | Flag | Description | 21 | | ------------- | -------------------------------------------- | 22 | | `-y`, `--yes` | Confirms the transfer to a new organization. | 23 | -------------------------------------------------------------------------------- /cli/group/unarchive.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: group unarchive 3 | sidebarTitle: unarchive 4 | --- 5 | 6 | You can unarchive inactive databases by running the following command: 7 | 8 | ```bash 9 | turso group unarchive 10 | ``` 11 | 12 | 13 | 14 | Databases get archived after 10 days of inactivity for users on a free plan — [learn more](/features/scale-to-zero). 15 | 16 | 17 | -------------------------------------------------------------------------------- /cli/group/update.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: group update 3 | sidebarTitle: update 4 | --- 5 | 6 | You can update the group, including all databases the following command: 7 | 8 | ```bash 9 | turso group update [flags] 10 | ``` 11 | 12 | ## Flags 13 | 14 | | Flag | Description | 15 | | --------------------- | ----------------------------------------------------------------------------------- | 16 | | `--extensions string` | Enable extensions by passing `all` or `none`. | 17 | | `--version string` | Specify the version of the group to update to. Values include `latest` or `canary`. | 18 | | `-y`, `--yes` | Skip confirmation prompt and confirm. | 19 | 20 | ## Examples 21 | 22 | ### Update a group to enable all extensions 23 | 24 | You can update a group and all its databases to enable `all` extensions: 25 | 26 | ```bash 27 | turso group update --extensions all 28 | ``` 29 | -------------------------------------------------------------------------------- /cli/headless-mode.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Headless Mode 3 | --- 4 | 5 | The Turso CLI will automatically attempt to open a browser, or wait for further instructions when interacting with various commands. 6 | 7 | You can opt out of this behaviour by passing the `--headless` flag with operations: 8 | 9 | ```bash 10 | turso auth login --headless 11 | ``` 12 | 13 | 14 | 15 | If you're using Windows with WSL or a remote CI/CD environment, pass the `--headless` flag. 16 | 17 | 18 | -------------------------------------------------------------------------------- /cli/help.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Help 3 | --- 4 | 5 | You can always find a summary of all commands by running the following command: 6 | 7 | ```bash 8 | turso help 9 | ``` 10 | 11 | You can also find out more about each command, as well as any required or optional arguments by passing the `--help` flag to the command: 12 | 13 | ```bash 14 | turso auth --help 15 | turso db create --help 16 | ``` 17 | 18 | If you require support integrating Turso into your project, [we can help](/support). 19 | -------------------------------------------------------------------------------- /cli/installation.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Installation 3 | description: Learn how to install the Turso CLI on Mac, Linux and Windows. 4 | --- 5 | 6 | ## macOS 7 | 8 | To install the Turso CLI on macOS, we recommend that you use Homebrew: 9 | 10 | ```bash 11 | brew install tursodatabase/tap/turso 12 | ``` 13 | 14 | If you don't use Homebrew, you can use the following command to execute a shell script that installs the CLI: 15 | 16 | ```bash 17 | curl -sSfL https://get.tur.so/install.sh | bash 18 | ``` 19 | 20 | ## Linux 21 | 22 | Run the following command to execute a shell script that installs the CLI: 23 | 24 | ```bash 25 | curl -sSfL https://get.tur.so/install.sh | bash 26 | ``` 27 | 28 | ## Windows 29 | 30 | Installing the Turso CLI on Windows requires that you have [WSL](https://learn.microsoft.com/en-us/windows/wsl/install) installed. 31 | 32 | Once WSL is installed, run the following in PowerShell: 33 | 34 | ```bash 35 | wsl 36 | ``` 37 | 38 | You can then execute the script to install the Turso CLI: 39 | 40 | ```bash 41 | curl -sSfL https://get.tur.so/install.sh | bash 42 | ``` 43 | 44 | ## Verify installation 45 | 46 | You must open a new shell to verify the installation with the following command: 47 | 48 | ```bash 49 | turso 50 | ``` 51 | -------------------------------------------------------------------------------- /cli/introduction.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Introduction 3 | --- 4 | 5 | The Turso CLI gives you everything you need from the command line to manage your database, API tokens, inviting users, and launching the database shell. If you're waiting for a migration to run, there's also a relax command. 6 | 7 | You can also programmatically manage your Turso account, including groups, databases, organizations and invites using the [Platform API](/api-reference). 8 | 9 | 10 | 11 | 12 | 13 | Begin by installing the Turso CLI: 14 | 15 | 16 | 17 | ```bash macOS 18 | brew install tursodatabase/tap/turso 19 | ``` 20 | 21 | ```bash Linux 22 | curl -sSfL https://get.tur.so/install.sh | bash 23 | ``` 24 | 25 | ```bash Windows (WSL) 26 | curl -sSfL https://get.tur.so/install.sh | bash 27 | ``` 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | Now signup or login: 36 | 37 | 38 | 39 | ```bash Signup 40 | turso auth signup 41 | ``` 42 | 43 | ```bash Login 44 | turso auth login 45 | ``` 46 | 47 | ```bash Signup (WSL) 48 | turso auth signup --headless 49 | ``` 50 | 51 | ```bash Login (WSL) 52 | turso auth login --headless 53 | ``` 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | The Turso CLI provides the following commands: 62 | 63 | | Command | Description | 64 | | --------------------------- | -------------------------------------------------------------------- | 65 | | [`auth`](/cli/auth) | Authenticate and manage API tokens. | 66 | | [`contact`](/cli/contact) | Submit your feedback, ideas and create a meeting with the team. | 67 | | [`db`](/cli/db) | Create and manage databases, access tokens and connect to the shell. | 68 | | `dev` | Run Turso [locally](/local-development) for development. | 69 | | [`group`](/cli/group) | Create groups for databases with a shared location. | 70 | | [`org`](/cli/org) | Manage billing and invite members. | 71 | | [`plan`](/cli/plan) | `overages`, `select`, `show`, `upgrade` | 72 | | [`quickstart`](/quickstart) | Get started with Turso in 5 minutes. | 73 | | `relax` | Take some time out and relax with Turso. | 74 | | `update` | Update to the Turso CLI to the latest version with one command. | 75 | 76 | 77 | 78 | 79 | -------------------------------------------------------------------------------- /cli/org/billing.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: org billing 3 | sidebarTitle: billing 4 | --- 5 | 6 | To open the billing portal for your organization: 7 | 8 | ```bash 9 | turso org billing 10 | ``` 11 | -------------------------------------------------------------------------------- /cli/org/create.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: org create 3 | sidebarTitle: create 4 | --- 5 | 6 | To create a new organization that you own, run the following command: 7 | 8 | ```bash 9 | turso org create 10 | ``` 11 | 12 | 13 | 14 | You will be asked to add a payment method and subscribe to the Scaler plan to successfully create a new organization. 15 | 16 | 17 | -------------------------------------------------------------------------------- /cli/org/destroy.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: destroy 3 | --- 4 | 5 | To delete an existing organization that you own, run the following command: 6 | 7 | ```bash 8 | turso org destroy 9 | ``` 10 | 11 | 12 | 13 | You will need to transfer or delete any existing projects before you can delete an organization. Users cannot also destroy the a personal account or active organization. 14 | 15 | 16 | -------------------------------------------------------------------------------- /cli/org/list.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: org list 3 | sidebarTitle: list 4 | --- 5 | 6 | To list organizations of which you are the owner or a member, run the following command: 7 | 8 | ```bash 9 | turso org list 10 | ``` 11 | -------------------------------------------------------------------------------- /cli/org/members/add.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: org members add 3 | sidebarTitle: add 4 | --- 5 | 6 | To add an existing Turso user as a member to the current active organization, run the following command: 7 | 8 | ```bash 9 | turso org members add [flags] 10 | ``` 11 | 12 | ## Flags 13 | 14 | | Flag | Description | 15 | | --------------- | ------------------------- | 16 | | `-a`, `--admin` | Add the user as an admin. | 17 | -------------------------------------------------------------------------------- /cli/org/members/invite.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: org members invite 3 | sidebarTitle: invite 4 | --- 5 | 6 | To invite someone who isn't already a Turso user to the current active organization, run the following command: 7 | 8 | ```bash 9 | turso org members invite [flags] 10 | ``` 11 | 12 | ## Flags 13 | 14 | | Flag | Description | 15 | | --------------- | ------------------------- | 16 | | `-a`, `--admin` | Add the user as an admin. | 17 | -------------------------------------------------------------------------------- /cli/org/members/list.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: org members list 3 | sidebarTitle: list 4 | --- 5 | 6 | To list all members of the current active organization, run the following command: 7 | 8 | ```bash 9 | turso org members list 10 | ``` 11 | 12 | 13 | 14 | This command is only available to active organizations, use [`org switch`](/cli/org/switch) if you're currently authenticated with your personal account. 15 | 16 | 17 | -------------------------------------------------------------------------------- /cli/org/members/rm.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: org members rm 3 | sidebarTitle: rm 4 | --- 5 | 6 | To remove a member from the current organization, use the following command: 7 | 8 | ```bash 9 | turso org members rm 10 | ``` 11 | -------------------------------------------------------------------------------- /cli/org/switch.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: org switch 3 | sidebarTitle: switch 4 | --- 5 | 6 | To switch the current active organization for the CLI, use the following command: 7 | 8 | ```bash 9 | turso org switch 10 | ``` 11 | -------------------------------------------------------------------------------- /cli/plan/overages/disable.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: plan overages disable 3 | sidebarTitle: disable 4 | --- 5 | 6 | You can disable overages for the current repository by running the following command: 7 | 8 | ```bash 9 | turso plan overages disable 10 | ``` 11 | 12 | 13 | 14 | Any overages that have already been incurred will still be charged. 15 | 16 | 17 | -------------------------------------------------------------------------------- /cli/plan/overages/enable.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: plan overages enable 3 | sidebarTitle: enable 4 | --- 5 | 6 | You can enable overages for the current repository by running the following command: 7 | 8 | ```bash 9 | turso plan overages enable 10 | ``` 11 | -------------------------------------------------------------------------------- /cli/plan/select.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: plan select 3 | sidebarTitle: select 4 | --- 5 | 6 | You can switch your current plan at any time using the command: 7 | 8 | ```bash 9 | turso plan select 10 | ``` 11 | 12 | 13 | 14 | You will need to add your credit card details to your account before you can upgrade to a paid plan. [Learn more](https://turso.tech/pricing) about pricing. 15 | 16 | 17 | -------------------------------------------------------------------------------- /cli/plan/show.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: plan show 3 | sidebarTitle: show 4 | --- 5 | 6 | You can show the current plan usage and limits with the command: 7 | 8 | ```bash 9 | turso plan show 10 | ``` 11 | -------------------------------------------------------------------------------- /cli/plan/upgrade.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: plan upgrade 3 | sidebarTitle: upgrade 4 | --- 5 | 6 | You can upgrade your account to a paid plan at any time using the command: 7 | 8 | ```bash 9 | turso plan upgrade 10 | ``` 11 | 12 | 13 | 14 | You will need to add your credit card details to your account before you can upgrade to a paid plan. 15 | 16 | 17 | -------------------------------------------------------------------------------- /cli/upgrading.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Upgrading 3 | description: Update the Turso CLI to the latest version to benefit from all the latest features, and fixes. 4 | --- 5 | 6 | ## macOS 7 | 8 | ```bash 9 | brew update 10 | brew upgrade 11 | ``` 12 | 13 | ## Linux 14 | 15 | ```bash 16 | turso update 17 | ``` 18 | 19 | ## Windows 20 | 21 | ```bash 22 | turso update 23 | ``` 24 | -------------------------------------------------------------------------------- /data-and-connections.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Data & Connections 3 | description: Learn how data consistency and connections work with Turso databases. 4 | --- 5 | 6 | Turso, an extension of [libSQL](/libsql) (a SQLite fork), modifies the consistency model due to its network-accessible and replicated nature, deviating from SQLite's strictly serializable standard. 7 | 8 | ## Establishing Connections 9 | 10 | Database operations begin with a client establishing either an HTTP or websocket connection to a database. Following this, an internal SQLite database connection is set up within the server to facilitate the operations. 11 | 12 | ## Data Consistency 13 | 14 | Database operations are tightly controlled to maintain order and data integrity. 15 | 16 | ### Primary Database Operations 17 | 18 | - All operations are linearizable, maintaining an ordered history. 19 | - Writes are fully serialized, with subsequent writes awaiting transaction completion. 20 | - Users should exercise caution with long-running or abandoned transactions to prevent blocking other writes. 21 | 22 | ## Transactional Consistency 23 | 24 | - Transactions in libSQL, encompassing both batch and interactive transactions, adhere to SQLite's transaction semantics. 25 | - libSQL provides snapshot isolation for read operations, ensuring immediate visibility of writes within the same process. This guarantees serializability and isolation from other transactions. 26 | -------------------------------------------------------------------------------- /favicon.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | -------------------------------------------------------------------------------- /features/branching.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Branching 3 | description: 4 | --- 5 | 6 | A branch is a separate database instance that is created from an existing database. You can also create a branch from a [point-in-time](/features/point-in-time-recovery) snapshot of a database. Branches are useful for development and testing, because they allow you to make changes to the database without affecting the original database. 7 | 8 | ## How it works 9 | 10 | 1. You create a new database from an existing database using the CLI or API. 11 | 2. You connect to the new database using the group API token. 12 | 3. Make changes to the new schema using a migration tool (optional). 13 | 4. Apply the changes to the original database using a migration tool when merging using a GitHub Action (optional). 14 | 5. Delete the database when you no longer need it. 15 | 16 | ## Usage 17 | 18 | You can create a new database from an existing database using the CLI or API: 19 | 20 | 21 | 22 | ```bash CLI 23 | turso db create my-new-database-branch --from-db my-existing-database 24 | ``` 25 | 26 | ```bash Platform API 27 | curl -L -X POST 'https://api.turso.tech/v1/organizations/{organizationSlug}/databases' \ 28 | -H 'Authorization: Bearer TOKEN' \ 29 | -H 'Content-Type: application/json' \ 30 | -d '{ 31 | "name": "new-database", 32 | "group": "default", 33 | "seed": { 34 | "type:": "database", 35 | "name": "my-existing-database" 36 | } 37 | }' 38 | ``` 39 | 40 | 41 | 42 | Refer to the following references for more details about all arguments: 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | ## Things to know 57 | 58 | - Database branches are completely separate from the original database. This means that you need to handle merging any schema changes or data manually using a migration tool. 59 | - You will need to [create a new token](/cli/db/tokens/create) (or use a group token) to connect to the new database. 60 | - You will need to manually delete the database branch when you no longer need it. 61 | - Branches count towards your plan's database quota. 62 | 63 | ## CI/CD 64 | 65 | Automating branching is useful for creating a new database for each pull request. This allows you to test changes without affecting the original database. 66 | 67 | Here's an example of what that might look like using the [Platform API](/api-reference/databases/create): 68 | 69 | ```yml .github/workflows/create-database-branch.yml 70 | name: Create Database 71 | on: create 72 | 73 | jobs: 74 | triggerAPI: 75 | runs-on: ubuntu-latest 76 | steps: 77 | - name: Generate Branch Name 78 | id: branch_name 79 | run: | 80 | BRANCH_NAME=$(echo "${{ github.ref_name }}" | tr -cd '[:alnum:]' | sed 's/./\L&/g' | cut -c 1-32) 81 | echo "::set-output name=branch_name::$BRANCH_NAME" 82 | - name: Create Database 83 | run: | 84 | curl -X POST \ 85 | -H "Authorization: Bearer ${{ secrets.API_TOKEN }}" \ 86 | -H "Content-Type: application/json" \ 87 | -d '{"name": "${{ steps.branch_name.outputs.branch_name }}", "group": "default", "seed": {"type": "database", "name": "${{ secrets.DATABASE_NAME }}"} }' \ 88 | "https://api.turso.tech/v1/organizations/${{ secrets.ORGANIZATION_NAME }}/databases" 89 | ``` 90 | -------------------------------------------------------------------------------- /features/data-edge.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Data Edge (Deprecated) 3 | description: Allow your users to reach local replicas of your database, wherever they are. 4 | --- 5 | 6 | 7 | This feature is now deprecated for all new users. Existing users can continue 8 | to use Edge Replicas on Fly — [read the 9 | announcement](https://turso.tech/blog/upcoming-changes-to-the-turso-platform-and-roadmap) 10 | 11 | 12 | For those seeking the ultimate in speed, Turso enables the [embedding of databases](/features/embedded-replicas) directly within your application on the same node. This configuration eliminates inter-regional request hopping, effectively bringing latency down to zero. 13 | 14 | 24 | 25 | ## How it works 26 | 27 | 1. You create a database in a primary location 28 | 2. You add additional locations where data should be replicated 29 | 3. You query a single URL that automatically routes to the nearest edge 30 | 31 | 32 | 33 | Turso automatically handles keeping replicas updated — [learn more](/data-and-connections). 34 | 35 | 36 | 37 | ## Add replica location 38 | 39 | You can add locations to your database group using the [Turso CLI](/cli/group/locations/add) or [Platform API](/api-reference/groups/add-location): 40 | 41 | 42 | 43 | ```bash CLI 44 | turso group locations add 45 | ``` 46 | 47 | ```bash Platform API 48 | curl -L -X POST 'https://api.turso.tech/v1/organizations/{organizationSlug}/groups/{groupName}/locations/{location}' \ 49 | -H 'Authorization: Bearer TOKEN' 50 | ``` 51 | 52 | 53 | 54 | ## Remove replica location 55 | 56 | You can remove locations from your database group using the [Turso CLI](/cli/group/locations/remove) or [Platform API](/api-reference/groups/remove-location): 57 | 58 | 59 | 60 | ```bash CLI 61 | turso group locations remove <...location-codes> 62 | ``` 63 | 64 | ```bash Platform API 65 | curl -L -X DELETE 'https://api.turso.tech/v1/organizations/{organizationSlug}/groups/{groupName}/locations/{location}' \ 66 | -H 'Authorization: Bearer TOKEN' 67 | ``` 68 | 69 | 70 | -------------------------------------------------------------------------------- /features/embedded-replicas/read-your-writes.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/tursodatabase/turso-docs/60e72d978353bcb8d5c5d0ff6cb68a822844cad4/features/embedded-replicas/read-your-writes.png -------------------------------------------------------------------------------- /features/embedded-replicas/rust/railway.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Turso + Railway 3 | sidebarTitle: 4 | description: Deploy a Rust app using [Turso embedded replicas](/features/embedded-replicas) to [Railway](https://railway.app/). 5 | --- 6 | 7 | ![Koyeb banner](/images/platforms/railway-banner.png) 8 | 9 | ## Prerequisites 10 | 11 | Before you start, make sure you: 12 | 13 | - [Install the Turso CLI](/cli/installation) 14 | - [Sign up or login to Turso](/cli/authentication#signup) 15 | - [Install the Railway CLI](https://docs.railway.app/guides/cli#installing-the-cli) 16 | 17 | 18 | 19 | 20 | 21 | You will need an existing database to continue. If you don't have one, [create one](/quickstart). 22 | 23 | 24 | 25 | You will want to store these as environment variables. 26 | 27 | 28 | 29 | 30 | Fork and clone the following embedded replica project from GitHub locally: 31 | 32 | 37 | See the full source code 38 | 39 | 40 | 41 | 42 | 43 | Run the following command to create a new Railway project. Provide the project's name when prompted. 44 | 45 | ```sh 46 | railway init 47 | ``` 48 | 49 | 50 | 51 | 52 | 53 | [Create a new empty service](https://docs.railway.app/guides/services#creating-a-service) on your Railway project to act as your app's deployment target. 54 | 55 | 56 | 57 | 58 | 59 | Run the following command to list and select the service to link to your application: 60 | 61 | ```sh 62 | railway service 63 | ``` 64 | 65 | 66 | 67 | 68 | 69 | Open the service on your Railway dashboard and add your Turso database Credentials. 70 | 71 | ```sh 72 | TURSO_DATABASE_URL=libsql://[db-name]-[github-username].turso.io 73 | TURSO_AUTH_TOKEN=... 74 | LOCAL_DB=file:db/recipe-book.db 75 | ``` 76 | 77 | 78 | 79 | 80 | 81 | Run the following command to deploy your application: 82 | 83 | ```sh 84 | railway up 85 | ``` 86 | 87 | 88 | If you are on a free plan, you'll need to connect your Railway account to GitHub to have access to code deployments. 89 | 90 | 91 | 92 | 93 | -------------------------------------------------------------------------------- /features/embedded-replicas/with-akamai.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Turso + Linode by Akamai 3 | sidebarTitle: Turso + Akamai 4 | description: Deploy a JavaScript/Rust app using [Turso embedded replicas](/features/embedded-replicas) to [Akamai](https://www.linode.com/). 5 | --- 6 | 7 | ![Akamai banner](/images/platforms/akamai-banner.png) 8 | 9 | ## Prerequisites 10 | 11 | Before you start, make sure you: 12 | 13 | - [Install the Turso CLI](/cli/installation) 14 | - [Sign up or login to Turso](/cli/authentication#signup) 15 | - Have an Akamai account - [create one](https://login.linode.com/signup) 16 | 17 | 18 | 19 | 20 | 21 | You will need an existing database to continue. If you don't have one, [create one](/quickstart). 22 | 23 | 24 | 25 | You will want to store these as environment variables. 26 | 27 | 28 | 29 | 30 | Fork one of the following embedded replica projects from GitHub 31 | 32 | 33 | 38 | See the full source code 39 | 40 | 45 | See the full source code 46 | 47 | 48 | 49 | 50 | 51 | 52 | Configure and create a new linode. Then, [set up SSH authentication](https://www.linode.com/docs/guides/use-public-key-authentication-with-ssh/) to securely access the Linode server from your terminal. 53 | 54 | Prepare the newly created linode server environment by accessing and set it up for Rust/JavaScript development depending on the project you forked earlier. Install and set up [Git](https://git-scm.com/) too. 55 | 56 | 57 | 58 | 59 | 60 | SSH into your server, clone the project from GitHub, and follow its README instructions to set it up. 61 | 62 | 63 | 64 | 65 | 66 | Build, run the project, and set up load balancing for it. 67 | [pm2](https://www.npmjs.com/package/pm2) is one of the good candidates out there with built-in load balancing, log monitoring, and bug/exception alerts. 68 | 69 | 70 | You can go with your favorite options for where to buy domains, reverse proxy setup, and SSL certificates. [Caddy](https://caddyserver.com/) is another good option here. 71 | 72 | 73 | 74 | 75 | -------------------------------------------------------------------------------- /features/embedded-replicas/with-fly.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Embedded Replicas on Fly 3 | sidebarTitle: Turso + Fly 4 | description: Deploy a JavaScript app using [Turso embedded replicas](/features/embedded-replicas) to [Fly.io](https://www.fly.io/). 5 | --- 6 | 7 | ![Koyeb banner](/images/platforms/fly-banner.png) 8 | 9 | ## Prerequisites 10 | 11 | Before you start, make sure you: 12 | 13 | - [Install the Turso CLI](/cli/installation) 14 | - [Sign up or login to Turso](/cli/authentication#signup) 15 | - [Install the Fly.io CLI](https://fly.io/docs/hands-on/install-flyctl/) 16 | 17 | 18 | 19 | 20 | 21 | You should have an application ready using your Turso database that you want to deploy to Fly. 22 | 23 | 24 | 25 | 26 | 27 | Using the Fly CLI, launch it: 28 | 29 | ```bash 30 | fly launch 31 | ``` 32 | 33 | Your application will automatically deploy to Fly, but we're not ready yet. 34 | 35 | 36 | 37 | 38 | 39 | Now create a volume that will be used to store the embedded replica(s): 40 | 41 | ```bash 42 | fly volumes create libsql_data 43 | ``` 44 | 45 | 46 | 47 | 48 | 49 | The files `fly.toml` and `Dockerfile` created created when you launched previously. 50 | 51 | Update `fly.toml` this file to mount the new volume: 52 | 53 | ```toml 54 | [[mounts]] 55 | source = "libsql_data" 56 | destination = "/app/data" 57 | ``` 58 | 59 | Then inside `Dockerfile`, make sure you install and update `ca-certificates`: 60 | 61 | ```dockerfile 62 | RUN apt-get update -qq && \ 63 | apt-get install -y ca-certificates && \ 64 | update-ca-certificates 65 | ``` 66 | 67 | Make sure to also add the following line after any `COPY` commands to copy the certificates: 68 | 69 | ```dockerfile 70 | COPY --from=build /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/ 71 | ``` 72 | 73 | 74 | 75 | 76 | 77 | You will want to change the `url` to point to a local file, and set the `syncUrl` to be your Turso database URL: 78 | 79 | ```ts 80 | import { createClient } from "@libsql/client"; 81 | 82 | const client = createClient({ 83 | url: "file:/app/data/local.db", 84 | syncUrl: process.env.TURSO_DATABASE_URL, 85 | authToken: process.env.TURSO_AUTH_TOKEN, 86 | syncInterval: 60, 87 | }); 88 | ``` 89 | 90 | 91 | 92 | 93 | 94 | ```bash 95 | fly deploy 96 | ``` 97 | 98 | 99 | 100 | 101 | -------------------------------------------------------------------------------- /features/embedded-replicas/with-koyeb.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Turso + Koyeb 3 | sidebarTitle: 4 | description: Deploy a JavaScript/Rust app using [Turso embedded replicas](/features/embedded-replicas) to [Koyeb](https://www.koyeb.com/). 5 | --- 6 | 7 | ![Koyeb banner](/images/platforms/koyeb-banner.png) 8 | 9 | ## Prerequisites 10 | 11 | Before you start, make sure you: 12 | 13 | - [Install the Turso CLI](/cli/installation) 14 | - [Sign up or login to Turso](/cli/authentication#signup) 15 | - Have a Koyeb account - [create one](https://app.koyeb.com/) 16 | 17 | 18 | 19 | 20 | 21 | You will need an existing database to continue. If you don't have one, [create one](/quickstart). 22 | 23 | 24 | 25 | You will want to store these as environment variables. 26 | 27 | 28 | 29 | 30 | Fork one of the following embedded replica project from GitHub 31 | 32 | 33 | 38 | See the full source code 39 | 40 | 45 | See the full source code 46 | 47 | 48 | 49 | 50 | Or, you can: 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | 1. Create a new app in the Koyeb control panel. 59 | 60 | 2. Select GitHub as the deployment option. 61 | 62 | 3. Import the GitHub project to Koyeb. 63 | 64 | 65 | 66 | 67 | 68 | ![Koyeb deploy page - environment variables](/images/platforms/koyeb-env-variables.png) 69 | 70 | 71 | 72 | 73 | 74 | Click the **Deploy** button at the bottom to deploy your web service. 75 | 76 | 77 | 78 | -------------------------------------------------------------------------------- /features/embedded-replicas/with-railway.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Turso + Railway 3 | sidebarTitle: 4 | description: Deploy a JavaScript/Rust app using [Turso embedded replicas](/features/embedded-replicas) to [Railway](https://railway.app/). 5 | --- 6 | 7 | ![Koyeb banner](/images/platforms/railway-banner.png) 8 | 9 | ## Prerequisites 10 | 11 | Before you start, make sure you: 12 | 13 | - [Install the Turso CLI](/cli/installation) 14 | - [Sign up or login to Turso](/cli/authentication#signup) 15 | - [Install the Railway CLI](https://docs.railway.app/guides/cli#installing-the-cli) 16 | 17 | 18 | 19 | 20 | 21 | You will need an existing database to continue. If you don't have one, [create one](/quickstart). 22 | 23 | 24 | 25 | You will want to store these as environment variables. 26 | 27 | 28 | 29 | 30 | Fork and clone the following embedded replica project from GitHub locally: 31 | 32 | 33 | 38 | See the full source code 39 | 40 | 45 | See the full source code 46 | 47 | 48 | 49 | 50 | 51 | 52 | Run the following command to create a new Railway project. Provide the project's name when prompted. 53 | 54 | ```sh 55 | railway init 56 | ``` 57 | 58 | 59 | 60 | 61 | 62 | [Create a new empty service](https://docs.railway.app/guides/services#creating-a-service) on your Railway project to act as your app's deployment target. 63 | 64 | 65 | 66 | 67 | 68 | Run the following command to list and select the service to link to your application: 69 | 70 | ```sh 71 | railway service 72 | ``` 73 | 74 | 75 | 76 | 77 | 78 | Open the service on your Railway dashboard and add your Turso database Credentials. 79 | 80 | ```sh 81 | TURSO_DATABASE_URL=libsql://[db-name]-[github-username].turso.io 82 | TURSO_AUTH_TOKEN=... 83 | LOCAL_DB=file:local-db-name.db 84 | ``` 85 | 86 | 87 | 88 | 89 | 90 | Run the following command to deploy your application: 91 | 92 | ```sh 93 | railway up 94 | ``` 95 | 96 | 97 | Make sure you [expose your application to the internet](https://docs.railway.app/guides/public-networking) to make it accessible from the public network. 98 | 99 | 100 | 101 | If you are on a free plan, you'll need to connect your Railway account to GitHub to have access to code deployments. 102 | 103 | 104 | 105 | 106 | -------------------------------------------------------------------------------- /features/embedded-replicas/with-render.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Turso + Render 3 | sidebarTitle: 4 | description: Deploy a JavaScript app using [Turso embedded replicas](/features/embedded-replicas) to [Render](https://render.com/). 5 | --- 6 | 7 | ![Render banner](/images/platforms/render-banner.png) 8 | 9 | ## Prerequisites 10 | 11 | Before you start, make sure you: 12 | 13 | - [Install the Turso CLI](/cli/installation) 14 | - [Sign up or login to Turso](/cli/authentication#signup) 15 | - Have a Render account - [create one](https://dashboard.render.com/) 16 | 17 | 18 | 19 | 20 | 21 | You will need an existing database to continue. If you don't have one, [create one](/quickstart). 22 | 23 | 24 | 25 | You will want to store these as environment variables. 26 | 27 | 28 | 29 | 30 | Fork the following embedded replica project from GitHub locally: 31 | 32 | 37 | See the full source code 38 | 39 | 40 | 41 | Or, you can: 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | Create a new Render **Web Service** by clicking on the "New Web Service" button on the Web Services card inside you Render dashboard. 51 | 52 | 53 | 54 | 55 | 56 | 1. Select "build and deploy from a Git repository" and proceed to the next page. 57 | 58 | 1. Click on "Connect" for your target project repository 59 | 60 | 61 | 62 | 63 | 64 | On the web service configuration page, under "Advanced" add **a secret file** and fill it in with your database secret credentials: 65 | 66 | ![Render secret credentials](images/platforms/render-env-vars.png) 67 | 68 | 69 | 70 | 71 | 72 | Scroll to the bottom of the web service configuration page and click on "Create Web Service". 73 | 74 | 75 | 76 | 77 | -------------------------------------------------------------------------------- /features/platform-api.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Platform API 3 | description: Manage databases, and teams with the Turso Platform API. 4 | --- 5 | 6 | The Turso [Platform API](/api-reference) is a RESTful API that allows you to manage databases, and users. It is the same API that is used by the Turso Platform Web UI and [CLI](/cli). 7 | 8 | The API is built for platforms that want to integrate with Turso to provide their users a serverless SQLite database. 9 | 10 | You can create databases, [database branches](/features/branching), [recover databases](/features/point-in-time-recovery) from a point in time, as well as [manage teams](/features/organizations), API tokens, and more with the Turso Platform API. 11 | 12 | ## API Resources 13 | 14 | 15 | -------------------------------------------------------------------------------- /features/point-in-time-recovery.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Point-in-Time Recovery 3 | description: 4 | --- 5 | 6 | Turso supports point-in-time recovery (PITR) for databases. PITR allows you to restore a database to a specific point in time. This is useful for recovering from user errors, such as dropping a table by mistake. 7 | 8 | 9 | 10 | Backups are created automatically at `COMMIT`. Free plan users can restore to any point in time within the last 24 hours. Hobby, Scaler, and Pro users can restore to any point in time within the last 10, 30, or 90 days, respectively. 11 | 12 | 13 | 14 | ## How it works 15 | 16 | 1. You create a new database from the existing database using the CLI or API. 17 | 2. You update your application to use the new database connection string. 18 | 3. You delete the old database when you no longer need it. 19 | 20 | 21 | 22 | The newly created database includes data only from periods prior to the specified timestamp. Additionally, there may be a gap of up to 15 seconds in the data immediately preceding the timestamp, as this depends on the timing of Turso's most recent periodic batch checkpoint. 23 | 24 | 25 | 26 | ## Usage 27 | 28 | 29 | 30 | ```bash CLI 31 | turso db create my-new-database --from-db my-existing-database --timestamp 2024-01-01T00:00:00Z 32 | ``` 33 | 34 | ```bash Platform API 35 | curl -L -X POST 'https://api.turso.tech/v1/organizations/{organizationSlug}/databases' \ 36 | -H 'Authorization: Bearer TOKEN' \ 37 | -H 'Content-Type: application/json' \ 38 | -d '{ 39 | "name": "new-database", 40 | "group": "default", 41 | "seed": { 42 | "type:": "database", 43 | "name": "my-existing-database", 44 | "timestamp": "2024-01-01T00:00:00Z" 45 | } 46 | }' 47 | ``` 48 | 49 | 50 | 51 | Refer to the following references for more details about all arguments: 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | 62 | 63 | 64 | 65 | ## Things to know 66 | 67 | - Restoring from a PITR creates a new database. You will need to update your application to use the new database connection string. 68 | - You cannot restore from a PITR to a database that already exists. 69 | - You will need to [create a new token](/cli/db/tokens/create) (or use a group token) to connect to the new database. 70 | - You will need to manually delete the old database when you no longer need it. 71 | - Restores count towards your plan's database quota. 72 | -------------------------------------------------------------------------------- /features/scale-to-zero.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Scale to Zero 3 | --- 4 | 5 | 6 | This feature is now deprecated for all new users. Existing free users will be 7 | moved from Fly to AWS, and receive no cold starts by default — [read the 8 | announcement](https://turso.tech/blog/upcoming-changes-to-the-turso-platform-and-roadmap) 9 | 10 | 11 | For free Starter Plan users, Turso dynamically scales databases down to zero after an hour of no activity. This behaviour is how we can continue to provide hundreds of databases on the free plan. 12 | 13 | When a request is made, the databases automatically scale back up to one. There may be a delay of up to `500ms` for databases that have been inactive. 14 | 15 | 16 | 17 | [Database groups](/concepts#groups) with extended inactivity (**10 days**) will require a manual "unarchive" operation using the [CLI](/cli/group/unarchive) or API. 18 | 19 | 20 | -------------------------------------------------------------------------------- /features/sqlite-extensions.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: SQLite Extensions 3 | description: Learn how to use SQLite extensions with Turso. 4 | --- 5 | 6 | Turso comes loaded with extensions that provide additional functionality to SQLite. Some plans will have more extensions preloaded. 7 | 8 | 9 | If you're looking to enable vector extensions, you should instead consider 10 | using the native [libSQL vector datatype](/features/ai-and-embeddings). 11 | 12 | 13 | ## Preloaded Extensions 14 | 15 | The following extensions are always-on and available: 16 | 17 | | Extension | Version | Description | 18 | | ----------------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------- | 19 | | [JSON](https://www.sqlite.org/json1.html) | Built-in | Work with JSON data in SQLite. | 20 | | [FTS5](https://www.sqlite.org/fts5.html) | Built-in | Full-text search and indexing. | 21 | | [R\*Tree](https://www.sqlite.org/rtree.html) | Built-in | Indexing and querying spatial data. | 22 | | [SQLean Crypto](https://github.com/nalgeon/sqlean/blob/0.24.1/docs/crypto.md) | 0.24.1 | Hashing, message digest, encoding, and decoding. | 23 | | [SQLean Fuzzy](https://github.com/nalgeon/sqlean/blob/0.24.1/docs/fuzzy.md) | 0.24.1 | Fuzzy string matching and phonetics. A fork of Spellfix1 with improvements. | 24 | | [SQLean Math](https://github.com/nalgeon/sqlean/blob/0.24.1/docs/math.md) | 0.24.1 | Advanced mathematical calculations. | 25 | | [SQLean Stats](https://github.com/nalgeon/sqlean/blob/0.24.1/docs/stats.md) | 0.24.1 | Common statistical functions with SQLite. | 26 | | [SQLean Text](https://github.com/nalgeon/sqlean/blob/0.24.1/docs/text.md) | 0.24.1 | String manipulation (reverse, split) with SQLite. | 27 | | [SQLean UUID](https://github.com/nalgeon/sqlean/blob/0.24.1/docs/uuid.md) | 0.24.1 | Limited support for RFC 4122 compliant UUIDs. | 28 | 29 | ## Optional Extensions 30 | 31 | The following extensions are also enabled in addition to the preloaded extensions on databases using the Fly Cloud Provider (Pro & Enterprise). 32 | 33 | | Extension | Version | Description | 34 | | ----------------------------------------------------------------------------- | ------- | -------------------------------------------- | 35 | | [SQLean Regexp](https://github.com/nalgeon/sqlean/blob/0.24.1/docs/regexp.md) | 0.24.1 | Regular expressions with SQLite. | 36 | | [sqlite-vec](https://github.com/asg017/sqlite-vec/tree/v0.1.3) | 0.1.3 | The Vector Search successor to `sqlite-vss`. | 37 | -------------------------------------------------------------------------------- /images/cloud/import.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/tursodatabase/turso-docs/60e72d978353bcb8d5c5d0ff6cb68a822844cad4/images/cloud/import.png -------------------------------------------------------------------------------- /images/concepts/database-group.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/tursodatabase/turso-docs/60e72d978353bcb8d5c5d0ff6cb68a822844cad4/images/concepts/database-group.png -------------------------------------------------------------------------------- /images/guides/actix-banner.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/tursodatabase/turso-docs/60e72d978353bcb8d5c5d0ff6cb68a822844cad4/images/guides/actix-banner.png -------------------------------------------------------------------------------- /images/guides/astro-banner.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/tursodatabase/turso-docs/60e72d978353bcb8d5c5d0ff6cb68a822844cad4/images/guides/astro-banner.png -------------------------------------------------------------------------------- /images/guides/axum-banner.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/tursodatabase/turso-docs/60e72d978353bcb8d5c5d0ff6cb68a822844cad4/images/guides/axum-banner.png -------------------------------------------------------------------------------- /images/guides/doctrine-dbal-banner.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/tursodatabase/turso-docs/60e72d978353bcb8d5c5d0ff6cb68a822844cad4/images/guides/doctrine-dbal-banner.png -------------------------------------------------------------------------------- /images/guides/drizzle-banner.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/tursodatabase/turso-docs/60e72d978353bcb8d5c5d0ff6cb68a822844cad4/images/guides/drizzle-banner.png -------------------------------------------------------------------------------- /images/guides/elysia-banner.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/tursodatabase/turso-docs/60e72d978353bcb8d5c5d0ff6cb68a822844cad4/images/guides/elysia-banner.png -------------------------------------------------------------------------------- /images/guides/flask-banner.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/tursodatabase/turso-docs/60e72d978353bcb8d5c5d0ff6cb68a822844cad4/images/guides/flask-banner.png -------------------------------------------------------------------------------- /images/guides/flutter-banner.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/tursodatabase/turso-docs/60e72d978353bcb8d5c5d0ff6cb68a822844cad4/images/guides/flutter-banner.png -------------------------------------------------------------------------------- /images/guides/hono-banner.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/tursodatabase/turso-docs/60e72d978353bcb8d5c5d0ff6cb68a822844cad4/images/guides/hono-banner.png -------------------------------------------------------------------------------- /images/guides/laravel-banner.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/tursodatabase/turso-docs/60e72d978353bcb8d5c5d0ff6cb68a822844cad4/images/guides/laravel-banner.png -------------------------------------------------------------------------------- /images/guides/nextjs-banner.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/tursodatabase/turso-docs/60e72d978353bcb8d5c5d0ff6cb68a822844cad4/images/guides/nextjs-banner.png -------------------------------------------------------------------------------- /images/guides/nuxt-banner.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/tursodatabase/turso-docs/60e72d978353bcb8d5c5d0ff6cb68a822844cad4/images/guides/nuxt-banner.png -------------------------------------------------------------------------------- /images/guides/prisma-banner.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/tursodatabase/turso-docs/60e72d978353bcb8d5c5d0ff6cb68a822844cad4/images/guides/prisma-banner.png -------------------------------------------------------------------------------- /images/guides/quasar-banner.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/tursodatabase/turso-docs/60e72d978353bcb8d5c5d0ff6cb68a822844cad4/images/guides/quasar-banner.png -------------------------------------------------------------------------------- /images/guides/qwik-banner.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/tursodatabase/turso-docs/60e72d978353bcb8d5c5d0ff6cb68a822844cad4/images/guides/qwik-banner.png -------------------------------------------------------------------------------- /images/guides/remix-banner.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/tursodatabase/turso-docs/60e72d978353bcb8d5c5d0ff6cb68a822844cad4/images/guides/remix-banner.png -------------------------------------------------------------------------------- /images/guides/rocket-banner.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/tursodatabase/turso-docs/60e72d978353bcb8d5c5d0ff6cb68a822844cad4/images/guides/rocket-banner.png -------------------------------------------------------------------------------- /images/guides/sqlalchemy-banner.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/tursodatabase/turso-docs/60e72d978353bcb8d5c5d0ff6cb68a822844cad4/images/guides/sqlalchemy-banner.png -------------------------------------------------------------------------------- /images/guides/svelte-banner.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/tursodatabase/turso-docs/60e72d978353bcb8d5c5d0ff6cb68a822844cad4/images/guides/svelte-banner.png -------------------------------------------------------------------------------- /images/guides/tauri-banner.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/tursodatabase/turso-docs/60e72d978353bcb8d5c5d0ff6cb68a822844cad4/images/guides/tauri-banner.png -------------------------------------------------------------------------------- /images/platforms/akamai-banner.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/tursodatabase/turso-docs/60e72d978353bcb8d5c5d0ff6cb68a822844cad4/images/platforms/akamai-banner.png -------------------------------------------------------------------------------- /images/platforms/fly-banner.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/tursodatabase/turso-docs/60e72d978353bcb8d5c5d0ff6cb68a822844cad4/images/platforms/fly-banner.png -------------------------------------------------------------------------------- /images/platforms/koyeb-banner.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/tursodatabase/turso-docs/60e72d978353bcb8d5c5d0ff6cb68a822844cad4/images/platforms/koyeb-banner.png -------------------------------------------------------------------------------- /images/platforms/koyeb-env-variables.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/tursodatabase/turso-docs/60e72d978353bcb8d5c5d0ff6cb68a822844cad4/images/platforms/koyeb-env-variables.png -------------------------------------------------------------------------------- /images/platforms/railway-banner.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/tursodatabase/turso-docs/60e72d978353bcb8d5c5d0ff6cb68a822844cad4/images/platforms/railway-banner.png -------------------------------------------------------------------------------- /images/platforms/render-banner.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/tursodatabase/turso-docs/60e72d978353bcb8d5c5d0ff6cb68a822844cad4/images/platforms/render-banner.png -------------------------------------------------------------------------------- /images/platforms/render-env-vars.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/tursodatabase/turso-docs/60e72d978353bcb8d5c5d0ff6cb68a822844cad4/images/platforms/render-env-vars.png -------------------------------------------------------------------------------- /images/turso-banner.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/tursodatabase/turso-docs/60e72d978353bcb8d5c5d0ff6cb68a822844cad4/images/turso-banner.png -------------------------------------------------------------------------------- /integrations/cloudflare.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Cloudflare 3 | description: 4 | --- 5 | -------------------------------------------------------------------------------- /libsql.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: libSQL 3 | description: libSQL is SQLite for modern applications. 4 | --- 5 | 6 | Turso is a distributed database built on [libSQL](https://github.com/tursodatabase/libsql/), a fork of SQLite. It's optimized for low query latency, making it suitable for global applications. 7 | 8 | Postgres and MySQL have long vied for SQL dominance, while SQLite remains a favored choice due to its simplicity and reliability, often dubbed the "hello world" of databases. 9 | 10 | libSQL is a fork of SQLite that aims to be a modern database, with a focus on low query latency and high availability. It's designed to be a drop-in replacement for SQLite, and scales globally with Turso over HTTP. 11 | 12 | 13 | 14 | 15 | 16 | Browse the libSQL source code on GitHub, report issues, feature requests and contribute using pull requests. 17 | 18 | 19 | 20 | 21 | 22 | Join the community on Discord to talk about the development of libSQL. 23 | 24 | 25 | 26 | 27 | 28 | ## Why fork SQLite? 29 | 30 | SQLite is [open-source, not open-contribution](https://www.sqlite.org/copyright.html), which makes it difficult to innovate and evolve with it. 31 | 32 | Turso is committed to the open-source community, and we welcome contributions to libSQL. We're also committed to keeping libSQL free and open-source, as well rejoining core SQLite if their policy changes. 33 | 34 | Read the [libSQL Manifesto](https://turso.tech/libsql-manifesto) for more details. 35 | 36 | ## Turso vs. libSQL 37 | 38 | Turso manages the distribution of libSQL instances, and provides a global HTTP API for querying and managing databases. It also provides a CLI, Web UI and HTTP API for managing databases, and team management. 39 | 40 | When you use Turso, you don't need to worry about managing libSQL instances, or configuring replication. You can focus on building your application, and let Turso handle the rest. 41 | 42 | [SDKs](/sdk) are fully compatible with libSQL, whether you use self-hosted or Turso-hosted libSQL. 43 | 44 | ## SQLite Compatibility 45 | 46 | libSQL will remain SQLite compatible by providing the same API and file format, but with additional features and optimizations. 47 | 48 | ## Encryption at rest 49 | 50 | libSQL introduces an essential feature for production environments: **encryption at rest**. This feature enhances data security by encrypting database files, making them inaccessible without the correct encryption key. 51 | 52 | libSQL's encryption leverages existing, proven encryption solutions, integrating them directly into the fork of SQLite. The encryption is page-based, allowing for efficient data access without decrypting the entire file. Supported encryption standards include SQLCipher (default) and wxSQLite3's AES 256 Bit, with further options for customization per database. 53 | 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | 62 | 63 | 64 | The encryption key used should be generated and managed by you. 65 | 66 | ## Extensions 67 | 68 | 69 | If you're looking to enable vector extensions, you should instead consider 70 | using the native [libSQL vector datatype](/features/ai-and-embeddings). 71 | 72 | 73 | A full list of supported extensions can be found [here](/features/sqlite-extensions). 74 | -------------------------------------------------------------------------------- /logo/turso-dark.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | -------------------------------------------------------------------------------- /logo/turso-light.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "private": true, 3 | "scripts": { 4 | "dev": "mintlify dev" 5 | }, 6 | "devDependencies": { 7 | "mintlify": "^4.0.206" 8 | } 9 | } 10 | -------------------------------------------------------------------------------- /quickstart.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Quickstart 3 | description: Welcome to Turso! Get started with Turso in minutes. 4 | --- 5 | 6 | **In this quickstart you will learn how to:** 7 | 8 | 1. Install the Turso CLI 9 | 2. Signup to Turso 10 | 3. Create your first Turso Database 11 | 4. Connect to Database Shell 12 | 13 | 14 | 15 | 16 | 17 | We'll be using the Turso CLI throughout this quickstart to manage databases, create replicas in other regions, and connect to the database shell. 18 | 19 | 20 | 21 | ```bash macOS 22 | brew install tursodatabase/tap/turso 23 | ``` 24 | 25 | ```bash Linux 26 | curl -sSfL https://get.tur.so/install.sh | bash 27 | ``` 28 | 29 | ```bash Windows (WSL) 30 | curl -sSfL https://get.tur.so/install.sh | bash 31 | ``` 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | The next command will open your browser to sign up: 40 | 41 | 42 | 43 | ```bash Signup 44 | turso auth signup 45 | ``` 46 | 47 | ```bash Login 48 | turso auth login 49 | ``` 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | Now create your first database in a location closest to you with the name `my-db`: 58 | 59 | ```bash 60 | turso db create my-db 61 | ``` 62 | 63 | The Turso CLI automatically detected your closest region to create a database. It used this location to create a `default` "group" for your database, which you can inspect using the following command: 64 | 65 | ```bash 66 | turso db show my-db 67 | ``` 68 | 69 | 70 | 71 | 72 | 73 | Congratulations, you created a database! Now connect to it with the `shell` command: 74 | 75 | ```bash 76 | turso db shell my-db 77 | ``` 78 | 79 | 80 | 81 | Replace `my-db` with the name of your database if you named it differently. 82 | 83 | 84 | 85 | 86 | 87 | Now create a table for `users` using SQL: 88 | 89 | ```sql 90 | CREATE TABLE users ( 91 | ID INTEGER PRIMARY KEY AUTOINCREMENT, 92 | name TEXT 93 | ); 94 | ``` 95 | 96 | 97 | 98 | 99 | 100 | Then insert a row into the `users` table: 101 | 102 | ```sql 103 | INSERT INTO users (name) VALUES ("Iku"); 104 | ``` 105 | 106 | 107 | 108 | 109 | 110 | Finally, query for all `users`: 111 | 112 | ```sql 113 | SELECT * FROM users; 114 | ``` 115 | 116 | 117 | 118 | 119 | When you're ready to move onto the next step, you'll want to to quit the shell: 120 | 121 | ```sql 122 | .quit 123 | ``` 124 | 125 | 126 | 127 | 128 | 129 | You're now ready to connect your application to your database. Pick from one of the SDKs below to continue: 130 | 131 | 132 | 133 | 134 | 135 | 136 | -------------------------------------------------------------------------------- /sdk/activerecord/guides/rails.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Ruby on Rails + Turso 3 | sidebarTitle: Ruby on Rails 4 | description: Set up Turso in your Ruby on Rails project in minutes. 5 | --- 6 | 7 | 8 | 9 | ## Prerequisites 10 | 11 | Before you start, make sure you: 12 | 13 | - [Install the Turso CLI](/cli/installation) 14 | - [Sign up or login to Turso](/cli/authentication#signup) 15 | - Have a Rails app — [learn more](https://guides.rubyonrails.org/getting_started.html) 16 | 17 | 18 | 19 | 20 | 21 | Add the following to your Gemfile: 22 | 23 | ```ruby 24 | gem 'libsql_activerecord' 25 | ``` 26 | 27 | Then run: 28 | 29 | ```bash 30 | bundle install 31 | ``` 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | Add your Turso credentials to your Rails credentials file or environment variables. 40 | 41 | 42 | 43 | 44 | 45 | ```yml 46 | default: &default 47 | adapter: libsql 48 | pool: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %> 49 | 50 | development: 51 | <<: *default 52 | url: <%= ENV['TURSO_DATABASE_URL'] %> 53 | auth_token: <%= ENV['TURSO_AUTH_TOKEN'] %> 54 | path: storage/development.sqlite3 # For embedded replica 55 | ``` 56 | 57 | 58 | 59 | 60 | 61 | Generate a migration: 62 | 63 | ```bash 64 | rails generate migration CreateProducts name:string description:text 65 | ``` 66 | 67 | Run the migration: 68 | 69 | ```bash 70 | rails db:migrate 71 | ``` 72 | 73 | 74 | 75 | 76 | 77 | Create a model in `app/models/product.rb`: 78 | 79 | ```ruby 80 | class Product < ApplicationRecord 81 | validates :name, presence: true 82 | end 83 | ``` 84 | 85 | 86 | 87 | 88 | 89 | In your controllers, you can now use ActiveRecord methods to interact with your Turso database: 90 | 91 | ```ruby 92 | class ProductsController < ApplicationController 93 | def index 94 | @products = Product.all 95 | end 96 | 97 | def create 98 | @product = Product.new(product_params) 99 | if @product.save 100 | redirect_to @product, notice: 'Product was successfully created.' 101 | else 102 | render :new 103 | end 104 | end 105 | 106 | private 107 | 108 | def product_params 109 | params.require(:product).permit(:name, :description) 110 | end 111 | end 112 | ``` 113 | 114 | 115 | 116 | 117 | 118 | You can also execute raw SQL queries: 119 | 120 | ```ruby 121 | results = ActiveRecord::Base.connection.execute("SELECT * FROM products") 122 | ``` 123 | 124 | 125 | 126 | 127 | 128 | ## Examples 129 | 130 | 131 | 136 | See the full source code 137 | 138 | 139 | -------------------------------------------------------------------------------- /sdk/authentication.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Authentication 3 | --- 4 | 5 | SDKs connect to Turso using the `libsql://` protocol, unless using the [HTTP API](/sdk/http). 6 | 7 | ## Database URL 8 | 9 | You can find your database URL using the [Turso CLI](/cli/db/show) or [Platform API](/api-reference/databases/retrieve), it looks something like this: 10 | 11 | 12 | 13 | ```bash libSQL 14 | libsql://[DB-NAME]-[ORG-NAME].turso.io 15 | ``` 16 | 17 | ```bash HTTPS 18 | https://[DB-NAME]-[ORG-NAME].turso.io 19 | ``` 20 | 21 | 22 | 23 |
24 | 25 | 26 | 27 | WebSockets generally offer better performance when maintaining an open socket for multiple queries, whereas HTTP is typically more efficient for single queries due to reduced client-server round trips — it's advisable to benchmark both to ascertain the best option for your specific needs. 28 | 29 | 30 | 31 | ## Auth Tokens 32 | 33 | SDKs require an auth token, unless [working locally](/local-development). You can create a new token for your database (or group) using the [Turso CLI](/cli) and [Platform API](/api-reference). 34 | 35 | Using Turso CLI and Platform API you can: 36 | 37 | - Create tokens for a one database or all databases in a group 38 | - Create `full-access` and `read-only` tokens 39 | - Set expiration for tokens 40 | - Invalidate all tokens 41 | -------------------------------------------------------------------------------- /sdk/c/examples.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Turso Examples (C) 3 | sidebarTitle: Examples 4 | --- 5 | 6 | | Example | Description | 7 | | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | 8 | | [local](https://github.com/tursodatabase/libsql-c/tree/master/examples/local) | Uses libsql with a local SQLite file. Creates database, inserts data, and queries. | 9 | | [remote](https://github.com/tursodatabase/libsql-c/tree/master/examples/remote) | Connects to a remote database. Requires environment variables for URL and auth token. | 10 | | [sync](https://github.com/tursodatabase/libsql-c/tree/master/examples/sync) | Demonstrates synchronization between local and remote databases. | 11 | | [batch](https://github.com/tursodatabase/libsql-c/tree/master/examples/batch) | Executes multiple SQL statements in a single batch operation. | 12 | | [transactions](https://github.com/tursodatabase/libsql-c/tree/master/examples/transactions) | Shows transaction usage: starting, performing operations, and committing/rolling back. | 13 | | [memory](https://github.com/tursodatabase/libsql-c/tree/master/examples/memory) | Uses an in-memory SQLite database for temporary storage or fast access. | 14 | | [vector](https://github.com/tursodatabase/libsql-c/tree/master/examples/vector) | Works with vector embeddings, storing and querying for similarity search. | 15 | | [encryption](https://github.com/tursodatabase/libsql-c/tree/master/examples/encryption) | Creates and uses an encrypted SQLite database, demonstrating setup and data operations. | 16 | -------------------------------------------------------------------------------- /sdk/flutter/examples.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Examples 3 | url: https://github.com/dikatok/libsql_dart/tree/main/example 4 | --- 5 | -------------------------------------------------------------------------------- /sdk/flutter/integrations/drift.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Drift + Turso / LibSQL 3 | sidebarTitle: Drift 4 | description: Configure `drift` to work with `libsql_dart` 5 | --- 6 | 7 | ## Prerequisites 8 | 9 | Before you start, make sure you: 10 | 11 | - [Install the Turso CLI](/cli/installation) 12 | - [Sign up or login to Turso](/cli/authentication#signup) 13 | 14 | 15 | 16 | 17 | 18 | ```bash 19 | flutter pub add drift_libsql drift drift_flutter dev:build_runner dev:drift_dev 20 | ``` 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | ```dart 33 | class TaskTable extends Table { 34 | IntColumn get id => integer().autoIncrement()(); 35 | TextColumn get title => text()(); 36 | TextColumn get description => text()(); 37 | BoolColumn get completed => boolean()(); 38 | } 39 | ``` 40 | 41 | 42 | 43 | 44 | 45 | ```dart 46 | @DriftDatabase(tables: [TaskTable]) 47 | class AppDatabase extends _$AppDatabase { 48 | AppDatabase(super.e); 49 | 50 | @override 51 | int get schemaVersion => 1; 52 | } 53 | ``` 54 | 55 | 56 | 57 | 58 | 59 | ```bash 60 | dart run build_runner build 61 | ``` 62 | 63 | 64 | 65 | 66 | 67 | ```dart 68 | final db = AppDatabase(DriftLibsqlDatabase( 69 | "${dir.path}/replica.db", 70 | syncUrl: url, 71 | authToken: token, 72 | readYourWrites: true, 73 | syncIntervalSeconds: 3, 74 | )); 75 | ``` 76 | 77 | 78 | 79 | 80 | 81 | ```dart 82 | await db.into(db.taskTable).insert(TaskTableCompanion.insert( 83 | title: task.title, 84 | description: task.description, 85 | completed: task.completed)); 86 | ``` 87 | 88 | 89 | 90 | 91 | -------------------------------------------------------------------------------- /sdk/go/examples.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Examples 3 | url: https://github.com/libsql/go-libsql/tree/main/example 4 | --- 5 | -------------------------------------------------------------------------------- /sdk/go/reference.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Reference 3 | --- 4 | 5 | ## Embedded Replicas 6 | 7 | You can work with [embedded replicas](/features/embedded-replicas) that can sync from the remote database to a local SQLite file, and delegate writes to the remote primary database: 8 | 9 | ```go 10 | package main 11 | 12 | import ( 13 | "database/sql" 14 | "fmt" 15 | "os" 16 | "path/filepath" 17 | 18 | "github.com/tursodatabase/go-libsql" 19 | ) 20 | 21 | func main() { 22 | dbName := "local.db" 23 | primaryUrl := "libsql://[DATABASE].turso.io" 24 | authToken := "..." 25 | 26 | dir, err := os.MkdirTemp("", "libsql-*") 27 | if err != nil { 28 | fmt.Println("Error creating temporary directory:", err) 29 | os.Exit(1) 30 | } 31 | defer os.RemoveAll(dir) 32 | 33 | dbPath := filepath.Join(dir, dbName) 34 | 35 | connector, err := libsql.NewEmbeddedReplicaConnector(dbPath, primaryUrl, 36 | libsql.WithAuthToken(authToken) 37 | ) 38 | if err != nil { 39 | fmt.Println("Error creating connector:", err) 40 | os.Exit(1) 41 | } 42 | defer connector.Close() 43 | 44 | db := sql.OpenDB(connector) 45 | defer db.Close() 46 | } 47 | ``` 48 | 49 | 50 | 51 | ### Manual Sync 52 | 53 | The `Sync` function allows you to sync manually the local database with the remote counterpart: 54 | 55 | ```go 56 | if err := connector.Sync(); err != nil { 57 | fmt.Println("Error syncing database:", err) 58 | } 59 | ``` 60 | 61 | ### Periodic Sync 62 | 63 | You can automatically sync at intervals using `WithSyncInterval` and passing a `time.Duration` as an argument. For example, to sync every minute, you can use the following code: 64 | 65 | ```go 66 | syncInterval := time.Minute 67 | 68 | connector, err := libsql.NewEmbeddedReplicaConnector(dbPath, primaryUrl, 69 | libsql.WithAuthToken(authToken), 70 | libsql.WithSyncInterval(syncInterval), 71 | ) 72 | ``` 73 | 74 | ### Read Your Writes 75 | 76 | By default, the database connection ensures that writes are immediately visible to subsequent read operations initiated by the same connection. 77 | 78 | You can disable this behaviour using `WithReadYourWrites(false)`: 79 | 80 | ```go 81 | connector, err := libsql.NewEmbeddedReplicaConnector(dbPath, primaryUrl, 82 | libsql.WithAuthToken(authToken), 83 | libsql.WithReadYourWrites(false), 84 | ) 85 | ``` 86 | 87 | ## Encryption 88 | 89 | To enable encryption on a SQLite file, pass the encryption key value as an argument to the constructor: 90 | 91 | ```go 92 | encryptionKey := "SuperSecretKey" 93 | 94 | connector, err := libsql.NewEmbeddedReplicaConnector(dbPath, primaryUrl, 95 | libsql.WithAuthToken(authToken), 96 | libsql.WithEncryption(encryptionKey), 97 | ) 98 | ``` 99 | 100 | 101 | 102 | Encrypted databases appear as raw data and cannot be read as standard SQLite databases. You must use the libSQL client for any operations — [learn more](/libsql#encryption-at-rest). 103 | 104 | 105 | -------------------------------------------------------------------------------- /sdk/http/guides/flutter.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Flutter + Turso 3 | sidebarTitle: Flutter 4 | description: Set up Turso in your Flutter project in minutes 5 | --- 6 | 7 | ![Flutter banner](/images/guides/flutter-banner.png) 8 | 9 | ## Prerequisites 10 | 11 | Before you start, make sure you: 12 | 13 | - [Install the Turso CLI](/cli/installation) 14 | - [Sign up or login to Turso](/cli/authentication#signup) 15 | - Have a Flutter app — [learn more](https://docs.flutter.dev/get-started/codelab) 16 | 17 | 18 | 19 | 20 | 21 | ```bash 22 | dart pub add http 23 | ``` 24 | 25 | 26 | 27 | 28 | 29 | Get the database URL: 30 | 31 | ```bash 32 | turso db show --url 33 | ``` 34 | 35 | Get the database authentication token: 36 | 37 | ```bash 38 | turso db tokens create 39 | ``` 40 | 41 | Pass the credentials to the flutter app by using the `--dart-define` flags: 42 | 43 | ```bash 44 | flutter run --debug \ 45 | --dart-define=TURSO_URL="..." \ 46 | --dart-define=TURSO_AUTH_TOKEN="..." 47 | ``` 48 | 49 | 50 | Make sure that the `TURSO_URL` passed above should be modified to use the 51 | `https` protocol instead of `libsql`. (e.g "https://[db-name].turso.io") 52 | 53 | 54 | 55 | 56 | 57 | 58 | ```dart lib/main.dart 59 | import 'package:http/http.dart' as http; 60 | 61 | const String tursoDbUrl = 62 | String.fromEnvironment("TURSO_URL", defaultValue: ""); 63 | const String tursoAuthToken = 64 | String.fromEnvironment("TURSO_AUTH_TOKEN", defaultValue: ""); 65 | 66 | late Future> itemResults; 67 | 68 | Future> getItems() async { 69 | final response = await http.post(Uri.parse(tursoDbUrl), 70 | headers: { 71 | HttpHeaders.authorizationHeader: "Bearer $tursoAuthToken", 72 | HttpHeaders.acceptHeader: "application/json" 73 | }, 74 | body: json.encode({ 75 | "statements": ["select * from table_name"] 76 | })); 77 | 78 | var itemList = List.from(jsonDecode(response.body)[0]["results"] 79 | ["rows"] 80 | .map((dynamic item) => item[0])); 81 | return itemList; 82 | } 83 | 84 | itemResults = getItems(); 85 | ``` 86 | 87 | 88 | 89 | 90 | 91 | ## Examples 92 | 93 | 94 | 99 | See the full source code 100 | 101 | 106 | See the full source code 107 | 108 | 109 | -------------------------------------------------------------------------------- /sdk/introduction.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Introduction 3 | --- 4 | 5 | Turso provides multiple SDKs that you can use to connect a local SQLite file or remote Turso Cloud database, as well as support for embedded databases. If you're using a language or framework that isn't supported with an official driver, you can use Turso over HTTP. 6 | 7 | ## Official SDKs 8 | 9 | Turso SDKs are fully compatible with [libSQL](/libsql), so you can use the same SDK to connect to a local database ([SQLite](/local-development#sqlite)), [libSQL server](/local-development#libsql-server), a remote database, or an [embedded replica](/features/embedded-replicas). 10 | 11 | 12 | 13 | ## Community SDKs 14 | 15 | These SDKs are community-driven and don't come with official Turso support. 16 | 17 | 18 | 19 | 24 | 28 | 29 | } 30 | href="/sdk/flutter/quickstart" 31 | /> 32 | 33 | 39 | 40 | 49 | 53 | 54 | } 55 | href="https://github.com/richan-fongdasen/turso-laravel" 56 | /> 57 | 58 | 64 | 65 | 71 | 72 | 78 | 79 | 80 | 81 | ## Turso over HTTP 82 | 83 | 84 | 85 | 86 | 87 | 88 | -------------------------------------------------------------------------------- /sdk/java/quickstart.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Turso Quickstart (Java) 3 | sidebarTitle: Quickstart 4 | description: Get started with Turso and Java using the libSQL client in a few simple steps. 5 | --- 6 | 7 | 8 | -------------------------------------------------------------------------------- /sdk/java/reference.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Java Reference 3 | sidebarTitle: Reference 4 | description: libSQL Java Reference 5 | --- 6 | 7 | 8 | -------------------------------------------------------------------------------- /sdk/kotlin/quickstart.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Turso Quickstart (Android) 3 | sidebarTitle: Quickstart 4 | description: Get started with Turso and Android using the libSQL client in a few simple steps. 5 | --- 6 | 7 | 8 | 9 | 10 | This will only work with the Android Gradle Plugin for now. Fully Kotlin 11 | support is coming. 12 | 13 | 14 | In this Kotlin quickstart we will learn how to: 15 | 16 | - Retrieve database credentials 17 | - Add libSQL as a dependency in your Android Gradle project 18 | - Connect to a local or remote Turso database 19 | - Execute a query using SQL 20 | - Sync changes to local database (optional) 21 | 22 | 23 | 24 | 25 | You will need an existing database to continue. If you don't have one, [create one](/quickstart). 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | Add libsql as a implementation dependency in Gradle: 36 | 37 | 38 | This will only work with the Android Gradle Plugin for now. 39 | 40 | 41 | ```kotlin 42 | dependencies { 43 | implementation("tech.turso.libsql:libsql:0.1.0") 44 | } 45 | ``` 46 | 47 | 48 | 49 | 50 | 51 | You must first create a `Database` object and then open a `Connection` to it: 52 | 53 | 54 | 55 | 56 | ```kotlin 57 | import tech.turso.libsql.Libsql 58 | 59 | val db = Libsql.open( 60 | path = "./local.db", 61 | url = "TURSO_DATABASE_URL", 62 | authToken = "TURSO_AUTH_TOKEN", 63 | ) 64 | 65 | val conn = db.connect() 66 | ``` 67 | 68 | 69 | 70 | 71 | ```kotlin 72 | import tech.turso.libsql.Libsql 73 | 74 | val db = Libsql.open(path = "./local.db") 75 | val conn = db.connect() 76 | ``` 77 | 78 | 79 | 80 | 81 | ```kotlin 82 | import tech.turso.libsql.Libsql 83 | 84 | val db = Libsql.open( 85 | url = "TURSO_DATABASE_URL", 86 | authToken = "TURSO_AUTH_TOKEN", 87 | ) 88 | 89 | val conn = db.connect() 90 | ``` 91 | 92 | 93 | 94 | 95 | 96 | 97 | 98 | 99 | You can execute a SQL query against your existing database by calling `execute()`: 100 | 101 | ```kotlin 102 | db.connect().use { 103 | it.execute("INSERT INTO users (id) VALUES (1)") 104 | } 105 | ``` 106 | 107 | If you need to use placeholders for values, you can do that: 108 | 109 | 110 | 111 | ```kotlin Positional 112 | db.connect().use { 113 | it.query("SELECT * FROM users WHERE id = ?", 1) 114 | } 115 | ``` 116 | 117 | ```kotlin Named 118 | db.connect().use { 119 | it.query("INSERT INTO users (name) VALUES (:name)", mapOf(":name" to "Iku")) 120 | } 121 | ``` 122 | 123 | 124 | 125 | 126 | 127 | 128 | 129 | When using embedded replicas you should call `sync()` on the database type to 130 | sync your local database with the primary database, unless you are using 131 | `syncInterval` (though there is no issue with calling `sync` with 132 | `syncInterval` enabled): 133 | 134 | ```kotlin 135 | db.sync() 136 | ``` 137 | 138 | 139 | 140 | -------------------------------------------------------------------------------- /sdk/php/examples.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Examples 3 | url: https://github.com/tursodatabase/turso-client-php/tree/main/examples 4 | --- 5 | 6 | [View examples on GitHub](https://github.com/tursodatabase/libsql-client-ts/tree/main/packages/libsql-client/examples) 7 | -------------------------------------------------------------------------------- /sdk/python/examples.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Examples 3 | url: https://github.com/tursodatabase/libsql-experimental-python/tree/main/examples 4 | --- 5 | -------------------------------------------------------------------------------- /sdk/python/guides/flask.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Flask + Turso 3 | sidebarTitle: Flask 4 | description: Set up Turso in your Flask project in minutes 5 | --- 6 | 7 | ![Flask banner](/images/guides/flask-banner.png) 8 | 9 | ## Prerequisites 10 | 11 | Before you start, make sure you: 12 | 13 | - [Install the Turso CLI](/cli/installation) 14 | - [Sign up or login to Turso](/cli/authentication#signup) 15 | - Have a Flask app — [learn more](https://flask.palletsprojects.com/en/3.0.x/installation/#create-an-environment) 16 | 17 | 18 | 19 | 20 | 21 | ```bash 22 | pip install sqlalchemy-libsql python-dotenv 23 | ``` 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | ```python models.py 36 | from sqlalchemy import String 37 | from sqlalchemy.orm import DeclarativeBase 38 | from sqlalchemy.orm import Mapped 39 | from sqlalchemy.orm import mapped_column 40 | 41 | class Base(DeclarativeBase): 42 | pass 43 | 44 | class Item(Base): 45 | __tablename__ = "items" 46 | id: Mapped[str] = mapped_column(primary_key=True) 47 | foo: Mapped[str] = mapped_column(String(255)) 48 | bar: Mapped[str] = mapped_column(String(100)) 49 | def __repr__(self) -> str: 50 | return f"Item(id={self.id!r}, foo={self.foo!r}, bar={self.bar!r})" 51 | ``` 52 | 53 | 54 | 55 | 56 | 57 | ```python 58 | from dotenv import load_dotenv 59 | from sqlalchemy import create_engine 60 | from sqlalchemy.orm import Session 61 | from sqlalchemy import select 62 | from models import Item 63 | 64 | load_dotenv() 65 | 66 | # Get environment variables 67 | TURSO_DATABASE_URL = os.environ.get("TURSO_DATABASE_URL") 68 | TURSO_AUTH_TOKEN = os.environ.get("TURSO_AUTH_TOKEN") 69 | 70 | # construct special SQLAlchemy URL 71 | dbUrl = f"sqlite+{TURSO_DATABASE_URL}/?authToken={TURSO_AUTH_TOKEN}&secure=true" 72 | 73 | engine = create_engine(dbUrl, connect_args={'check_same_thread': False}, echo=True) 74 | 75 | @app.route("/", methods=(["GET"])) 76 | def home(): 77 | session = Session(engine) 78 | 79 | # get & print items 80 | stmt = select(Item) 81 | 82 | for item in session.scalars(stmt): 83 | print(item) 84 | ``` 85 | 86 | 87 | 88 | 89 | 90 | ## Examples 91 | 92 | 93 | 98 | See the full source code 99 | 100 | 101 | -------------------------------------------------------------------------------- /sdk/python/orm/sqlalchemy.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: SQLAlchemy + Turso 3 | sidebarTitle: SQLAlchemy 4 | description: Configure SQLAlchemy to work with your Turso database 5 | --- 6 | 7 | ![SQLAlchemy Quickstart](/images/guides/sqlalchemy-banner.png) 8 | 9 | ## Prerequisites 10 | 11 | Before you start, make sure you: 12 | 13 | - [Install the Turso CLI](/cli/installation) 14 | - [Sign up or login to Turso](/cli/authentication#signup) 15 | 16 | 17 | 18 | 19 | 20 | ```bash 21 | pip install sqlalchemy-libsql 22 | ``` 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | ```python models.py 35 | from sqlalchemy import String 36 | from sqlalchemy.orm import DeclarativeBase 37 | from sqlalchemy.orm import Mapped 38 | from sqlalchemy.orm import mapped_column 39 | 40 | class Base(DeclarativeBase): 41 | pass 42 | 43 | class Foo(Base): 44 | __tablename__ = "foo" 45 | id: Mapped[str] = mapped_column(primary_key=True) 46 | bar: Mapped[str] = mapped_column(String(100)) 47 | def __repr__(self) -> str: 48 | return f"Item(id={self.id!r}, bar={self.bar!r})" 49 | 50 | ``` 51 | 52 | 53 | 54 | 55 | 56 | ```py app.py 57 | from dotenv import load_dotenv 58 | from sqlalchemy import create_engine 59 | 60 | TURSO_DATABASE_URL = os.environ.get("TURSO_DATABASE_URL") 61 | TURSO_AUTH_TOKEN = os.environ.get("TURSO_AUTH_TOKEN") 62 | 63 | dbUrl = f"sqlite+{TURSO_DATABASE_URL}/?authToken={TURSO_AUTH_TOKEN}&secure=true" 64 | 65 | engine = create_engine(dbUrl, connect_args={'check_same_thread': False}, echo=True) 66 | ``` 67 | 68 | 69 | 70 | 71 | 72 | ```py app.py 73 | from sqlalchemy.orm import Session 74 | from sqlalchemy import select 75 | from models import Foo 76 | 77 | @app.route("/", methods=(["GET"])) 78 | def home(): 79 | session = Session(engine) 80 | 81 | # get & print foos 82 | stmt = select(Foo) 83 | 84 | for item in session.scalars(stmt): 85 | print(item) 86 | 87 | ``` 88 | 89 | 90 | 91 | 92 | -------------------------------------------------------------------------------- /sdk/python/quickstart.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Turso Quickstart (Python) 3 | sidebarTitle: Quickstart 4 | description: Get started with Turso and Python using the libSQL client in a few simple steps. 5 | --- 6 | 7 | In this Python quickstart we will learn how to: 8 | 9 | - Retrieve database credentials 10 | - Install the libSQL package 11 | - Connect to a Turso database 12 | - Execute a query using SQL 13 | - Sync changes to local database (optional) 14 | 15 | 16 | 17 | 18 | You will need an existing database to continue. If you don't have one, [create one](/quickstart). 19 | 20 | 21 | 22 | You will want to store these as environment variables. 23 | 24 | 25 | 26 | 27 | 28 | First begin by adding libSQL to your project: 29 | 30 | ```bash 31 | pip install libsql-experimental 32 | ``` 33 | 34 | 35 | 36 | 37 | 38 | Then import the package: 39 | 40 | ```py 41 | import libsql_experimental as libsql 42 | ``` 43 | 44 | Now connect to your local or remote database using the libSQL connector: 45 | 46 | 47 | 48 | ```py 49 | url = os.getenv("TURSO_DATABASE_URL") 50 | auth_token = os.getenv("TURSO_AUTH_TOKEN") 51 | 52 | conn = libsql.connect("hello.db", sync_url=url, auth_token=auth_token) 53 | conn.sync() 54 | ``` 55 | 56 | 57 | 58 | 59 | ```py 60 | conn = libsql.connect("hello.db") 61 | cur = conn.cursor() 62 | ``` 63 | 64 | 65 | 66 | {/* 67 | ```py 68 | url = os.getenv("TURSO_DATABASE_URL") 69 | auth_token = os.getenv("TURSO_AUTH_TOKEN") 70 | 71 | conn = libsql.connect(database=url, auth_token=auth_token) 72 | ``` 73 | 74 | */} 75 | 76 | 77 | 78 | 79 | 80 | 81 | You can execute SQL queries against your existing database as follows: 82 | 83 | ```py 84 | conn.execute("CREATE TABLE IF NOT EXISTS users (id INTEGER);") 85 | conn.execute("INSERT INTO users(id) VALUES (10);") 86 | 87 | print(conn.execute("select * from users").fetchall()) 88 | ``` 89 | 90 | 91 | 92 | 93 | 94 | When using embedded replicas you should call `sync()` on the connector to sync your local database with the primary database. 95 | 96 | ```py 97 | conn.execute("CREATE TABLE IF NOT EXISTS users (id INTEGER);") 98 | conn.execute("INSERT INTO users(id) VALUES (1);") 99 | conn.commit() 100 | 101 | conn.sync() 102 | 103 | print(conn.execute("select * from users").fetchall()) 104 | ``` 105 | 106 | 107 | 108 | -------------------------------------------------------------------------------- /sdk/python/reference.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Reference 3 | --- 4 | 5 | ## Embedded Replicas 6 | 7 | You can work with [embedded replicas](/features/embedded-replicas) that can sync from the remote database to a local SQLite file, and delegate writes to the remote primary database: 8 | 9 | ```py 10 | import os 11 | 12 | import libsql_experimental as libsql 13 | 14 | conn = libsql.connect("local.db", sync_url=os.getenv("LIBSQL_URL"), 15 | auth_token=os.getenv("LIBSQL_AUTH_TOKEN")) 16 | conn.execute("CREATE TABLE IF NOT EXISTS users (id INTEGER);") 17 | conn.execute("INSERT INTO users(id) VALUES (1);") 18 | conn.commit() 19 | 20 | print(conn.execute("select * from users").fetchall()) 21 | ``` 22 | 23 | 24 | 25 | ### Periodic Sync 26 | 27 | You can automatically sync at intervals by passing time in seconds to the `sync_interval` option. For example, to sync every minute, you can use the following code: 28 | 29 | ```py 30 | conn = libsql.connect("local.db", sync_interval=60, sync_url=os.getenv("LIBSQL_URL"), 31 | auth_token=os.getenv("LIBSQL_AUTH_TOKEN")) 32 | ``` 33 | 34 | ### Manual Sync 35 | 36 | The `Sync` function allows you to sync manually the local database with the remote counterpart: 37 | 38 | ```py 39 | conn.execute("INSERT INTO users(id) VALUES (2);") 40 | conn.commit() 41 | conn.sync() 42 | ``` 43 | 44 | ## Encryption 45 | 46 | To enable encryption on a SQLite file, pass the encryption secret to the `encryption_key` option: 47 | 48 | ```py 49 | conn = libsql.connect("encrypted.db", sync_url=os.getenv("LIBSQL_URL"), 50 | auth_token=os.getenv("LIBSQL_AUTH_TOKEN"), 51 | encryption_key=os.getenv("ENCRYPTION_KEY")) 52 | ``` 53 | 54 | 55 | 56 | Encrypted databases appear as raw data and cannot be read as standard SQLite databases. You must use the libSQL client for any operations — [learn more](/libsql#encryption-at-rest). 57 | 58 | 59 | -------------------------------------------------------------------------------- /sdk/ruby/examples.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Turso Examples (Ruby) 3 | sidebarTitle: Examples 4 | --- 5 | 6 | | Example | Description | 7 | | ---------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | 8 | | [local](https://github.com/tursodatabase/libsql-ruby/tree/master/examples/local) | Uses libsql with a local SQLite file. Creates database, inserts data, and queries. | 9 | | [remote](https://github.com/tursodatabase/libsql-ruby/tree/master/examples/remote) | Connects to a remote database. Requires environment variables for URL and auth token. | 10 | | [sync](https://github.com/tursodatabase/libsql-ruby/tree/master/examples/sync) | Demonstrates synchronization between local and remote databases. | 11 | | [transactions](https://github.com/tursodatabase/libsql-ruby/tree/master/examples/transactions) | Shows transaction usage: starting, performing operations, and committing/rolling back. | 12 | | [memory](https://github.com/tursodatabase/libsql-ruby/tree/master/examples/memory) | Uses an in-memory SQLite database for temporary storage or fast access. | 13 | | [vector](https://github.com/tursodatabase/libsql-ruby/tree/master/examples/vector) | Works with vector embeddings, storing and querying for similarity search. | 14 | | [encryption](https://github.com/tursodatabase/libsql-ruby/tree/master/examples/encryption) | Creates and uses an encrypted SQLite database, demonstrating setup and data operations. | 15 | -------------------------------------------------------------------------------- /sdk/ruby/quickstart.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Turso Quickstart (Ruby) 3 | sidebarTitle: Quickstart 4 | description: Get started with Turso and Ruby using the libSQL client in a few simple steps. 5 | --- 6 | 7 | 8 | 9 | In this Ruby quickstart we will learn how to: 10 | 11 | - Retrieve database credentials 12 | - Install the libSQL package 13 | - Connect to a local or remote Turso database 14 | - Execute a query using SQL 15 | - Sync changes to local database (optional) 16 | 17 | 18 | 19 | 20 | You will need an existing database to continue. If you don't have one, [create one](/quickstart). 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | Inside your Ruby project, install the following Rubygem: 31 | 32 | ```bash 33 | bundle add turso_libsql 34 | ``` 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | ```rb 44 | require 'turso_libsql' 45 | 46 | db =Libsql::Database.new( 47 | path: 'local.db', 48 | url: ENV['TURSO_DATABASE_URL'], 49 | auth_token: ENV['TURSO_AUTH_TOKEN'], 50 | sync_interval: 100 51 | ) 52 | ``` 53 | 54 | 55 | 56 | 57 | ```rb 58 | require 'turso_libsql' 59 | 60 | db = Libsql::Database.new(path: 'local.db') 61 | ``` 62 | 63 | 64 | 65 | 66 | ```rb 67 | require 'turso_libsql' 68 | 69 | db = Libsql::Database.new( 70 | url: ENV['TURSO_DATABASE_URL'], 71 | auth_token: ENV['TURSO_AUTH_TOKEN'] 72 | ) 73 | ``` 74 | 75 | 76 | 77 | 78 | 79 | 80 | 81 | 82 | You can execute a SQL query against your existing database by preparing a statement and then executing it: 83 | 84 | ```c 85 | db.connect do |conn| 86 | rows = conn.query 'SELECT * FROM users' 87 | rows.close 88 | end 89 | ``` 90 | 91 | If you need to use placeholders for values, you can do that: 92 | 93 | 94 | 95 | ```c Positional 96 | name = 'Iku' 97 | rows = conn.execute 'INSERT INTO users (id) VALUES (?)', [name] 98 | ``` 99 | 100 | 101 | 102 | 103 | 104 | 105 | 106 | When using embedded replicas, you should call `sync` on the database to sync your local database with the primary database, unless you are using `sync_interval` (though there is no issue with calling `sync` with `sync_interval` enabled): 107 | 108 | ```rb 109 | db.sync 110 | ``` 111 | 112 | 113 | 114 | -------------------------------------------------------------------------------- /sdk/rust/examples.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Examples 3 | url: https://github.com/tursodatabase/libsql/tree/main/libsql/examples 4 | --- 5 | -------------------------------------------------------------------------------- /sdk/rust/guides/actix.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Turso + Actix 3 | sidebarTitle: Actix 4 | description: Set up Turso in your Actix project in minutes 5 | --- 6 | 7 | ![Actix banner](/images/guides/actix-banner.png) 8 | 9 | ## Prerequisites 10 | 11 | Before you start, make sure you: 12 | 13 | - [Install the Turso CLI](/cli/installation) 14 | - [Sign up or login to Turso](/cli/authentication#signup) 15 | - Have an Actix app — [learn more](https://actix.rs/docs/getting-started) 16 | 17 | 18 | 19 | 20 | 21 | You will need an existing database to continue. If you don't have one, [create one](/quickstart). 22 | 23 | 24 | 25 | You will want to store these as environment variables. 26 | 27 | 28 | 29 | 30 | 31 | ```sh 32 | cargo add libsql 33 | ``` 34 | 35 | 36 | Optionally, you can add a package such as [`dotenvy`](https://docs.rs/dotenvy/latest/dotenvy) to help you work with `.env` files: 37 | 38 | ```sh 39 | cargo add dotenvy 40 | ``` 41 | 42 | 43 | 44 | 45 | 46 | 47 | ```rust 48 | #[tokio::main] 49 | #[actix_web::main] 50 | async fn main() -> std::io::Result<()> { 51 | HttpServer::new(|| App::new().route("/", web::get().to(index)).route("/items", web::get().to(get_items))) 52 | .bind(("127.0.0.1", 8080))? 53 | .run() 54 | .await 55 | } 56 | 57 | async fn get_items() -> Result { 58 | dotenv().expect(".env file not found"); 59 | 60 | let db_url = env::var("TURSO_DATABASE_URL").unwrap(); 61 | let auth_token = env::var("TURSO_AUTH_TOKEN").unwrap(); 62 | let db_file = env::var("LOCAL_DB").unwrap(); 63 | 64 | let db = Builder::new_remote_replica(db_file, url, auth_token) 65 | .read_your_writes(true) 66 | .build() 67 | .await 68 | .unwrap(); 69 | 70 | let conn = db.connect().unwrap(); 71 | 72 | let mut results = conn.query("SELECT * FROM items", ()).await.unwrap(); 73 | 74 | let mut items: Vec = Vec::new(); 75 | 76 | while let Some(row) = results.next().await.unwrap() { 77 | let item: Item = Item { 78 | task: row.get(0).unwrap(), 79 | }; 80 | items.push(item); 81 | } 82 | 83 | Ok(HttpResponse::Ok().json(items)) 84 | } 85 | ``` 86 | 87 | 88 | 89 | 90 | 91 | ## Examples 92 | 93 | 94 | 99 | See the full source code 100 | 101 | 102 | -------------------------------------------------------------------------------- /sdk/rust/guides/rocket.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Turso + Rocket 3 | sidebarTitle: Rocket 4 | description: Set up Turso in your Rocket project in minutes 5 | --- 6 | 7 | ![Rocket banner](/images/guides/rocket-banner.png) 8 | 9 | ## Prerequisites 10 | 11 | Before you start, make sure you: 12 | 13 | - [Install the Turso CLI](/cli/installation) 14 | - [Sign up or login to Turso](/cli/authentication#signup) 15 | - Have a Rocket app — [learn more](https://rocket.rs/v0.5/guide/getting-started/) 16 | 17 | 18 | 19 | 20 | 21 | You will need an existing database to continue. If you don't have one, [create one](/quickstart). 22 | 23 | 24 | 25 | You will want to store these as environment variables. 26 | 27 | 28 | 29 | 30 | 31 | ```sh 32 | cargo add libsql 33 | ``` 34 | 35 | 36 | Optionally, you can add a package such as [`dotenvy`](https://docs.rs/dotenvy/latest/dotenvy) to help you work with `.env` files: 37 | 38 | ```sh 39 | cargo add dotenvy 40 | ``` 41 | 42 | 43 | 44 | 45 | 46 | 47 | ```rust 48 | #[get("/todos")] 49 | async fn get_todos() -> Json> { 50 | dotenv().expect(".env file not found"); 51 | 52 | let url = env::var("TURSO_DATABASE_URL").expect("TURSO_DATABASE_URL not found!"); 53 | let token = env::var("TURSO_AUTH_TOKEN").expect("TURSO_AUTH_TOKEN not found!"); 54 | 55 | let db = Database::open_remote(url, token).unwrap(); 56 | let conn = db.connect().unwrap(); 57 | 58 | let mut response = conn.query("select * from todos", ()).await.unwrap(); 59 | 60 | let mut todos: Vec = Vec::new(); 61 | while let Some(row) = response.next().unwrap() { 62 | let todo: Todo = Todo { 63 | task: row.get(0).unwrap(), 64 | }; 65 | todos.push(todo); 66 | } 67 | 68 | Json(todos) 69 | } 70 | 71 | #[launch] 72 | fn rocket() -> _ { 73 | dotenv().ok(); 74 | rocket::build().mount("/", routes![get_todos]) 75 | } 76 | ``` 77 | 78 | 79 | 80 | 81 | 82 | ## Examples 83 | 84 | 85 | 90 | See the full source code 91 | 92 | 93 | -------------------------------------------------------------------------------- /sdk/swift/quickstart.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Turso Quickstart (Swift) 3 | sidebarTitle: Quickstart 4 | description: Get started with Turso and Swift using the libSQL client in a few simple steps. 5 | --- 6 | 7 | 8 | 9 | In this Swift quickstart we will learn how to: 10 | 11 | - Retrieve database credentials 12 | - Install the libSQL package 13 | - Connect to a local or remote Turso database 14 | - Execute a query using SQL 15 | - Sync changes to local database (optional) 16 | 17 | 18 | 19 | 20 | You will need an existing database to continue. If you don't have one, [create one](/quickstart). 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | First begin by adding `libsql` as a package dependency in XCode using this repo: 31 | 32 | 33 | Build from source code 34 | 35 | 36 | Or add it to your SwiftPM dependencies: 37 | 38 | ```swift 39 | import PackageDescription 40 | 41 | let package = Package( 42 | // ... 43 | dependencies: [ 44 | .package(url: "https://github.com/tursodatabase/libsql-swift", from: "0.1.1"), 45 | ], 46 | // ... 47 | ) 48 | ``` 49 | 50 | 51 | 52 | 53 | 54 | You must first create a `Database` object and then open a `Connection` to it: 55 | 56 | 57 | 58 | 59 | ```swift 60 | import Libsql 61 | 62 | let db = try Database( 63 | path: "./local.db", 64 | url: "TURSO_DATABASE_URL", 65 | authToken: "TURSO_AUTH_TOKEN", 66 | syncInterval: 300 67 | ) 68 | 69 | let conn = try db.connect() 70 | ``` 71 | 72 | 73 | 74 | 75 | ```swift 76 | import Libsql 77 | 78 | let db = try Database( 79 | path: "./local.db", 80 | ) 81 | 82 | let conn = try db.connect() 83 | ``` 84 | 85 | 86 | 87 | 88 | ```swift 89 | import Libsql 90 | 91 | let db = try Database( 92 | url: "TURSO_DATABASE_URL", 93 | authToken: "TURSO_AUTH_TOKEN" 94 | ) 95 | 96 | let conn = try db.connect() 97 | ``` 98 | 99 | 100 | 101 | 102 | 103 | 104 | 105 | 106 | You can execute a SQL query against your existing database by calling `query()`, 107 | or `execute()` when you expect the query to not yield any rows: 108 | 109 | ```swift 110 | let rows = try conn.query("SELECT * FROM users") 111 | ``` 112 | 113 | If you need to use placeholders for values, you can do that: 114 | 115 | 116 | 117 | ```swift Positional Query 118 | try conn.query("SELECT * FROM users WHERE id = ?", 1) 119 | ``` 120 | 121 | ```swift Positional Insert 122 | try conn.execute("INSERT INTO users (id) VALUES (?)", 1) 123 | ``` 124 | 125 | Named arguments are not supported yet. 126 | 127 | 128 | 129 | 130 | 131 | 132 | 133 | When using embedded replicas you should call `sync()` on the database type to 134 | sync your local database with the primary database, unless you are using 135 | `sync_interval` (though there is no issue with calling `sync` with 136 | `sync_interval` enabled): 137 | 138 | ```swift 139 | try db.sync() 140 | ``` 141 | 142 | 143 | 144 | -------------------------------------------------------------------------------- /sdk/ts/examples.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Examples 3 | url: https://github.com/tursodatabase/libsql-client-ts/tree/main/packages/libsql-client/examples 4 | --- 5 | -------------------------------------------------------------------------------- /sdk/ts/guides/astro.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Astro + Turso 3 | sidebarTitle: Astro 4 | description: Set up Turso in your Astro project in minutes. 5 | --- 6 | 7 | ![Astro banner](/images/guides/astro-banner.png) 8 | 9 | ## Prerequisites 10 | 11 | To get the most out of this guide, you'll need to: 12 | 13 | - [Install the Turso CLI](/cli/installation) 14 | - [Sign up or login to Turso](/cli/authentication#signup) 15 | - Have an Astro project — [learn more](https://docs.astro.build/en/install/auto/#1-run-the-setup-wizard) 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | ```ts src/turso.ts 34 | import { createClient } from "@libsql/client/web"; 35 | 36 | export const turso = createClient({ 37 | url: import.meta.env.TURSO_DATABASE_URL!, 38 | authToken: import.meta.env.TURSO_AUTH_TOKEN, 39 | }); 40 | ``` 41 | 42 | 43 | Astro will soon introduce a new ENV API. [Take a 44 | look](https://docs.astro.build/en/reference/configuration-reference/#experimentalenv). 45 | 46 | 47 | 48 | 49 | 50 | 51 | ```ts 52 | --- 53 | import { turso } from './turso' 54 | 55 | const { rows } = await turso.execute('SELECT * FROM table_name') 56 | --- 57 | ``` 58 | 59 | 60 | 61 | 62 | 63 | ## Examples 64 | 65 | 66 | 71 | See the full source code 72 | 73 | 74 | -------------------------------------------------------------------------------- /sdk/ts/guides/elysia.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Elysia + Turso 3 | sidebarTitle: Elysia 4 | description: Set up Turso in your Elysia project in minutes. 5 | --- 6 | 7 | ![Elysia banner](/images/guides/elysia-banner.png) 8 | 9 | ## Prerequisites 10 | 11 | Before you start, make sure you: 12 | 13 | - [Install the Turso CLI](/cli/installation) 14 | - [Sign up or login to Turso](/cli/authentication#signup) 15 | - Have an Elysia app — [learn more](https://elysiajs.com/quick-start.html) 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | ```ts 40 | import { Elysia } from "elysia"; 41 | import { turso } from "./lib/turso"; 42 | 43 | const app = new Elysia().get("/items", async () => { 44 | const { rows } = await turso.execute("SELECT * FROM items"); 45 | return rows; 46 | }); 47 | ``` 48 | 49 | 50 | 51 | 52 | 53 | ## Examples 54 | 55 | 56 | 61 | See the full source code 62 | 63 | 64 | -------------------------------------------------------------------------------- /sdk/ts/guides/hono.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Hono + Turso 3 | sidebarTitle: Hono 4 | description: Set up Turso in your Hono project in minutes. 5 | --- 6 | 7 | ![Hono banner](/images/guides/hono-banner.png) 8 | 9 | ## Prerequisites 10 | 11 | Before you start, make sure you: 12 | 13 | - [Install the Turso CLI](/cli/installation) 14 | - [Sign up or login to Turso](/cli/authentication#signup) 15 | - Have a Hono app — [learn more](https://hono.dev/top#quick-start) 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | ```ts 40 | import { Hono } from "hono"; 41 | import { turso } from "./lib/turso"; 42 | 43 | const app = new Hono(); 44 | 45 | app.get("/items", async (c) => { 46 | const { rows } = await turso.execute("SELECT * FROM items"); 47 | 48 | return c.json({ rows }); 49 | }); 50 | ``` 51 | 52 | 53 | 54 | 55 | 56 | ## Examples 57 | 58 | 59 | 64 | See the full source code 65 | 66 | 67 | -------------------------------------------------------------------------------- /sdk/ts/guides/nextjs.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Next.js + Turso 3 | sidebarTitle: Next.js 4 | description: Set up Turso in your Next.js project in minutes. 5 | --- 6 | 7 | ![Next.js banner](/images/guides/nextjs-banner.png) 8 | 9 | ## Prerequisites 10 | 11 | Before you start, make sure you: 12 | 13 | - [Install the Turso CLI](/cli/installation) 14 | - [Sign up or login to Turso](/cli/authentication#signup) 15 | - Have a Next.js app — [learn more](https://nextjs.org/docs/getting-started/installation) 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | ```tsx App Router 42 | import { turso } from "@/lib/turso"; 43 | 44 | export default async function Page() { 45 | const { rows } = await turso.execute("SELECT * FROM table_name"); 46 | 47 | return ( 48 |
    49 | {rows.map((row) => ( 50 |
  • {row.id}
    • 51 | ))} 52 |
53 | ); 54 | } 55 | ``` 56 | 57 | ```ts Pages Directory 58 | import type { InferGetServerSidePropsType, GetServerSideProps } from "next"; 59 | 60 | import { turso } from "@/lib/turso"; 61 | 62 | export const getServerSideProps = (async () => { 63 | const { rows } = await turso.execute("SELECT * FROM table_name"); 64 | 65 | return { 66 | props: { 67 | rows, 68 | }, 69 | }; 70 | }) satisfies GetServerSideProps<{ rows: any[] }>; 71 | 72 | export default function Page({ 73 | rows, 74 | }: InferGetServerSidePropsType) { 75 | return ( 76 |
    77 | {rows.map((row) => ( 78 |
  • {row.id}
    • 79 | ))} 80 |
81 | ); 82 | } 83 | ``` 84 | 85 | 86 | 87 | 88 | 89 | 90 | 91 | ## Examples 92 | 93 | 94 | 99 | See the full source code 100 | 101 | 102 | -------------------------------------------------------------------------------- /sdk/ts/guides/nuxt.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Nuxt + Turso 3 | sidebarTitle: Nuxt 4 | description: Set up Turso in your Nuxt project in minutes 5 | --- 6 | 7 | ![Nuxt banner](/images/guides/nuxt-banner.png) 8 | 9 | Before you start, make sure you: 10 | 11 | - [Install the Turso CLI](/cli/installation) 12 | - [Sign up or login to Turso](/cli/authentication#signup) 13 | - Have a Nuxt app — [learn more](https://nuxt.com/docs/getting-started/installation#new-project) 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | Get the database URL: 26 | 27 | ```bash 28 | turso db show --url 29 | ``` 30 | 31 | Get the database authentication token: 32 | 33 | ```bash 34 | turso db tokens create 35 | ``` 36 | 37 | Assign credentials to the environment variables inside `.env`. 38 | 39 | ```bash 40 | NUXT_TURSO_DATABASE_URL= 41 | NUXT_TURSO_AUTH_TOKEN= 42 | ``` 43 | 44 | 45 | 46 | 47 | 48 | ```ts nuxt.config.ts 49 | export default defineNuxtConfig({ 50 | runtimeConfig: { 51 | turso: { 52 | databaseUrl: "", 53 | authToken: "", 54 | }, 55 | }, 56 | }); 57 | ``` 58 | 59 | 60 | Make sure that names of the keys in the `runtimeConfig` object match the names 61 | of your environment variables. Read more about this 62 | [here](https://nuxt.com/docs/guide/going-further/runtime-config). 63 | 64 | 65 | 66 | 67 | 68 | 69 | ```ts server/utils/turso.ts 70 | import { createClient } from "@libsql/client"; 71 | // You can optionally pass in the event to useRuntimeConfig 72 | // import { H3Event } from "h3"; 73 | 74 | export function useTurso(/* event: H3Event */) { 75 | const { turso } = useRuntimeConfig(/* event */); 76 | 77 | return createClient({ 78 | url: turso.databaseUrl, 79 | authToken: turso.authToken, 80 | }); 81 | } 82 | ``` 83 | 84 | 85 | 86 | 87 | 88 | ```ts server/api/items.get.ts 89 | export default defineEventHandler(async (event) => { 90 | const client = useTurso(/* event */); 91 | const { rows } = await client.execute("select * from table_name"); 92 | 93 | return { 94 | data: { 95 | items: rows, 96 | }, 97 | }; 98 | }); 99 | ``` 100 | 101 | 102 | 103 | 104 | 105 | ## Examples 106 | 107 | 108 | 113 | See the full source code 114 | 115 | 116 | -------------------------------------------------------------------------------- /sdk/ts/guides/quasar.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Quasar + Turso 3 | sidebarTitle: Quasar 4 | description: Set up Turso in your Quasar project in minutes 5 | --- 6 | 7 | ![Quasar banner](/images/guides/quasar-banner.png) 8 | 9 | ## Prerequisites 10 | 11 | Before you start, make sure you: 12 | 13 | - [Install the Turso CLI](/cli/installation) 14 | - [Sign up or login to Turso](/cli/authentication#signup) 15 | - Have a Quasar app — [learn more](https://quasar.dev/start/quick-start#step-1-create-a-project) 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | Get the database URL: 28 | 29 | ```bash 30 | turso db show --url 31 | ``` 32 | 33 | Get the database authentication token: 34 | 35 | ```bash 36 | turso db tokens create 37 | ``` 38 | 39 | Assign credentials to the environment variables inside `.env.local`. 40 | 41 | ```bash 42 | VITE_TURSO_DATABASE_URL="..." 43 | VITE_TURSO_AUTH_TOKEN="..." 44 | ``` 45 | 46 | 47 | 48 | 49 | 50 | ```js 51 | import { createClient } from "@libsql/client/web"; 52 | 53 | const turso = createClient({ 54 | url: import.meta.env.VITE_TURSO_DATABASE_URL, 55 | authToken: import.meta.env.VITE_TURSO_AUTH_TOKEN, 56 | }); 57 | ``` 58 | 59 | 60 | Avoid a [gotcha 61 | moment](https://github.com/quasarframework/quasar/discussions/16071) by 62 | modifying the app configuration using the settings below. 63 | 64 | 65 | ```javascript quasar.config.js 66 | { 67 | build: { 68 | target: { 69 | browser: [ 70 | 'es2020', 'edge88', 'firefox78', 'chrome87', 'safari13.1' 71 | ], 72 | node: 'node16' 73 | }, 74 | extendViteConf(config) { 75 | config.optimizeDeps = { 76 | esbuildOptions: { 77 | target: 'es2020', 78 | } 79 | } 80 | } 81 | } 82 | } 83 | ``` 84 | 85 | 86 | 87 | 88 | 89 | ```js IndexPage.vue 90 | import { ref } from "vue"; 91 | 92 | const items = ref(); 93 | 94 | const { rows } = await turso.execute("select * from my-table"); 95 | 96 | items.value = rows; 97 | ``` 98 | 99 | 100 | 101 | 102 | 103 | ## Examples 104 | 105 | 106 | 111 | See the full source code 112 | 113 | 114 | -------------------------------------------------------------------------------- /sdk/ts/guides/qwik.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Qwik + Turso 3 | sidebarTitle: Qwik 4 | description: Set up Turso in your Qwik project in minutes 5 | --- 6 | 7 | ![Qwik banner](/images/guides/qwik-banner.png) 8 | 9 | ## Prerequisites 10 | 11 | Before you start, make sure you: 12 | 13 | - [Install the Turso CLI](/cli/installation) 14 | - [Sign up or login to Turso](/cli/authentication#signup) 15 | - Have a Qwik app — [learn more](https://qwik.builder.io/docs/getting-started/#create-an-app-using-the-cli) 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | ```bash npm 24 | npm run qwik add turso 25 | ``` 26 | 27 | ```bash pnpm 28 | pnpm qwik add turso 29 | ``` 30 | 31 | ```bash yarn 32 | yarn qwik add turso 33 | ``` 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | Get the database URL: 42 | 43 | ```bash 44 | turso db show --url 45 | ``` 46 | 47 | Get the database authentication token: 48 | 49 | ```bash 50 | turso db tokens create 51 | ``` 52 | 53 | Assign credentials to the environment variables inside `.env.local`. 54 | 55 | ```bash 56 | PRIVATE_TURSO_DATABASE_URL="..." 57 | PRIVATE_TURSO_AUTH_TOKEN="..." 58 | ``` 59 | 60 | 61 | 62 | 63 | 64 | ```ts 65 | import { tursoClient } from "~/utils/turso"; 66 | 67 | export const useFrameworks = routeLoader$( 68 | async (requestEvent: RequestEventBase) => { 69 | const db = tursoClient(requestEvent["env"]); 70 | const { rows } = await db.execute("select * from table_name"); 71 | 72 | return { 73 | items: rows, 74 | }; 75 | } 76 | ); 77 | ``` 78 | 79 | 80 | 81 | 82 | 83 | ## Examples 84 | 85 | 86 | 91 | See the full source code 92 | 93 | 98 | See the full source code 99 | 100 | 101 | -------------------------------------------------------------------------------- /sdk/ts/guides/remix.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Remix + Turso 3 | sidebarTitle: Remix 4 | description: Set up Turso in your Remix project in minutes 5 | --- 6 | 7 | ![Remix banner](/images/guides/remix-banner.png) 8 | 9 | ## Prerequisites 10 | 11 | Before you start, make sure you: 12 | 13 | - [Install the Turso CLI](/cli/installation) 14 | - [Sign up or login to Turso](/cli/authentication#signup) 15 | - Have a Remix app — [learn more](https://remix.run/docs/en/main/start/quickstart#quick-start) 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | ```ts app/routes/_index.ts 40 | import type { LoaderFunction } from "@remix-run/node"; 41 | 42 | import { turso } from "~/lib/turso"; 43 | 44 | export const loader: LoaderFunction = async () => { 45 | const { rows } = await turso.execute("SELECT * from TABLE_NAME"); 46 | 47 | return { 48 | items: rows, 49 | }; 50 | }; 51 | ``` 52 | 53 | 54 | 55 | 56 | 57 | ## Examples 58 | 59 | 60 | 65 | See the full source code 66 | 67 | 72 | See the full source code 73 | 74 | 75 | -------------------------------------------------------------------------------- /sdk/ts/guides/sveltekit.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: SvelteKit + Turso 3 | sidebarTitle: SvelteKit 4 | description: Set up Turso in your SvelteKit project in minutes 5 | --- 6 | 7 | ![SvelteKit banner](/images/guides/svelte-banner.png) 8 | 9 | ## Prerequisites 10 | 11 | Before you start, make sure you: 12 | 13 | - [Install the Turso CLI](/cli/installation) 14 | - [Sign up or login to Turso](/cli/authentication#signup) 15 | - Have a SvelteKit app — [learn more](https://kit.svelte.dev/docs/creating-a-project) 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | ```ts Node.js / Serverless 36 | import { TURSO_DATABASE_URL, TURSO_AUTH_TOKEN } from "$env/static/private"; 37 | import { createClient } from "@libsql/client"; 38 | 39 | export const turso = createClient({ 40 | url: TURSO_DATABASE_URL, 41 | authToken: TURSO_AUTH_TOKEN, 42 | }); 43 | ``` 44 | 45 | ```ts Edge Runtimes 46 | import { TURSO_DATABASE_URL, TURSO_AUTH_TOKEN } from "$env/static/private"; 47 | import { createClient } from "@libsql/client/web"; 48 | 49 | export const turso = createClient({ 50 | url: TURSO_DATABASE_URL, 51 | authToken: TURSO_AUTH_TOKEN, 52 | }); 53 | ``` 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | 62 | 63 | ```ts src/routes/+page.server.ts 64 | import { turso } from "$lib/turso.server"; 65 | 66 | export async function load() { 67 | const { rows } = await turso.execute("SELECT * FROM table_name"); 68 | 69 | return { rows }; 70 | } 71 | ``` 72 | 73 | ```svelte src/routes/+page.svelte 74 | 77 | 78 |
    79 | {#each data.rows as row} 80 |
  • {row.id}
    • 81 | {/each} 82 |
83 | ``` 84 | 85 | 86 | 87 | 88 | 89 | 90 | 91 | ## Examples 92 | 93 | 94 | 99 | See the full source code 100 | 101 | 102 | -------------------------------------------------------------------------------- /sdk/ts/integrations/sentry.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Sentry 3 | description: Trace slow queries and capture SQL errors with Sentry. 4 | --- 5 | 6 | The [Sentry](https://sentry.io/integrations/turso) integration for `@libsql/client` provides tracing, breadcrumbs, and error handling for SQL queries. 7 | 8 | 9 | 10 | ## Install 11 | 12 | ```bash 13 | npm install sentry-integration-libsql-client 14 | ``` 15 | 16 | ## Quickstart 17 | 18 | Once you have a `@libsql/client` instance, you can integrate it with Sentry like this: 19 | 20 | ```ts 21 | import * as Sentry from "@sentry/node"; 22 | import { createClient } from "@libsql/client"; 23 | import { libsqlIntegration } from "sentry-integration-libsql-client"; 24 | 25 | const libsqlClient = createClient({ 26 | url: "libsql://...", 27 | authToken: "...", 28 | }); 29 | 30 | Sentry.init({ 31 | dsn: "...", 32 | integrations: [libsqlIntegration(libsqlClient, Sentry)], 33 | }); 34 | 35 | await libsqlClient.execute("SELECT * FROM users"); 36 | ``` 37 | 38 | ## Options 39 | 40 | By default, everything is turned on. You can configure what you want by passing a third argument to the `libsqlIntegration` function. 41 | 42 | | Option | Default | Description | 43 | | ------------- | ------- | -------------------------------------- | 44 | | `tracing` | `true` | Enable tracing for SQL queries. | 45 | | `breadcrumbs` | `true` | Enable breadcrumbs for SQL queries. | 46 | | `errors` | `true` | Enable error handling for SQL queries. | 47 | 48 | ```ts 49 | Sentry.init({ 50 | dsn: "...", 51 | integrations: [ 52 | libsqlIntegration(libsqlClient, Sentry, { 53 | tracing: false, 54 | breadcrumbs: false, 55 | errors: false, 56 | }), 57 | ], 58 | }); 59 | ``` 60 | -------------------------------------------------------------------------------- /sdk/ts/orm/prisma.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Prisma + Turso 3 | sidebarTitle: Prisma 4 | description: Configure Prisma to work with your Turso database 5 | --- 6 | 7 | ![Prisma banner](/images/guides/prisma-banner.png) 8 | 9 | ## Prerequisites 10 | 11 | Before you start, make sure you: 12 | 13 | - [Install the Turso CLI](/cli/installation) 14 | - [Sign up or login to Turso](/cli/authentication#signup) 15 | - Prisma versions 5.4.2 and later 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | ```bash npm 24 | npm install @libsql/client @prisma/adapter-libsql 25 | ``` 26 | 27 | ```bash pnpm 28 | pnpm add @libsql/client @prisma/adapter-libsql 29 | ``` 30 | 31 | ```bash yarn 32 | yarn add @libsql/client @prisma/adapter-libsql 33 | ``` 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | ```js prisma/schema.prisma 48 | generator client { 49 | provider = "prisma-client-js" 50 | previewFeatures = ["driverAdapters"] 51 | } 52 | 53 | datasource db { 54 | provider = "sqlite" 55 | url = "file:./dev.db" 56 | } 57 | ``` 58 | 59 | 60 | 61 | 62 | 63 | 64 | 65 | ```sh npm 66 | npx prisma generate 67 | ``` 68 | 69 | ```sh pnpm 70 | pnpm dlx prisma generate 71 | ``` 72 | 73 | 74 | 75 | 76 | 77 | 78 | 79 | 80 | 81 | ```ts Node.js / Serverless 82 | import { PrismaClient } from "@prisma/client"; 83 | import { PrismaLibSQL } from "@prisma/adapter-libsql"; 84 | import { createClient } from "@libsql/client"; 85 | 86 | const libsql = createClient({ 87 | url: process.env.TURSO_DATABASE_URL, 88 | authToken: process.env.TURSO_AUTH_TOKEN, 89 | }); 90 | 91 | const adapter = new PrismaLibSQL(libsql); 92 | const prisma = new PrismaClient({ adapter }); 93 | ``` 94 | 95 | ```ts Edge Runtimes 96 | import { PrismaClient } from "@prisma/client"; 97 | import { PrismaLibSQL } from "@prisma/adapter-libsql"; 98 | import { createClient } from "@libsql/client/web"; 99 | 100 | const libsql = createClient({ 101 | url: process.env.TURSO_DATABASE_URL, 102 | authToken: process.env.TURSO_AUTH_TOKEN, 103 | }); 104 | 105 | const adapter = new PrismaLibSQL(libsql); 106 | const prisma = new PrismaClient({ adapter }); 107 | ``` 108 | 109 | 110 | 111 | 112 | 113 | 114 | 115 | Prisma Migrate and Introspection workflows are currently not supported when working with Turso — [learn more](https://www.prisma.io/docs/orm/overview/databases/turso#how-to-manage-schema-changes). 116 | 117 | First, generate a migration file using prisma migrate dev against a local SQLite database 118 | 119 | 120 | 121 | ```sh npm 122 | npx prisma migrate dev --name init 123 | ``` 124 | 125 | ```sh pnpm 126 | pnpm dlx prisma migrate dev --name init 127 | ``` 128 | 129 | 130 | 131 | Then, apply the migration to your Turso database using the Turso's CLI 132 | 133 | ```bash 134 | turso db shell turso-prisma-db < ./prisma/migrations/20230922132717_init/migration.sql 135 | ``` 136 | 137 | 138 | 139 | Replace `20230922132717_init` with the name of your migration created from the `npx prisma migrate dev` command. 140 | 141 | 142 | 143 | 144 | 145 | 146 | 147 | ```ts 148 | const response = await prisma.table_name.findMany(); 149 | ``` 150 | 151 | 152 | 153 | 154 | -------------------------------------------------------------------------------- /sdk/ts/quickstart.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Turso Quickstart (TypeScript / JS) 3 | sidebarTitle: Quickstart 4 | description: Get started with Turso and TypeScript using the libSQL client in a few simple steps 5 | --- 6 | 7 | In this JavaScript quickstart we will learn how to: 8 | 9 | - Retrieve database credentials 10 | - Install the JavaScript libSQL client 11 | - Connect to a remote Turso database 12 | - Execute a query using SQL 13 | 14 | 15 | 16 | 17 | You will need an existing database to continue. If you don't have one, [create one](/quickstart). 18 | 19 | 20 | 21 | You will want to store these as environment variables. 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | Next add your database URL and auth token: 32 | 33 | 34 | 35 | 36 | 37 | 38 | You can execute a SQL query against your existing database by calling `execute()`: 39 | 40 | ```ts 41 | await turso.execute("SELECT * FROM users"); 42 | ``` 43 | 44 | If you need to use placeholders for values, you can do that: 45 | 46 | 47 | 48 | ```ts Positional 49 | await turso.execute({ 50 | sql: "SELECT * FROM users WHERE id = ?", 51 | args: [1], 52 | }); 53 | ``` 54 | 55 | ```ts Named 56 | await turso.execute({ 57 | sql: "INSERT INTO users VALUES (:name)", 58 | args: { name: "Iku" }, 59 | }); 60 | ``` 61 | 62 | 63 | 64 | 65 | 66 | -------------------------------------------------------------------------------- /support.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Support 3 | description: We're always here to help. 4 | --- 5 | 6 | 7 | 8 | 9 | 10 | If you're new to Turso, the easiest way to get started is with this quickstart. 11 | 12 | 13 | 14 | 15 | 16 | Show off what you're working on, ask for help, and chat with the community. 17 | 18 | 19 | 20 | 21 | 22 | If you spot something that doesn't look right, or you've discovered a security related bug or issue, let us know. 23 | 24 | 25 | 26 | 27 | 28 | If you have a question about your account or billing, you'll find answers to most questions on our website. 29 | 30 | 31 | 32 | 33 | --------------------------------------------------------------------------------