165 lines
6.7 KiB
Markdown
165 lines
6.7 KiB
Markdown
|
# libSQL API for JavaScript/TypeScript
|
||
|
|
||
|
[![npm](https://badge.fury.io/js/libsql.svg)](https://badge.fury.io/js/libsql)
|
||
|
[![Ask AI](https://img.shields.io/badge/Phorm-Ask_AI-%23F2777A.svg?&logo=data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iNSIgaGVpZ2h0PSI0IiBmaWxsPSJub25lIiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciPgogIDxwYXRoIGQ9Ik00LjQzIDEuODgyYTEuNDQgMS40NCAwIDAgMS0uMDk4LjQyNmMtLjA1LjEyMy0uMTE1LjIzLS4xOTIuMzIyLS4wNzUuMDktLjE2LjE2NS0uMjU1LjIyNmExLjM1MyAxLjM1MyAwIDAgMS0uNTk1LjIxMmMtLjA5OS4wMTItLjE5Mi4wMTQtLjI3OS4wMDZsLTEuNTkzLS4xNHYtLjQwNmgxLjY1OGMuMDkuMDAxLjE3LS4xNjkuMjQ2LS4xOTFhLjYwMy42MDMgMCAwIDAgLjItLjEwNi41MjkuNTI5IDAgMCAwIC4xMzgtLjE3LjY1NC42NTQgMCAwIDAgLjA2NS0uMjRsLjAyOC0uMzJhLjkzLjkzIDAgMCAwLS4wMzYtLjI0OS41NjcuNTY3IDAgMCAwLS4xMDMtLjIuNTAyLjUwMiAwIDAgMC0uMTY4LS4xMzguNjA4LjYwOCAwIDAgMC0uMjQtLjA2N0wyLjQzNy43MjkgMS42MjUuNjcxYS4zMjIuMzIyIDAgMCAwLS4yMzIuMDU4LjM3NS4zNzUgMCAwIDAtLjExNi4yMzJsLS4xMTYgMS40NS0uMDU4LjY5Ny0uMDU4Ljc1NEwuNzA1IDRsLS4zNTctLjA3OUwuNjAyLjkwNkMuNjE3LjcyNi42NjMuNTc0LjczOS40NTRhLjk1OC45NTggMCAwIDEgLjI3NC0uMjg1Ljk3MS45NzEgMCAwIDEgLjMzNy0uMTRjLjExOS0uMDI2LjIyNy0uMDM0LjMyNS0uMDI2TDMuMjMyLjE2Yy4xNTkuMDE0LjMzNi4wMy40NTkuMDgyYTEuMTczIDEuMTczIDAgMCAxIC41NDUuNDQ3Yy4wNi4wOTQuMTA5LjE5Mi4xNDQuMjkzYTEuMzkyIDEuMzkyIDAgMCAxIC4wNzguNThsLS4wMjkuMzJaIiBmaWxsPSIjRjI3NzdBIi8+CiAgPHBhdGggZD0iTTQuMDgyIDIuMDA3YTEuNDU1IDEuNDU1IDAgMCAxLS4wOTguNDI3Yy0uMDUuMTI0LS4xMTQuMjMyLS4xOTIuMzI0YTEuMTMgMS4xMyAwIDAgMS0uMjU0LjIyNyAxLjM1MyAxLjM1MyAwIDAgMS0uNTk1LjIxNGMtLjEuMDEyLS4xOTMuMDE0LS4yOC4wMDZsLTEuNTYtLjEwOC4wMzQtLjQwNi4wMy0uMzQ4IDEuNTU5LjE1NGMuMDkgMCAuMTczLS4wMS4yNDgtLjAzM2EuNjAzLjYwMyAwIDAgMCAuMi0uMTA2LjUzMi41MzIgMCAwIDAgLjEzOS0uMTcyLjY2LjY2IDAgMCAwIC4wNjQtLjI0MWwuMDI5LS4zMjFhLjk0Ljk0IDAgMCAwLS4wMzYtLjI1LjU3LjU3IDAgMCAwLS4xMDMtLjIwMi41MDIuNTAyIDAgMCAwLS4xNjgtLjEzOC42MDUuNjA1IDAgMCAwLS4yNC0uMDY3TDEuMjczLjgyN2MtLjA5NC0uMDA4LS4xNjguMDEtLjIyMS4wNTUtLjA1My4wNDUtLjA4NC4xMTQtLjA5Mi4yMDZMLjcwNSA0IDAgMy45MzhsLjI1NS0yLjkxMUExLjAxIDEuMDEgMCAwIDEgLjM5My41NzIuOTYyLjk2MiAwIDAgMSAuNjY2LjI4NmEuOTcuOTcgMCAwIDEgLjMzOC0uMTRDMS4xMjIuMTIgMS4yMy4xMSAxLjMyOC4xMTlsMS41OTMuMTRjLjE2LjAxNC4zLjA0Ny40MjMuMWExLjE3IDEuMTcgMCAwIDEgLjU0NS40NDhjLjA2MS4wOTUuMTA5LjE5My4xNDQuMjk1YTEuNDA2IDEuNDA2IDAgMCAxIC4wNzcuNTgzbC0uMDI4LjMyMloiIGZpbGw9IndoaXRlIi8+CiAgPHBhdGggZD0iTTQuMDgyIDIuMDA3YTEuNDU1IDEuNDU1IDAgMCAxLS4wOTguNDI3Yy0uMDUuMTI0LS4xMTQuMjMyLS4xOTIuMzI0YTEuMTMgMS4xMyAwIDAgMS0uMjU0LjIyNyAxLjM1MyAxLjM1MyAwIDAgMS0uNTk1LjIxNGMtLjEuMDEyLS4xOTMuMDE0LS4yOC4wMDZsLTEuNTYtLjEwOC4wMzQtLjQwNi4wMy0uMzQ4IDEuNTU5LjE1NGMuMDkgMCAuMTczLS4wMS4yNDgtLjAzM2EuNjAzLjYwMyAwIDAgMCAuMi0uMTA2LjUzMi41MzIgMCAwIDAgLjEzOS0uMTcyLjY2LjY2IDAgMCAwIC4wNjQtLjI0MWwuMDI5LS4zMjFhLjk0Ljk0IDAgMCAwLS4wMzYtLjI1LjU3LjU3IDAgMCAwLS4xMDMtLjIwMi41MDIuNTAyIDAgMCAwLS4xNjgtLjEzOC42MDUuNjA1IDAgMCAwLS4yNC0uMDY3TDEuMjczLjgyN2MtLjA5NC0uMDA4LS4xNjguMDEtLjIyMS4wNTUtLjA1My4wNDUtLjA4NC4xMTQtLjA5Mi4yMDZMLjcwNSA0IDAgMy45MzhsLjI1NS0yLjkxMUExLjAxIDEuMDEgMCAwIDEgLjM5My41NzIuOTYyLjk2MiAwIDAgMSAuNjY2LjI4NmEuOTcuOTcgMCAwIDEgLjMzOC0uMTRDMS4xMjIuMTIgMS4yMy4xMSAxLjMyOC4xMTlsMS41OTMuMTRjLjE2LjAxNC4zLjA0Ny40MjMuMWExLjE3IDEuMTcgMCAwIDEgLjU0NS40NDhjLjA2MS4wOTUuMTA5LjE5My4xNDQuMjk1YTEuNDA2IDEuNDA2IDAgMCAxIC4wNzcuNTgzbC0uMDI4LjMyMloiIGZpbGw9IndoaXRlIi8+Cjwvc3ZnPgo=)](https://www.phorm.ai/query?projectId=3c9a471f-4a47-469f-81f6-4ea1ff9ab418)
|
||
|
|
||
|
[libSQL](https://github.com/libsql/libsql) is an open source, open contribution fork of SQLite.
|
||
|
This source repository contains libSQL API bindings for Node, which aims to be compatible with [better-sqlite3](https://github.com/WiseLibs/better-sqlite3/), but with opt-in promise API.
|
||
|
|
||
|
*Please note that if there is also the [libSQL SDK](https://github.com/libsql/libsql-client-ts), which is useful if you don't need `better-sqlite3` compatibility or use libSQL in environments like serverless functions that require `fetch()`-based database access protocol.*
|
||
|
|
||
|
## Features
|
||
|
|
||
|
* In-memory and local libSQL/SQLite databases
|
||
|
* Remote libSQL databases
|
||
|
* Embedded, in-app replica that syncs with a remote libSQL database
|
||
|
* Supports Bun, Deno, and Node on macOS, Linux, and Windows.
|
||
|
|
||
|
## Installing
|
||
|
|
||
|
You can install the package with:
|
||
|
|
||
|
**Node:**
|
||
|
|
||
|
```sh
|
||
|
npm i libsql
|
||
|
```
|
||
|
|
||
|
**Bun:**
|
||
|
|
||
|
```sh
|
||
|
bun add libsql
|
||
|
```
|
||
|
|
||
|
**Deno:**
|
||
|
|
||
|
Use the `npm:` prefix for package import:
|
||
|
|
||
|
```typescript
|
||
|
import Database from 'npm:libsql';
|
||
|
```
|
||
|
|
||
|
## Documentation
|
||
|
|
||
|
* [API reference](docs/api.md)
|
||
|
|
||
|
## Getting Started
|
||
|
|
||
|
To try out your first libsql program, type the following in `hello.js`:
|
||
|
|
||
|
```javascript
|
||
|
import Database from 'libsql';
|
||
|
|
||
|
const db = new Database(':memory:');
|
||
|
|
||
|
db.exec("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, email TEXT)");
|
||
|
db.exec("INSERT INTO users (id, name, email) VALUES (1, 'Alice', 'alice@example.org')");
|
||
|
|
||
|
const row = db.prepare("SELECT * FROM users WHERE id = ?").get(1);
|
||
|
|
||
|
console.log(`Name: ${row.name}, email: ${row.email}`);
|
||
|
```
|
||
|
|
||
|
and then run:
|
||
|
|
||
|
```shell
|
||
|
$ node hello.js
|
||
|
```
|
||
|
|
||
|
To use the promise API, import `libsql/promise`:
|
||
|
|
||
|
```javascript
|
||
|
import Database from 'libsql/promise';
|
||
|
|
||
|
const db = new Database(':memory:');
|
||
|
|
||
|
await db.exec("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, email TEXT)");
|
||
|
await db.exec("INSERT INTO users (id, name, email) VALUES (1, 'Alice', 'alice@example.org')");
|
||
|
|
||
|
const stmt = await db.prepare("SELECT * FROM users WHERE id = ?");
|
||
|
const row = stmt.get(1);
|
||
|
|
||
|
console.log(`Name: ${row.name}, email: ${row.email}`);
|
||
|
```
|
||
|
|
||
|
#### Connecting to a local database file
|
||
|
|
||
|
```javascript
|
||
|
import Database from 'libsql';
|
||
|
|
||
|
const db = new Database('hello.db');
|
||
|
````
|
||
|
|
||
|
#### Connecting to a Remote libSQL server
|
||
|
|
||
|
```javascript
|
||
|
import Database from 'libsql';
|
||
|
|
||
|
const url = process.env.LIBSQL_URL;
|
||
|
const authToken = process.env.LIBSQL_AUTH_TOKEN;
|
||
|
|
||
|
const opts = {
|
||
|
authToken: authToken,
|
||
|
};
|
||
|
|
||
|
const db = new Database(url, opts);
|
||
|
```
|
||
|
|
||
|
#### Creating an in-app replica and syncing it
|
||
|
|
||
|
```javascript
|
||
|
import libsql
|
||
|
|
||
|
const opts = { syncUrl: "<url>", authToken: "<optional auth token>" };
|
||
|
const db = new Database('hello.db', opts);
|
||
|
db.sync();
|
||
|
```
|
||
|
|
||
|
#### Creating a table
|
||
|
|
||
|
```javascript
|
||
|
db.exec("CREATE TABLE users (id INTEGER, email TEXT);")
|
||
|
```
|
||
|
|
||
|
#### Inserting rows into a table
|
||
|
|
||
|
```javascript
|
||
|
db.exec("INSERT INTO users VALUES (1, 'alice@example.org')")
|
||
|
```
|
||
|
|
||
|
#### Querying rows from a table
|
||
|
|
||
|
```javascript
|
||
|
const row = db.prepare("SELECT * FROM users WHERE id = ?").get(1);
|
||
|
```
|
||
|
|
||
|
## Developing
|
||
|
|
||
|
To build the `libsql` package, run:
|
||
|
|
||
|
```console
|
||
|
LIBSQL_JS_DEV=1 npm run build
|
||
|
```
|
||
|
|
||
|
You can then run the integration tests with:
|
||
|
|
||
|
```console
|
||
|
export LIBSQL_JS_DEV=1
|
||
|
npm link
|
||
|
cd integration-tests
|
||
|
npm link libsql
|
||
|
npm test
|
||
|
```
|
||
|
|
||
|
## License
|
||
|
|
||
|
This project is licensed under the [MIT license].
|
||
|
|
||
|
### Contribution
|
||
|
|
||
|
Unless you explicitly state otherwise, any contribution intentionally submitted
|
||
|
for inclusion in libSQL by you, shall be licensed as MIT, without any additional
|
||
|
terms or conditions.
|
||
|
|
||
|
[MIT license]: https://github.com/libsql/libsql-node/blob/main/LICENSE
|