readme update + contributing.md

Author: tanner0101

.github/contributing.md

@@ -0,0 +1,29 @@
+# Contributing to PostgresNIO
+
+👋 Welcome to the Vapor team! 
+
+## Testing
+
+To run this package's tests, you need to start a local Postgres database. The easiest way to do this is using Docker.
+
+If you have Docker installed and running, you can use the `docker-compose` included with this package. The following command will download the required files and boot a local Postgres server:
+
+```fish
+docker-compose up psql-12
+```
+
+Run this in the project's root folder (where the `docker-compose.yml` file is). Check out that file to see the other versions of Postgres you can test against.
+
+Once you have a server running, you can run the test suite from Xcode by hitting `CMD+u` or from the command line:
+
+```fish
+swift test
+```
+
+Make sure to add tests for any new code you write.
+
+----------
+
+Join us on Discord if you have any questions: [http://vapor.team](http://vapor.team).
+
+— Thanks! 🙌

README.md

@@ -96,6 +96,7 @@ let conn = try PostgresConnection.connect(
     to: .makeAddressResolvingHost("my.psql.server", port: 5432),
     on: eventLoop
 ).wait()
+defer { try! conn.close().wait() }
 ```
 
 Note: These examples will make use of `wait()` for simplicity. This is appropriate if you are using PostgresNIO on the main thread, like for a CLI tool or in tests. However, you should never use `wait()` on an event loop.
@@ -111,18 +112,32 @@ There are also some additional arguments you can supply to `connect`.
 - `tlsConfiguration` An optional `TLSConfiguration` struct. If supplied, the PostgreSQL connection will be upgraded to use SSL.
 - `serverHostname` An optional `String` to use in conjunction with `tlsConfiguration` to specify the server's hostname. 
 
-`connect` will return a future `PostgresConnection`, or an error if it could not connect.
+`connect` will return a future `PostgresConnection`, or an error if it could not connect. Make sure you close the connection before it deinitializes.
 
-### Client Protocol
+### Authentication
 
-Interaction with a server revolves around the `PostgresClient` protocol. This protocol includes methods like `query(_:)` for executing SQL queries and reading the resulting rows. 
+Once you have a connection, you will need to authenticate with the server using the `authenticate` method.
 
-`PostgresConnection` is the default implementation of `PostgresClient` provided by this package. Assume the client here is the connection from the previous example.
+```swift
+try conn.authenticate(
+    username: "vapor_username",
+    database: "vapor_database",
+    password: "vapor_password"
+).wait()
+```
+
+This requires a username. You may supply a database name and password if needed. 
+
+### Database Protocol
+
+Interaction with a server revolves around the `PostgresDatabase` protocol. This protocol includes methods like `query(_:)` for executing SQL queries and reading the resulting rows. 
+
+`PostgresConnection` is the default implementation of `PostgresDatabase` provided by this package. Assume `db` here is the connection from the previous example.
 
 ```swift
 import PostgresNIO
 
-let client: PostgresClient = ...
+let db: PostgresDatabase = ...
 // now we can use client to do queries
 ```
 
@@ -135,11 +150,11 @@ These queries are most useful for schema or transactional queries, or simple sel
 `simpleQuery` has two overloads, one that returns an array of rows, and one that accepts a closure for handling each row as it is returned.
 
 ```swift
-let rows = try client.simpleQuery("SELECT version()").wait()
-print(rows) // [["version": "11.0.0"]]
+let rows = try db.simpleQuery("SELECT version()").wait()
+print(rows) // [["version": "12.x.x"]]
 
-try client.simpleQuery("SELECT version()") { row in
-    print(row) // ["version": "11.0.0"]
+try db.simpleQuery("SELECT version()") { row in
+    print(row) // ["version": "12.x.x"]
 }.wait()
 ```
 
@@ -152,10 +167,10 @@ These queries are most useful for selecting, inserting, and updating data. Data
 Just like `simpleQuery`, `query` also offers two overloads. One that returns an array of rows, and one that accepts a closure for handling each row as it is returned.
 
 ```swift
-let rows = try client.query("SELECT * FROM planets WHERE name = $1", ["Earth"]).wait()
+let rows = try db.query("SELECT * FROM planets WHERE name = $1", ["Earth"]).wait()
 print(rows) // [["id": 42, "name": "Earth"]]
 
-try client.query("SELECT * FROM planets WHERE name = $1", ["Earth"]) { row in
+try db.query("SELECT * FROM planets WHERE name = $1", ["Earth"]) { row in
     print(row) // ["id": 42, "name": "Earth"]
 }.wait()
 ```
@@ -209,36 +224,3 @@ print(data.numeric) // PostgresNumeric?
 ```
 
 `PostgresData` is also used for sending data _to_ the server via parameterized values. To create `PostgresData` from a Swift type, use the available intializer methods. 
-
-## Library development
-
-If you want to contribute to the library development, here is how to get started.
-
-### Testing
-
-To run the test, you need to start a local PostgreSQL database using Docker.
-
-If you have Docker installed and running, you can use Docker Compose to start PostgreSQL:
-
-The following command will download the required containers to run the test and start them:
-
-```
-$ docker-compose up -d psql-11
-```
-
-You can choose to run one of the following PostgreSQL version: `psql-11`, `psql-10`, `psql-9`, `psql-ssl`.
-
-From another console or from Xcode, you can then run the test:
-
-```
-$ swift test
-```
-
-You can check that the test are passing, before adding your own to the test suite.
-
-Finally, you can shut down and clean up Docker test environment with:
-
-```
-$ docker-compose down --volumes
-```
-