|
| 1 | +Typed Dart bindings for [sql.js](https://github.com/sql-js/sql.js) — SQLite |
| 2 | +compiled to WebAssembly. Provides synchronous, in-memory SQLite for Node.js |
| 3 | +applications, with explicit persistence to disk. |
| 4 | + |
| 5 | +Unlike native bindings, sql.js needs no compilation and runs the same |
| 6 | +everywhere WebAssembly does. The database lives in memory; you persist it to a |
| 7 | +file with `save` or `close`. |
| 8 | + |
| 9 | +## Installation |
| 10 | + |
| 11 | +```yaml |
| 12 | +dependencies: |
| 13 | + dart_node_sql_js: ^0.13.0-beta |
| 14 | + nadz: ^0.0.7-beta |
| 15 | +``` |
| 16 | +
|
| 17 | +Also install the npm package: |
| 18 | +
|
| 19 | +```bash |
| 20 | +npm install sql.js |
| 21 | +``` |
| 22 | + |
| 23 | +## Quick Start |
| 24 | + |
| 25 | +```dart |
| 26 | +import 'package:dart_node_sql_js/dart_node_sql_js.dart'; |
| 27 | +import 'package:nadz/nadz.dart'; |
| 28 | +
|
| 29 | +Future<void> main() async { |
| 30 | + // Initialize the WebAssembly runtime once at startup. |
| 31 | + final runtime = switch (await initializeSqlJs()) { |
| 32 | + Success(:final value) => value, |
| 33 | + Error(:final error) => throw Exception(error), |
| 34 | + }; |
| 35 | +
|
| 36 | + // Opens ./my.db if it exists, otherwise creates a new database. |
| 37 | + final db = switch (openDatabase('./my.db', sqlJs: runtime)) { |
| 38 | + Success(:final value) => value, |
| 39 | + Error(:final error) => throw Exception(error), |
| 40 | + }; |
| 41 | +
|
| 42 | + db.exec('CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)'); |
| 43 | +
|
| 44 | + final insert = switch (db.prepare('INSERT INTO users (name) VALUES (?)')) { |
| 45 | + Success(:final value) => value, |
| 46 | + Error(:final error) => throw Exception(error), |
| 47 | + }; |
| 48 | + insert.run(['Alice']); |
| 49 | +
|
| 50 | + final query = switch (db.prepare('SELECT * FROM users')) { |
| 51 | + Success(:final value) => value, |
| 52 | + Error(:final error) => throw Exception(error), |
| 53 | + }; |
| 54 | + final rows = switch (query.all()) { |
| 55 | + Success(:final value) => value, |
| 56 | + Error(:final error) => throw Exception(error), |
| 57 | + }; |
| 58 | + print(rows); // [{id: 1, name: Alice}] |
| 59 | +
|
| 60 | + // Persist the in-memory database to ./my.db. |
| 61 | + db.close(); |
| 62 | +} |
| 63 | +``` |
| 64 | + |
| 65 | +## Persistence |
| 66 | + |
| 67 | +sql.js is entirely in-memory. The only way to serialize it (`export()`) frees |
| 68 | +every live prepared statement, so this binding does **not** write to disk after |
| 69 | +each statement. Instead: |
| 70 | + |
| 71 | +- `db.save()` flushes the current state to the backing file on demand. |
| 72 | +- `db.close()` saves and then releases the database. |
| 73 | + |
| 74 | +Reopening the same path loads the persisted bytes. |
| 75 | + |
| 76 | +## API |
| 77 | + |
| 78 | +`initializeSqlJs()` returns a `Future<Result<SqlJsRuntime, String>>`. Pass the |
| 79 | +runtime to every `openDatabase` call. |
| 80 | + |
| 81 | +`openDatabase(path, sqlJs: runtime)` returns a `Result<Database, String>` with: |
| 82 | + |
| 83 | +| Member | Description | |
| 84 | +|--------|-------------| |
| 85 | +| `prepare(sql)` | Prepare a reusable statement. | |
| 86 | +| `exec(sql)` | Run one or more statements, ignoring results. | |
| 87 | +| `pragma(value)` | Run a `PRAGMA`. | |
| 88 | +| `save()` | Persist the in-memory database to its file. | |
| 89 | +| `close()` | Persist, then close. | |
| 90 | +| `isOpen()` | Whether the database is still open. | |
| 91 | + |
| 92 | +A prepared `Statement` exposes: |
| 93 | + |
| 94 | +| Member | Description | |
| 95 | +|--------|-------------| |
| 96 | +| `all([params])` | All rows as a list of column-keyed maps. | |
| 97 | +| `get([params])` | The first row, or null. | |
| 98 | +| `run([params])` | Execute, returning `changes` and `lastInsertRowid`. | |
| 99 | + |
| 100 | +Every operation returns a `Result` (from [nadz](https://pub.dev/packages/nadz)) |
| 101 | +instead of throwing. |
| 102 | + |
| 103 | +## License |
| 104 | + |
| 105 | +BSD 3-Clause. See [LICENSE](LICENSE). |
0 commit comments