Fixes #97: SQLite is now async, optimized, tests

2022-10-21 10:00:43 +02:00
parent b9da9b7965
commit c1a78e0105
65 changed files with 329 additions and 142 deletions
@@ -0,0 +1,107 @@
+# Deno SQLite Module
+
+[![test status](https://github.com/dyedgreen/deno-sqlite/workflows/tests/badge.svg?branch=master)](https://github.com/dyedgreen/deno-sqlite/actions)
+[![deno doc](https://doc.deno.land/badge.svg)](https://deno.land/x/sqlite/mod.ts)
+
+This is an SQLite module for JavaScript and TypeScript. The wrapper is targeted
+at [Deno](https://deno.land) and uses a version of SQLite3 compiled to
+WebAssembly (WASM). This module focuses on correctness, ease of use and
+performance.
+
+This module guarantees API compatibility according to
+[semantic versioning](https://semver.org). Please report any issues you
+encounter. Note that the `master` branch might contain new or breaking features.
+The versioning guarantee applies only to
+[tagged releases](https://github.com/dyedgreen/deno-sqlite/releases).
+
+## Documentation
+
+Documentation is available [Deno Docs](https://deno.land/x/sqlite). There is
+also a list of examples in the [`examples`](./examples) folder.
+
+## Example
+
+```javascript
+import { DB } from "https://deno.land/x/sqlite/mod.ts";
+
+// Open a database
+const db = new DB("test.db");
+db.execute(`
+  CREATE TABLE IF NOT EXISTS people (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    name TEXT
+  )
+`);
+
+const names = ["Peter Parker", "Clark Kent", "Bruce Wayne"];
+
+// Run a simple query
+for (const name of names) {
+  db.query("INSERT INTO people (name) VALUES (?)", [name]);
+}
+
+// Print out data in table
+for (const [name] of db.query("SELECT name FROM people")) {
+  console.log(name);
+}
+
+// Close connection
+db.close();
+```
+
+## Comparison to Plugin based Modules
+
+### TL;DR
+
+If you want something that just works (and is fast), use this library.
+
+Depending on your specific needs, there is also
+[sqlite3](https://github.com/denodrivers/sqlite3), however using this module
+requires the `--allow-ffi` and `--unstable` flags, which means the database
+connection may bypass e.g. file access permissions.
+
+### Advantages
+
+- Security: benefit from Denos security settings, without the need to trust a
+  third party
+- Portability: runs everywhere Deno runs and can even run in the browser
+- Ease of Use: takes full advantage of Denos module cache and does not require
+  any network access after initial download
+- Speed: thanks to WASM, the database performance is comparable to native
+  bindings in most situations and the API is carefully designed to provide
+  optimal performance
+
+### Disadvantages
+
+- Weaker Persistence Guarantees: due to limitations in Denos file system APIs,
+  SQLite can't acquire file locks or memory map files (e.g. this module does not
+  support WAL mode)
+
+## Browser Version (Experimental)
+
+There is **experimental** support for using `deno-sqlite` in the browser. You
+can generate a browser compatible module by running:
+
+```bash
+deno bundle --import-map browser/import_map.json browser/mod.ts [output_bundle_path]
+```
+
+The modules documentation can be seen by running
+
+```bash
+deno doc browser/mod.ts
+```
+
+Databases created in the browser are persisted using
+[indexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API).
+
+## Users
+
+- [cotton](https://github.com/rahmanfadhil/cotton)
+- [deno-nessie](https://github.com/halvardssm/deno-nessie)
+- [denodb](https://github.com/eveningkid/denodb)
+- [denolib/typeorm](https://github.com/denolib/typeorm)
+- [small-orm-sqlite](https://github.com/enimatek-nl/small-orm-sqlite)
+
+_(listed in alphabetical order, please submit a PR if you are using this library
+and are not included)_