Merge pull request #298 from Yasumoto/jmsmith-manual-mysql

Manually create MySQL connection

3.0/docs/async/getting-started.md

@@ -0,0 +1,17 @@
+# Getting Started with Async
+
+Vapor is powered by Apple's [SwiftNIO](https://github.com/apple/swift-nio), a powerful non-blocking networking framework. If you are using the fully-powered Vapor framework to create a website, then you will likely not need to use this directly. However, if you are using a lower-level library (like a Database framework) then you will need to understand a little about how it works.
+
+## Workers
+
+Vapor's async abstraction is built on a few pieces, including the async [`Worker`](https://github.com/vapor-community/async/blob/1.0.0-rc.1.1/Sources/Async/EventLoop/Worker.swift). This protocol has an `eventLoop`, which fits nicely with SwiftNIO's constructs.
+
+### Example
+
+You need to create a SwiftNIO [`EventGroup`](https://github.com/apple/swift-nio/blob/master/README.md#eventloops-and-eventloopgroups) that can power the connection:
+
+```
+let database = MySQLDatabase(config: config)
+let worker = MultiThreadedEventLoopGroup(numThreads: System.coreCount)
+let futureConnection = database.makeConnection(on: worker)
+```

3.0/docs/mysql/core.md

@@ -32,7 +32,7 @@ let package = Package(
     name: "MyApp",
     dependencies: [
         /// Any other dependencies ...
-        
+
         // 🐬 Non-blocking, event-driven Swift client for MySQL.
         .package(url: "https://github.com/vapor/mysql.git", from: "3.0.0-rc"),
     ],
@@ -64,7 +64,7 @@ import MySQL
 try services.register(MySQLProvider())
 ```
 
-Registering the provider will add all of the services required for MySQL to work properly. It also includes a default database config struct that uses typical development environment credentials. 
+Registering the provider will add all of the services required for MySQL to work properly. It also includes a default database config struct that uses typical development environment credentials.
 
 You can of course override this config struct if you have non-standard credentials.
 
@@ -94,7 +94,7 @@ Visiting this route should display your MySQL version.
 
 A `MySQLConnection` is normally created using the `Request` container and can perform two different types of queries.
 
-### Create
+### Create (with Request)
 
 There are two methods for creating a `MySQLConnection`.
 
@@ -109,13 +109,17 @@ return req.withConnection(to: .mysql) { conn in
 
 As the names imply,  `withPooledConnection(to:)` utilizes a connection pool. `withConnection(to:)` does not. Connection pooling is a great way to ensure your application does not exceed the limits of your database, even under peak load.
 
+### Create (manually)
+
+If you are writing a simple tool and would like to use the `MySQL` wrapper directly, it is also quite simple. You should read up on Vapor's [async `Worker`](../../async/getting-started.md) to power the connection.
+
 ### Simply Query
 
-Use `.simpleQuery(_:)` to perform a query on your MySQL database that does not bind any parameters. Some queries you send to MySQL may actually require that you use the `simpleQuery(_:)` method instead of the parameterized method. 
+Use `.simpleQuery(_:)` to perform a query on your MySQL database that does not bind any parameters. Some queries you send to MySQL may actually require that you use the `simpleQuery(_:)` method instead of the parameterized method.
 
 !!! note
     This method sends and receives data as text-encoded, meaning it is not optimal for transmitting things like integers.
-    
+
 ```swift
 let rows = req.withPooledConnection(to: .mysql) { conn in
     return conn.simpleQuery("SELECT * FROM users;")
@@ -149,6 +153,3 @@ print(users) // Future<[[MySQLColumn: MySQLData]]>
 
 You can also provide a callback, similar to simple queries, for handling each row individually.
 
-
-
-