Folders and files

Name		Name	Last commit message	Last commit date
Latest commit History 570 Commits
.cargo		.cargo
.github/workflows		.github/workflows
docs		docs
examples		examples
integration-tests		integration-tests
npm		npm
perf		perf
scripts		scripts
src		src
.gitignore		.gitignore
.npmignore		.npmignore
Cargo.toml		Cargo.toml
LICENSE		LICENSE
README.md		README.md
auth.js		auth.js
build.rs		build.rs
compat.js		compat.js
index.d.ts		index.d.ts
index.js		index.js
package-lock.json		package-lock.json
package.json		package.json
promise.js		promise.js
rust-toolchain.toml		rust-toolchain.toml
sqlite-error.js		sqlite-error.js
tsconfig.json		tsconfig.json
yarn.lock		yarn.lock

Repository files navigation

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 withbetter-sqlite3, but with opt-in promise API.

Please note that there is also thelibSQL SDK, which is useful if you don't needbetter-sqlite3 compatibility or use libSQL in environments like serverless functions that requirefetch()-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 thenpm: prefix for package import:

importDatabasefrom'npm:libsql';

Documentation

API reference

Getting Started

To try out your first libsql program, type the following inhello.js:

importDatabasefrom'libsql';constdb=newDatabase(':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')");constrow=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, importlibsql/promise:

importDatabasefrom'libsql/promise';constdb=newDatabase(':memory:');awaitdb.exec("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, email TEXT)");awaitdb.exec("INSERT INTO users (id, name, email) VALUES (1, 'Alice', 'alice@example.org')");conststmt=awaitdb.prepare("SELECT * FROM users WHERE id = ?");constrow=stmt.get(1);console.log(`Name:${row.name}, email:${row.email}`);

Connecting to a local database file

importDatabasefrom'libsql';constdb=newDatabase('hello.db');

Connecting to a Remote libSQL server

importDatabasefrom'libsql';consturl=process.env.LIBSQL_URL;constauthToken=process.env.LIBSQL_AUTH_TOKEN;constopts={authToken:authToken,};constdb=newDatabase(url,opts);

Creating an in-app replica and syncing it

importlibsqlconstopts={syncUrl:"<url>",authToken:"<optional auth token>"};constdb=newDatabase('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

constrow=db.prepare("SELECT * FROM users WHERE id = ?").get(1);

Developing

To build thelibsql package, run:

LIBSQL_JS_DEV=1 npm run build

You can then run the integration tests with:

export LIBSQL_JS_DEV=1npm linkcd integration-testsnpm link libsqlnpm test

License

This project is licensed under theMIT license.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submittedfor inclusion in libSQL by you, shall be licensed as MIT, without any additionalterms or conditions.