mirror of https://github.com/vapor/docs.git
70 lines
2.9 KiB
Markdown
70 lines
2.9 KiB
Markdown
# Using SQL
|
|
|
|
The SQL library helps you build and serialize SQL queries in Swift. It has an extensible, protocol-based design that supports many standard SQL queries like:
|
|
|
|
- `SELECT`, `INSERT`, `UPDATE`, `DELETE`
|
|
- `CREATE TABLE`, `ALTER TABLE`, `DROP TABLE`
|
|
- `CREATE INDEX`, `DROP INDEX`
|
|
|
|
This package also integrates deeply with `Codable` and parameter binding to make working with your database fast and secure.
|
|
|
|
This guide assumes you have already chosen and configured a driver in [SQL → Getting Started](getting-started.md). In some cases, these SQL dialects will have different syntaxes or supported features. Be sure to check their API docs for additional functionality.
|
|
|
|
## Connection
|
|
|
|
The first step to building a SQL query is getting access to a connection. Most often, you will use `withPooledConnection(to:)` followed by your database's `dbid`.
|
|
|
|
!!! note
|
|
Refer to the table in [SQL → Getting Started](getting-started.md) for your database's default `dbid`.
|
|
The `dbid` allows you to use multiple databases per application.
|
|
|
|
```swift
|
|
router.get("sql") { req in
|
|
return req.withPooledConnection(to: .<#dbid#>) { conn in
|
|
return // use conn to perform a query
|
|
}
|
|
}
|
|
```
|
|
|
|
Check out [Database Kit → Overview → Connections](../database-kit/overview.md#connections) for more information. The rest of this guide will assume you have access to a SQL database connection.
|
|
|
|
## Select
|
|
|
|
Use the [`select()`](https://api.vapor.codes/sql/latest/SQL/Protocols/SQLConnection.html#/s:3SQL13SQLConnectionPAAE6selectAA16SQLSelectBuilderCyxGyF) method on a connection to create a [`SQLSelectBuilder`](https://api.vapor.codes/sql/latest/SQL/Classes/SQLSelectBuilder.html). This builder helps you create `SELECT` statements and supports:
|
|
|
|
- `*`, columns, and expressions like functions
|
|
- `FROM`
|
|
- `JOIN`
|
|
- `GROUP BY`
|
|
- `ORDER BY`
|
|
|
|
The select builder conforms to [`SQLPredicateBuilder`](https://api.vapor.codes/sql/latest/SQL/Protocols/SQLPredicateBuilder.html) for building `WHERE` predicates. It also conforms to [`SQLQueryFetcher`](https://api.vapor.codes/sql/latest/SQL/Protocols/SQLQueryFetcher.html) for decoding `Codable` models from the result set.
|
|
|
|
Let's take a look at an example `SELECT` query. Replace the Xcode placeholder with the name of the database you are using, i.e., `SQLite`.
|
|
|
|
```swift
|
|
struct User: SQLTable, Codable {
|
|
static let sqlTableIdentifierString = "users"
|
|
let id: Int?
|
|
let name: String
|
|
}
|
|
|
|
let users = conn.select()
|
|
.all().from(User.self)
|
|
.where(\User.name == "Vapor")
|
|
.all(decoding: User.self)
|
|
print(users) // Future<[User]>
|
|
```
|
|
|
|
The resulting SQL will look something like this:
|
|
|
|
```sql
|
|
SELECT * FROM "users" WHERE "users"."name" = ?
|
|
```
|
|
|
|
As you can see, the Swift code reads similarly to actual SQL. Be sure to visit the API docs for the various builder protocols to see all available methods.
|
|
|
|
## API Docs
|
|
|
|
Check out the [API docs](https://api.vapor.codes/sql/latest/SQL/index.html) for more in-depth information about SQL's APIs.
|