Protocol

SQLDatabase

The common interface to SQLKit for both drivers and client code.

protocol SQLDatabase : Sendable

Mentioned in

Basic Usage

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

logger
The Logger used for logging all operations relating to a given database.
eventLoop
The EventLoop used for asynchronous operations on a given database.
version
The version number the database reports for itself.
dialect
The descriptor for the dialect of SQL supported by the given database.
queryLogLevel
The logging level used for reporting queries run on the given database to the database’s logger. Defaults to .debug.

Query interface

execute(sql:_:)
Requests that the given generic SQL query be serialized and executed on the database, and that the onRow closure be invoked once for each result row the query returns (if any).
withSession(_:)
Requests 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

delete(from:)
Create a new SQLDeleteBuilder.
delete(from:)
Create a new SQLDeleteBuilder.
insert(into:)
Create a new SQLInsertBuilder.
insert(into:)
Create a new SQLInsertBuilder.
select()
Create a new SQLSelectBuilder.
union(_:)
Create a new SQLUnionBuilder, providing a builder to create the first query.
update(_:)
Create a new SQLUpdateBuilder associated with this database.
update(_:)
Create a new SQLUpdateBuilder associated with this database.

DDL queries

alter(table:)
Create a new SQLAlterTableBuilder.
alter(table:)
Create a new SQLAlterTableBuilder.
alter(table:)
Create a new SQLAlterTableBuilder.
create(table:)
Create a new SQLCreateTableBuilder.
create(table:)
Create a new SQLCreateTableBuilder.
drop(table:)
Create a new SQLDropTableBuilder.
drop(table:)
Create a new SQLDropTableBuilder.
alter(enum:)
Create a new SQLAlterEnumBuilder.
alter(enum:)
Create a new SQLAlterEnumBuilder.
create(enum:)
Create a new SQLCreateEnumBuilder.
create(enum:)
Create a new SQLCreateEnumBuilder.
drop(enum:)
Create a new SQLDropEnumBuilder.
drop(enum:)
Create a new SQLDropEnumBuilder.
create(index:)
Creates a new SQLCreateIndexBuilder.
create(index:)
Creates a new SQLCreateIndexBuilder.
drop(index:)
Create a new SQLDropIndexBuilder.
drop(index:)
Create a new SQLDropIndexBuilder.
create(trigger:table:when:event:)
Create a new SQLCreateTriggerBuilder.
create(trigger:table:when:event:)
Create a new SQLCreateTriggerBuilder.
drop(trigger:)
Create a new SQLDropTableBuilder.
drop(trigger:)
Create a new SQLDropTableBuilder.

Raw queries

raw(_:)
Create a new SQLRawBuilder.
serialize(_:)
Serialize an arbitrary SQLExpression using the database’s dialect.

Logging

logging(to:)
Return a new SQLDatabase which is indistinguishable from the original save that its logger property is replaced by the given Logger.

Legacy query interface

execute(sql:_:)
Requests that the given generic SQL query be serialized and executed on the database, and that the onRow closure be invoked once for each result row the query returns (if any).

Instance Methods

alter(enum:)
Create a new SQLAlterEnumBuilder.
alter(table:)
Create a new SQLAlterTableBuilder.
create(enum:)
Create a new SQLCreateEnumBuilder.
create(index:)
Creates a new SQLCreateIndexBuilder.
create(table:)
Create a new SQLCreateTableBuilder.
create(trigger:table:when:event:)
Create a new SQLCreateTriggerBuilder.
delete(from:)
Create a new SQLDeleteBuilder.
drop(enum:)
Create a new SQLDropEnumBuilder.
drop(index:)
Create a new SQLDropIndexBuilder.
drop(table:)
Create a new SQLDropTableBuilder.
drop(trigger:)
Create a new SQLDropTableBuilder.
execute(sql:_:)
Requests that the given generic SQL query be serialized and executed on the database, and that the onRow closure be invoked once for each result row the query returns (if any).
insert(into:)
Create a new SQLInsertBuilder.
update(_:)
Create a new SQLUpdateBuilder associated with this database.

Relationships

Inherits From

Swift.Sendable
Swift.SendableMetatype