Spaces:
Sleeping
Sleeping
File size: 7,415 Bytes
2bdf3d7 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 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 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 | # libSQL API for JavaScript/TypeScript
[](https://badge.fury.io/js/libsql)
[](https://www.phorm.ai/query?projectId=3c9a471f-4a47-469f-81f6-4ea1ff9ab418)
> [!IMPORTANT]
> **Turso database and libSQL are two different projects from the same team.**
>
> **libSQL** (this repository) is an open-source fork of SQLite. It extends SQLite with features like embedded replicas and remote access, but inherits SQLite's fundamental limitations such as the single-writer model.
>
> **[Turso database](https://github.com/tursodatabase/turso)** is a SQLite-compatible database rewritten from scratch in Rust. It is **not** a fork of SQLite — it is a completely new implementation that goes beyond what any SQLite fork can offer, including concurrent writes and bi-directional sync with offline support. Turso is currently in beta.
>
> **If you're starting a new project, you probably want to look into [Turso](https://github.com/tursodatabase/turso).** libSQL is actively maintained, but new features are being developed in Turso.
[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.
## 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
|