Skip to content

Commit 53901a1

Browse files
author
Brian Carlson
committed
Start updating docs for esm style imports
1 parent 09d12d9 commit 53901a1

File tree

8 files changed

+57
-34
lines changed

8 files changed

+57
-34
lines changed

‎docs/pages/apis/client.mdx‎

Lines changed: 5 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -33,8 +33,7 @@ type Config = {
3333
example to create a client with specific connection information:
3434
3535
```js
36-
import pg from 'pg'
37-
const { Client } = pg
36+
import { Client } from 'pg'
3837

3938
const client = new Client({
4039
user: 'database-user',
@@ -48,8 +47,7 @@ const client = new Client({
4847
## client.connect
4948

5049
```js
51-
import pg from 'pg'
52-
const { Client } = pg
50+
import { Client } from 'pg'
5351
const client = new Client()
5452

5553
await client.connect()
@@ -91,8 +89,7 @@ client.query(text: string, values?: any[]) => Promise<Result>
9189
**Plain text query**
9290

9391
```js
94-
import pg from 'pg'
95-
const { Client } = pg
92+
import { Client } from 'pg'
9693
const client = new Client()
9794

9895
await client.connect()
@@ -106,8 +103,7 @@ await client.end()
106103
**Parameterized query**
107104

108105
```js
109-
import pg from 'pg'
110-
const { Client } = pg
106+
import { Client } from 'pg'
111107
const client = new Client()
112108

113109
await client.connect()
@@ -145,8 +141,7 @@ await client.end()
145141
If you pass an object to `client.query` and the object has a `.submit` function on it, the client will pass it's PostgreSQL server connection to the object and delegate query dispatching to the supplied object. This is an advanced feature mostly intended for library authors. It is incidentally also currently how the callback and promise based queries above are handled internally, but this is subject to change. It is also how [pg-cursor](https://github.com/brianc/node-pg-cursor) and [pg-query-stream](https://github.com/brianc/node-pg-query-stream) work.
146142

147143
```js
148-
import pg from 'pg'
149-
const { Query } = pg
144+
import { Query } from 'pg'
150145
const query = new Query('select $1::text as name', ['brianc'])
151146

152147
const result = client.query(query)

‎docs/pages/apis/cursor.mdx‎

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -18,8 +18,7 @@ $ npm install pg pg-cursor
1818
Instantiates a new Cursor. A cursor is an instance of `Submittable` and should be passed directly to the `client.query` method.
1919

2020
```js
21-
import pg from 'pg'
22-
const { Pool } = pg
21+
import { Pool } from 'pg'
2322
import Cursor from 'pg-cursor'
2423

2524
const pool = new Pool()
@@ -58,8 +57,7 @@ If the cursor has read to the end of the result sets all subsequent calls to cur
5857
Here is an example of reading to the end of a cursor:
5958

6059
```js
61-
import pg from 'pg'
62-
const { Pool } = pg
60+
import { Pool } from 'pg'
6361
import Cursor from 'pg-cursor'
6462

6563
const pool = new Pool()

‎docs/pages/apis/pool.mdx‎

Lines changed: 6 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -48,8 +48,7 @@ type Config = {
4848
example to create a new pool with configuration:
4949
5050
```js
51-
import pg from 'pg'
52-
const { Pool } = pg
51+
import { Pool } from 'pg'
5352

5453
const pool = new Pool({
5554
host: 'localhost',
@@ -69,8 +68,7 @@ pool.query(text: string, values?: any[]) => Promise<pg.Result>
6968
```
7069

7170
```js
72-
import pg from 'pg'
73-
const { Pool } = pg
71+
import { Pool } from 'pg'
7472

7573
const pool = new Pool()
7674

@@ -102,8 +100,7 @@ Acquires a client from the pool.
102100
- If the pool is 'full' and all clients are currently checked out will wait in a FIFO queue until a client becomes available by it being released back to the pool.
103101

104102
```js
105-
import pg from 'pg'
106-
const { Pool } = pg
103+
import { Pool } from 'pg'
107104

108105
const pool = new Pool()
109106

@@ -121,8 +118,7 @@ Client instances returned from `pool.connect` will have a `release` method which
121118
The `release` method on an acquired client returns it back to the pool. If you pass a truthy value in the `destroy` parameter, instead of releasing the client to the pool, the pool will be instructed to disconnect and destroy this client, leaving a space within itself for a new client.
122119

123120
```js
124-
import pg from 'pg'
125-
const { Pool } = pg
121+
import { Pool } from 'pg'
126122

127123
const pool = new Pool()
128124

@@ -134,8 +130,7 @@ client.release()
134130
```
135131

136132
```js
137-
import pg from 'pg'
138-
const { Pool } = pg
133+
import { Pool } from 'pg'
139134

140135
const pool = new Pool()
141136
assert(pool.totalCount === 0)
@@ -168,8 +163,7 @@ Calling `pool.end` will drain the pool of all active clients, disconnect them, a
168163

169164
```js
170165
// again both promises and callbacks are supported:
171-
import pg from 'pg'
172-
const { Pool } = pg
166+
import { Pool } from 'pg'
173167

174168
const pool = new Pool()
175169

‎docs/pages/features/_meta.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,5 +5,6 @@
55
"transactions": "Transactions",
66
"types": "Data Types",
77
"ssl": "SSL",
8-
"native": "Native"
8+
"native": "Native",
9+
"esm": "ESM"
910
}

‎docs/pages/features/esm.mdx‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
title: ESM
3+
---
4+
5+
## ESM Support
6+
7+
As of v8.15.x node-postgres supporters the __ECMAScript Module__ (ESM) format. This means you can use `import` statements instead of `require` or `import pg from 'pg'`.
8+
9+
CommonJS modules are still supported. The ESM format is an opt-in feature and will not affect existing codebases that use CommonJS.
10+
11+
The docs have been changed to show ESM usage, but in a CommonJS context you can still use the same code, you just need to change the import format.
12+
13+
If you're using CommonJS, you can use the following code to import the `pg` module:
14+
15+
```js
16+
const pg = require('pg')
17+
const { Client } = pg
18+
// etc...
19+
```
20+
21+
### ESM Usage
22+
23+
If you're using ESM, you can use the following code to import the `pg` module:
24+
25+
```js
26+
import { Client } from 'pg'
27+
// etc...
28+
```
29+
30+
31+
Previously if you were using ESM you would have to use the following code:
32+
33+
```js
34+
import pg from 'pg'
35+
const { Client } = pg
36+
// etc...
37+
```

‎docs/pages/index.mdx‎

Lines changed: 4 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -19,15 +19,14 @@ If you or your company would like to sponsor node-postgres stop by [GitHub Spons
1919

2020
# Version compatibility
2121

22-
node-postgres strives to be compatible with all recent LTS versions of node & the most recent "stable" version. At the time of this writing node-postgres is compatible with node 8.x, 10.x, 12.x and 14.x To use node >= 14.x you will need to install `[email protected]` or later due to some internal stream changes on the node 14 branch. Dropping support for an old node lts version will always be considered a breaking change in node-postgres and will be done on _major_ version number changes only, and we will try to keep support for 8.x for as long as reasonably possible.
22+
node-postgres strives to be compatible with all recent LTS versions of node & the most recent "stable" version. At the time of this writing node-postgres is compatible with node 18.x, 20.x, 22.x, and 24.x.
2323

2424
## Getting started
2525

2626
The simplest possible way to connect, query, and disconnect is with async/await:
2727

2828
```js
29-
import pg from 'pg'
30-
const { Client } = pg
29+
import { Client } from 'pg'
3130
const client = new Client()
3231
await client.connect()
3332

@@ -41,8 +40,7 @@ await client.end()
4140
For the sake of simplicity, these docs will assume that the methods are successful. In real life use, make sure to properly handle errors thrown in the methods. A `try/catch` block is a great way to do so:
4241

4342
```ts
44-
import pg from 'pg'
45-
const { Client } = pg
43+
import { Client } from 'pg'
4644
const client = new Client()
4745
await client.connect()
4846

@@ -61,8 +59,7 @@ try {
6159
If you prefer a callback-style approach to asynchronous programming, all async methods support an optional callback parameter as well:
6260

6361
```js
64-
import pg from 'pg'
65-
const { Client } = pg
62+
import { Client } from 'pg'
6663
const client = new Client()
6764

6865
client.connect((err) => {

‎docs/public/favicon.ico‎

15 KB
Binary file not shown.

‎docs/theme.config.js‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,7 @@ l-161 -22 -94 41 c-201 87 -327 113 -533 112 -77 -1 -166 -7 -196 -13z m-89
5858
head: (
5959
<>
6060
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
61+
<link rel="shortcut icon" href="/favicon.ico" />
6162
<meta
6263
name="description"
6364
content="node-postgres is a collection of node.js modules for interfacing with your PostgreSQL database."

0 commit comments

Comments
 (0)