From 9a0d5cebe981c6684348db6629a33a571eb46651 Mon Sep 17 00:00:00 2001 From: Pekka Enberg Date: Wed, 13 Aug 2025 12:26:11 +0300 Subject: [PATCH 1/7] docs/manual: Fix limitations section heading style --- docs/manual.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/manual.md b/docs/manual.md index 7e22e2642..5e8b87493 100644 --- a/docs/manual.md +++ b/docs/manual.md @@ -71,7 +71,7 @@ turso> SELECT 'hello, world'; hello, world ``` -## Limitations +### Limitations Turso aims towards full SQLite compatibility but has the following limitations: From ece8f106d96178cc69836efbe0af730a239622a8 Mon Sep 17 00:00:00 2001 From: Pekka Enberg Date: Wed, 13 Aug 2025 12:26:31 +0300 Subject: [PATCH 2/7] docs/manual: Fix JavaScript section The API changed so fix that up. Also improve flow of text. --- docs/manual.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/docs/manual.md b/docs/manual.md index 5e8b87493..ca85f6429 100644 --- a/docs/manual.md +++ b/docs/manual.md @@ -324,6 +324,8 @@ turso> SELECT * FROM t; Turso supports a JavaScript API, both with native and WebAssembly package options. +Please read the [JavaScript API reference](docs/javascript-api-reference.md) for more information. + ### Installation Installing the native package: @@ -338,19 +340,15 @@ Installing the WebAssembly package: npm i @tursodatabase/database --cpu wasm32 ``` -### API reference - -See [JavaScript API reference](docs/javascript-api-reference.md) for more information. - ### Getting Started To use Turso from JavaScript application, you need to import `Database` type from the `@tursodatabase/database` package. You can the prepare a statement with `Database.prepare` method and execute the SQL statement with `Statement.get()` method. ``` -import Database from '@tursodatabase/database'; +import { connect } from '@tursodatabase/database'; -const db = new Database('turso.db'); +const db = await connect('turso.db'); const row = db.prepare('SELECT 1').get(); console.log(row); ``` From bbc7994f596de2d6a62bb37b6b8182e4b291fb70 Mon Sep 17 00:00:00 2001 From: Pekka Enberg Date: Wed, 13 Aug 2025 12:41:41 +0300 Subject: [PATCH 3/7] docs/manual: Document shell command line options --- docs/manual.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/docs/manual.md b/docs/manual.md index ca85f6429..1912aaea7 100644 --- a/docs/manual.md +++ b/docs/manual.md @@ -7,6 +7,8 @@ Welcome to Turso database manual! * [Introduction](#introduction) * [Getting Started](#getting-started) * [Limitations](#limitations) +* [The SQL shell](#the-sql-shell) + * [Command line options](#command-line-options) * [The SQL language](#the-sql-language) * [`ALTER TABLE` — change table definition](#alter-table--change-table-definition) * [`BEGIN TRANSACTION` — start a transaction](#begin-transaction--start-a-transaction) @@ -86,6 +88,36 @@ Turso aims towards full SQLite compatibility but has the following limitations: For more detailed list of SQLite compatibility, please refer to [COMPAT.md](../COMPAT.md). +## The SQL shell + +The `tursodb` command provides an interactive SQL shell, similar to `sqlite3`. You can start it in in-memory mode as follows: + +```console +$ tursodb +Turso +Enter ".help" for usage hints. +Connected to a transient in-memory database. +Use ".open FILENAME" to reopen on a persistent database +turso> SELECT 'hello, world'; +hello, world +``` + +### Command line options + +The SQL shell supports the following command line options: + +| Option | Description | +|--------|-------------| +| `-m`, `--output-mode` `` | Configure output mode. Supported values for ``:
  • `pretty` for pretty output (default)
  • `list` for minimal SQLite compatible format
