Skip to content
Open
Changes from 3 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 15 additions & 1 deletion docs/runtime/sql.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -1367,7 +1367,7 @@ Bun converts MySQL types to JavaScript types:
| BIT(1) | boolean | BIT(1) in MySQL |
| GEOMETRY | Buffer | Binary character set; the bytes are a 4-byte SRID followed by WKB |

`DATETIME` and `TIMESTAMP` values have no timezone on the wire, so Bun reads them back as **UTC**. The `Date` you get has the same UTC wall-clock that was stored, regardless of the machine's timezone. Reading as UTC matches how Bun writes values (a bound `Date` stores its UTC components). The same applies to PostgreSQL's `timestamp` (without time zone); `timestamptz` carries an explicit offset and is unaffected.
`DATETIME` and `TIMESTAMP` values have no timezone on the wire, so Bun reads them back as **UTC**. The `Date` you get has the same UTC wall-clock that was stored, regardless of the machine's timezone. Reading as UTC matches how Bun writes values (a bound `Date` stores its UTC components). PostgreSQL's `timestamp` (without time zone) behaves the same way. See [Timestamps and time zones](#timestamps-and-time-zones).

#### Differences from PostgreSQL

Expand All @@ -1383,6 +1383,20 @@ We haven't implemented `LOAD DATA INFILE` support yet.

### PostgreSQL-Specific Features

#### Timestamps and time zones

A `timestamp` (without time zone, OID 1114) value has no offset on the wire. Bun decodes it as **UTC**: the `Date` you get has the same UTC wall clock that was stored, regardless of the machine's time zone. Bun decodes it the same way in regular queries and in `sql``.simple()` queries. This matches how Bun writes values (a bound `Date` stores its UTC components), so a `Date` round-trips exactly on any host.

```ts
// Column: created_at timestamp, stored value: 2024-01-15 12:00:00
const [row] = await sql`SELECT created_at FROM events`;
row.created_at.toISOString(); // "2024-01-15T12:00:00.000Z" on every host
```

`node-postgres` (`pg`), `postgres.js`, and PGlite decode `timestamp` as **local time** instead. If you migrate from one of them and the host is not UTC, the same stored value produces a `Date` for a different instant. `timestamptz` carries an explicit offset and decodes the same in every driver. Prefer `timestamptz` when a column stores a point in time.

#### Not yet implemented

We haven't implemented these yet:

- `COPY` support
Expand Down