Merge pull request #36 from djmitche/format-docs

Include documentation on the URL format in the README

Author: hjr3

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.