1  pg-connection-string
  2  ====================
  3  
  4  [![NPM](https://nodei.co/npm/pg-connection-string.png?compact=true)](https://nodei.co/npm/pg-connection-string/)
  5  
  6  Functions for dealing with a PostgresSQL connection string
  7  
  8  `parse` method taken from [node-postgres](https://github.com/brianc/node-postgres.git)
  9  Copyright (c) 2010-2014 Brian Carlson (brian.m.carlson@gmail.com)
 10  MIT License
 11  
 12  ## Usage
 13  
 14  ```js
 15  const parse = require('pg-connection-string').parse;
 16  
 17  const config = parse('postgres://someuser:somepassword@somehost:381/somedatabase')
 18  ```
 19  
 20  The resulting config contains a subset of the following properties:
 21  
 22  * `user` - User with which to authenticate to the server
 23  * `password` - Corresponding password
 24  * `host` - Postgres server hostname or, for UNIX domain sockets, the socket filename
 25  * `port` - port on which to connect
 26  * `database` - Database name within the server
 27  * `client_encoding` - string encoding the client will use
 28  * `ssl`, either a boolean or an object with properties
 29    * `rejectUnauthorized`
 30    * `cert`
 31    * `key`
 32    * `ca`
 33  * any other query parameters (for example, `application_name`) are preserved intact.
 34  
 35  ### ClientConfig Compatibility for TypeScript
 36  
 37  The pg-connection-string `ConnectionOptions` interface is not compatible with the `ClientConfig` interface that [pg.Client](https://node-postgres.com/apis/client) expects. To remedy this, use the `parseIntoClientConfig` function instead of `parse`:
 38  
 39  ```ts
 40  import { ClientConfig } from 'pg';
 41  import { parseIntoClientConfig } from 'pg-connection-string';
 42  
 43  const config: ClientConfig = parseIntoClientConfig('postgres://someuser:somepassword@somehost:381/somedatabase')
 44  ```
 45  
 46  You can also use `toClientConfig` to convert an existing `ConnectionOptions` interface into a `ClientConfig` interface:
 47  
 48  ```ts
 49  import { ClientConfig } from 'pg';
 50  import { parse, toClientConfig } from 'pg-connection-string';
 51  
 52  const config = parse('postgres://someuser:somepassword@somehost:381/somedatabase')
 53  const clientConfig: ClientConfig = toClientConfig(config)
 54  ```
 55  
 56  ## Connection Strings
 57  
 58  The short summary of acceptable URLs is:
 59  
 60   * `socket:<path>?<query>` - UNIX domain socket
 61   * `postgres://<user>:<password>@<host>:<port>/<database>?<query>` - TCP connection
 62  
 63  But see below for more details.
 64  
 65  ### UNIX Domain Sockets
 66  
 67  When user and password are not given, the socket path follows `socket:`, as in `socket:/var/run/pgsql`.
 68  This form can be shortened to just a path: `/var/run/pgsql`.
 69  
 70  When user and password are given, they are included in the typical URL positions, with an empty `host`, as in `socket://user:pass@/var/run/pgsql`.
 71  
 72  Query parameters follow a `?` character, including the following special query parameters:
 73  
 74   * `db=<database>` - sets the database name (urlencoded)
 75   * `encoding=<encoding>` - sets the `client_encoding` property
 76  
 77  ### TCP Connections
 78  
 79  TCP connections to the Postgres server are indicated with `pg:` or `postgres:` schemes (in fact, any scheme but `socket:` is accepted).
 80  If username and password are included, they should be urlencoded.
 81  The database name, however, should *not* be urlencoded.
 82  
 83  Query parameters follow a `?` character, including the following special query parameters:
 84   * `host=<host>` - sets `host` property, overriding the URL's host
 85   * `encoding=<encoding>` - sets the `client_encoding` property
 86   * `ssl=1`, `ssl=true`, `ssl=0`, `ssl=false` - sets `ssl` to true or false, accordingly
 87   * `uselibpqcompat=true` - use libpq semantics
 88   * `sslmode=<sslmode>` when `uselibpqcompat=true` is not set
 89     * `sslmode=disable` - sets `ssl` to false
 90     * `sslmode=no-verify` - sets `ssl` to `{ rejectUnauthorized: false }`
 91     * `sslmode=prefer`, `sslmode=require`, `sslmode=verify-ca`, `sslmode=verify-full` - sets `ssl` to true
 92   * `sslmode=<sslmode>` when `uselibpqcompat=true`
 93     * `sslmode=disable` - sets `ssl` to false
 94     * `sslmode=prefer` - sets `ssl` to `{ rejectUnauthorized: false }`
 95     * `sslmode=require` - sets `ssl` to `{ rejectUnauthorized: false }` unless `sslrootcert` is specified, in which case it behaves like `verify-ca`
 96     * `sslmode=verify-ca` - sets `ssl` to `{ checkServerIdentity: no-op }` (verify CA, but not server identity). This verifies the presented certificate against the effective CA specified in sslrootcert.
 97     * `sslmode=verify-full` - sets `ssl` to `{}` (verify CA and server identity)
 98   * `sslcert=<filename>` - reads data from the given file and includes the result as `ssl.cert`
 99   * `sslkey=<filename>` - reads data from the given file and includes the result as `ssl.key`
100   * `sslrootcert=<filename>` - reads data from the given file and includes the result as `ssl.ca`
101  
102  A bare relative URL, such as `salesdata`, will indicate a database name while leaving other properties empty.
103  
104  > [!CAUTION]
105  > Choosing an sslmode other than verify-full has serious security implications. Please read https://www.postgresql.org/docs/current/libpq-ssl.html#LIBPQ-SSL-SSLMODE-STATEMENTS to understand the trade-offs.