diff --git a/3.0/docs/async/getting-started.md b/3.0/docs/async/getting-started.md new file mode 100644 index 00000000..1f40a978 --- /dev/null +++ b/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) +``` diff --git a/3.0/docs/mysql/core.md b/3.0/docs/mysql/core.md index d30e5f12..447e70d0 100644 --- a/3.0/docs/mysql/core.md +++ b/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. - - -