Protocol
SQLDatabase
The common interface to SQLKit for both drivers and client code.
protocol SQLDatabase : SendableMentioned in
Overview
SQLDatabase is the core of an SQLKit driver and the primary entry point for user code. This common interface provides the information and behaviors necessary to define and leverage the package’s functionality.
Conformances to SQLDatabase are typically provided by an external database-specific driver package, alongside several wrapper types for handling connection logic and other details. A driver package must at minimum provide concrete implementations of SQLDatabase, SQLDialect, and SQLRow.
The API described by the base SQLDatabase protocol is low-level, meant for SQLKit drivers to implement; most users will not need to interact with these APIs directly. The high-level starting point for SQLKit is SQLQueryBuilder; the various query builders provide extension methods on SQLDatabase which are the intended public interface.
For comparison, this is an example of using SQLDatabase and SQLExpressions directly:
let database: SQLDatabase = ...
var select = SQLSelect()
select.columns = [SQLColumn(SQLIdentifier("x"))]
select.tables = [SQLIdentifier("y")]
select.predicate = SQLBinaryExpression(
left: SQLColumn(SQLIdentifier("z")),
op: SQLBinaryOperator.equal,
right: SQLLiteral.numeric("1")
)
nonisolated(unsafe) var resultRows: [SQLRow] = []
try await database.execute(sql: select, { resultRows.append($0) })
// Executed query: SELECT x FROM y WHERE z = 1
var resultValues: [Int] = try resultRows.map {
try $0.decode(column: "x", as: Int.self)
}And this is the same example, written to make use of SQLSelectBuilder:
let database: SQLDatabase = ...
let resultValues: [Int] = try await database.select()
.column("x")
.from("y")
.where("z", .equal, 1)
.all(decodingColumn: "x", as: Int.self)Topics
Properties
var logger: LoggerTheLoggerused for logging all operations relating to a given database.var eventLoop: any EventLoopTheEventLoopused for asynchronous operations on a given database.var version: (any SQLDatabaseReportedVersion)?The version number the database reports for itself.var dialect: any SQLDialectThe descriptor for the dialect of SQL supported by the given database.var queryLogLevel: Logger.Level?The logging level used for reporting queries run on the given database to the database’s logger. Defaults to.debug.
Query interface
func execute(sql: any SQLExpression, (any SQLRow) -> ()) async throwsRequests that the given generic SQL query be serialized and executed on the database, and that theonRowclosure be invoked once for each result row the query returns (if any).func withSession<R>((any SQLDatabase) async throws -> R) async throws -> RRequests the provided closure be called with a database which is guaranteed to represent a single “session”, suitable for e.g. executing a series of queries representing a transaction.
DML queries
func delete(from: String) -> SQLDeleteBuilderCreate a newSQLDeleteBuilder.func delete(from: any SQLExpression) -> SQLDeleteBuilderCreate a newSQLDeleteBuilder.func insert(into: String) -> SQLInsertBuilderCreate a newSQLInsertBuilder.func insert(into: any SQLExpression) -> SQLInsertBuilderCreate a newSQLInsertBuilder.func select() -> SQLSelectBuilderCreate a newSQLSelectBuilder.func union((SQLSelectBuilder) throws -> SQLSelectBuilder) rethrows -> SQLUnionBuilderCreate a newSQLUnionBuilder, providing a builder to create the first query.func update(String) -> SQLUpdateBuilderCreate a newSQLUpdateBuilderassociated with this database.func update(any SQLExpression) -> SQLUpdateBuilderCreate a newSQLUpdateBuilderassociated with this database.
DDL queries
func alter(table: String) -> SQLAlterTableBuilderCreate a newSQLAlterTableBuilder.func alter(table: SQLIdentifier) -> SQLAlterTableBuilderCreate a newSQLAlterTableBuilder.func alter(table: any SQLExpression) -> SQLAlterTableBuilderCreate a newSQLAlterTableBuilder.func create(table: String) -> SQLCreateTableBuilderCreate a newSQLCreateTableBuilder.func create(table: any SQLExpression) -> SQLCreateTableBuilderCreate a newSQLCreateTableBuilder.func drop(table: String) -> SQLDropTableBuilderCreate a newSQLDropTableBuilder.func drop(table: any SQLExpression) -> SQLDropTableBuilderCreate a newSQLDropTableBuilder.func alter(enum: String) -> SQLAlterEnumBuilderCreate a newSQLAlterEnumBuilder.func alter(enum: any SQLExpression) -> SQLAlterEnumBuilderCreate a newSQLAlterEnumBuilder.func create(enum: String) -> SQLCreateEnumBuilderCreate a newSQLCreateEnumBuilder.func create(enum: any SQLExpression) -> SQLCreateEnumBuilderCreate a newSQLCreateEnumBuilder.func drop(enum: String) -> SQLDropEnumBuilderCreate a newSQLDropEnumBuilder.func drop(enum: any SQLExpression) -> SQLDropEnumBuilderCreate a newSQLDropEnumBuilder.func create(index: String) -> SQLCreateIndexBuilderCreates a newSQLCreateIndexBuilder.func create(index: any SQLExpression) -> SQLCreateIndexBuilderCreates a newSQLCreateIndexBuilder.func drop(index: String) -> SQLDropIndexBuilderCreate a newSQLDropIndexBuilder.func drop(index: any SQLExpression) -> SQLDropIndexBuilderCreate a newSQLDropIndexBuilder.func create(trigger: String, table: String, when: SQLCreateTrigger.WhenSpecifier, event: SQLCreateTrigger.EventSpecifier) -> SQLCreateTriggerBuilderCreate a newSQLCreateTriggerBuilder.func create(trigger: any SQLExpression, table: any SQLExpression, when: any SQLExpression, event: any SQLExpression) -> SQLCreateTriggerBuilderCreate a newSQLCreateTriggerBuilder.func drop(trigger: String) -> SQLDropTriggerBuilderCreate a newSQLDropTableBuilder.func drop(trigger: any SQLExpression) -> SQLDropTriggerBuilderCreate a newSQLDropTableBuilder.
Raw queries
func raw(SQLQueryString) -> SQLRawBuilderCreate a newSQLRawBuilder.func serialize(any SQLExpression) -> (sql: String, binds: [any Encodable & Sendable])Serialize an arbitrarySQLExpressionusing the database’s dialect.
Logging
func logging(to: Logger) -> any SQLDatabaseReturn a newSQLDatabasewhich is indistinguishable from the original save that itsloggerproperty is replaced by the givenLogger.
Legacy query interface
func execute(sql: any SQLExpression, (any SQLRow) -> ()) -> EventLoopFuture<Void>Requests that the given generic SQL query be serialized and executed on the database, and that theonRowclosure be invoked once for each result row the query returns (if any).
Instance Methods
func alter(enum:)Create a newSQLAlterEnumBuilder.func alter(table:)Create a newSQLAlterTableBuilder.func create(enum:)Create a newSQLCreateEnumBuilder.func create(index:)Creates a newSQLCreateIndexBuilder.func create(table:)Create a newSQLCreateTableBuilder.func create(trigger:table:when:event:)Create a newSQLCreateTriggerBuilder.func delete(from:)Create a newSQLDeleteBuilder.func drop(enum:)Create a newSQLDropEnumBuilder.func drop(index:)Create a newSQLDropIndexBuilder.func drop(table:)Create a newSQLDropTableBuilder.func drop(trigger:)Create a newSQLDropTableBuilder.func execute(sql:_:)Requests that the given generic SQL query be serialized and executed on the database, and that theonRowclosure be invoked once for each result row the query returns (if any).func insert(into:)Create a newSQLInsertBuilder.func update(_:)Create a newSQLUpdateBuilderassociated with this database.
Relationships
Inherits From
Swift.SendableSwift.SendableMetatype
See Also
Data Access
protocol SQLRowRepresents a single row in a result set returned from an executed SQL query.struct SQLRowDecoderAn implementation ofDecoderdesigned to decode “models” (or, in general, aggregateDecodabletypes) fromSQLRows returned from a database query.struct SQLQueryEncoderAn implementation ofEncoderdesigned to encode “models” (or, in general, aggregateEncodabletypes) into a form which can be used as input to a database query.