TableRecord
A type that builds database queries with the Swift language instead of SQL.
protocol TableRecordA TableRecord type is tied to one database table, and can build SQL queries on that table.
To build SQL queries that involve several tables, define some Association between two TableRecord types.
Most of the time, your record types will get TableRecord conformance through the MutablePersistableRecord or PersistableRecord protocols, which provide persistence methods.
Configuring the Generated SQL
static var databaseTableName: StringThe name of the database table used to build SQL queries.
static var databaseSelection: [any SQLSelectable]The columns selected by the record.
static func numberOfSelectedColumns(Database) throws -> Int Returns the number of selected columns.
Counting Records
static func fetchCount(Database) throws -> Int Returns the number of records in the database table.
Testing for Record Existence
static func exists(Database, id: ID) throws -> Bool Returns whether a record exists for this primary key.
static func exists(Database, key: some DatabaseValueConvertible) throws -> Bool Returns whether a record exists for this primary key.
static func exists(Database, key: [String : (any DatabaseValueConvertible)?]) throws -> Bool Returns whether a record exists for this primary or unique key.
func recordNotFound(Database) -> any Error Returns an error that tells that the record does not exist in the database.
Throwing Record Not Found Errors
static func recordNotFound(Database, id: Self.ID) -> any Error Returns an error for a record that does not exist in the database.
static func recordNotFound(Database, key: some DatabaseValueConvertible) -> any Error Returns an error for a record that does not exist in the database.
static func recordNotFound(key: [String : (any DatabaseValueConvertible)?]) -> RecordError Returns an error for a record that does not exist in the database.
Deleting Records
static func deleteAll(Database) throws -> Int Deletes all records, and returns the number of deleted records.
static func deleteAll(Database, ids: some Collection<ID>) throws -> Int Deletes records identified by their primary keys, and returns the number of deleted records.
static func deleteAll(Database, keys: some Collection<some DatabaseValueConvertible>) throws -> Int Deletes records identified by their primary keys, and returns the number of deleted records.
static func deleteAll(Database, keys: [[String : (any DatabaseValueConvertible)?]]) throws -> Int Deletes records identified by their primary or unique keys, and returns the number of deleted records.
static func deleteOne(Database, id: ID) throws -> Bool Deletes the record identified by its primary key, and returns whether a record was deleted.
static func deleteOne(Database, key: some DatabaseValueConvertible) throws -> Bool Deletes the record identified by its primary key, and returns whether a record was deleted.
static func deleteOne(Database, key: [String : (any DatabaseValueConvertible)?]) throws -> Bool Deletes the record identified by its primary or unique key, and returns whether a record was deleted.
Updating Records
static func updateAll(Database, onConflict: Database.ConflictResolution?, ColumnAssignment...) throws -> Int Updates all records, and returns the number of updated records.
static func updateAll(Database, onConflict: Database.ConflictResolution?, [ColumnAssignment]) throws -> Int Updates all records, and returns the number of updated records.
Building Query Interface Requests
TableRecord provide convenience access to most DerivableRequest and QueryInterfaceRequest methods as static methods on the type itself.
static func aliased(TableAlias) -> QueryInterfaceRequest<Self> Returns a request that can be referred to with the provided alias.
static func all() -> QueryInterfaceRequest<Self> Returns a request for all records in the table.
static func annotated(with: [any SQLSelectable]) -> QueryInterfaceRequest<Self> Returns a request with the provided result columns appended to the record selection.
static func annotated(with: AssociationAggregate<Self>...) -> QueryInterfaceRequest<Self> Returns a request with the given association aggregates appended to the record selection.
static func annotated(with: [AssociationAggregate<Self>]) -> QueryInterfaceRequest<Self> Returns a request with the given association aggregates appended to the record selection.
static func annotated(with: any SQLSelectable...) -> QueryInterfaceRequest<Self> Returns a request with the provided result columns appended to the record selection.
static func annotated<A>(withOptional: A) -> QueryInterfaceRequest<Self> Returns a request with the columns of the eventual associated record appended to the record selection.
static func annotated<A>(withRequired: A) -> QueryInterfaceRequest<Self> Returns a request with the columns of the associated record appended to the record selection. Records that do not have an associated record are discarded.
static func filter(some SQLSpecificExpressible) -> QueryInterfaceRequest<Self> Returns a request filtered with a boolean SQL expression.
static func filter(id: ID) -> QueryInterfaceRequest<Self> Returns a request filtered by primary key.
static func filter(ids: some Collection<ID>) -> QueryInterfaceRequest<Self> Returns a request filtered by primary key.
static func filter(key: [String : (any DatabaseValueConvertible)?]?) -> QueryInterfaceRequest<Self> Returns a request filtered by primary or unique key.
static func filter(key: some DatabaseValueConvertible) -> QueryInterfaceRequest<Self> Returns a request filtered by primary key.
static func filter(keys: [[String : (any DatabaseValueConvertible)?]]) -> QueryInterfaceRequest<Self> Returns a request filtered by primary or unique key.
static func filter(keys: some Collection<some DatabaseValueConvertible>) -> QueryInterfaceRequest<Self> Returns a request filtered by primary key.
static func filter(literal: SQL) -> QueryInterfaceRequest<Self> Returns a request filtered with an
SQLliteral.static func filter(sql: String, arguments: StatementArguments) -> QueryInterfaceRequest<Self> Returns a request filtered with an SQL string.
static func having(AssociationAggregate<Self>) -> QueryInterfaceRequest<Self> Returns a request filtered according to the provided association aggregate.
static func including<A>(all: A) -> QueryInterfaceRequest<Self> Returns a request that fetches all records associated with each record in this request.
static func including<A>(optional: A) -> QueryInterfaceRequest<Self> Returns a request that fetches the eventual record associated with each record of this request.
static func including<A>(required: A) -> QueryInterfaceRequest<Self> Returns a request that fetches the record associated with each record in this request. Records that do not have an associated record are discarded.
static func joining<A>(optional: A) -> QueryInterfaceRequest<Self> Returns a request that joins each record of this request to its eventual associated record.
static func joining<A>(required: A) -> QueryInterfaceRequest<Self> Returns a request that joins each record of this request to its associated record. Records that do not have an associated record are discarded.
static func limit(Int, offset: Int?) -> QueryInterfaceRequest<Self> Returns a limited request.
static func matching(FTS3Pattern?) -> QueryInterfaceRequest<Self> Returns a request filtered on records that match an
FTS3full-text pattern.static func matching(FTS5Pattern?) -> QueryInterfaceRequest<Self> Returns a request filtered on records that match an
FTS5full-text pattern.static func none() -> QueryInterfaceRequest<Self> Returns an empty request that fetches no record.
static func order([any SQLOrderingTerm]) -> QueryInterfaceRequest<Self> Returns a request sorted according to the given SQL ordering terms.
static func order(any SQLOrderingTerm...) -> QueryInterfaceRequest<Self> Returns a request sorted according to the given SQL ordering terms.
static func order(literal: SQL) -> QueryInterfaceRequest<Self> Returns a request sorted according to the given
SQLliteral.static func order(sql: String, arguments: StatementArguments) -> QueryInterfaceRequest<Self> Returns a request sorted according to the given SQL string.
static func orderByPrimaryKey() -> QueryInterfaceRequest<Self> Returns a request sorted by primary key.
func request<A>(for: A) -> QueryInterfaceRequest<A.RowDecoder> Returns a request for the associated record(s).
static func select([any SQLSelectable]) -> QueryInterfaceRequest<Self> Returns a request that selects the provided result columns.
static func select(any SQLSelectable...) -> QueryInterfaceRequest<Self> Returns a request that selects the provided result columns.
static func select<RowDecoder>(any SQLSelectable..., as: RowDecoder.Type) -> QueryInterfaceRequest<RowDecoder> Returns a request that selects the provided result columns, and defines the type of decoded rows.
static func select<RowDecoder>([any SQLSelectable], as: RowDecoder.Type) -> QueryInterfaceRequest<RowDecoder> Returns a request that selects the provided result columns, and defines the type of decoded rows.
static func select(literal: SQL) -> QueryInterfaceRequest<Self> Returns a request that selects the provided
SQLliteral.static func select<RowDecoder>(literal: SQL, as: RowDecoder.Type) -> QueryInterfaceRequest<RowDecoder> Returns a request that selects the provided
SQLliteral, and defines the type of decoded rows.static func select(sql: String, arguments: StatementArguments) -> QueryInterfaceRequest<Self> Returns a request that selects the provided SQL string.
static func select<RowDecoder>(sql: String, arguments: StatementArguments, as: RowDecoder.Type) -> QueryInterfaceRequest<RowDecoder> Returns a request that selects the provided SQL string, and defines the type of decoded rows.
static func selectID() -> QueryInterfaceRequest<Self.ID> Returns a request that selects the primary key.
static func selectPrimaryKey<PrimaryKey>(as: PrimaryKey.Type) -> QueryInterfaceRequest<PrimaryKey> Returns a request that selects the primary key.
static func with<RowDecoder>(CommonTableExpression<RowDecoder>) -> QueryInterfaceRequest<Self> Returns a request that embeds a common table expression.
Defining Associations
static func association<Destination>(to: CommonTableExpression<Destination>) -> JoinAssociation<Self, Destination> Creates an association to a common table expression.
static func association<Destination>(to: CommonTableExpression<Destination>, on: @escaping (_ left: TableAlias, _ right: TableAlias) -> any SQLExpressible) -> JoinAssociation<Self, Destination> Creates an association to a common table expression.
static func belongsTo<Destination>(Destination.Type, key: String?, using: ForeignKey?) -> BelongsToAssociation<Self, Destination> Creates a
BelongsToAssociationbetweenSelfand the destinationTableRecordtype.static func belongsTo<Destination>(Table<Destination>, key: String?, using: ForeignKey?) -> BelongsToAssociation<Self, Destination> Creates a
BelongsToAssociationbetweenSelfand the destinationTable.static func hasMany<Destination>(Destination.Type, key: String?, using: ForeignKey?) -> HasManyAssociation<Self, Destination> Creates a
HasManyAssociationbetweenSelfand the destinationTableRecordtype.static func hasMany<Destination>(Table<Destination>, key: String?, using: ForeignKey?) -> HasManyAssociation<Self, Destination> Creates a
HasManyAssociationbetweenSelfand the destinationTable.static func hasMany<Pivot, Target>(Target.RowDecoder.Type, through: Pivot, using: Target, key: String?) -> HasManyThroughAssociation<Self, Target.RowDecoder> Creates a
HasManyThroughAssociationbetweenSelfand the destinationTableRecordtype.static func hasOne<Destination>(Destination.Type, key: String?, using: ForeignKey?) -> HasOneAssociation<Self, Destination> Creates a
HasOneAssociationbetweenSelfand the destinationTableRecordtype.static func hasOne<Destination>(Table<Destination>, key: String?, using: ForeignKey?) -> HasOneAssociation<Self, Destination> Creates a
HasOneAssociationbetweenSelfand the destinationTable.static func hasOne<Pivot, Target>(Target.RowDecoder.Type, through: Pivot, using: Target, key: String?) -> HasOneThroughAssociation<Self, Target.RowDecoder> Creates a
HasOneThroughAssociationbetweenSelfand the destinationTableRecordtype.