mirror of https://github.com/vapor/docs.git
update MySQL docs for 3.0 release
This commit is contained in:
tanner0101
parent
c0d6ef7568
commit
37c1b62258
|
|
@ -114,7 +114,7 @@ See the documentation for your specific database type for more information about
|
|||
|database|docs|api docs|
|
||||
|-|-|-|
|
||||
|PostgreSQL|[PostgreSQL → Getting Started](../postgresql/getting-started.md)|_Coming soon_|
|
||||
|MySQL|[MySQL → Getting Started](../mysql/getting-started.md)|_Coming soon_|
|
||||
|MySQL|[MySQL → Getting Started](../mysql/getting-started.md)|[`MySQLDatabase`](https://api.vapor.codes/mysql/latest/MySQL/Classes/MySQLDatabase.html)|
|
||||
|SQLite|[SQLite → Getting Started](../sqlite/getting-started.md)|[`SQLiteDatabase`](https://api.vapor.codes/sqlite/latest/SQLite/Classes/SQLiteDatabase.html)|
|
||||
|
||||
## Creating a Migration
|
||||
|
|
|
|||
|
|
@ -91,7 +91,7 @@ Each database has it's own unique data types, so refer to your database's docume
|
|||
|database|docs|api docs|
|
||||
|-|-|-|
|
||||
|PostgreSQL|[PostgreSQL → Getting Started](../postgresql/getting-started.md)|_Coming soon_|
|
||||
|MySQL|[MySQL → Getting Started](../mysql/getting-started.md)|_Coming soon_|
|
||||
|MySQL|[MySQL → Getting Started](../mysql/getting-started.md)|[`MySQLDataType`](https://api.vapor.codes/mysql/latest/MySQL/Structs/MySQLDataType.html)|
|
||||
|SQLite|[SQLite → Getting Started](../sqlite/getting-started.md)|[`SQLiteDataType`](https://api.vapor.codes/sqlite/latest/SQLite/Enums/SQLiteDataType.html)|
|
||||
|
||||
#### Deleting a Schema
|
||||
|
|
|
|||
|
|
@ -1,17 +1,14 @@
|
|||
# MySQL
|
||||
|
||||
MySQL ([vapor/mysql](https://github.com/vapor/mysql)) is a pure-Swift (no `libmysql` dependency), event-driven, non-blocking driver for MySQL. It's built on top of the [SwiftNIO](http://github.com/apple/swift-nio) networking library.
|
||||
MySQL ([vapor/mysql](https://github.com/vapor/mysql)) is a pure Swift MySQL (and MariaDB) client built on top of [SwiftNIO](https://github.com/apple/swift-nio.git).
|
||||
|
||||
!!! seealso
|
||||
The higher-level, Fluent ORM guide is located at [Fluent → Getting Started](../fluent/getting-started.md)
|
||||
|
||||
Using just the MySQL package for your project may be a good idea if any of the following are true.
|
||||
The higher-level, Fluent ORM guide is located at [Fluent → Getting Started](../fluent/getting-started.md). Using just the MySQL package directly for your project may be a good idea if any of the following are true:
|
||||
|
||||
- You have an existing DB with non-standard structure.
|
||||
- You rely heavily on custom or complex SQL queries.
|
||||
- You just plain don't like ORMs.
|
||||
|
||||
MySQL core is built on top of DatabaseKit which provides some conveniences like connection pooling and integrations with Vapor's [Services](../getting-started/services.md) architecture.
|
||||
MySQL core extends [DatabaseKit](../database-kit/getting-started.md) which provides some conveniences like connection pooling and integrations with Vapor's [Services](../getting-started/services.md) architecture.
|
||||
|
||||
!!! tip
|
||||
Even if you do choose to use [Fluent MySQL](../fluent/getting-started.md), all of the features of MySQL core will be available to you.
|
||||
|
|
@ -33,8 +30,8 @@ let package = Package(
|
|||
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"),
|
||||
// 🐬 Pure Swift MySQL client built on non-blocking, event-driven sockets.
|
||||
.package(url: "https://github.com/vapor/mysql.git", from: "3.0.0"),
|
||||
],
|
||||
targets: [
|
||||
.target(name: "App", dependencies: ["MySQL", ...]),
|
||||
|
|
@ -50,104 +47,62 @@ Don't forget to add the module as a dependency in the `targets` array. Once you
|
|||
vapor xcode
|
||||
```
|
||||
|
||||
|
||||
### Config
|
||||
|
||||
The next step is to configure the database in your [`configure.swift`](../getting-started/structure.md#configureswift) file.
|
||||
The next step is to configure the database in [`configure.swift`](../getting-started/structure.md#configureswift).
|
||||
|
||||
```swift
|
||||
import MySQL
|
||||
|
||||
/// ...
|
||||
|
||||
/// Register providers first
|
||||
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 standard credentials.
|
||||
|
||||
You can of course override this config struct if you have non-standard credentials.
|
||||
#### Customizing Config
|
||||
|
||||
You can of course override the default configuration provided by `MySQLProvider` if you'd like.
|
||||
|
||||
To configure your database manually, register a [`DatabasesConfig`](https://api.vapor.codes/database-kit/latest/DatabaseKit/Structs/DatabasesConfig.html) struct to your services.
|
||||
|
||||
```swift
|
||||
/// Register custom MySQL Config
|
||||
let mysqlConfig = MySQLDatabaseConfig(hostname: "localhost", port: 3306, username: "vapor")
|
||||
services.register(mysqlConfig)
|
||||
// Configure a MySQL database
|
||||
let mysql = try MySQLDatabase(config: MySQLDatabaseConfig(...))
|
||||
|
||||
/// Register the configured MySQL database to the database config.
|
||||
var databases = DatabasesConfig()
|
||||
databases.add(database: mysql, as: .mysql)
|
||||
services.register(databases)
|
||||
```
|
||||
|
||||
See [`MySQLDatabase`](https://api.vapor.codes/mysql/latest/MySQL/Classes/MySQLDatabase.html) and [`MySQLDatabaseConfig`](https://api.vapor.codes/mysql/latest/MySQL/Structs/MySQLDatabaseConfig.html) for more information.
|
||||
|
||||
MySQL's default database identifier is `.mysql`. You can create a custom identifier if you want by extending [`DatabaseIdentifier`](https://api.vapor.codes/database-kit/latest/DatabaseKit/Structs/DatabaseIdentifier.html).
|
||||
|
||||
### Query
|
||||
|
||||
Now that the database is configured, you can make your first query.
|
||||
|
||||
```swift
|
||||
router.get("mysql-version") { req -> Future<String> in
|
||||
struct MySQLVersion: Codable {
|
||||
let version: String
|
||||
}
|
||||
|
||||
router.get("sql") { req in
|
||||
return req.withPooledConnection(to: .mysql) { conn in
|
||||
return try conn.query("select @@version as v;").map(to: String.self) { rows in
|
||||
return try rows[0].firstValue(forColumn: "v")?.decode(String.self) ?? "n/a"
|
||||
}
|
||||
return conn.raw("SELECT @@version as version")
|
||||
.all(decoding: MySQLVersion.self)
|
||||
}.map { rows in
|
||||
return rows[0].version
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Visiting this route should display your MySQL version.
|
||||
Visiting this route should display your MySQL version.
|
||||
|
||||
## Connection
|
||||
Here we are making use database connection pooling. You can learn more about creating connections in [DatabaseKit → Getting Started](../database-kit/getting-started.md).
|
||||
|
||||
A `MySQLConnection` is normally created using the `Request` container and can perform two different types of queries.
|
||||
|
||||
### Create
|
||||
|
||||
There are a few methods for creating a `MySQLConnection` with a `Container` (typically a `Request`).
|
||||
|
||||
```swift
|
||||
return req.withPooledConnection(to: .mysql) { conn in
|
||||
/// ...
|
||||
}
|
||||
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.
|
||||
|
||||
You can also create a connection manually using `MySQLDatabase.makeConnection(on:)` and passing a [`Worker`](../getting-started/async.md).
|
||||
|
||||
### 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.
|
||||
|
||||
!!! 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;")
|
||||
}
|
||||
print(rows) // Future<[[MySQLColumn: MySQLData]]>
|
||||
```
|
||||
|
||||
You can also choose to receive each row in a callback, which is great for conserving memory for large queries.
|
||||
|
||||
```swift
|
||||
let done = req.withPooledConnection(to: .mysql) { conn in
|
||||
return conn.simpleQuery("SELECT * FROM users;") { row in
|
||||
print(row) // [MySQLColumn: MySQLData]
|
||||
}
|
||||
}
|
||||
print(done) // Future<Void>
|
||||
```
|
||||
|
||||
### Parameterized Query
|
||||
|
||||
MySQL also supports sending parameterized queries (sometimes called prepared statements). This method allows you to insert data placeholders into the SQL string and send the values separately.
|
||||
|
||||
Data sent via parameterized queries is binary encoded, making it more efficient for sending some data types. In general, you should use parameterized queries where ever possible.
|
||||
|
||||
```swift
|
||||
let users = req.withPooledConnection(to: .mysql) { conn in
|
||||
return try conn.query("SELECT * users WHERE name = $1;", ["Vapor"])
|
||||
}
|
||||
print(users) // Future<[[MySQLColumn: MySQLData]]>
|
||||
```
|
||||
|
||||
You can also provide a callback, similar to simple queries, for handling each row individually.
|
||||
Learn more about building queries in [SQL → Getting Started](../sql/getting-started.md).
|
||||
|
||||
Visit MySQL's [API docs](https://api.vapor.codes/mysql/latest/MySQL/index.html) for detailed information about all available types and methods.
|
||||
|
|
|
|||
Loading…
Reference in New Issue