@statewalker/db-duckdb-node 0.1.2 → 0.1.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +44 -11
- package/package.json +8 -4
package/README.md
CHANGED
|
@@ -1,27 +1,60 @@
|
|
|
1
1
|
# @statewalker/db-duckdb-node
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
## What it is
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
A DuckDB driver for Node.js that implements `Db` from `@statewalker/db-api`.
|
|
6
|
+
It uses the native bindings from `@duckdb/node-api` and opens a DuckDB file or
|
|
7
|
+
an in-memory database.
|
|
8
|
+
|
|
9
|
+
## Why it exists
|
|
10
|
+
|
|
11
|
+
It lets code written against `Db` run on DuckDB in Node.js: servers, CLIs,
|
|
12
|
+
build scripts and tests. The same code runs in the browser on
|
|
13
|
+
`@statewalker/db-duckdb-browser`.
|
|
14
|
+
|
|
15
|
+
## How to use
|
|
6
16
|
|
|
7
17
|
```sh
|
|
8
18
|
pnpm add @statewalker/db-duckdb-node
|
|
9
19
|
```
|
|
10
20
|
|
|
11
|
-
|
|
21
|
+
`@duckdb/node-api` installs a prebuilt native binary for your platform.
|
|
22
|
+
|
|
23
|
+
| Import | Gives | Environment |
|
|
24
|
+
| --- | --- | --- |
|
|
25
|
+
| `@statewalker/db-duckdb-node` | `newNodeDuckDb`; types `Db`, `DbEntry`, `DbOptions` re-exported from `@statewalker/db-api` | Node.js |
|
|
26
|
+
|
|
27
|
+
`newNodeDuckDb(options?)` returns `Promise<Db>`. It opens `options.path`, or
|
|
28
|
+
`:memory:` without a path. The `Db` implements `query`, `exec` and `close`; it
|
|
29
|
+
has no `flush`.
|
|
30
|
+
|
|
31
|
+
## Examples
|
|
12
32
|
|
|
13
33
|
```ts
|
|
14
|
-
import {
|
|
34
|
+
import { newNodeDuckDb } from "@statewalker/db-duckdb-node";
|
|
15
35
|
|
|
16
|
-
const db = await
|
|
17
|
-
await db.
|
|
36
|
+
const db = await newNodeDuckDb({ path: "./data.duckdb" });
|
|
37
|
+
await db.exec("CREATE TABLE IF NOT EXISTS t (x INTEGER)");
|
|
38
|
+
await db.exec("INSERT INTO t VALUES (1), (2)");
|
|
39
|
+
const rows = await db.query<{ x: number }>("SELECT x FROM t WHERE x > $1", [1]);
|
|
40
|
+
await db.close();
|
|
18
41
|
```
|
|
19
42
|
|
|
20
|
-
##
|
|
43
|
+
## Internals
|
|
21
44
|
|
|
22
|
-
-
|
|
45
|
+
- **One instance, one connection.** The factory creates a `DuckDBInstance`
|
|
46
|
+
and a single connection; `close()` closes both synchronously.
|
|
47
|
+
- **Parameters.** With parameters, `query` prepares the statement, binds the
|
|
48
|
+
array and runs it. Both `$1` and `?` placeholders work.
|
|
49
|
+
- **Rows are plain JS objects** (`getRowObjectsJS()`). DuckDB `BIGINT` values,
|
|
50
|
+
including `count(*)`, come back as `bigint`, not `number`.
|
|
51
|
+
- **Errors are DuckDB's.** A bad path rejects with
|
|
52
|
+
`IO Error: Cannot open file "...": No such file or directory`. Bad SQL rejects
|
|
53
|
+
with `Parser Error: ...`. A call after `close()` rejects with
|
|
54
|
+
`Failed to query: connection disconnected`.
|
|
55
|
+
- **Dependencies:** `@duckdb/node-api` (the engine), `@statewalker/db-api`
|
|
56
|
+
(the interface types).
|
|
23
57
|
|
|
24
|
-
##
|
|
58
|
+
## License
|
|
25
59
|
|
|
26
|
-
|
|
27
|
-
- `@statewalker/db-duckdb-browser` — Browser-side counterpart.
|
|
60
|
+
MIT
|
package/package.json
CHANGED
|
@@ -1,10 +1,13 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@statewalker/db-duckdb-node",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.4",
|
|
4
4
|
"private": false,
|
|
5
5
|
"type": "module",
|
|
6
6
|
"description": "DuckDB Node.js driver for @statewalker/db-api using @duckdb/node-api.",
|
|
7
|
-
"
|
|
7
|
+
"bugs": {
|
|
8
|
+
"url": "https://github.com/statewalker/statewalker-db/issues"
|
|
9
|
+
},
|
|
10
|
+
"homepage": "https://github.com/statewalker/statewalker-db/tree/main/packages/db-duckdb-node#readme",
|
|
8
11
|
"author": {
|
|
9
12
|
"name": "Mikhail Kotelnikov",
|
|
10
13
|
"email": "mikhail.kotelnikov@gmail.com"
|
|
@@ -12,7 +15,8 @@
|
|
|
12
15
|
"license": "MIT",
|
|
13
16
|
"repository": {
|
|
14
17
|
"type": "git",
|
|
15
|
-
"url": "git+
|
|
18
|
+
"url": "git+https://github.com/statewalker/statewalker-db.git",
|
|
19
|
+
"directory": "packages/db-duckdb-node"
|
|
16
20
|
},
|
|
17
21
|
"exports": {
|
|
18
22
|
".": {
|
|
@@ -27,7 +31,7 @@
|
|
|
27
31
|
],
|
|
28
32
|
"dependencies": {
|
|
29
33
|
"@duckdb/node-api": "^1.5.5-r.4",
|
|
30
|
-
"@statewalker/db-api": "^0.1.
|
|
34
|
+
"@statewalker/db-api": "^0.1.4"
|
|
31
35
|
},
|
|
32
36
|
"devDependencies": {
|
|
33
37
|
"@types/node": "^26.6.4",
|