From fb3dd9e89f0df51dbba20933816e2982061fb7b1 Mon Sep 17 00:00:00 2001 From: Joe Smith Date: Sun, 25 Mar 2018 12:11:34 -0700 Subject: [PATCH 1/2] Manually create MySQL connection Documentation is good if using the rest of Vapor, but we should also point folks in the right direction if they are just using this for simpler DB automation. --- 3.0/docs/mysql/core.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/3.0/docs/mysql/core.md b/3.0/docs/mysql/core.md index d30e5f12..f7e55c8f 100644 --- a/3.0/docs/mysql/core.md +++ b/3.0/docs/mysql/core.md @@ -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,6 +109,16 @@ 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, it is also quite simple. 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) +``` + ### 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. From d342368441e28f11192dd2e9a31e6bf804f47a14 Mon Sep 17 00:00:00 2001 From: Joe Smith Date: Tue, 27 Mar 2018 20:40:55 -0700 Subject: [PATCH 2/2] Create async getting started doc --- 3.0/docs/async/getting-started.md | 17 +++++++++++++++++ 3.0/docs/mysql/core.md | 19 +++++-------------- 2 files changed, 22 insertions(+), 14 deletions(-) create mode 100644 3.0/docs/async/getting-started.md 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 f7e55c8f..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. @@ -111,21 +111,15 @@ As the names imply, `withPooledConnection(to:)` utilizes a connection pool. `wi ### Create (manually) -If you are writing a simple tool and would like to use the `MySQL` wrapper, it is also quite simple. 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) -``` +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;") @@ -159,6 +153,3 @@ print(users) // Future<[[MySQLColumn: MySQLData]]> You can also provide a callback, similar to simple queries, for handling each row individually. - - -