bun-types 1.2.21-canary.20250818T140818 → 1.2.21-canary.20250820T140622
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/bun.d.ts +87 -718
- package/deprecated.d.ts +31 -0
- package/docs/api/fetch.md +1 -1
- package/docs/api/spawn.md +1 -1
- package/docs/api/sql.md +348 -21
- package/docs/cli/pm.md +1 -1
- package/docs/cli/publish.md +1 -1
- package/docs/guides/ecosystem/nuxt.md +1 -1
- package/docs/guides/install/add-peer.md +2 -2
- package/docs/guides/install/from-npm-install-to-bun-install.md +1 -1
- package/docs/guides/test/run-tests.md +3 -3
- package/docs/guides/test/snapshot.md +3 -3
- package/docs/guides/test/update-snapshots.md +1 -1
- package/docs/guides/util/version.md +1 -1
- package/docs/installation.md +4 -4
- package/docs/runtime/debugger.md +3 -3
- package/docs/test/dom.md +1 -1
- package/index.d.ts +1 -0
- package/overrides.d.ts +6 -0
- package/package.json +1 -1
- package/sql.d.ts +805 -0
- package/sqlite.d.ts +104 -86
package/deprecated.d.ts
CHANGED
|
@@ -1,4 +1,35 @@
|
|
|
1
1
|
declare module "bun" {
|
|
2
|
+
/** @deprecated This type is unused in Bun's types and might be removed in the near future */
|
|
3
|
+
type Platform =
|
|
4
|
+
| "aix"
|
|
5
|
+
| "android"
|
|
6
|
+
| "darwin"
|
|
7
|
+
| "freebsd"
|
|
8
|
+
| "haiku"
|
|
9
|
+
| "linux"
|
|
10
|
+
| "openbsd"
|
|
11
|
+
| "sunos"
|
|
12
|
+
| "win32"
|
|
13
|
+
| "cygwin"
|
|
14
|
+
| "netbsd";
|
|
15
|
+
|
|
16
|
+
/** @deprecated This type is unused in Bun's types and might be removed in the near future */
|
|
17
|
+
type Architecture = "arm" | "arm64" | "ia32" | "mips" | "mipsel" | "ppc" | "ppc64" | "s390" | "s390x" | "x64";
|
|
18
|
+
|
|
19
|
+
/** @deprecated This type is unused in Bun's types and might be removed in the near future */
|
|
20
|
+
type UncaughtExceptionListener = (error: Error, origin: UncaughtExceptionOrigin) => void;
|
|
21
|
+
|
|
22
|
+
/**
|
|
23
|
+
* Most of the time the unhandledRejection will be an Error, but this should not be relied upon
|
|
24
|
+
* as *anything* can be thrown/rejected, it is therefore unsafe to assume that the value is an Error.
|
|
25
|
+
*
|
|
26
|
+
* @deprecated This type is unused in Bun's types and might be removed in the near future
|
|
27
|
+
*/
|
|
28
|
+
type UnhandledRejectionListener = (reason: unknown, promise: Promise<unknown>) => void;
|
|
29
|
+
|
|
30
|
+
/** @deprecated This type is unused in Bun's types and might be removed in the near future */
|
|
31
|
+
type MultipleResolveListener = (type: MultipleResolveType, promise: Promise<unknown>, value: unknown) => void;
|
|
32
|
+
|
|
2
33
|
/**
|
|
3
34
|
* Consume all data from a {@link ReadableStream} until it closes or errors.
|
|
4
35
|
*
|
package/docs/api/fetch.md
CHANGED
|
@@ -336,7 +336,7 @@ This will print the request and response headers to your terminal:
|
|
|
336
336
|
```sh
|
|
337
337
|
[fetch] > HTTP/1.1 GET http://example.com/
|
|
338
338
|
[fetch] > Connection: keep-alive
|
|
339
|
-
[fetch] > User-Agent: Bun/1.2.21-canary.
|
|
339
|
+
[fetch] > User-Agent: Bun/1.2.21-canary.20250820T140622
|
|
340
340
|
[fetch] > Accept: */*
|
|
341
341
|
[fetch] > Host: example.com
|
|
342
342
|
[fetch] > Accept-Encoding: gzip, deflate, br
|
package/docs/api/spawn.md
CHANGED
|
@@ -140,7 +140,7 @@ You can read results from the subprocess via the `stdout` and `stderr` propertie
|
|
|
140
140
|
```ts
|
|
141
141
|
const proc = Bun.spawn(["bun", "--version"]);
|
|
142
142
|
const text = await proc.stdout.text();
|
|
143
|
-
console.log(text); // => "1.2.21-canary.
|
|
143
|
+
console.log(text); // => "1.2.21-canary.20250820T140622\n"
|
|
144
144
|
```
|
|
145
145
|
|
|
146
146
|
Configure the output stream by passing one of the following values to `stdout/stderr`:
|
package/docs/api/sql.md
CHANGED
|
@@ -1,20 +1,20 @@
|
|
|
1
|
-
Bun provides native bindings for working with
|
|
1
|
+
Bun provides native bindings for working with SQL databases through a unified Promise-based API that supports both PostgreSQL and SQLite. The interface is designed to be simple and performant, using tagged template literals for queries and offering features like connection pooling, transactions, and prepared statements.
|
|
2
2
|
|
|
3
3
|
```ts
|
|
4
|
-
import { sql } from "bun";
|
|
4
|
+
import { sql, SQL } from "bun";
|
|
5
5
|
|
|
6
|
+
// PostgreSQL (default)
|
|
6
7
|
const users = await sql`
|
|
7
8
|
SELECT * FROM users
|
|
8
9
|
WHERE active = ${true}
|
|
9
10
|
LIMIT ${10}
|
|
10
11
|
`;
|
|
11
12
|
|
|
12
|
-
//
|
|
13
|
-
const
|
|
14
|
-
|
|
15
|
-
FROM users
|
|
16
|
-
WHERE active = ${
|
|
17
|
-
AND age >= ${18}
|
|
13
|
+
// With a a SQLite db
|
|
14
|
+
const sqlite = new SQL("sqlite://myapp.db");
|
|
15
|
+
const results = await sqlite`
|
|
16
|
+
SELECT * FROM users
|
|
17
|
+
WHERE active = ${1}
|
|
18
18
|
`;
|
|
19
19
|
```
|
|
20
20
|
|
|
@@ -44,6 +44,115 @@ const activeUsers = await sql`
|
|
|
44
44
|
|
|
45
45
|
{% /features %}
|
|
46
46
|
|
|
47
|
+
## Database Support
|
|
48
|
+
|
|
49
|
+
Bun.SQL provides a unified API for multiple database systems:
|
|
50
|
+
|
|
51
|
+
### PostgreSQL
|
|
52
|
+
|
|
53
|
+
PostgreSQL is used when:
|
|
54
|
+
|
|
55
|
+
- The connection string doesn't match SQLite patterns (it's the fallback adapter)
|
|
56
|
+
- The connection string explicitly uses `postgres://` or `postgresql://` protocols
|
|
57
|
+
- No connection string is provided and environment variables point to PostgreSQL
|
|
58
|
+
|
|
59
|
+
```ts
|
|
60
|
+
import { sql } from "bun";
|
|
61
|
+
// Uses PostgreSQL if DATABASE_URL is not set or is a PostgreSQL URL
|
|
62
|
+
await sql`SELECT ...`;
|
|
63
|
+
|
|
64
|
+
import { SQL } from "bun";
|
|
65
|
+
const pg = new SQL("postgres://user:pass@localhost:5432/mydb");
|
|
66
|
+
await pg`SELECT ...`;
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
### SQLite
|
|
70
|
+
|
|
71
|
+
SQLite support is now built into Bun.SQL, providing the same tagged template literal interface as PostgreSQL:
|
|
72
|
+
|
|
73
|
+
```ts
|
|
74
|
+
import { SQL } from "bun";
|
|
75
|
+
|
|
76
|
+
// In-memory database
|
|
77
|
+
const memory = new SQL(":memory:");
|
|
78
|
+
const memory2 = new SQL("sqlite://:memory:");
|
|
79
|
+
|
|
80
|
+
// File-based database
|
|
81
|
+
const db = new SQL("sqlite://myapp.db");
|
|
82
|
+
|
|
83
|
+
// Using options object
|
|
84
|
+
const db2 = new SQL({
|
|
85
|
+
adapter: "sqlite",
|
|
86
|
+
filename: "./data/app.db",
|
|
87
|
+
});
|
|
88
|
+
|
|
89
|
+
// For simple filenames, specify adapter explicitly
|
|
90
|
+
const db3 = new SQL("myapp.db", { adapter: "sqlite" });
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
<details>
|
|
94
|
+
<summary>SQLite Connection String Formats</summary>
|
|
95
|
+
|
|
96
|
+
SQLite accepts various URL formats for connection strings:
|
|
97
|
+
|
|
98
|
+
```ts
|
|
99
|
+
// Standard sqlite:// protocol
|
|
100
|
+
new SQL("sqlite://path/to/database.db");
|
|
101
|
+
new SQL("sqlite:path/to/database.db"); // Without slashes
|
|
102
|
+
|
|
103
|
+
// file:// protocol (also recognized as SQLite)
|
|
104
|
+
new SQL("file://path/to/database.db");
|
|
105
|
+
new SQL("file:path/to/database.db");
|
|
106
|
+
|
|
107
|
+
// Special :memory: database
|
|
108
|
+
new SQL(":memory:");
|
|
109
|
+
new SQL("sqlite://:memory:");
|
|
110
|
+
new SQL("file://:memory:");
|
|
111
|
+
|
|
112
|
+
// Relative and absolute paths
|
|
113
|
+
new SQL("sqlite://./local.db"); // Relative to current directory
|
|
114
|
+
new SQL("sqlite://../parent/db.db"); // Parent directory
|
|
115
|
+
new SQL("sqlite:///absolute/path.db"); // Absolute path
|
|
116
|
+
|
|
117
|
+
// With query parameters
|
|
118
|
+
new SQL("sqlite://data.db?mode=ro"); // Read-only mode
|
|
119
|
+
new SQL("sqlite://data.db?mode=rw"); // Read-write mode (no create)
|
|
120
|
+
new SQL("sqlite://data.db?mode=rwc"); // Read-write-create mode (default)
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
**Note:** Simple filenames without a protocol (like `"myapp.db"`) require explicitly specifying `{ adapter: "sqlite" }` to avoid ambiguity with PostgreSQL.
|
|
124
|
+
|
|
125
|
+
</details>
|
|
126
|
+
|
|
127
|
+
<details>
|
|
128
|
+
<summary>SQLite-Specific Options</summary>
|
|
129
|
+
|
|
130
|
+
SQLite databases support additional configuration options:
|
|
131
|
+
|
|
132
|
+
```ts
|
|
133
|
+
const db = new SQL({
|
|
134
|
+
adapter: "sqlite",
|
|
135
|
+
filename: "app.db",
|
|
136
|
+
|
|
137
|
+
// SQLite-specific options
|
|
138
|
+
readonly: false, // Open in read-only mode
|
|
139
|
+
create: true, // Create database if it doesn't exist
|
|
140
|
+
readwrite: true, // Open for reading and writing
|
|
141
|
+
|
|
142
|
+
// Additional Bun:sqlite options
|
|
143
|
+
strict: true, // Enable strict mode
|
|
144
|
+
safeIntegers: false, // Use JavaScript numbers for integers
|
|
145
|
+
});
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
Query parameters in the URL are parsed to set these options:
|
|
149
|
+
|
|
150
|
+
- `?mode=ro` → `readonly: true`
|
|
151
|
+
- `?mode=rw` → `readonly: false, create: false`
|
|
152
|
+
- `?mode=rwc` → `readonly: false, create: true` (default)
|
|
153
|
+
|
|
154
|
+
</details>
|
|
155
|
+
|
|
47
156
|
### Inserting data
|
|
48
157
|
|
|
49
158
|
You can pass JavaScript values directly to the SQL template literal and escaping will be handled for you.
|
|
@@ -251,14 +360,55 @@ await query;
|
|
|
251
360
|
|
|
252
361
|
## Database Environment Variables
|
|
253
362
|
|
|
254
|
-
`sql` connection parameters can be configured using environment variables. The client checks these variables in a specific order of precedence.
|
|
363
|
+
`sql` connection parameters can be configured using environment variables. The client checks these variables in a specific order of precedence and automatically detects the database type based on the connection string format.
|
|
364
|
+
|
|
365
|
+
### Automatic Database Detection
|
|
366
|
+
|
|
367
|
+
When using `Bun.sql()` without arguments or `new SQL()` with a connection string, the adapter is automatically detected based on the URL format. SQLite becomes the default adapter in these cases:
|
|
368
|
+
|
|
369
|
+
#### SQLite Auto-Detection
|
|
370
|
+
|
|
371
|
+
SQLite is automatically selected when the connection string matches these patterns:
|
|
372
|
+
|
|
373
|
+
- `:memory:` - In-memory database
|
|
374
|
+
- `sqlite://...` - SQLite protocol URLs
|
|
375
|
+
- `sqlite:...` - SQLite protocol without slashes
|
|
376
|
+
- `file://...` - File protocol URLs
|
|
377
|
+
- `file:...` - File protocol without slashes
|
|
378
|
+
|
|
379
|
+
```ts
|
|
380
|
+
// These all use SQLite automatically (no adapter needed)
|
|
381
|
+
const sql1 = new SQL(":memory:");
|
|
382
|
+
const sql2 = new SQL("sqlite://app.db");
|
|
383
|
+
const sql3 = new SQL("file://./database.db");
|
|
384
|
+
|
|
385
|
+
// Works with DATABASE_URL environment variable
|
|
386
|
+
DATABASE_URL=":memory:" bun run app.js
|
|
387
|
+
DATABASE_URL="sqlite://myapp.db" bun run app.js
|
|
388
|
+
DATABASE_URL="file://./data/app.db" bun run app.js
|
|
389
|
+
```
|
|
390
|
+
|
|
391
|
+
#### PostgreSQL Auto-Detection
|
|
392
|
+
|
|
393
|
+
PostgreSQL is the default for all other connection strings:
|
|
394
|
+
|
|
395
|
+
```bash
|
|
396
|
+
# PostgreSQL is detected for these patterns
|
|
397
|
+
DATABASE_URL="postgres://user:pass@localhost:5432/mydb" bun run app.js
|
|
398
|
+
DATABASE_URL="postgresql://user:pass@localhost:5432/mydb" bun run app.js
|
|
399
|
+
|
|
400
|
+
# Or any URL that doesn't match SQLite patterns
|
|
401
|
+
DATABASE_URL="localhost:5432/mydb" bun run app.js
|
|
402
|
+
```
|
|
255
403
|
|
|
256
|
-
|
|
404
|
+
### PostgreSQL Environment Variables
|
|
405
|
+
|
|
406
|
+
The following environment variables can be used to define the PostgreSQL connection:
|
|
257
407
|
|
|
258
408
|
| Environment Variable | Description |
|
|
259
409
|
| --------------------------- | ------------------------------------------ |
|
|
260
410
|
| `POSTGRES_URL` | Primary connection URL for PostgreSQL |
|
|
261
|
-
| `DATABASE_URL` | Alternative connection URL
|
|
411
|
+
| `DATABASE_URL` | Alternative connection URL (auto-detected) |
|
|
262
412
|
| `PGURL` | Alternative connection URL |
|
|
263
413
|
| `PG_URL` | Alternative connection URL |
|
|
264
414
|
| `TLS_POSTGRES_DATABASE_URL` | SSL/TLS-enabled connection URL |
|
|
@@ -274,6 +424,19 @@ If no connection URL is provided, the system checks for the following individual
|
|
|
274
424
|
| `PGPASSWORD` | - | (empty) | Database password |
|
|
275
425
|
| `PGDATABASE` | - | username | Database name |
|
|
276
426
|
|
|
427
|
+
### SQLite Environment Variables
|
|
428
|
+
|
|
429
|
+
SQLite connections can be configured via `DATABASE_URL` when it contains a SQLite-compatible URL:
|
|
430
|
+
|
|
431
|
+
```bash
|
|
432
|
+
# These are all recognized as SQLite
|
|
433
|
+
DATABASE_URL=":memory:"
|
|
434
|
+
DATABASE_URL="sqlite://./app.db"
|
|
435
|
+
DATABASE_URL="file:///absolute/path/to/db.sqlite"
|
|
436
|
+
```
|
|
437
|
+
|
|
438
|
+
**Note:** PostgreSQL-specific environment variables (`POSTGRES_URL`, `PGHOST`, etc.) are ignored when using SQLite.
|
|
439
|
+
|
|
277
440
|
## Runtime Preconnection
|
|
278
441
|
|
|
279
442
|
Bun can preconnect to PostgreSQL at startup to improve performance by establishing database connections before your application code runs. This is useful for reducing connection latency on the first database query.
|
|
@@ -293,16 +456,18 @@ The `--sql-preconnect` flag will automatically establish a PostgreSQL connection
|
|
|
293
456
|
|
|
294
457
|
## Connection Options
|
|
295
458
|
|
|
296
|
-
You can configure your database connection manually by passing options to the SQL constructor:
|
|
459
|
+
You can configure your database connection manually by passing options to the SQL constructor. Options vary depending on the database adapter:
|
|
460
|
+
|
|
461
|
+
### PostgreSQL Options
|
|
297
462
|
|
|
298
463
|
```ts
|
|
299
464
|
import { SQL } from "bun";
|
|
300
465
|
|
|
301
466
|
const db = new SQL({
|
|
302
|
-
//
|
|
467
|
+
// Connection details (adapter is auto-detected as PostgreSQL)
|
|
303
468
|
url: "postgres://user:pass@localhost:5432/dbname",
|
|
304
469
|
|
|
305
|
-
//
|
|
470
|
+
// Alternative connection parameters
|
|
306
471
|
hostname: "localhost",
|
|
307
472
|
port: 5432,
|
|
308
473
|
database: "myapp",
|
|
@@ -330,14 +495,53 @@ const db = new SQL({
|
|
|
330
495
|
|
|
331
496
|
// Callbacks
|
|
332
497
|
onconnect: client => {
|
|
333
|
-
console.log("Connected to
|
|
498
|
+
console.log("Connected to PostgreSQL");
|
|
334
499
|
},
|
|
335
500
|
onclose: client => {
|
|
336
|
-
console.log("
|
|
501
|
+
console.log("PostgreSQL connection closed");
|
|
337
502
|
},
|
|
338
503
|
});
|
|
339
504
|
```
|
|
340
505
|
|
|
506
|
+
### SQLite Options
|
|
507
|
+
|
|
508
|
+
```ts
|
|
509
|
+
import { SQL } from "bun";
|
|
510
|
+
|
|
511
|
+
const db = new SQL({
|
|
512
|
+
// Required for SQLite
|
|
513
|
+
adapter: "sqlite",
|
|
514
|
+
filename: "./data/app.db", // or ":memory:" for in-memory database
|
|
515
|
+
|
|
516
|
+
// SQLite-specific access modes
|
|
517
|
+
readonly: false, // Open in read-only mode
|
|
518
|
+
create: true, // Create database if it doesn't exist
|
|
519
|
+
readwrite: true, // Allow read and write operations
|
|
520
|
+
|
|
521
|
+
// SQLite data handling
|
|
522
|
+
strict: true, // Enable strict mode for better type safety
|
|
523
|
+
safeIntegers: false, // Use BigInt for integers exceeding JS number range
|
|
524
|
+
|
|
525
|
+
// Callbacks
|
|
526
|
+
onconnect: client => {
|
|
527
|
+
console.log("SQLite database opened");
|
|
528
|
+
},
|
|
529
|
+
onclose: client => {
|
|
530
|
+
console.log("SQLite database closed");
|
|
531
|
+
},
|
|
532
|
+
});
|
|
533
|
+
```
|
|
534
|
+
|
|
535
|
+
<details>
|
|
536
|
+
<summary>SQLite Connection Notes</summary>
|
|
537
|
+
|
|
538
|
+
- **Connection Pooling**: SQLite doesn't use connection pooling as it's a file-based database. Each `SQL` instance represents a single connection.
|
|
539
|
+
- **Transactions**: SQLite supports nested transactions through savepoints, similar to PostgreSQL.
|
|
540
|
+
- **Concurrent Access**: SQLite handles concurrent access through file locking. Use WAL mode for better concurrency.
|
|
541
|
+
- **Memory Databases**: Using `:memory:` creates a temporary database that exists only for the connection lifetime.
|
|
542
|
+
|
|
543
|
+
</details>
|
|
544
|
+
|
|
341
545
|
## Dynamic passwords
|
|
342
546
|
|
|
343
547
|
When clients need to use alternative authentication schemes such as access tokens or connections to databases with rotating passwords, provide either a synchronous or asynchronous function that will resolve the dynamic password value at connection time.
|
|
@@ -353,11 +557,66 @@ const sql = new SQL(url, {
|
|
|
353
557
|
});
|
|
354
558
|
```
|
|
355
559
|
|
|
560
|
+
## SQLite-Specific Features
|
|
561
|
+
|
|
562
|
+
### Query Execution
|
|
563
|
+
|
|
564
|
+
SQLite executes queries synchronously, unlike PostgreSQL which uses asynchronous I/O. However, the API remains consistent using Promises:
|
|
565
|
+
|
|
566
|
+
```ts
|
|
567
|
+
const sqlite = new SQL("sqlite://app.db");
|
|
568
|
+
|
|
569
|
+
// Works the same as PostgreSQL, but executes synchronously under the hood
|
|
570
|
+
const users = await sqlite`SELECT * FROM users`;
|
|
571
|
+
|
|
572
|
+
// Parameters work identically
|
|
573
|
+
const user = await sqlite`SELECT * FROM users WHERE id = ${userId}`;
|
|
574
|
+
```
|
|
575
|
+
|
|
576
|
+
### SQLite Pragmas
|
|
577
|
+
|
|
578
|
+
You can use PRAGMA statements to configure SQLite behavior:
|
|
579
|
+
|
|
580
|
+
```ts
|
|
581
|
+
const sqlite = new SQL("sqlite://app.db");
|
|
582
|
+
|
|
583
|
+
// Enable foreign keys
|
|
584
|
+
await sqlite`PRAGMA foreign_keys = ON`;
|
|
585
|
+
|
|
586
|
+
// Set journal mode to WAL for better concurrency
|
|
587
|
+
await sqlite`PRAGMA journal_mode = WAL`;
|
|
588
|
+
|
|
589
|
+
// Check integrity
|
|
590
|
+
const integrity = await sqlite`PRAGMA integrity_check`;
|
|
591
|
+
```
|
|
592
|
+
|
|
593
|
+
### Data Type Differences
|
|
594
|
+
|
|
595
|
+
SQLite has a more flexible type system than PostgreSQL:
|
|
596
|
+
|
|
597
|
+
```ts
|
|
598
|
+
// SQLite stores data in 5 storage classes: NULL, INTEGER, REAL, TEXT, BLOB
|
|
599
|
+
const sqlite = new SQL("sqlite://app.db");
|
|
600
|
+
|
|
601
|
+
// SQLite is more lenient with types
|
|
602
|
+
await sqlite`
|
|
603
|
+
CREATE TABLE flexible (
|
|
604
|
+
id INTEGER PRIMARY KEY,
|
|
605
|
+
data TEXT, -- Can store numbers as strings
|
|
606
|
+
value NUMERIC, -- Can store integers, reals, or text
|
|
607
|
+
blob BLOB -- Binary data
|
|
608
|
+
)
|
|
609
|
+
`;
|
|
610
|
+
|
|
611
|
+
// JavaScript values are automatically converted
|
|
612
|
+
await sqlite`INSERT INTO flexible VALUES (${1}, ${"text"}, ${123.45}, ${Buffer.from("binary")})`;
|
|
613
|
+
```
|
|
614
|
+
|
|
356
615
|
## Transactions
|
|
357
616
|
|
|
358
|
-
To start a new transaction, use `sql.begin`. This method
|
|
617
|
+
To start a new transaction, use `sql.begin`. This method works for both PostgreSQL and SQLite. For PostgreSQL, it reserves a dedicated connection from the pool. For SQLite, it begins a transaction on the single connection.
|
|
359
618
|
|
|
360
|
-
The `BEGIN` command is sent automatically, including any optional configurations you specify. If an error occurs during the transaction, a `ROLLBACK` is triggered to
|
|
619
|
+
The `BEGIN` command is sent automatically, including any optional configurations you specify. If an error occurs during the transaction, a `ROLLBACK` is triggered to ensure the process continues smoothly.
|
|
361
620
|
|
|
362
621
|
### Basic Transactions
|
|
363
622
|
|
|
@@ -552,9 +811,34 @@ Note that disabling prepared statements may impact performance for queries that
|
|
|
552
811
|
|
|
553
812
|
## Error Handling
|
|
554
813
|
|
|
555
|
-
The client provides typed errors for different failure scenarios:
|
|
814
|
+
The client provides typed errors for different failure scenarios. Errors are database-specific and extend from base error classes:
|
|
556
815
|
|
|
557
|
-
###
|
|
816
|
+
### Error Classes
|
|
817
|
+
|
|
818
|
+
```ts
|
|
819
|
+
import { SQL } from "bun";
|
|
820
|
+
|
|
821
|
+
try {
|
|
822
|
+
await sql`SELECT * FROM users`;
|
|
823
|
+
} catch (error) {
|
|
824
|
+
if (error instanceof SQL.PostgresError) {
|
|
825
|
+
// PostgreSQL-specific error
|
|
826
|
+
console.log(error.code); // PostgreSQL error code
|
|
827
|
+
console.log(error.detail); // Detailed error message
|
|
828
|
+
console.log(error.hint); // Helpful hint from PostgreSQL
|
|
829
|
+
} else if (error instanceof SQL.SQLiteError) {
|
|
830
|
+
// SQLite-specific error
|
|
831
|
+
console.log(error.code); // SQLite error code (e.g., "SQLITE_CONSTRAINT")
|
|
832
|
+
console.log(error.errno); // SQLite error number
|
|
833
|
+
console.log(error.byteOffset); // Byte offset in SQL statement (if available)
|
|
834
|
+
} else if (error instanceof SQL.SQLError) {
|
|
835
|
+
// Generic SQL error (base class)
|
|
836
|
+
console.log(error.message);
|
|
837
|
+
}
|
|
838
|
+
}
|
|
839
|
+
```
|
|
840
|
+
|
|
841
|
+
### PostgreSQL Connection Errors
|
|
558
842
|
|
|
559
843
|
| Connection Errors | Description |
|
|
560
844
|
| --------------------------------- | ---------------------------------------------------- |
|
|
@@ -619,6 +903,50 @@ The client provides typed errors for different failure scenarios:
|
|
|
619
903
|
| `ERR_POSTGRES_UNSAFE_TRANSACTION` | Unsafe transaction operation detected |
|
|
620
904
|
| `ERR_POSTGRES_INVALID_TRANSACTION_STATE` | Invalid transaction state |
|
|
621
905
|
|
|
906
|
+
### SQLite-Specific Errors
|
|
907
|
+
|
|
908
|
+
SQLite errors provide error codes and numbers that correspond to SQLite's standard error codes:
|
|
909
|
+
|
|
910
|
+
<details>
|
|
911
|
+
<summary>Common SQLite Error Codes</summary>
|
|
912
|
+
|
|
913
|
+
| Error Code | errno | Description |
|
|
914
|
+
| ------------------- | ----- | ---------------------------------------------------- |
|
|
915
|
+
| `SQLITE_CONSTRAINT` | 19 | Constraint violation (UNIQUE, CHECK, NOT NULL, etc.) |
|
|
916
|
+
| `SQLITE_BUSY` | 5 | Database is locked |
|
|
917
|
+
| `SQLITE_LOCKED` | 6 | Table in the database is locked |
|
|
918
|
+
| `SQLITE_READONLY` | 8 | Attempt to write to a readonly database |
|
|
919
|
+
| `SQLITE_IOERR` | 10 | Disk I/O error |
|
|
920
|
+
| `SQLITE_CORRUPT` | 11 | Database disk image is malformed |
|
|
921
|
+
| `SQLITE_FULL` | 13 | Database or disk is full |
|
|
922
|
+
| `SQLITE_CANTOPEN` | 14 | Unable to open database file |
|
|
923
|
+
| `SQLITE_PROTOCOL` | 15 | Database lock protocol error |
|
|
924
|
+
| `SQLITE_SCHEMA` | 17 | Database schema has changed |
|
|
925
|
+
| `SQLITE_TOOBIG` | 18 | String or BLOB exceeds size limit |
|
|
926
|
+
| `SQLITE_MISMATCH` | 20 | Data type mismatch |
|
|
927
|
+
| `SQLITE_MISUSE` | 21 | Library used incorrectly |
|
|
928
|
+
| `SQLITE_AUTH` | 23 | Authorization denied |
|
|
929
|
+
|
|
930
|
+
Example error handling:
|
|
931
|
+
|
|
932
|
+
```ts
|
|
933
|
+
const sqlite = new SQL("sqlite://app.db");
|
|
934
|
+
|
|
935
|
+
try {
|
|
936
|
+
await sqlite`INSERT INTO users (id, name) VALUES (1, 'Alice')`;
|
|
937
|
+
await sqlite`INSERT INTO users (id, name) VALUES (1, 'Bob')`; // Duplicate ID
|
|
938
|
+
} catch (error) {
|
|
939
|
+
if (error instanceof SQL.SQLiteError) {
|
|
940
|
+
if (error.code === "SQLITE_CONSTRAINT") {
|
|
941
|
+
console.log("Constraint violation:", error.message);
|
|
942
|
+
// Handle unique constraint violation
|
|
943
|
+
}
|
|
944
|
+
}
|
|
945
|
+
}
|
|
946
|
+
```
|
|
947
|
+
|
|
948
|
+
</details>
|
|
949
|
+
|
|
622
950
|
## Numbers and BigInt
|
|
623
951
|
|
|
624
952
|
Bun's SQL client includes special handling for large numbers that exceed the range of a 53-bit integer. Here's how it works:
|
|
@@ -652,7 +980,6 @@ There's still some things we haven't finished yet.
|
|
|
652
980
|
|
|
653
981
|
- Connection preloading via `--db-preconnect` Bun CLI flag
|
|
654
982
|
- MySQL support: [we're working on it](https://github.com/oven-sh/bun/pull/15274)
|
|
655
|
-
- SQLite support: planned, but not started. Ideally, we implement it natively instead of wrapping `bun:sqlite`.
|
|
656
983
|
- Column name transforms (e.g. `snake_case` to `camelCase`). This is mostly blocked on a unicode-aware implementation of changing the case in C++ using WebKit's `WTF::String`.
|
|
657
984
|
- Column type transforms
|
|
658
985
|
|
package/docs/cli/pm.md
CHANGED
|
@@ -213,7 +213,7 @@ To display current package version and help:
|
|
|
213
213
|
|
|
214
214
|
```bash
|
|
215
215
|
$ bun pm version
|
|
216
|
-
bun pm version v1.2.21-canary.
|
|
216
|
+
bun pm version v1.2.21-canary.20250820T140622 (ca7428e9)
|
|
217
217
|
Current package version: v1.0.0
|
|
218
218
|
|
|
219
219
|
Increment:
|
package/docs/cli/publish.md
CHANGED
|
@@ -9,7 +9,7 @@ $ bunx nuxi init my-nuxt-app
|
|
|
9
9
|
✔ Which package manager would you like to use?
|
|
10
10
|
bun
|
|
11
11
|
◐ Installing dependencies...
|
|
12
|
-
bun install v1.2.21-canary.
|
|
12
|
+
bun install v1.2.21-canary.20250820T140622 (16b4bf34)
|
|
13
13
|
+ @nuxt/devtools@0.8.2
|
|
14
14
|
+ nuxt@3.7.0
|
|
15
15
|
785 packages installed [2.67s]
|
|
@@ -15,7 +15,7 @@ This will add the package to `peerDependencies` in `package.json`.
|
|
|
15
15
|
```json-diff
|
|
16
16
|
{
|
|
17
17
|
"peerDependencies": {
|
|
18
|
-
+ "@types/bun": "^1.2.21-canary.
|
|
18
|
+
+ "@types/bun": "^1.2.21-canary.20250820T140622"
|
|
19
19
|
}
|
|
20
20
|
}
|
|
21
21
|
```
|
|
@@ -27,7 +27,7 @@ Running `bun install` will install peer dependencies by default, unless marked o
|
|
|
27
27
|
```json-diff
|
|
28
28
|
{
|
|
29
29
|
"peerDependencies": {
|
|
30
|
-
"@types/bun": "^1.2.21-canary.
|
|
30
|
+
"@types/bun": "^1.2.21-canary.20250820T140622"
|
|
31
31
|
},
|
|
32
32
|
"peerDependenciesMeta": {
|
|
33
33
|
+ "@types/bun": {
|
|
@@ -97,7 +97,7 @@ $ bun update
|
|
|
97
97
|
$ bun update @types/bun --latest
|
|
98
98
|
|
|
99
99
|
# Update a dependency to a specific version
|
|
100
|
-
$ bun update @types/bun@1.2.21-canary.
|
|
100
|
+
$ bun update @types/bun@1.2.21-canary.20250820T140622
|
|
101
101
|
|
|
102
102
|
# Update all dependencies to the latest versions
|
|
103
103
|
$ bun update --latest
|
|
@@ -21,7 +21,7 @@ Here's what the output of a typical test run looks like. In this case, there are
|
|
|
21
21
|
|
|
22
22
|
```sh
|
|
23
23
|
$ bun test
|
|
24
|
-
bun test v1.2.21-canary.
|
|
24
|
+
bun test v1.2.21-canary.20250820T140622 (9c68abdb)
|
|
25
25
|
|
|
26
26
|
test.test.js:
|
|
27
27
|
✓ add [0.87ms]
|
|
@@ -47,7 +47,7 @@ To only run certain test files, pass a positional argument to `bun test`. The ru
|
|
|
47
47
|
|
|
48
48
|
```sh
|
|
49
49
|
$ bun test test3
|
|
50
|
-
bun test v1.2.21-canary.
|
|
50
|
+
bun test v1.2.21-canary.20250820T140622 (9c68abdb)
|
|
51
51
|
|
|
52
52
|
test3.test.js:
|
|
53
53
|
✓ add [1.40ms]
|
|
@@ -85,7 +85,7 @@ Adding `-t add` will only run tests with "add" in the name. This works with test
|
|
|
85
85
|
|
|
86
86
|
```sh
|
|
87
87
|
$ bun test -t add
|
|
88
|
-
bun test v1.2.21-canary.
|
|
88
|
+
bun test v1.2.21-canary.20250820T140622 (9c68abdb)
|
|
89
89
|
|
|
90
90
|
test.test.js:
|
|
91
91
|
✓ add [1.79ms]
|
|
@@ -18,7 +18,7 @@ The first time this test is executed, Bun will evaluate the value passed into `e
|
|
|
18
18
|
|
|
19
19
|
```sh
|
|
20
20
|
$ bun test test/snap
|
|
21
|
-
bun test v1.2.21-canary.
|
|
21
|
+
bun test v1.2.21-canary.20250820T140622 (9c68abdb)
|
|
22
22
|
|
|
23
23
|
test/snap.test.ts:
|
|
24
24
|
✓ snapshot [1.48ms]
|
|
@@ -61,7 +61,7 @@ Later, when this test file is executed again, Bun will read the snapshot file an
|
|
|
61
61
|
|
|
62
62
|
```sh
|
|
63
63
|
$ bun test
|
|
64
|
-
bun test v1.2.21-canary.
|
|
64
|
+
bun test v1.2.21-canary.20250820T140622 (9c68abdb)
|
|
65
65
|
|
|
66
66
|
test/snap.test.ts:
|
|
67
67
|
✓ snapshot [1.05ms]
|
|
@@ -78,7 +78,7 @@ To update snapshots, use the `--update-snapshots` flag.
|
|
|
78
78
|
|
|
79
79
|
```sh
|
|
80
80
|
$ bun test --update-snapshots
|
|
81
|
-
bun test v1.2.21-canary.
|
|
81
|
+
bun test v1.2.21-canary.20250820T140622 (9c68abdb)
|
|
82
82
|
|
|
83
83
|
test/snap.test.ts:
|
|
84
84
|
✓ snapshot [0.86ms]
|
|
@@ -29,7 +29,7 @@ To regenerate snapshots, use the `--update-snapshots` flag.
|
|
|
29
29
|
|
|
30
30
|
```sh
|
|
31
31
|
$ bun test --update-snapshots
|
|
32
|
-
bun test v1.2.21-canary.
|
|
32
|
+
bun test v1.2.21-canary.20250820T140622 (9c68abdb)
|
|
33
33
|
|
|
34
34
|
test/snap.test.ts:
|
|
35
35
|
✓ snapshot [0.86ms]
|