aljaz/turso
1
0
Fork 0
mirror of https://github.com/aljazceru/turso.git synced 2025-12-25 12:04:21 +01:00
Code Issues Packages Projects Releases Wiki Activity

Merge 'Unify JavaScript package README files' from Pekka Enberg

Browse Source 
Reviewed-by: Nikita Sivukhin (@sivukhin)

Closes #2563
This commit is contained in:
Pekka Enberg
2025-08-12 19:51:32 +03:00
committed by GitHub
parent 0285fddd85 475799b3e9
commit 3dd58e98e7
3 changed files with 142 additions and 34 deletions
Download Patch File Download Diff File Expand all files Collapse all files

79
bindings/javascript/README.md
View File

@@ -1,16 +1,29 @@
# @tursodatabase/database
<p align="center">
<h1 align="center">Turso Database for JavaScript</h1>
</p>
The next evolution of SQLite: A high-performance, SQLite-compatible database library for Node.js
<p align="center">
<a title="JavaScript" target="_blank" href="https://www.npmjs.com/package/@tursodatabase/database"><img alt="npm" src="https://img.shields.io/npm/v/@tursodatabase/database"></a>
<a title="MIT" target="_blank" href="https://github.com/tursodatabase/turso/blob/main/LICENSE.md"><img src="http://img.shields.io/badge/license-MIT-orange.svg?style=flat-square"></a>
</p>
<p align="center">
<a title="Users Discord" target="_blank" href="https://tur.so/discord"><img alt="Chat with other users of Turso on Discord" src="https://img.shields.io/discord/933071162680958986?label=Discord&logo=Discord&style=social"></a>
</p>
---
## About
This package is the Turso in-memory database library for JavaScript.
> **⚠️ Warning:** This software is ALPHA, only use for development, testing, and experimentation. We are working to make it production ready, but do not use it for critical data right now.
## Features
- **SQLite Compatible**: Drop-in replacement for better-sqlite3 with familiar API
- **High Performance**: Built with Rust for maximum speed and efficiency
- **In-Process**: No network overhead, runs directly in your Node.js process
- **TypeScript Support**: Full TypeScript definitions included
- **Cross-Platform**: Supports Linux, macOS, Windows and browsers (through WebAssembly)
- **Transaction Support**: Full ACID transactions with rollback support
- **Prepared Statements**: Optimized query execution with parameter binding
- **SQLite compatible:** SQLite query language and file format support ([status](https://github.com/tursodatabase/turso/blob/main/COMPAT.md)).
- **In-process**: No network overhead, runs directly in your Node.js process
- **TypeScript support**: Full TypeScript definitions included
- **Cross-platform**: Supports Linux, macOS, Windows and browsers (through WebAssembly)
## Installation
@@ -18,15 +31,15 @@ The next evolution of SQLite: A high-performance, SQLite-compatible database lib
npm install @tursodatabase/database
```
## Quick Start
## Getting Started
### In-Memory Database
```javascript
import Database from '@tursodatabase/database';
import { connect } from '@tursodatabase/database';
// Create an in-memory database
const db = new Database(':memory:');
const db = await connect(':memory:');
// Create a table
db.exec('CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, email TEXT)');
@@ -48,10 +61,10 @@ console.log(users);
### File-Based Database
```javascript
import Database from '@tursodatabase/database';
import { connect } from '@tursodatabase/database';
// Create or open a database file
const db = new Database('my-database.db');
const db = await connect('my-database.db');
// Create a table
db.exec(`
@@ -70,13 +83,47 @@ const result = insertPost.run('Hello World', 'This is my first blog post!');
console.log(`Inserted post with ID: ${result.lastInsertRowid}`);
```
### Transactions
```javascript
import { connect } from '@tursodatabase/database';
const db = await connect('transactions.db');
// Using transactions for atomic operations
const transaction = db.transaction((users) => {
const insert = db.prepare('INSERT INTO users (name, email) VALUES (?, ?)');
for (const user of users) {
insert.run(user.name, user.email);
}
});
// Execute transaction
transaction([
{ name: 'Alice', email: 'alice@example.com' },
{ name: 'Bob', email: 'bob@example.com' }
]);
```
### WebAssembly Support
Turso Database can run in browsers using WebAssembly. Check the `browser.js` and WASM artifacts for browser usage.
## API Reference
For complete API documentation, see [JavaScript API Reference](../../docs/javascript-api-reference.md).
## Related Packages
* The [@tursodatabase/serverless](https://www.npmjs.com/package/@tursodatabase/serverless) package provides a serverless driver with the same API.
* The [@tursodatabase/sync](https://www.npmjs.com/package/@tursodatabase/sync) package provides bidirectional sync between a local Turso database and Turso Cloud.
## License
MIT
This project is licensed under the [MIT license](../../LICENSE.md).
## Support
- [GitHub Issues](https://github.com/tursodatabase/turso/issues)
- [Documentation](https://docs.turso.tech)
- [Discord Community](https://discord.gg/turso)
- [Discord Community](https://tur.so/discord)

48
packages/turso-serverless/README.md
View File

@@ -1,9 +1,22 @@
# Turso serverless JavaScript driver
<p align="center">
<h1 align="center">Turso Serverless Driver for JavaScript</h1>
</p>
<p align="center">
<a title="JavaScript" target="_blank" href="https://www.npmjs.com/package/@tursodatabase/serverless"><img alt="npm" src="https://img.shields.io/npm/v/@tursodatabase/serverless"></a>
<a title="MIT" target="_blank" href="https://github.com/tursodatabase/turso/blob/main/LICENSE.md"><img src="http://img.shields.io/badge/license-MIT-orange.svg?style=flat-square"></a>
</p>
<p align="center">
<a title="Users Discord" target="_blank" href="https://tur.so/discord"><img alt="Chat with other users of Turso on Discord" src="https://img.shields.io/discord/933071162680958986?label=Discord&logo=Discord&style=social"></a>
</p>
---
## About
A serverless database driver for Turso Cloud, using only `fetch()`. Connect to your database from serverless and edge functions, such as Cloudflare Workers and Vercel.
> [!NOTE]
> This driver is experimental and, therefore, subject to change at any time.
> **📝 Note:** This driver is experimental and, therefore, subject to change at any time.
## Installation
@@ -11,7 +24,9 @@ A serverless database driver for Turso Cloud, using only `fetch()`. Connect to y
npm install @tursodatabase/serverless
```
## Usage
## Getting Started
### Basic Usage
```javascript
import { connect } from "@tursodatabase/serverless";
@@ -36,7 +51,11 @@ console.log(rows);
for await (const row of stmt.iterate([123])) {
console.log(row);
}
```
### Batch Operations
```javascript
// Execute multiple statements in a batch
await conn.batch([
"CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, email TEXT)",
@@ -45,9 +64,9 @@ await conn.batch([
]);
```
### Compatibility layer for libSQL API
### libSQL Compatibility Layer
This driver supports the libSQL API as a compatibility layer.
For existing libSQL applications, use the compatibility layer:
```javascript
import { createClient } from "@tursodatabase/serverless/compat";
@@ -73,6 +92,21 @@ await client.batch([
Check out the `examples/` directory for complete usage examples.
## API Reference
For complete API documentation, see [JavaScript API Reference](../../docs/javascript-api-reference.md).
## Related Packages
* The [@tursodatabase/database](https://www.npmjs.com/package/@tursodatabase/database) package provides the Turso in-memory database, compatible with SQLite.
* The [@tursodatabase/sync](https://www.npmjs.com/package/@tursodatabase/sync) package provides bidirectional sync between a local Turso database and Turso Cloud.
## License
MIT
This project is licensed under the [MIT license](../../LICENSE.md).
## Support
- [GitHub Issues](https://github.com/tursodatabase/turso/issues)
- [Documentation](https://docs.turso.tech)
- [Discord Community](https://tur.so/discord)

49
packages/turso-sync-js/README.md
View File

@@ -1,20 +1,32 @@
# turso-sync-js package
<p align="center">
<h1 align="center">Turso Sync for JavaScript</h1>
</p>
> [!WARNING]
> **`@tursodatabase/sync`** is in a **very experimental** stage.
> It may cause **data corruption** in **both local and remote databases**.
>
> We are actively working to make it a **production-grade** package, but **it is not safe for critical data yet**.
<p align="center">
<a title="JavaScript" target="_blank" href="https://www.npmjs.com/package/@tursodatabase/sync"><img alt="npm" src="https://img.shields.io/npm/v/@tursodatabase/sync"></a>
<a title="MIT" target="_blank" href="https://github.com/tursodatabase/turso/blob/main/LICENSE.md"><img src="http://img.shields.io/badge/license-MIT-orange.svg?style=flat-square"></a>
</p>
<p align="center">
<a title="Users Discord" target="_blank" href="https://tur.so/discord"><img alt="Chat with other users of Turso on Discord" src="https://img.shields.io/discord/933071162680958986?label=Discord&logo=Discord&style=social"></a>
</p>
## Usage
---
[![npm version](https://img.shields.io/npm/v/@tursodatabase/sync)](https://www.npmjs.com/package/@tursodatabase/sync)
## About
```
npm i @tursodatabase/sync
This package is for syncing local Turso databases to the Turso Cloud and back.
> **⚠️ Warning:** This software is ALPHA, only use for development, testing, and experimentation. We are working to make it production ready, but do not use it for critical data right now.
## Installation
```bash
npm install @tursodatabase/sync
```
Example usage with remote DB hosting at [Turso Cloud](https://turso.tech)
## Getting Started
To sync a database hosted at [Turso Cloud](https://turso.tech):
```js
import { connect } from '@tursodatabase/sync';
@@ -31,3 +43,18 @@ await db.pull(); // pull changes from the remote
await db.push(); // push changes to the remote
await db.sync(); // pull & push changes
```
## Related Packages
* The [@tursodatabase/database](https://www.npmjs.com/package/@tursodatabase/database) package provides the Turso in-memory database, compatible with SQLite.
* The [@tursodatabase/serverless](https://www.npmjs.com/package/@tursodatabase/serverless) package provides a serverless driver with the same API.
## License
This project is licensed under the [MIT license](../../LICENSE.md).
## Support
- [GitHub Issues](https://github.com/tursodatabase/turso/issues)
- [Documentation](https://docs.turso.tech)
- [Discord Community](https://tur.so/discord)