Update docs - add ESM info

* Update docs - start

* Add logo & discord

* Start updating docs for esm style imports

* Update docs with logo & info on pooling

* Update more import statements

---------

Co-authored-by: Brian Carlson <[email protected]>

Author: brianc

docs/README.md

@@ -0,0 +1,20 @@
+# node-postgres docs website
+
+This is the documentation for node-postgres which is currently hosted at [https://node-postgres.com](https://node-postgres.com).
+
+## Development
+
+To run the documentation locally, you need to have [Node.js](https://nodejs.org) installed. Then, you can clone the repository and install the dependencies:
+
+```bash
+cd docs
+yarn
+```
+
+Once you've installed the deps, you can run the development server:
+
+```bash
+yarn dev
+```
+
+This will start a local server at [http://localhost:3000](http://localhost:3000) where you can view the documentation and see your changes.

docs/components/logo.tsx

@@ -0,0 +1,11 @@
+import React from 'react'
+
+type Props = {
+  src: string
+  alt?: string
+}
+
+export function Logo(props: Props) {
+  const alt = props.alt || 'Logo'
+  return <img src={props.src} alt={alt} width={100} height={100} style={{ width: 400, height: 'auto' }} />
+}

docs/pages/apis/client.mdx

@@ -33,8 +33,7 @@ type Config = {
 example to create a client with specific connection information:
 
 ```js
-import pg from 'pg'
-const { Client } = pg
+import { Client } from 'pg'
 
 const client = new Client({
   user: 'database-user',
@@ -48,8 +47,7 @@ const client = new Client({
 ## client.connect
 
 ```js
-import pg from 'pg'
-const { Client } = pg
+import { Client } from 'pg'
 const client = new Client()
 
 await client.connect()
@@ -91,8 +89,7 @@ client.query(text: string, values?: any[]) => Promise<Result>
 **Plain text query**
 
 ```js
-import pg from 'pg'
-const { Client } = pg
+import { Client } from 'pg'
 const client = new Client()
 
 await client.connect()
@@ -106,8 +103,7 @@ await client.end()
 **Parameterized query**
 
 ```js
-import pg from 'pg'
-const { Client } = pg
+import { Client } from 'pg'
 const client = new Client()
 
 await client.connect()
@@ -145,8 +141,7 @@ await client.end()
 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.
 
 ```js
-import pg from 'pg'
-const { Query } = pg
+import { Query } from 'pg'
 const query = new Query('select $1::text as name', ['brianc'])
 
 const result = client.query(query)

docs/pages/apis/cursor.mdx

@@ -18,8 +18,7 @@ $ npm install pg pg-cursor
 Instantiates a new Cursor. A cursor is an instance of `Submittable` and should be passed directly to the `client.query` method.
 
 ```js
-import pg from 'pg'
-const { Pool } = pg
+import { Pool } from 'pg'
 import Cursor from 'pg-cursor'
 
 const pool = new Pool()
@@ -29,11 +28,9 @@ const values = [10]
 
 const cursor = client.query(new Cursor(text, values))
 
-cursor.read(100, (err, rows) => {
-  cursor.close(() => {
-    client.release()
-  })
-})
+const { rows } = await cursor.read(100)
+console.log(rows.length) // 100 (unless the table has fewer than 100 rows)
+client.release()
 ```
 
 ```ts
@@ -58,8 +55,7 @@ If the cursor has read to the end of the result sets all subsequent calls to cur
 Here is an example of reading to the end of a cursor:
 
 ```js
-import pg from 'pg'
-const { Pool } = pg
+import { Pool } from 'pg'
 import Cursor from 'pg-cursor'
 
 const pool = new Pool()

docs/pages/apis/pool.mdx

@@ -48,8 +48,7 @@ type Config = {
 example to create a new pool with configuration:
 
 ```js
-import pg from 'pg'
-const { Pool } = pg
+import { Pool } from 'pg'
 
 const pool = new Pool({
   host: 'localhost',
@@ -69,8 +68,7 @@ pool.query(text: string, values?: any[]) => Promise<pg.Result>
 ```
 
 ```js
-import pg from 'pg'
-const { Pool } = pg
+import { Pool } from 'pg'
 
 const pool = new Pool()
 
@@ -102,8 +100,7 @@ Acquires a client from the pool.
 - 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.
 
 ```js
-import pg from 'pg'
-const { Pool } = pg
+import { Pool } from 'pg'
 
 const pool = new Pool()
 
@@ -121,8 +118,7 @@ Client instances returned from `pool.connect` will have a `release` method which
 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.
 
 ```js
-import pg from 'pg'
-const { Pool } = pg
+import { Pool } from 'pg'
 
 const pool = new Pool()
 
@@ -134,8 +130,7 @@ client.release()
 ```
 
 ```js
-import pg from 'pg'
-const { Pool } = pg
+import { Pool } from 'pg'
 
 const pool = new Pool()
 assert(pool.totalCount === 0)
@@ -168,8 +163,7 @@ Calling `pool.end` will drain the pool of all active clients, disconnect them, a
 
 ```js
 // again both promises and callbacks are supported:
-import pg from 'pg'
-const { Pool } = pg
+import { Pool } from 'pg'
 
 const pool = new Pool()
 

docs/pages/features/_meta.json

@@ -5,5 +5,7 @@
   "transactions": "Transactions",
   "types": "Data Types",
   "ssl": "SSL",
-  "native": "Native"
+  "native": "Native",
+  "esm": "ESM",
+  "callbacks": "Callbacks"
 }

docs/pages/features/callbacks.mdx

@@ -0,0 +1,39 @@
+---
+title: Callbacks
+---
+
+## Callback Support
+
+`async` / `await` is the preferred way to write async code these days with node, but callbacks are supported in the `pg` module and the `pg-pool` module. To use them, pass a callback function as the last argument to the following methods & it will be called and a promise will not be returned:
+
+
+```js
+const { Pool, Client } = require('pg')
+
+// pool
+const pool = new Pool()
+// run a query on an available client
+pool.query('SELECT NOW()', (err, res) => {
+  console.log(err, res)
+})
+
+// check out a client to do something more complex like a transaction
+pool.connect((err, client, release) => {
+  client.query('SELECT NOW()', (err, res) => {
+    release()
+    console.log(err, res)
+    pool.end()
+  })
+
+})
+
+// single client
+const client = new Client()
+client.connect((err) => {
+  if (err) throw err
+  client.query('SELECT NOW()', (err, res) => {
+    console.log(err, res)
+    client.end()
+  })
+})
+```

docs/pages/features/esm.mdx

@@ -0,0 +1,37 @@
+---
+title: ESM
+---
+
+## ESM Support
+
+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'`.
+
+CommonJS modules are still supported. The ESM format is an opt-in feature and will not affect existing codebases that use CommonJS.
+
+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.
+
+If you're using CommonJS, you can use the following code to import the `pg` module:
+
+```js
+  const pg = require('pg')
+  const { Client } = pg
+  // etc...
+```
+
+### ESM Usage
+
+If you're using ESM, you can use the following code to import the `pg` module:
+
+```js
+  import { Client } from 'pg'
+  // etc...
+```
+
+
+Previously if you were using ESM you would have to use the following code:
+
+```js
+  import pg from 'pg'
+  const { Client } = pg
+  // etc...
+```

docs/pages/features/ssl.mdx

@@ -22,8 +22,7 @@ const config = {
   },
 }
 
-import pg from 'pg'
-const { Client, Pool } = pg
+import { Client, Pool } from 'pg'
 
 const client = new Client(config)
 await client.connect()

docs/pages/features/transactions.mdx

@@ -16,8 +16,7 @@ To execute a transaction with node-postgres you simply execute `BEGIN / COMMIT /
 ## Examples
 
 ```js
-import pg from 'pg'
-const { Pool } = pg
+import { Pool } from 'pg'
 const pool = new Pool()
 
 const client = await pool.connect()