From b4e0ba329ade3d976e0804dd0d79438274e7233f Mon Sep 17 00:00:00 2001
From: "Dustin J. Mitchell" <dustin@mozilla.com>
Date: Sun, 16 Feb 2020 12:30:46 -0500
Subject: [PATCH] Include documentation on the URL format in the README

This summarizes the common forms, but omits some of the more particular,
and unnecessary forms, such as specifying UNIX domain sockets with
`pg://` URLs.
---
 README.md | 51 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 51 insertions(+)

diff --git a/README.md b/README.md
index 4943d885..d5b45ab9 100644
--- a/README.md
+++ b/README.md
@@ -19,3 +19,54 @@ var parse = require('pg-connection-string').parse;
 
 var config = parse('postgres://someuser:somepassword@somehost:381/somedatabase')
 ```
+
+The resulting config contains a subset of the following properties:
+
+* `host` - Postgres server hostname or, for UNIX doamain sockets, the socket filename
+* `port` - port on which to connect
+* `user` - User with which to authenticate to the server
+* `password` - Corresponding password
+* `database` - Database name within the server
+* `client_encoding` - string encoding the client will use
+* `ssl`, either a boolean or an object with properties
+  * `cert`
+  * `key`
+  * `ca`
+* any other query parameters (for example, `application_name`) are preserved intact.
+
+## Connection Strings
+
+The short summary of acceptable URLs is:
+
+ * `socket:<path>?<query>` - UNIX domain socket
+ * `postgres://<user>:<password>@<host>:<port>/<database>?<query>` - TCP connection
+
+But see below for more details.
+
+### UNIX Domain Sockets
+
+When user and password are not given, the socket path follows `socket:`, as in `socket:/var/run/pgsql`.
+This form can be shortened to just a path: `/var/run/pgsql`.
+
+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`.
+
+Query parameters follow a `?` character, including the following special query parameters:
+
+ * `db=<database>` - sets the database name (urlencoded)
+ * `encoding=<encoding>` - sets the `client_encoding` property
+
+### TCP Connections
+
+TCP connections to the Postgres server are indicated with `pg:` or `postgres:` schemes (in fact, any scheme but `socket:` is accepted).
+If username and password are included, they should be urlencoded.
+The database name, however, should *not* be urlencoded.
+
+Query parameters follow a `?` character, including the following special query parameters:
+ * `host=<host>` - sets `host` property, overriding the URL's host
+ * `encoding=<encoding>` - sets the `client_encoding` property
+ * `ssl=1`, `ssl=true`, `ssl=0`, `ssl=false` - sets `ssl` to true or false, accordingly
+ * `sslcert=<filename>` - reads data from the given file and includes the result as `ssl.cert`
+ * `sslkey=<filename>` - reads data from the given file and includes the result as `ssl.key`
+ * `sslrootcert=<filename>` - reads data from the given file and includes the result as `ssl.ca`
+
+A bare relative URL, such as `salesdata`, will indicate a database name while leaving other properties empty.