97 | You must call the releaseCallback or{' '}
98 | client.release (which points to the releaseCallback) when
99 | you are finished with a client. If you forget to release the client then your application will quickly exhaust
100 | available, idle clients in the pool and all further calls to pool.connect will timeout
101 | with an error or hang indefinitely if you have connectionTimeoutMillis configured to 0.
102 |
103 |
104 | ## releaseCallback
105 |
106 | ### release: (err?: Error)
107 |
108 | The `releaseCallback` releases an acquired client back to the pool. If you pass a truthy value in the `err` position to the callback, 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.
109 |
110 | ```js
111 | const { Pool } = require('pg')
112 |
113 | const pool = new Pool()
114 | assert(pool.totalCount === 0)
115 | assert(pool.idleCount === 0)
116 | ;(async function() {
117 | const client = await pool.connect()
118 | await client.query('SELECT NOW()')
119 | assert(pool.totalCount === 1)
120 | assert(pool.idleCount === 0)
121 |
122 | // tell the pool to destroy this client
123 | client.release(true)
124 | assert(pool.idleCount === 0)
125 | assert(pool.totalCount === 0)
126 | })()
127 | ```
128 |
129 | Client instances returned from `pool.connect` will have a `release` method which will release them from the pool. This is the same method that is passed to the connect callback as the 3rd argument if you're using the pool with callbacks.
130 |
131 | ```js
132 | const { Pool } = require('pg')
133 |
134 | const pool = new Pool()
135 | pool.connect((err, client, release) => {
136 | assert(client.release === release)
137 | })
138 | ```
139 |
140 | ## pool.query
141 |
142 | Often we only need to run a single query on the database, so as convenience the pool has a method to run a query on the first available idle client and return its result.
143 |
144 | ### pool.query(callback: (err?: Error, result: pg.Result)) => void
145 |
146 | ```js
147 | const { Pool } = require('pg')
148 |
149 | const pool = new Pool()
150 |
151 | pool.query('SELECT $1::text as name', ['brianc'], (err, result) => {
152 | if (err) {
153 | return console.error('Error executing query', err.stack)
154 | }
155 | console.log(result.rows[0].name) // brianc
156 | })
157 | ```
158 |
159 | Promises are also supported:
160 |
161 | ### `pool.query() => Promise
177 | Do not use pool.query if you need transactional integrity: the pool will dispatch every query passed
178 | to pool.query on the first available idle client. Transactions within PostgreSQL are scoped to a single client and so
179 | dispatching individual queries within a single transaction across multiple, random clients will cause big problems in
180 | your app and not work. For more info please read transactions.
181 |
182 |
183 | ## pool.end
184 |
185 | Calling `pool.end` will drain the pool of all active clients, disconnect them, and shut down any internal timers in the pool. It is common to call this at the end of a script using the pool or when your process is attempting to shut down cleanly.
186 |
187 | ```js
188 | // again both promises and callbacks are supported:
189 | const { Pool } = require('pg')
190 |
191 | const pool = new Pool()
192 |
193 | // either this:
194 | pool.end(() => {
195 | console.log('pool has ended')
196 | })
197 |
198 | // or this:
199 | pool.end().then(() => console.log('pool has ended'))
200 | ```
201 |
202 | ## properties
203 |
204 | ### `pool.totalCount: int`
205 |
206 | The total number of clients existing within the pool.
207 |
208 | ### `pool.idleCount: int`
209 |
210 | The number of clients which are not checked out but are currently idle in the pool.
211 |
212 | ### `pool.waitingCount: int`
213 |
214 | The number of queued requests waiting on a client when all clients are checked out. It can be helpful to monitor this number to see if you need to adjust the size of the pool.
215 |
216 | ## events
217 |
218 | `Pool` instances are also instances of [`EventEmitter`](https://nodejs.org/api/events.html).
219 |
220 | ### `pool.on('connect', (client: Client) => void) => void`
221 |
222 | Whenever the pool establishes a new client connection to the PostgreSQL backend it will emit the `connect` event with the newly connected client. This presents an opportunity for you to run setup commands on a client.
223 |
224 | ```js
225 | const pool = new Pool()
226 | pool.on('connect', client => {
227 | client.query('SET DATESTYLE = iso, mdy')
228 | })
229 | ```
230 |
231 | ### `pool.on('acquire', (client: Client) => void) => void`
232 |
233 | Whenever a client is checked out from the pool the pool will emit the `acquire` event with the client that was acquired.
234 |
235 | ### `pool.on('error', (err: Error, client: Client) => void) => void`
236 |
237 | When a client is sitting idly in the pool it can still emit errors because it is connected to a live backend. If the backend goes down or a network partition is encountered all the idle, connected clients in your application will emit an error _through_ the pool's error event emitter. The error listener is passed the error as the first argument and the client upon which the error occurred as the 2nd argument. The client will be automatically terminated and removed from the pool, it is only passed to the error handler in case you want to inspect it.
238 |
239 |
240 | It is important you add an event listener to the pool to catch errors. Just like other event emitters, if a pool emits
241 | an error event and no listeners are added node will emit an uncaught error and
242 | potentially exit.
243 |
244 |
245 | ### `pool.on('remove', (client: Client) => void) => void`
246 |
247 | Whenever a client is closed & removed from the pool the pool will emit the `remove` event.
248 |
--------------------------------------------------------------------------------
/content/api/2-client.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: pg.Client
3 | slug: /api/client
4 | ---
5 |
6 | ## constructor
7 |
8 | ### new Client([config: object])
9 |
10 | Every field of the `config` object is entirely optional. A `Client` instance will use [environment variables](/features/connecting#environment-variables) for all missing values.
11 |
12 | ```flow
13 | config = {
14 | user?: string, // default process.env.PGUSER || process.env.USER
15 | password?: string or function, //default process.env.PGPASSWORD
16 | host?: string, // default process.env.PGHOST
17 | database?: string, // default process.env.PGDATABASE || user
18 | port?: number, // default process.env.PGPORT
19 | connectionString?: string, // e.g. postgres://user:password@host:5432/database
20 | ssl?: any, // passed directly to node.TLSSocket, supports all tls.connect options
21 | types?: any, // custom type parsers
22 | statement_timeout?: number, // number of milliseconds before a statement in query will time out, default is no timeout
23 | query_timeout?: number, // number of milliseconds before a query call will timeout, default is no timeout
24 | application_name?: string, // The name of the application that created this Client instance
25 | connectionTimeoutMillis?: number, // number of milliseconds to wait for connection, default is no timeout
26 | idle_in_transaction_session_timeout?: number // number of milliseconds before terminating any session with an open idle transaction, default is no timeout
27 | }
28 | ```
29 |
30 | example to create a client with specific connection information:
31 |
32 | ```js
33 | const { Client } = require('pg')
34 |
35 | const client = new Client({
36 | host: 'my.database-server.com',
37 | port: 5334,
38 | user: 'database-user',
39 | password: 'secretpassword!!',
40 | })
41 | ```
42 |
43 | ## client.connect
44 |
45 | ### `client.connect(callback: (err: Error) => void) => void`
46 |
47 | Calling `client.connect` with a callback:
48 |
49 | ```js
50 | const { Client } = require('pg')
51 | const client = new Client()
52 | client.connect(err => {
53 | if (err) {
54 | console.error('connection error', err.stack)
55 | } else {
56 | console.log('connected')
57 | }
58 | })
59 | ```
60 |
61 | ### `client.connect() => Promisenote: you cannot instantiate this directly
9 |
10 | ## properties
11 |
12 | ### `result.rows: Array
67 | PostgreSQL does not support parameters for identifiers. If you need to have dynamic database, schema, table, or column names (e.g. in DDL statements) use pg-format package for handling escaping these values to ensure you do not have SQL injection!
68 |
69 |
70 | Parameters passed as the second argument to `query()` will be converted to raw data types using the following rules:
71 |
72 | **null and undefined**
73 |
74 | If parameterizing `null` and `undefined` then both will be converted to `null`.
75 |
76 | **Date**
77 |
78 | Custom conversion to a UTC date string.
79 |
80 | **Buffer**
81 |
82 | Buffer instances are unchanged.
83 |
84 | **Array**
85 |
86 | Converted to a string that describes a Postgres array. Each array item is recursively converted using the rules described here.
87 |
88 | **Object**
89 |
90 | If a parameterized value has the method `toPostgres` then it will be called and its return value will be used in the query.
91 | The signature of `toPostgres` is the following:
92 |
93 | ```
94 | toPostgres (prepareValue: (value) => any): any
95 | ```
96 |
97 | The `prepareValue` function provided can be used to convert nested types to raw data types suitable for the database.
98 |
99 | Otherwise if no `toPostgres` method is defined then `JSON.stringify` is called on the parameterized value.
100 |
101 | **Everything else**
102 |
103 | All other parameterized values will be converted by calling `value.toString` on the value.
104 |
105 | ## Query config object
106 |
107 | `pool.query` and `client.query` both support taking a config object as an argument instead of taking a string and optional array of parameters. The same example above could also be performed like so:
108 |
109 | ```js
110 | const query = {
111 | text: 'INSERT INTO users(name, email) VALUES($1, $2)',
112 | values: ['brianc', 'brian.m.carlson@gmail.com'],
113 | }
114 |
115 | // callback
116 | client.query(query, (err, res) => {
117 | if (err) {
118 | console.log(err.stack)
119 | } else {
120 | console.log(res.rows[0])
121 | }
122 | })
123 |
124 | // promise
125 | client
126 | .query(query)
127 | .then(res => console.log(res.rows[0]))
128 | .catch(e => console.error(e.stack))
129 | ```
130 |
131 | The query config object allows for a few more advanced scenarios:
132 |
133 | ### Prepared statements
134 |
135 | PostgreSQL has the concept of a [prepared statement](https://www.postgresql.org/docs/9.3/static/sql-prepare.html). node-postgres supports this by supplying a `name` parameter to the query config object. If you supply a `name` parameter the query execution plan will be cached on the PostgreSQL server on a **per connection basis**. This means if you use two different connections each will have to parse & plan the query once. node-postgres handles this transparently for you: a client only requests a query to be parsed the first time that particular client has seen that query name:
136 |
137 | ```js
138 | const query = {
139 | // give the query a unique name
140 | name: 'fetch-user',
141 | text: 'SELECT * FROM user WHERE id = $1',
142 | values: [1],
143 | }
144 |
145 | // callback
146 | client.query(query, (err, res) => {
147 | if (err) {
148 | console.log(err.stack)
149 | } else {
150 | console.log(res.rows[0])
151 | }
152 | })
153 |
154 | // promise
155 | client
156 | .query(query)
157 | .then(res => console.log(res.rows[0]))
158 | .catch(e => console.error(e.stack))
159 | ```
160 |
161 | In the above example the first time the client sees a query with the name `'fetch-user'` it will send a 'parse' request to the PostgreSQL server & execute the query as normal. The second time, it will skip the 'parse' request and send the _name_ of the query to the PostgreSQL server.
162 |
163 |
168 |
169 | ### Row mode
170 |
171 | By default node-postgres reads rows and collects them into JavaScript objects with the keys matching the column names and the values matching the corresponding row value for each column. If you do not need or do not want this behavior you can pass `rowMode: 'array'` to a query object. This will inform the result parser to bypass collecting rows into a JavaScript object, and instead will return each row as an array of values.
172 |
173 | ```js
174 | const query = {
175 | text: 'SELECT $1::text as first_name, $2::text as last_name',
176 | values: ['Brian', 'Carlson'],
177 | rowMode: 'array',
178 | }
179 |
180 | // callback
181 | client.query(query, (err, res) => {
182 | if (err) {
183 | console.log(err.stack)
184 | } else {
185 | console.log(res.fields.map(field => field.name)) // ['first_name', 'last_name']
186 | console.log(res.rows[0]) // ['Brian', 'Carlson']
187 | }
188 | })
189 |
190 | // promise
191 | client
192 | .query(query)
193 | .then(res => {
194 | console.log(res.fields.map(field => field.name)) // ['first_name', 'last_name']
195 | console.log(res.rows[0]) // ['Brian', 'Carlson']
196 | })
197 | .catch(e => console.error(e.stack))
198 | ```
199 |
200 | ### Types
201 |
202 | You can pass in a custom set of type parsers to use when parsing the results of a particular query. The `types` property must conform to the [Types](/api/types) API. Here is an example in which every value is returned as a string:
203 |
204 | ```js
205 | const query = {
206 | text: 'SELECT * from some_table',
207 | types: {
208 | getTypeParser: () => val => val,
209 | },
210 | }
211 | ```
212 |
--------------------------------------------------------------------------------
/content/features/3-pooling.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: Pooling
3 | slug: /features/pooling
4 | ---
5 |
6 | If you're working on a web application or other software which makes frequent queries you'll want to use a connection pool.
7 |
8 | The easiest and by far most common way to use node-postgres is through a connection pool.
9 |
10 | ## Why?
11 |
12 | - Connecting a new client to the PostgreSQL server requires a handshake which can take 20-30 milliseconds. During this time passwords are negotiated, SSL may be established, and configuration information is shared with the client & server. Incurring this cost _every time_ we want to execute a query would substantially slow down our application.
13 |
14 | - The PostgreSQL server can only handle a [limited number of clients at a time](https://wiki.postgresql.org/wiki/Number_Of_Database_Connections). Depending on the available memory of your PostgreSQL server you may even crash the server if you connect an unbounded number of clients. _note: I have crashed a large production PostgreSQL server instance in RDS by opening new clients and never disconnecting them in a python application long ago. It was not fun._
15 |
16 | - PostgreSQL can only process one query at a time on a single connected client in a first-in first-out manner. If your multi-tenant web application is using only a single connected client all queries among all simultaneous requests will be pipelined and executed serially, one after the other. No good!
17 |
18 | ### Good news
19 |
20 | node-postgres ships with built-in connection pooling via the [pg-pool](/api/pool) module.
21 |
22 | ## Examples
23 |
24 | The client pool allows you to have a reusable pool of clients you can check out, use, and return. You generally want a limited number of these in your application and usually just 1. Creating an unbounded number of pools defeats the purpose of pooling at all.
25 |
26 | ### Checkout, use, and return
27 |
28 | ```js
29 | const { Pool } = require('pg')
30 |
31 | const pool = new Pool()
32 |
33 | // the pool will emit an error on behalf of any idle clients
34 | // it contains if a backend error or network partition happens
35 | pool.on('error', (err, client) => {
36 | console.error('Unexpected error on idle client', err)
37 | process.exit(-1)
38 | })
39 |
40 | // callback - checkout a client
41 | pool.connect((err, client, done) => {
42 | if (err) throw err
43 | client.query('SELECT * FROM users WHERE id = $1', [1], (err, res) => {
44 | done()
45 |
46 | if (err) {
47 | console.log(err.stack)
48 | } else {
49 | console.log(res.rows[0])
50 | }
51 | })
52 | })
53 |
54 | // promise - checkout a client
55 | pool
56 | .connect()
57 | .then(client => {
58 | return client
59 | .query('SELECT * FROM users WHERE id = $1', [1])
60 | .then(res => {
61 | client.release()
62 | console.log(res.rows[0])
63 | })
64 | .catch(err => {
65 | client.release()
66 | console.log(err.stack)
67 | })
68 | })
69 |
70 | // async/await - check out a client
71 | ;(async () => {
72 | const client = await pool.connect()
73 | try {
74 | const res = await client.query('SELECT * FROM users WHERE id = $1', [1])
75 | console.log(res.rows[0])
76 | } catch (err) {
77 | console.log(err.stack)
78 | } finally {
79 | client.release()
80 | }
81 | })()
82 | ```
83 |
84 |
89 |
90 | ### Single query
91 |
92 | If you don't need a transaction or you just need to run a single query, the pool has a convenience method to run a query on any available client in the pool. This is the preferred way to query with node-postgres if you can as it removes the risk of leaking a client.
93 |
94 | ```js
95 | const { Pool } = require('pg')
96 |
97 | const pool = new Pool()
98 |
99 | pool.query('SELECT * FROM users WHERE id = $1', [1], (err, res) => {
100 | if (err) {
101 | throw err
102 | }
103 |
104 | console.log('user:', res.rows[0])
105 | })
106 | ```
107 |
108 | node-postgres also has built-in support for promises throughout all of its async APIs.
109 |
110 | ```js
111 | const { Pool } = require('pg')
112 |
113 | const pool = new Pool()
114 |
115 | pool
116 | .query('SELECT * FROM users WHERE id = $1', [1])
117 | .then(res => console.log('user:', res.rows[0]))
118 | .catch(err =>
119 | setImmediate(() => {
120 | throw err
121 | })
122 | )
123 | ```
124 |
125 | Promises allow us to use `async`/`await` in node v8.0 and above (or earlier if you're using babel).
126 |
127 | ```js
128 | const { Pool } = require('pg')
129 | const pool = new Pool()
130 |
131 | ;(async () => {
132 | const { rows } = await pool.query('SELECT * FROM users WHERE id = $1', [1])
133 | console.log('user:', rows[0])
134 | })().catch(err =>
135 | setImmediate(() => {
136 | throw err
137 | })
138 | )
139 | ```
140 |
141 | ### Shutdown
142 |
143 | To shut down a pool call `pool.end()` on the pool. This will wait for all checked-out clients to be returned and then shut down all the clients and the pool timers.
144 |
145 | ```js
146 | const { Pool } = require('pg')
147 | const pool = new Pool()
148 |
149 | ;(async () => {
150 | console.log('starting async query')
151 | const result = await pool.query('SELECT NOW()')
152 | console.log('async query finished')
153 |
154 | console.log('starting callback query')
155 | pool.query('SELECT NOW()', (err, res) => {
156 | console.log('callback query finished')
157 | })
158 |
159 | console.log('calling end')
160 | await pool.end()
161 | console.log('pool has drained')
162 | })()
163 | ```
164 |
165 | The output of the above will be:
166 |
167 | ```
168 | starting async query
169 | async query finished
170 | starting callback query
171 | calling end
172 | callback query finished
173 | pool has drained
174 | ```
175 |
176 |
181 |
--------------------------------------------------------------------------------
/content/features/4-transactions.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: Transactions
3 | slug: /features/transactions
4 | ---
5 |
6 | To execute a transaction with node-postgres you simply execute `BEGIN / COMMIT / ROLLBACK` queries yourself through a client. Because node-postgres strives to be low level and un-opinionated, it doesn't provide any higher level abstractions specifically around transactions.
7 |
8 |
9 | You must use the same client instance for all statements within a transaction. PostgreSQL
10 | isolates a transaction to individual clients. This means if you initialize or use transactions with the{' '}
11 | pool.query method you will have problems. Do not use transactions with
12 | the pool.query method.
13 |
14 |
15 | ## Examples
16 |
17 | ### A pooled client with callbacks
18 |
19 | ```js
20 | const { Pool } = require('pg')
21 | const pool = new Pool()
22 |
23 | pool.connect((err, client, done) => {
24 | const shouldAbort = err => {
25 | if (err) {
26 | console.error('Error in transaction', err.stack)
27 | client.query('ROLLBACK', err => {
28 | if (err) {
29 | console.error('Error rolling back client', err.stack)
30 | }
31 | // release the client back to the pool
32 | done()
33 | })
34 | }
35 | return !!err
36 | }
37 |
38 | client.query('BEGIN', err => {
39 | if (shouldAbort(err)) return
40 | const queryText = 'INSERT INTO users(name) VALUES($1) RETURNING id'
41 | client.query(queryText, ['brianc'], (err, res) => {
42 | if (shouldAbort(err)) return
43 |
44 | const insertPhotoText = 'INSERT INTO photos(user_id, photo_url) VALUES ($1, $2)'
45 | const insertPhotoValues = [res.rows[0].id, 's3.bucket.foo']
46 | client.query(insertPhotoText, insertPhotoValues, (err, res) => {
47 | if (shouldAbort(err)) return
48 |
49 | client.query('COMMIT', err => {
50 | if (err) {
51 | console.error('Error committing transaction', err.stack)
52 | }
53 | done()
54 | })
55 | })
56 | })
57 | })
58 | })
59 | ```
60 |
61 |
67 |
68 | ### A pooled client with async/await
69 |
70 | Things are considerably more straightforward if you're using async/await:
71 |
72 | ```js
73 | const { Pool } = require('pg')
74 | const pool = new Pool()
75 | ;(async () => {
76 | // note: we don't try/catch this because if connecting throws an exception
77 | // we don't need to dispose of the client (it will be undefined)
78 | const client = await pool.connect()
79 |
80 | try {
81 | await client.query('BEGIN')
82 | const queryText = 'INSERT INTO users(name) VALUES($1) RETURNING id'
83 | const res = await client.query(queryText, ['brianc'])
84 |
85 | const insertPhotoText = 'INSERT INTO photos(user_id, photo_url) VALUES ($1, $2)'
86 | const insertPhotoValues = [res.rows[0].id, 's3.bucket.foo']
87 | await client.query(insertPhotoText, insertPhotoValues)
88 | await client.query('COMMIT')
89 | } catch (e) {
90 | await client.query('ROLLBACK')
91 | throw e
92 | } finally {
93 | client.release()
94 | }
95 | })().catch(e => console.error(e.stack))
96 | ```
97 |
--------------------------------------------------------------------------------
/content/features/5-types.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: Data Types
3 | slug: /features/types
4 | ---
5 |
6 | PostgreSQL has a rich system of supported [data types](https://www.postgresql.org/docs/9.5/static/datatype.html). node-postgres does its best to support the most common data types out of the box and supplies an extensible type parser to allow for custom type serialization and parsing.
7 |
8 | ## strings by default
9 |
10 | node-postgres will convert a database type to a JavaScript string if it doesn't have a registered type parser for the database type. Furthermore, you can send any type to the PostgreSQL server as a string and node-postgres will pass it through without modifying it in any way. To circumvent the type parsing completely do something like the following.
11 |
12 | ```js
13 | const queryText = 'SELECT int_col::text, date_col::text, json_col::text FROM my_table'
14 | const result = await client.query(queryText)
15 |
16 | console.log(result.rows[0]) // will contain the unparsed string value of each column
17 | ```
18 |
19 | ## type parsing examples
20 |
21 | ### uuid + json / jsonb
22 |
23 | There is no data type in JavaScript for a uuid/guid so node-postgres converts a uuid to a string. JavaScript has great support for JSON and node-postgres converts json/jsonb objects directly into their JavaScript object via [`JSON.parse`](https://github.com/brianc/node-pg-types/blob/master/lib/textParsers.js#L193). Likewise sending an object to the PostgreSQL server via a query from node-postgres, node-posgres will call [`JSON.stringify`](https://github.com/brianc/node-postgres/blob/e5f0e5d36a91a72dda93c74388ac890fa42b3be0/lib/utils.js#L47) on your outbound value, automatically converting it to json for the server.
24 |
25 | ```js
26 | const createTableText = `
27 | CREATE EXTENSION IF NOT EXISTS "pgcrypto";
28 |
29 | CREATE TEMP TABLE IF NOT EXISTS users (
30 | id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
31 | data JSONB
32 | );
33 | `
34 | // create our temp table
35 | await client.query(createTableText)
36 |
37 | const newUser = { email: 'brian.m.carlson@gmail.com' }
38 | // create a new user
39 | await client.query('INSERT INTO users(data) VALUES($1)', [newUser])
40 |
41 | const { rows } = await client.query('SELECT * FROM users')
42 |
43 | console.log(rows)
44 | /*
45 | output:
46 | [{
47 | id: 'd70195fd-608e-42dc-b0f5-eee975a621e9',
48 | data: { email: 'brian.m.carlson@gmail.com' }
49 | }]
50 | */
51 | ```
52 |
53 | ### date / timestamp / timestamptz
54 |
55 | node-postgres will convert instances of JavaScript date objects into the expected input value for your PostgreSQL server. Likewise, when reading a `date`, `timestamp`, or `timestamptz` column value back into JavaScript, node-postgres will parse the value into an instance of a JavaScript `Date` object.
56 |
57 | ```js
58 | const createTableText = `
59 | CREATE TEMP TABLE dates(
60 | date_col DATE,
61 | timestamp_col TIMESTAMP,
62 | timestamptz_col TIMESTAMPTZ
63 | );
64 | `
65 | // create our temp table
66 | await client.query(createTableText)
67 |
68 | // insert the current time into it
69 | const now = new Date()
70 | const insertText = 'INSERT INTO dates(date_col, timestamp_col, timestamptz_col) VALUES ($1, $2, $3)'
71 | await client.query(insertText, [now, now, now])
72 |
73 | // read the row back out
74 | const result = await client.query('SELECT * FROM dates')
75 |
76 | console.log(result.rows)
77 | // {
78 | // date_col: 2017-05-29T05:00:00.000Z,
79 | // timestamp_col: 2017-05-29T23:18:13.263Z,
80 | // timestamptz_col: 2017-05-29T23:18:13.263Z
81 | // }
82 | ```
83 |
84 | psql output:
85 |
86 | ```psql
87 | bmc=# select * from dates;
88 | date_col | timestamp_col | timestamptz_col
89 | ------------+-------------------------+----------------------------
90 | 2017-05-29 | 2017-05-29 18:18:13.263 | 2017-05-29 18:18:13.263-05
91 | (1 row)
92 | ```
93 |
94 | node-postgres converts `DATE` and `TIMESTAMP` columns into the **local** time of the node process set at `process.env.TZ`.
95 |
96 | _note: I generally use `TIMESTAMPTZ` when storing dates; otherwise, inserting a time from a process in one timezone and reading it out in a process in another timezone can cause unexpected differences in the time._
97 |
98 |
103 |
--------------------------------------------------------------------------------
/content/features/6-ssl.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: SSL
3 | slug: /features/ssl
4 | ---
5 |
6 | node-postgres supports TLS/SSL connections to your PostgreSQL server as long as the server is configured to support it. When instantiating a pool or a client you can provide an `ssl` property on the config object and it will be passed to the constructor for the [node TLSSocket](https://nodejs.org/api/tls.html#tls_class_tls_tlssocket).
7 |
8 | ## Self-signed cert
9 |
10 | Here's an example of a configuration you can use to connect a client or a pool to a PostgreSQL server.
11 |
12 | ```js
13 | const config = {
14 | database: 'database-name',
15 | host: 'host-or-ip',
16 | // this object will be passed to the TLSSocket constructor
17 | ssl: {
18 | rejectUnauthorized: false,
19 | ca: fs.readFileSync('/path/to/server-certificates/root.crt').toString(),
20 | key: fs.readFileSync('/path/to/client-key/postgresql.key').toString(),
21 | cert: fs.readFileSync('/path/to/client-certificates/postgresql.crt').toString(),
22 | },
23 | }
24 |
25 | import { Client, Pool } from 'pg'
26 |
27 | const client = new Client(config)
28 | client.connect(err => {
29 | if (err) {
30 | console.error('error connecting', err.stack)
31 | } else {
32 | console.log('connected')
33 | client.end()
34 | }
35 | })
36 |
37 | const pool = new Pool(config)
38 | pool
39 | .connect()
40 | .then(client => {
41 | console.log('connected')
42 | client.release()
43 | })
44 | .catch(err => console.error('error connecting', err.stack))
45 | .then(() => pool.end())
46 | ```
47 |
48 | ## Usage with `connectionString`
49 |
50 | If you plan to use a combination of a database connection string from the environment and SSL settings in the config object directly, then you must avoid including any of `sslcert`, `sslkey`, `sslrootcert`, or `sslmode` in the connection string. If any of these options are used then the `ssl` object is replaced and any additional options provided there will be lost.
51 |
52 | ```js
53 | const config = {
54 | connectionString: 'postgres://user:password@host:port/db?sslmode=require',
55 | // Beware! The ssl object is overwritten when parsing the connectionString
56 | ssl: {
57 | rejectUnauthorized: false,
58 | ca: fs.readFileSync('/path/to/server-certificates/root.crt').toString(),
59 | },
60 | }
61 | ```
62 |
--------------------------------------------------------------------------------
/content/features/7-native.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: Native Bindings
3 | slug: /features/native
4 | metaTitle: bar
5 | ---
6 |
7 | Native bindings between node.js & [libpq](https://www.postgresql.org/docs/9.5/static/libpq.html) are provided by the [node-pg-native](https://github.com/brianc/node-pg-native) package. node-postgres can consume this package & use the native bindings to access the PostgreSQL server while giving you the same interface that is used with the JavaScript version of the library.
8 |
9 | To use the native bindings first you'll need to install them:
10 |
11 | ```sh
12 | $ npm install pg pg-native
13 | ```
14 |
15 | Once `pg-native` is installed instead of requiring a `Client` or `Pool` constructor from `pg` you do the following:
16 |
17 | ```js
18 | const { Client, Pool } = require('pg').native
19 | ```
20 |
21 | When you access the `.native` property on `require('pg')` it will automatically require the `pg-native` package and wrap it in the same API.
22 |
23 |
24 | Care has been taken to normalize between the two, but there might still be edge cases where things behave subtly differently due to the nature of using libpq over handling the binary protocol directly in JavaScript, so it's recommended you chose to either use the JavaScript driver or the native bindings both in development and production. For what its worth: I use the pure JavaScript driver because the JavaScript driver is more portable (doesn't need a compiler), and the pure JavaScript driver is plenty fast.
25 |
26 |
27 | Some of the modules using advanced features of PostgreSQL such as [pg-query-stream](https://github.com/brianc/node-pg-query-stream), [pg-cursor](https://github.com/brianc/node-pg-cursor),and [pg-copy-streams](https://github.com/brianc/node-pg-copy-streams) need to operate directly on the binary stream and therefore are incompatible with the native bindings.
28 |
--------------------------------------------------------------------------------
/content/guides.mdx:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/brianc/node-postgres-docs/1e4fed04ff2f864968994fbc999b679b47cdf606/content/guides.mdx
--------------------------------------------------------------------------------
/content/guides/1-project-structure.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Suggested Project Structure
3 | slug: /guides/project-structure
4 | ---
5 |
6 | Whenever I am writing a project & using node-postgres I like to create a file within it and make all interactions with the database go through this file. This serves a few purposes:
7 |
8 | - Allows my project to adjust to any changes to the node-postgres API without having to trace down all the places I directly use node-postgres in my application.
9 | - Allows me to have a single place to put logging and diagnostics around my database.
10 | - Allows me to make custom extensions to my database access code & share it throughout the project.
11 | - Allows a single place to bootstrap & configure the database.
12 |
13 | ## example
14 |
15 | _note: I am using callbacks in this example to introduce as few concepts as possible at a time, but the same is doable with promises or async/await_
16 |
17 | The location doesn't really matter - I've found it usually ends up being somewhat app specific and in line with whatever folder structure conventions you're using. For this example I'll use an express app structured like so:
18 |
19 | ```
20 | - app.js
21 | - index.js
22 | - routes/
23 | - index.js
24 | - photos.js
25 | - user.js
26 | - db/
27 | - index.js <--- this is where I put data access code
28 | ```
29 |
30 | Typically I'll start out my `db/index.js` file like so:
31 |
32 | ```js
33 | const { Pool } = require('pg')
34 |
35 | const pool = new Pool()
36 |
37 | module.exports = {
38 | query: (text, params, callback) => {
39 | return pool.query(text, params, callback)
40 | },
41 | }
42 | ```
43 |
44 | That's it. But now everywhere else in my application instead of requiring `pg` directly, I'll require this file. Here's an example of a route within `routes/user.js`:
45 |
46 | ```js
47 | // notice here I'm requiring my database adapter file
48 | // and not requiring node-postgres directly
49 | const db = require('../db')
50 |
51 | app.get('/:id', (req, res, next) => {
52 | db.query('SELECT * FROM users WHERE id = $1', [req.params.id], (err, result) => {
53 | if (err) {
54 | return next(err)
55 | }
56 | res.send(result.rows[0])
57 | })
58 | })
59 |
60 | // ... many other routes in this file
61 | ```
62 |
63 | Imagine we have lots of routes scattered throughout many files under our `routes/` directory. We now want to go back and log every single query that's executed, how long it took, and the number of rows it returned. If we had required node-postgres directly in every route file we'd have to go edit every single route - that would take forever & be really error prone! But thankfully we put our data access into `db/index.js`. Let's go add some logging:
64 |
65 | ```js
66 | const { Pool } = require('pg')
67 |
68 | const pool = new Pool()
69 |
70 | module.exports = {
71 | query: (text, params, callback) => {
72 | const start = Date.now()
73 | return pool.query(text, params, (err, res) => {
74 | const duration = Date.now() - start
75 | console.log('executed query', { text, duration, rows: res.rowCount })
76 | callback(err, res)
77 | })
78 | },
79 | }
80 | ```
81 |
82 | That was pretty quick! And now all of our queries everywhere in our application are being logged.
83 |
84 | _note: I didn't log the query parameters. Depending on your application you might be storing encrypted passwords or other sensitive information in your database. If you log your query parameters you might accidentally log sensitive information. Every app is different though so do what suits you best!_
85 |
86 | Now what if we need to check out a client from the pool to run several queries in a row in a transaction? We can add another method to our `db/index.js` file when we need to do this:
87 |
88 | ```js
89 | const { Pool } = require('pg')
90 |
91 | const pool = new Pool()
92 |
93 | module.exports = {
94 | query: (text, params, callback) => {
95 | const start = Date.now()
96 | return pool.query(text, params, (err, res) => {
97 | const duration = Date.now() - start
98 | console.log('executed query', { text, duration, rows: res.rowCount })
99 | callback(err, res)
100 | })
101 | },
102 | getClient: (callback) => {
103 | pool.connect((err, client, done) => {
104 | callback(err, client, done)
105 | })
106 | }
107 | }
108 | ```
109 |
110 | Okay. Great - the simplest thing that could possibly work. It seems like one of our routes that checks out a client to run a transaction is forgetting to call `done` in some situation! Oh no! We are leaking a client & have hundreds of these routes to go audit. Good thing we have all our client access going through this single file. Lets add some deeper diagnostic information here to help us track down where the client leak is happening.
111 |
112 | ```js
113 | const { Pool } = require('pg')
114 |
115 | const pool = new Pool()
116 |
117 | module.exports = {
118 | query: (text, params, callback) => {
119 | const start = Date.now()
120 | return pool.query(text, params, (err, res) => {
121 | const duration = Date.now() - start
122 | console.log('executed query', { text, duration, rows: res.rowCount })
123 | callback(err, res)
124 | })
125 | },
126 | getClient: (callback) => {
127 | pool.connect((err, client, done) => {
128 | const query = client.query
129 |
130 | // monkey patch the query method to keep track of the last query executed
131 | client.query = (...args) => {
132 | client.lastQuery = args
133 | return query.apply(client, args)
134 | }
135 |
136 | // set a timeout of 5 seconds, after which we will log this client's last query
137 | const timeout = setTimeout(() => {
138 | console.error('A client has been checked out for more than 5 seconds!')
139 | console.error(`The last executed query on this client was: ${client.lastQuery}`)
140 | }, 5000)
141 |
142 | const release = (err) => {
143 | // call the actual 'done' method, returning this client to the pool
144 | done(err)
145 |
146 | // clear our timeout
147 | clearTimeout(timeout)
148 |
149 | // set the query method back to its old un-monkey-patched version
150 | client.query = query
151 | }
152 |
153 | callback(err, client, release)
154 | })
155 | }
156 | }
157 | ```
158 |
159 | Using async/await:
160 |
161 | ```
162 | module.exports = {
163 | async query(text, params) {
164 | const start = Date.now()
165 | const res = await pool.query(text, params)
166 | const duration = Date.now() - start
167 | console.log('executed query', { text, duration, rows: res.rowCount })
168 | return res
169 | },
170 |
171 | async getClient() {
172 | const client = await pool.connect()
173 | const query = client.query
174 | const release = client.release
175 | // set a timeout of 5 seconds, after which we will log this client's last query
176 | const timeout = setTimeout(() => {
177 | console.error('A client has been checked out for more than 5 seconds!')
178 | console.error(`The last executed query on this client was: ${client.lastQuery}`)
179 | }, 5000)
180 | // monkey patch the query method to keep track of the last query executed
181 | client.query = (...args) => {
182 | client.lastQuery = args
183 | return query.apply(client, args)
184 | }
185 | client.release = () => {
186 | // clear our timeout
187 | clearTimeout(timeout)
188 | // set the methods back to their old un-monkey-patched version
189 | client.query = query
190 | client.release = release
191 | return release.apply(client)
192 | }
193 | return client
194 | }
195 | }
196 | ```
197 | That should hopefully give us enough diagnostic information to track down any leaks.
198 |
--------------------------------------------------------------------------------
/content/guides/2-async-express.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Express with async/await
3 | slug: /guides/async-express
4 | ---
5 |
6 | My preferred way to use node-postgres (and all async code in node.js) is with `async/await`. I find it makes reasoning about control-flow easier and allows me to write more concise and maintainable code.
7 |
8 | This is how I typically structure express web-applications with node-postgres to use `async/await`:
9 |
10 | ```
11 | - app.js
12 | - index.js
13 | - routes/
14 | - index.js
15 | - photos.js
16 | - user.js
17 | - db/
18 | - index.js <--- this is where I put data access code
19 | ```
20 |
21 | That's the same structure I used in the [project structure](/guides/project-structure) example.
22 |
23 | My `db/index.js` file usually starts out like this:
24 |
25 | ```js
26 | const { Pool } = require('pg')
27 |
28 | const pool = new Pool()
29 |
30 | module.exports = {
31 | query: (text, params) => pool.query(text, params),
32 | }
33 | ```
34 |
35 | Then I will install [express-promise-router](https://www.npmjs.com/package/express-promise-router) and use it to define my routes. Here is my `routes/user.js` file:
36 |
37 | ```js
38 | const Router = require('express-promise-router')
39 |
40 | const db = require('../db')
41 |
42 | // create a new express-promise-router
43 | // this has the same API as the normal express router except
44 | // it allows you to use async functions as route handlers
45 | const router = new Router()
46 |
47 | // export our router to be mounted by the parent application
48 | module.exports = router
49 |
50 | router.get('/:id', async (req, res) => {
51 | const { id } = req.params
52 | const { rows } = await db.query('SELECT * FROM users WHERE id = $1', [id])
53 | res.send(rows[0])
54 | })
55 | ```
56 |
57 | Then in my `routes/index.js` file I'll have something like this which mounts each individual router into the main application:
58 |
59 | ```js
60 | // ./routes/index.js
61 | const users = require('./user')
62 | const photos = require('./photos')
63 |
64 | module.exports = app => {
65 | app.use('/users', users)
66 | app.use('/photos', photos)
67 | // etc..
68 | }
69 | ```
70 |
71 | And finally in my `app.js` file where I bootstrap express I will have my `routes/index.js` file mount all my routes. The routes know they're using async functions but because of express-promise-router the main express app doesn't know and doesn't care!
72 |
73 | ```js
74 | // ./app.js
75 | const express = require('express')
76 | const mountRoutes = require('./routes')
77 |
78 | const app = express()
79 | mountRoutes(app)
80 |
81 | // ... more express setup stuff can follow
82 | ```
83 |
84 | Now you've got `async/await`, node-postgres, and express all working together!
85 |
--------------------------------------------------------------------------------
/content/guides/3-upgrading.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Upgrading
3 | slug: /guides/upgrading
4 | ---
5 |
6 | # Upgrading to 8.0
7 |
8 | node-postgres at 8.0 introduces a breaking change to ssl-verified connections. If you connect with ssl and use
9 |
10 | ```
11 | const client = new Client({ ssl: true })
12 | ```
13 |
14 | and the server's SSL certificate is self-signed, connections will fail as of node-postgres 8.0. To keep the existing behavior, modify the invocation to
15 |
16 | ```
17 | const client = new Client({ ssl: { rejectUnauthorized: false } })
18 | ```
19 |
20 | The rest of the changes are relatively minor and unlikely to cause issues; see [the announcement](/announcements#2020-02-25) for full details.
21 |
22 | # Upgrading to 7.0
23 |
24 | node-postgres at 7.0 introduces somewhat significant breaking changes to the public API.
25 |
26 | ## node version support
27 |
28 | Starting with `pg@7.0` the earliest version of node supported will be `node@4.x LTS`. Support for `node@0.12.x` and `node@.10.x` is dropped, and the module wont work as it relies on new es6 features not available in older versions of node.
29 |
30 | ## pg singleton
31 |
32 | In the past there was a singleton pool manager attached to the root `pg` object in the package. This singleton could be used to provision connection pools automatically by calling `pg.connect`. This API caused a lot of confusion for users. It also introduced a opaque module-managed singleton which was difficult to reason about, debug, error-prone, and inflexible. Starting in pg@6.0 the methods' documentation was removed, and starting in pg@6.3 the methods were deprecated with a warning message.
33 |
34 | If your application still relies on these they will be _gone_ in `pg@7.0`. In order to migrate you can do the following:
35 |
36 | ```js
37 | // old way, deprecated in 6.3.0:
38 |
39 | // connection using global singleton
40 | pg.connect(function(err, client, done) {
41 | client.query(/* etc, etc */)
42 | done()
43 | })
44 |
45 | // singleton pool shutdown
46 | pg.end()
47 |
48 | // ------------------
49 |
50 | // new way, available since 6.0.0:
51 |
52 | // create a pool
53 | var pool = new pg.Pool()
54 |
55 | // connection using created pool
56 | pool.connect(function(err, client, done) {
57 | client.query(/* etc, etc */)
58 | done()
59 | })
60 |
61 | // pool shutdown
62 | pool.end()
63 | ```
64 |
65 | node-postgres ships with a built-in pool object provided by [pg-pool](https://github.com/brianc/node-pg-pool) which is already used internally by the `pg.connect` and `pg.end` methods. Migrating to a user-managed pool (or set of pools) allows you to more directly control their set up their life-cycle.
66 |
67 | ## client.query(...).on
68 |
69 | Before `pg@7.0` the `client.query` method would _always_ return an instance of a query. The query instance was an event emitter, accepted a callback, and was also a promise. A few problems...
70 |
71 | - too many flow control options on a single object was confusing
72 | - event emitter `.on('error')` does not mix well with promise `.catch`
73 | - the `row` event was a common source of errors: it looks like a stream but has no support for back-pressure, misleading users into trying to pipe results or handling them in the event emitter for a desired performance gain.
74 | - error handling with a `.done` and `.error` emitter pair for every query is cumbersome and returning the emitter from `client.query` indicated this sort of pattern may be encouraged: it is not.
75 |
76 | Starting with `pg@7.0` the return value `client.query` will be dependent on what you pass to the method: I think this aligns more with how most node libraries handle the callback/promise combo, and I hope it will make the "just works" :tm: feeling better while reducing surface area and surprises around event emitter / callback combos.
77 |
78 | ### client.query with a callback
79 |
80 | ```js
81 | const query = client.query('SELECT NOW()', (err, res) => {
82 | /* etc, etc */
83 | })
84 | assert(query === undefined) // true
85 | ```
86 |
87 | If you pass a callback to the method `client.query` will return `undefined`. This limits flow control to the callback which is in-line with almost all of node's core APIs.
88 |
89 | ### client.query without a callback
90 |
91 | ```js
92 | const query = client.query('SELECT NOW()')
93 | assert(query instanceof Promise) // true
94 | assert(query.on === undefined) // true
95 | query.then((res) => /* etc, etc */)
96 | ```
97 |
98 | If you do **not** pass a callback `client.query` will return an instance of a `Promise`. This will **not** be a query instance and will not be an event emitter. This is in line with how most promise-based APIs work in node.
99 |
100 | ### client.query(Submittable)
101 |
102 | `client.query` has always accepted any object that has a `.submit` method on it. In this scenario the client calls `.submit` on the object, delegating execution responsibility to it. In this situation the client also **returns the instance it was passed**. This is how [pg-cursor](https://github.com/brianc/node-pg-cursor) and [pg-query-stream](https://github.com/brianc/node-pg-query-stream) work. So, if you need the event emitter functionality on your queries for some reason, it is still possible because `Query` is an instance of `Submittable`:
103 |
104 | ```js
105 | const { Client, Query } = require('pg')
106 | const query = client.query(new Query('SELECT NOW()'))
107 | query.on('row', row => {})
108 | query.on('end', res => {})
109 | query.on('error', res => {})
110 | ```
111 |
112 | `Query` is considered a public, documented part of the API of node-postgres and this form will be supported indefinitely.
113 |
114 | _note: I have been building apps with node-postgres for almost 7 years. In that time I have never used the event emitter API as the primary way to execute queries. I used to use callbacks and now I use async/await. If you need to stream results I highly recommend you use [pg-cursor](https://github.com/brianc/node-pg-cursor) or [pg-query-stream](https://github.com/brianc/node-pg-query-stream) and **not** the query object as an event emitter._
115 |
--------------------------------------------------------------------------------
/content/welcome.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: Welcome
3 | slug: /
4 | ---
5 |
6 | node-postgres is a collection of node.js modules for interfacing with your PostgreSQL database. It has support for callbacks, promises, async/await, connection pooling, prepared statements, cursors, streaming results, C/C++ bindings, rich type parsing, and more! Just like PostgreSQL itself there are a lot of features: this documentation aims to get you up and running quickly and in the right direction. It also tries to provide guides for more advanced & edge-case topics allowing you to tap into the full power of PostgreSQL from node.js.
7 |
8 | ## Install
9 |
10 | ```bash
11 | $ npm install pg
12 | ```
13 |
14 | ## Supporters
15 |
16 | node-postgres continued development and support is made possible by the many [supporters](https://github.com/brianc/node-postgres/blob/master/SPONSORS.md) with a special thanks to our featured supporters:
17 |
18 |
30 |
31 | If you or your company would like to sponsor node-postgres stop by [github sponsors](https://github.com/sponsors/brianc) and sign up or feel free to [email me](mailto:brian@pecanware.com) if you want to add your logo to the documentation or discuss higher tiers of sponsorship!
32 |
33 | # Version compatibility
34 |
35 | 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 `pg@8.2.x` 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.
36 |
37 | ## Getting started
38 |
39 | This is the simplest possible way to connect, query, and disconnect with async/await:
40 |
41 | ```js
42 | const { Client } = require('pg')
43 | const client = new Client()
44 | await client.connect()
45 |
46 | const res = await client.query('SELECT $1::text as message', ['Hello world!'])
47 | console.log(res.rows[0].message) // Hello world!
48 | await client.end()
49 | ```
50 |
51 | And here's the same thing with callbacks:
52 |
53 | ```js
54 | const { Client } = require('pg')
55 | const client = new Client()
56 |
57 | client.connect()
58 |
59 | client.query('SELECT $1::text as message', ['Hello world!'], (err, res) => {
60 | console.log(err ? err.stack : res.rows[0].message) // Hello World!
61 | client.end()
62 | })
63 | ```
64 |
65 | Our real-world apps are almost always more complicated than that, and I urge you to read on!
66 |
--------------------------------------------------------------------------------
/gatsby-config.js:
--------------------------------------------------------------------------------
1 | require("dotenv").config();
2 | const config = require("./config");
3 | module.exports = {
4 | pathPrefix: config.gatsby.pathPrefix,
5 | siteMetadata: {
6 | title: config.siteMetadata.title,
7 | description: config.siteMetadata.description,
8 | docsLocation: config.siteMetadata.docsLocation,
9 | ogImage: config.siteMetadata.ogImage,
10 | favicon: config.siteMetadata.favicon,
11 | logo: config.header.logo,
12 | headerTitle: config.header.title,
13 | githubUrl: config.header.githubUrl,
14 | helpUrl: config.header.helpUrl,
15 | tweetText: config.header.tweetText,
16 | headerLinks: config.header.links,
17 | siteUrl: config.gatsby.siteUrl,
18 | },
19 | plugins: [
20 | 'gatsby-plugin-sitemap',
21 | 'gatsby-plugin-sharp',
22 | {
23 | resolve: `gatsby-plugin-layout`,
24 | options: {
25 | component: require.resolve(`./src/templates/docs.js`)
26 | }
27 | },
28 | {
29 | resolve: 'gatsby-plugin-mdx',
30 | options: {
31 | gatsbyRemarkPlugins: [
32 | {
33 | resolve: 'gatsby-remark-autolink-headers',
34 | options: {
35 | icon: false
36 | }
37 | },
38 | {
39 | resolve: "gatsby-remark-images",
40 | options: {
41 | maxWidth: 1035,
42 | sizeByPixelDensity: true
43 | }
44 | },
45 | {
46 | resolve: 'gatsby-remark-copy-linked-files'
47 | }
48 | ],
49 | extensions: [".mdx", ".md"]
50 | }
51 | },
52 | 'gatsby-plugin-emotion',
53 | 'gatsby-plugin-remove-trailing-slashes',
54 | 'gatsby-plugin-react-helmet',
55 | {
56 | resolve: "gatsby-source-filesystem",
57 | options: {
58 | name: "docs",
59 | path: `${__dirname}/content/`
60 | }
61 | },
62 | {
63 | resolve: `gatsby-plugin-gtag`,
64 | options: {
65 | // your google analytics tracking id
66 | trackingId: config.gatsby.gaTrackingId,
67 | // Puts tracking script in the head instead of the body
68 | head: true,
69 | // enable ip anonymization
70 | anonymize: false,
71 | },
72 | },
73 | ]
74 | };
75 |
--------------------------------------------------------------------------------
/gatsby-node.js:
--------------------------------------------------------------------------------
1 | const path = require('path')
2 | const startCase = require('lodash.startcase')
3 |
4 | exports.createPages = ({ graphql, actions }) => {
5 | const { createPage } = actions
6 | return new Promise((resolve, reject) => {
7 | resolve(
8 | graphql(
9 | `
10 | {
11 | allMdx {
12 | edges {
13 | node {
14 | fields {
15 | id
16 | slug
17 | }
18 | }
19 | }
20 | }
21 | }
22 | `
23 | ).then(result => {
24 | if (result.errors) {
25 | console.log(result.errors) // eslint-disable-line no-console
26 | reject(result.errors)
27 | }
28 |
29 | // Create blog posts pages.
30 | result.data.allMdx.edges.forEach(({ node }) => {
31 | createPage({
32 | path: node.fields.slug ? node.fields.slug : '/',
33 | component: path.resolve('./src/templates/docs.js'),
34 | context: {
35 | id: node.fields.id,
36 | },
37 | })
38 | })
39 | })
40 | )
41 | })
42 | }
43 |
44 | exports.onCreateWebpackConfig = ({ actions }) => {
45 | actions.setWebpackConfig({
46 | resolve: {
47 | modules: [path.resolve(__dirname, 'src'), 'node_modules'],
48 | alias: { $components: path.resolve(__dirname, 'src/components') },
49 | },
50 | })
51 | }
52 |
53 | exports.onCreateBabelConfig = ({ actions }) => {
54 | actions.setBabelPlugin({
55 | name: '@babel/plugin-proposal-export-default-from',
56 | })
57 | }
58 |
59 | exports.onCreateNode = ({ node, getNode, actions }) => {
60 | const { createNodeField } = actions
61 |
62 | if (node.internal.type === `Mdx`) {
63 | const parent = getNode(node.parent)
64 | let value = parent.relativePath.replace(parent.ext, '')
65 |
66 | const filename = path.basename(getNode(node.id).fileAbsolutePath)
67 |
68 | if (value === 'index') {
69 | value = ''
70 | }
71 |
72 | createNodeField({
73 | name: `slug`,
74 | node,
75 | value: node.frontmatter.slug || `/${value}`,
76 | })
77 |
78 | createNodeField({
79 | name: 'filename',
80 | node,
81 | value: filename,
82 | })
83 |
84 | createNodeField({
85 | name: 'id',
86 | node,
87 | value: node.id,
88 | })
89 |
90 | createNodeField({
91 | name: 'title',
92 | node,
93 | value: node.frontmatter.title || startCase(parent.name),
94 | })
95 | }
96 | }
97 |
--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
1 | {
2 | "name": "node-postgres-docs",
3 | "private": true,
4 | "description": "node-postgres (npm install pg) documentation",
5 | "author": "Brian M. Carlson",
6 | "version": "1.0.0",
7 | "dependencies": {
8 | "@babel/plugin-proposal-export-default-from": "^7.0.0",
9 | "@emotion/core": "^10.0.10",
10 | "@emotion/styled-base": "^10.0.10",
11 | "@mdx-js/loader": "^1.0.10",
12 | "@mdx-js/mdx": "^1.0.10",
13 | "@mdx-js/react": "^1.0.6",
14 | "@playlyfe/gql": "^2.6.1",
15 | "dotenv": "^6.2.0",
16 | "emotion": "^10.0.9",
17 | "emotion-server": "^10.0.9",
18 | "emotion-theming": "^10.0.10",
19 | "gatsby": "2.13.23",
20 | "gatsby-link": "^2.1.1",
21 | "gatsby-plugin-emotion": "3.0.1",
22 | "gatsby-plugin-gtag": "^1.0.10",
23 | "gatsby-plugin-layout": "^1.0.15",
24 | "gatsby-plugin-mdx": "^1.2.22",
25 | "gatsby-plugin-react-helmet": "3.0.12",
26 | "gatsby-plugin-sharp": "^2.0.35",
27 | "gatsby-plugin-sitemap": "^2.0.12",
28 | "gatsby-remark-autolink-headers": "^2.3.5",
29 | "gatsby-remark-copy-linked-files": "^2.0.11",
30 | "gatsby-remark-images": "3.0.10",
31 | "gatsby-source-filesystem": "^2.0.29",
32 | "gatsby-transformer-remark": "^2.3.8",
33 | "graphql": "^14.2.1",
34 | "is-absolute-url": "^2.1.0",
35 | "lodash.flatten": "^4.4.0",
36 | "lodash.startcase": "^4.4.0",
37 | "react": "^16.8.6",
38 | "react-dom": "^16.8.6",
39 | "react-emotion": "^9.1.3",
40 | "react-feather": "^1.1.6",
41 | "react-github-btn": "^1.0.5",
42 | "react-helmet": "^5.2.0",
43 | "react-live": "^2.0.1",
44 | "system-components": "^3.0.3"
45 | },
46 | "license": "MIT",
47 | "main": "n/a",
48 | "scripts": {
49 | "start": "gatsby develop",
50 | "build": "gatsby build --prefix-paths",
51 | "deploy": "yarn build && gh-pages -d public"
52 | },
53 | "devDependencies": {
54 | "gatsby-plugin-remove-trailing-slashes": "^2.0.11",
55 | "gh-pages": "2.0.1",
56 | "prettier": "1.18.2",
57 | "prism-react-renderer": "^0.1.6"
58 | },
59 | "prettier": {
60 | "printWidth": 120,
61 | "semi": false,
62 | "trailingComma": "es5",
63 | "singleQuote": true
64 | }
65 | }
66 |
--------------------------------------------------------------------------------
/src/GithubLink.js:
--------------------------------------------------------------------------------
1 | import React from 'react'
2 | const githubIcon = require('./components/images/github.svg')
3 | import './components/styles.css'
4 |
5 | const GithubLink = ({ link, text }) => {
6 | return (
7 |
8 | 
22 | 
27 |
7 |
15 |
16 | )
17 | }
18 |
19 | export default YoutubeEmbed
20 |
--------------------------------------------------------------------------------
/src/components/Header.js:
--------------------------------------------------------------------------------
1 | import React from 'react'
2 | import { StaticQuery, graphql } from 'gatsby'
3 | import GitHubButton from 'react-github-btn'
4 | import Link from './link'
5 | import './styles.css'
6 |
7 | import Sidebar from './sidebar'
8 |
9 | const Header = ({ location }) => (
10 |
37 |
104 |
105 | )
106 | }}
107 | />
108 | )
109 |
110 | export default Header
111 |
--------------------------------------------------------------------------------
/src/components/NextPrevious.js:
--------------------------------------------------------------------------------
1 | import React from 'react';
2 | import Link from "./link";
3 | import './styles.css';
4 | class NextPrevious extends React.Component {
5 | render() {
6 | const { mdx, nav } = this.props;
7 | let currentIndex;
8 | const currentPaginationInfo = nav.map((el, index) => {
9 | if (el.url === mdx.fields.slug) {
10 | currentIndex = index;
11 | }
12 | });
13 | const nextInfo = {};
14 | const previousInfo = {};
15 | if (currentIndex === undefined) { // index
16 | nextInfo.url = nav[0].url;
17 | nextInfo.title = nav[0].title;
18 | previousInfo.url = null;
19 | previousInfo.title = null;
20 | currentIndex = -1;
21 | } else if (currentIndex === 0) { // first page
22 | nextInfo.url = nav[currentIndex+1] ? nav[currentIndex+1].url : null;
23 | nextInfo.title = nav[currentIndex+1] ? nav[currentIndex+1].title : null;
24 | previousInfo.url = null;
25 | previousInfo.title = null;
26 | } else if (currentIndex === (nav.length-1)) { // last page
27 | nextInfo.url = null;
28 | nextInfo.title = null;
29 | previousInfo.url = nav[currentIndex-1] ? nav[currentIndex-1].url : null;
30 | previousInfo.title = nav[currentIndex-1] ? nav[currentIndex-1].title : null;
31 | } else if (currentIndex) { // any other page
32 | nextInfo.url = nav[currentIndex+1].url;
33 | nextInfo.title = nav[currentIndex+1].title;
34 | previousInfo.url = nav[currentIndex-1].url;
35 | previousInfo.title = nav[currentIndex-1].title;
36 | }
37 | return (
38 |
39 | {previousInfo.url && currentIndex >= 0 ?
40 | (
41 |
70 | );
71 | }
72 | }
73 |
74 | export default NextPrevious;
75 |
--------------------------------------------------------------------------------
/src/components/container.js:
--------------------------------------------------------------------------------
1 | import system from "system-components/emotion";
2 |
3 | const Container = system(
4 | {
5 | is: "div",
6 | px: 3,
7 | mx: "auto",
8 | maxWidth: 1024
9 | },
10 | "maxWidth"
11 | );
12 | Container.displayName = "Container";
13 |
14 | export default Container;
15 |
--------------------------------------------------------------------------------
/src/components/footer.js:
--------------------------------------------------------------------------------
1 | import React, { Component } from 'react'
2 |
3 | export default class Footer extends Component {
4 | state = { over: false }
5 |
6 | onEnter = () => {
7 | this.setState({ over: true })
8 | }
9 |
10 | onLeave = () => {
11 | this.setState({ over: false })
12 | }
13 |
14 | render() {
15 | const { over } = this.state
16 |
17 | const style = {
18 | color: '#AAA',
19 | fontSize: 12,
20 | paddingBottom: 20,
21 | }
22 |
23 | const iconClasses = `fa fa-heart ${over ? 'beat' : ''}`
24 |
25 | return (
26 |
42 |
43 |
44 |
45 |
52 | ) : null
53 | }
54 | {nextInfo.url && currentIndex >= 0 ?
55 | (
56 |
46 | Previous
47 |
48 |
49 | {nav[currentIndex-1].title}
50 |
51 |
57 |
64 |
58 | Next
59 |
60 |
61 | {nav[currentIndex+1] && nav[currentIndex+1].title}
62 |
63 |
65 |
66 |
67 | ) : null
68 | }
69 |
27 |
38 | )
39 | }
40 | }
41 |
--------------------------------------------------------------------------------
/src/components/heading.js:
--------------------------------------------------------------------------------
1 | import system from "system-components/emotion";
2 |
3 | const Heading = system(
4 | {
5 | is: "h2",
6 | fontSize: 5,
7 | fontWeight: "700",
8 | lineHeight: 1.5,
9 | mt: 4,
10 | mb: 3
11 | },
12 | "fontFamily",
13 | "color",
14 | "textAlign"
15 | );
16 | Heading.displayName = "Heading";
17 |
18 | export default Heading;
19 |
--------------------------------------------------------------------------------
/src/components/images/github.svg:
--------------------------------------------------------------------------------
1 |
2 |
3 |
13 |
--------------------------------------------------------------------------------
/src/components/images/logo.svg:
--------------------------------------------------------------------------------
1 |
2 |
3 |
24 |
--------------------------------------------------------------------------------
/src/components/images/twitter.svg:
--------------------------------------------------------------------------------
1 |
2 |
3 |
15 |
--------------------------------------------------------------------------------
/src/components/index.js:
--------------------------------------------------------------------------------
1 | export theme from "./theme";
2 | export mdxComponents from "./mdxComponents";
3 | export ThemeProvider from "./themeProvider";
4 | export Layout from "./layout";
5 | export Container from "./container";
6 | export Heading from "./heading";
7 | export Notification from "./notification";
8 | export Link from "./link";
9 |
--------------------------------------------------------------------------------
/src/components/layout.js:
--------------------------------------------------------------------------------
1 | import React from 'react'
2 | import styled from 'react-emotion'
3 | import { MDXProvider } from '@mdx-js/react'
4 | import ThemeProvider from './themeProvider'
5 | import mdxComponents from './mdxComponents'
6 | import Sidebar from './sidebar'
7 | import RightSidebar from './rightSidebar'
8 |
9 | const Wrapper = styled('div')`
10 | display: flex;
11 | justify-content: space-between;
12 |
13 | @media only screen and (max-width: 767px) {
14 | display: block;
15 | }
16 | `
17 |
18 | const Content = styled('main')`
19 | display: flex;
20 | flex-grow: 1;
21 | margin: 0px 88px;
22 | margin-top: 3rem;
23 |
24 | @media only screen and (max-width: 1023px) {
25 | padding-left: 0;
26 | margin: 0 10px;
27 | margin-top: 3rem;
28 | }
29 | `
30 |
31 | const MaxWidth = styled('div')`
32 | @media only screen and (max-width: 50rem) {
33 | width: 100%;
34 | position: relative;
35 | }
36 | `
37 | const LeftSideBarWidth = styled('div')`
38 | width: 298px;
39 | `
40 | const RightSideBarWidth = styled('div')`
41 | width: 224px;
42 | `
43 | const Layout = ({ children, location }) => (
44 |
28 |
29 | made with
30 |
31 | by
32 |
33 | @briancarlson
34 |
35 |
36 |
37 |
42 | {cleanTokens(tokens).map((line, i) => {
43 | let lineClass = {};
44 | let isDiff = false;
45 | if (line[0] && line[0].content.length && line[0].content[0] === '+') {
46 | lineClass = {'backgroundColor': 'rgba(76, 175, 80, 0.2)'};
47 | isDiff = true;
48 | }
49 | else if (line[0] && line[0].content.length && line[0].content[0] === '-') {
50 | lineClass = {'backgroundColor': 'rgba(244, 67, 54, 0.2)'};
51 | isDiff = true;
52 | }
53 | else if(line[0] && line[0].content === '' && line[1] && line[1].content === '+') {
54 | lineClass = {'backgroundColor': 'rgba(76, 175, 80, 0.2)'};
55 | isDiff = true;
56 | } else if(line[0] && line[0].content === ''&& line[1] && line[1].content === '-') {
57 | lineClass = {'backgroundColor': 'rgba(244, 67, 54, 0.2)'};
58 | isDiff = true;
59 | }
60 | const lineProps = getLineProps({line, key: i});
61 | lineProps.style = lineClass;
62 | const diffStyle = {'userSelect': 'none', '-moz-user-select': '-moz-none'};
63 | let splitToken;
64 | return (
65 |
66 | {line.map((token, key) => {
67 | if(isDiff) {
68 | if ((key === 0 || key === 1) & (token.content.charAt(0) === '+' || token.content.charAt(0) === '-')) {
69 | if(token.content.length > 1) {
70 | splitToken = { 'types': ['template-string','string'], 'content': token.content.slice(1)};
71 | const firstChar = { 'types': ['operator'], 'content': token.content.charAt(0)};
72 | return (
73 |
74 |
75 |
76 |
77 | )
78 | } else {
79 | return (
80 |
81 | )
82 |
83 | }
84 | }
85 | }
86 | return ()
87 | } )}
88 |
89 | )})}
90 |
91 | )}
92 | -
115 |
CONTENTS
116 | {finalNavItems}
117 | 111 |
-
172 | {nav}
173 |
9 |
11 | {children}
12 |
13 |
14 | );
15 | }
16 |
--------------------------------------------------------------------------------
/src/html.js:
--------------------------------------------------------------------------------
1 | import React from 'react'
2 | import PropTypes from 'prop-types'
3 | import config from '../config'
4 |
5 | export default class HTML extends React.Component {
6 | render() {
7 | return (
8 |
9 |
10 |
11 |
12 |
13 | {config.siteMetadata.ogImage ? : null}
14 |
15 | {config.siteMetadata.ogImage ? : null}
16 | {config.siteMetadata.favicon ? (
17 |
18 | ) : null}
19 |
25 |
26 |
31 |
36 | {this.props.headComponents}
37 |
38 |
39 | {this.props.preBodyComponents}
40 |
41 | {this.props.postBodyComponents}
42 |
53 |
54 |
55 | )
56 | }
57 | }
58 |
59 | HTML.propTypes = {
60 | htmlAttributes: PropTypes.object,
61 | headComponents: PropTypes.array,
62 | bodyAttributes: PropTypes.object,
63 | preBodyComponents: PropTypes.array,
64 | body: PropTypes.string,
65 | postBodyComponents: PropTypes.array,
66 | }
67 |
--------------------------------------------------------------------------------
/src/sortNavItems.js:
--------------------------------------------------------------------------------
1 | import config from '../config'
2 | const forcedNavOrder = config.sidebar.forcedNavOrder
3 |
4 | // TODO(bmc) this entire file makes me sad - need to refactor this when I have more time
5 | // most of this was forked from the open source repo I cloned and quickly banged into shape
6 | export default function getSortedNavItems(allMdx) {
7 | const allFields = allMdx.edges.map(({ node }) => node.fields || {})
8 | const navItems = allMdx.edges
9 | .map(({ node }) => node.fields)
10 | .reduce(
11 | (acc, fields) => {
12 | const { slug: cur, title } = fields
13 |
14 | const containingSlug = allFields.find(({ slug: otherSlug }) => {
15 | // is this slug contained within another one (e.g. is this a 'header' slug?)
16 | return cur !== '/' && cur !== otherSlug && otherSlug.indexOf(cur) === 0
17 | })
18 |
19 | const newItem = {
20 | title,
21 | hasChildren: Boolean(containingSlug),
22 | url: cur,
23 | slug: cur,
24 | filename: fields.filename.name,
25 | }
26 |
27 | const prefix = '/' + cur.split('/')[1]
28 |
29 | if (forcedNavOrder.some(url => url === prefix)) {
30 | return { ...acc, [prefix]: [...acc[prefix] || [], { ...newItem }] }
31 | } else {
32 | return { ...acc, items: [...acc.items, newItem] }
33 | }
34 | },
35 | { items: [] }
36 | )
37 |
38 | const sortedTree = forcedNavOrder
39 | .reduce((acc, cur) => {
40 | const things = navItems[cur].sort((a, b) => {
41 | if (!a.hasChildren && !b.hasChildren) {
42 | return a.filename.localeCompare(b.filename)
43 | }
44 | })
45 | return acc.concat(things)
46 | }, [])
47 | .concat(navItems.items)
48 | return sortedTree
49 | }
50 |
--------------------------------------------------------------------------------
/src/templates/docs.js:
--------------------------------------------------------------------------------
1 | import React, { Component } from 'react'
2 | import Footer from '../components/footer'
3 | import Helmet from 'react-helmet'
4 | import { graphql } from 'gatsby'
5 | import { MDXRenderer } from 'gatsby-plugin-mdx'
6 | import styled, { injectGlobal } from 'react-emotion'
7 | import { Layout, Link } from '$components'
8 | import NextPrevious from '../components/NextPrevious'
9 | import '../components/styles.css'
10 | import config from '../../config'
11 | import getSortedNavItems from '../sortNavItems'
12 |
13 | injectGlobal`
14 | * {
15 | margin: 0;
16 | padding: 0;
17 | box-sizing: border-box;
18 | }
19 |
20 | html, body {
21 | font-family: -apple-system,
22 | BlinkMacSystemFont,
23 | "Segoe UI",
24 | "Roboto",
25 | "Roboto Light",
26 | "Oxygen",
27 | "Ubuntu",
28 | "Cantarell",
29 | "Fira Sans",
30 | "Droid Sans",
31 | "Helvetica Neue",
32 | sans-serif,
33 | "Apple Color Emoji",
34 | "Segoe UI Emoji",
35 | "Segoe UI Symbol";
36 |
37 | font-size: 16px;
38 | }
39 |
40 | a {
41 | transition: color 0.15s;
42 | color: #663399;
43 | }
44 | `
45 |
46 | const Edit = styled('div')`
47 | padding: 1rem 1.5rem;
48 | text-align: right;
49 |
50 | a {
51 | font-size: 14px;
52 | font-weight: 500;
53 | line-height: 1em;
54 | text-decoration: none;
55 | color: #555;
56 | border: 1px solid rgb(211, 220, 228);
57 | cursor: pointer;
58 | border-radius: 3px;
59 | transition: all 0.2s ease-out 0s;
60 | text-decoration: none;
61 | color: rgb(36, 42, 49);
62 | background-color: rgb(255, 255, 255);
63 | box-shadow: rgba(116, 129, 141, 0.1) 0px 1px 1px 0px;
64 | height: 30px;
65 | padding: 5px 16px;
66 | &:hover {
67 | background-color: rgb(245, 247, 249);
68 | }
69 | }
70 | `
71 |
72 | export default class MDXRuntimeTest extends Component {
73 | render() {
74 | const { data } = this.props
75 | const {
76 | allMdx,
77 | mdx,
78 | site: {
79 | siteMetadata: { docsLocation, title },
80 | },
81 | } = data
82 | const gitHub = require('../components/images/github.svg')
83 |
84 | const nav = getSortedNavItems(allMdx).filter(x => !x.hasChildren)
85 |
86 | // meta tags
87 | const metaTitle = mdx.fields.title
88 | const metaDescription = mdx.frontmatter.metaDescription
89 | let canonicalUrl = config.gatsby.siteUrl
90 | canonicalUrl = config.gatsby.pathPrefix !== '/' ? canonicalUrl + config.gatsby.pathPrefix : canonicalUrl
91 | canonicalUrl = canonicalUrl + mdx.fields.slug
92 |
93 | return (
94 |
110 |
112 |
113 | 
Edit on GitHub
114 |
115 |
116 |
117 | {mdx.fields.title}
111 |
118 | {mdx.body}
119 |
120 |
121 |
123 |
124 |