6.7 KiB
libSQL API for JavaScript/TypeScript
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, but with opt-in promise API.
Please note that if there is also the libSQL SDK, 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:
npm i libsql
Bun:
bun add libsql
Deno:
Use the npm:
prefix for package import:
import Database from 'npm:libsql';
Documentation
Getting Started
To try out your first libsql program, type the following in hello.js
:
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:
$ node hello.js
To use the promise API, import libsql/promise
:
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
import Database from 'libsql';
const db = new Database('hello.db');
Connecting to a Remote libSQL server
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
import libsql
const opts = { syncUrl: "<url>", authToken: "<optional auth token>" };
const db = new Database('hello.db', opts);
db.sync();
Creating a table
db.exec("CREATE TABLE users (id INTEGER, email TEXT);")
Inserting rows into a table
db.exec("INSERT INTO users VALUES (1, 'alice@example.org')")
Querying rows from a table
const row = db.prepare("SELECT * FROM users WHERE id = ?").get(1);
Developing
To build the libsql
package, run:
LIBSQL_JS_DEV=1 npm run build
You can then run the integration tests with:
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.