+| `-q`, `--quiet` | Don't display program information at startup | +| `-e`, `--echo` | Print commands before execution | +| `--readonly` | Open database in read-only mode | +| `-h`, `--help` | Print help | +| `-V`, `--version` | Print version | +| `--mcp` | Start a MCP server instead of the interactive shell | +| `--experimental-mvcc` | Enable experimental MVCC feature. **Note:** the feature is not production ready so do not use it for critical data right now. | +| `--experimental-views` | Enable experimental views feature. **Note**: the feature is not production ready so do not use it for critical data right now. | + ## The SQL language ### `ALTER TABLE` — change table definition From 379896d08707a72c32bcdf558d848f3c694407d2 Mon Sep 17 00:00:00 2001 From: Pekka Enberg Date: Wed, 13 Aug 2025 12:46:17 +0300 Subject: [PATCH 4/7] docs/manual: Document some shell commands --- docs/manual.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/manual.md b/docs/manual.md index 1912aaea7..f0b039eb8 100644 --- a/docs/manual.md +++ b/docs/manual.md @@ -8,6 +8,7 @@ Welcome to Turso database manual! * [Getting Started](#getting-started) * [Limitations](#limitations) * [The SQL shell](#the-sql-shell) + * [Shell commands](#shell-commands) * [Command line options](#command-line-options) * [The SQL language](#the-sql-language) * [`ALTER TABLE` — change table definition](#alter-table--change-table-definition) @@ -102,6 +103,15 @@ turso> SELECT 'hello, world'; hello, world ``` +### Shell commands + +The shell supports commands in addition to SQL statements. The commands start with a dot (".") followed by the command. The supported commands are: + +| Command | Description | +|---------|-------------| +| `.schema` | Display the database schema | +| `.dump` | Dump database contents as SQL statements | + ### Command line options The SQL shell supports the following command line options: From 770b43caa60cc1667b855a0fd639b17253d6b77c Mon Sep 17 00:00:00 2001 From: Pekka Enberg Date: Wed, 13 Aug 2025 12:47:21 +0300 Subject: [PATCH 5/7] docs/manual: Drop indexing from list of limitations Indexes are enabled by default now. --- docs/manual.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/manual.md b/docs/manual.md index f0b039eb8..608ed48e9 100644 --- a/docs/manual.md +++ b/docs/manual.md @@ -80,7 +80,6 @@ Turso aims towards full SQLite compatibility but has the following limitations: * No multi-process access * No multi-threading -* No indexing * No savepoints * No triggers * No views From c942239a5ab7a1b8059ea061ac755e7b979084b4 Mon Sep 17 00:00:00 2001 From: Pekka Enberg Date: Wed, 13 Aug 2025 12:54:37 +0300 Subject: [PATCH 6/7] docs/manual: Document more of SQLite C API --- docs/manual.md | 58 +++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 57 insertions(+), 1 deletion(-) diff --git a/docs/manual.md b/docs/manual.md index 608ed48e9..69be0d7a9 100644 --- a/docs/manual.md +++ b/docs/manual.md @@ -26,6 +26,11 @@ Welcome to Turso database manual! * [`UPDATE` — update rows of a table](#update--update-rows-of-a-table) * [JavaScript API](#javascript-api) * [SQLite C API](#sqlite-c-api) + * [Basic operations](#basic-operations) + * [`sqlite_open`](#sqlite3_open) + * [`sqlite_prepare`](#sqlite3_prepare) + * [`sqlite_step`](#sqlite3_step) + * [`sqlite_column`](#sqlite3_column) * [WAL manipulation](#wal-manipulation) * [`libsql_wal_frame_count`](#libsql_wal_frame_count) * [SQL Commands](#sql-commands) @@ -396,7 +401,58 @@ console.log(row); ## SQLite C API -Turso supports the SQLite C API, with libSQL extensions. +Turso supports a subset of the SQLite C API, including libSQL extensions. + +### Basic operations + +#### `sqlite3_open` + +Open a connection to a database. + +**Synopsis:** + +```c +int sqlite3_open(const char *filename, sqlite3 **db_out); +int sqlite3_open_v2(const char *filename, sqlite3 **db_out, int _flags, const char *_z_vfs); +``` + +#### `sqlite3_prepare` + +Prepare a SQL statement for execution. + +**Synopsis:** + +```c +int sqlite3_prepare_v2(sqlite3 *db, const char *sql, int _len, sqlite3_stmt **out_stmt, const char **_tail); +``` + +#### `sqlite3_step` + +Evaluate a prepared statement until it yields the next row or completes. + +**Synopsis:** + +```c +int sqlite3_step(sqlite3_stmt *stmt); +``` + +#### `sqlite3_column` + +Return the value of a column for the current row of a statement. + +**Synopsis:** + +```c +int sqlite3_column_type(sqlite3_stmt *_stmt, int _idx); +int sqlite3_column_count(sqlite3_stmt *_stmt); +const char *sqlite3_column_decltype(sqlite3_stmt *_stmt, int _idx); +const char *sqlite3_column_name(sqlite3_stmt *_stmt, int _idx); +int64_t sqlite3_column_int64(sqlite3_stmt *_stmt, int _idx); +double sqlite3_column_double(sqlite3_stmt *_stmt, int _idx); +const void *sqlite3_column_blob(sqlite3_stmt *_stmt, int _idx); +int sqlite3_column_bytes(sqlite3_stmt *_stmt, int _idx); +const unsigned char *sqlite3_column_text(sqlite3_stmt *stmt, int idx); +``` ### WAL manipulation From 09d64b22903c3e947f3020526f600cac48d8bbdb Mon Sep 17 00:00:00 2001 From: Pekka Enberg Date: Wed, 13 Aug 2025 12:55:56 +0300 Subject: [PATCH 7/7] docs/manual: Drop redundant section place-holder There's already a section on SQL query language. --- docs/manual.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/manual.md b/docs/manual.md index 69be0d7a9..e0735b816 100644 --- a/docs/manual.md +++ b/docs/manual.md @@ -33,7 +33,6 @@ Welcome to Turso database manual! * [`sqlite_column`](#sqlite3_column) * [WAL manipulation](#wal-manipulation) * [`libsql_wal_frame_count`](#libsql_wal_frame_count) -* [SQL Commands](#sql-commands) * [Appendix A: Turso Internals](#appendix-a-turso-internals) * [Frontend](#frontend) * [Parser](#parser) @@ -485,8 +484,6 @@ in the `p_frame_count` parameter. * The `p_frame_count` must be a valid pointer to a `u32` that will store the * number of frames in the WAL file. -## SQL Commands - ## Appendix A: Turso Internals Turso's architecture resembles SQLite's but differs primarily in its