extension TableRecord { /// Creates a "Belongs To" association between Self and the destination /// type, based on a database foreign key. /// /// struct Author: TableRecord { ... } /// struct Book: TableRecord { /// static let author = belongsTo(Author.self) /// } /// /// The association will let you define requests that load both the source /// and the destination type: /// /// // A request for all books with their authors: /// let request = Book.including(optional: Book.author) /// /// To consume those requests, define a type that adopts both the /// FetchableRecord and Decodable protocols: /// /// struct BookInfo: FetchableRecord, Decodable { /// var book: Book /// var author: Author? /// } /// /// let bookInfos = try dbQueue.read { db in /// return try BookInfo.fetchAll(db, request) /// } /// for bookInfo in bookInfos { /// print("\(bookInfo.book.title) by \(bookInfo.author.name)") /// } /// /// It is recommended that you define, alongside the static association, a /// property with the same name: /// /// struct Book: TableRecord, EncodableRecord { /// static let author = belongsTo(Author.self) /// var author: QueryInterfaceRequest { /// return request(for: Book.author) /// } /// } /// /// This property will let you navigate from the source type to the /// destination type: /// /// try dbQueue.read { db in /// let book: Book = ... /// let author = try book.author.fetchOne(db) // Author? /// } /// /// - parameters: /// - destination: The record type at the other side of the association. /// - key: An eventual decoding key for the association. By default, it /// is `destination.databaseTableName`. /// - foreignKey: An eventual foreign key. You need to provide an /// explicit foreign key when GRDB can't infer one from the database /// schema. This happens when the schema does not define any foreign /// key to the destination table, or when the schema defines several /// foreign keys to the destination table. public static func belongsTo( _ destination: Destination.Type, key: String? = nil, using foreignKey: ForeignKey? = nil) -> BelongsToAssociation where Destination: TableRecord { BelongsToAssociation( from: databaseTableName, to: Destination.relationForAll, key: key, using: foreignKey) } /// Creates a "Has many" association between Self and the destination type, /// based on a database foreign key. /// /// struct Book: TableRecord { ... } /// struct Author: TableRecord { /// static let books = hasMany(Book.self) /// } /// /// The association will let you define requests that load both the source /// and the destination type: /// /// // A request for all (author, book) pairs: /// let request = Author.including(required: Author.books) /// /// To consume those requests, define a type that adopts both the /// FetchableRecord and Decodable protocols: /// /// struct Authorship: FetchableRecord, Decodable { /// var author: Author /// var book: Book /// } /// /// let authorships = try dbQueue.read { db in /// return try Authorship.fetchAll(db, request) /// } /// for authorship in authorships { /// print("\(authorship.author.name) wrote \(authorship.book.title)") /// } /// /// It is recommended that you define, alongside the static association, a /// property with the same name: /// /// struct Author: TableRecord, EncodableRecord { /// static let books = hasMany(Book.self) /// var books: QueryInterfaceRequest { /// return request(for: Author.books) /// } /// } /// /// This property will let you navigate from the source type to the /// destination type: /// /// try dbQueue.read { db in /// let author: Author = ... /// let books = try author.books.fetchAll(db) // [Book] /// } /// /// - parameters: /// - destination: The record type at the other side of the association. /// - key: An eventual decoding key for the association. By default, it /// is `destination.databaseTableName`. /// - foreignKey: An eventual foreign key. You need to provide an /// explicit foreign key when GRDB can't infer one from the database /// schema. This happens when the schema does not define any foreign /// key from the destination table, or when the schema defines several /// foreign keys from the destination table. public static func hasMany( _ destination: Destination.Type, key: String? = nil, using foreignKey: ForeignKey? = nil) -> HasManyAssociation where Destination: TableRecord { HasManyAssociation( from: databaseTableName, to: Destination.relationForAll, key: key, using: foreignKey) } /// Creates a "Has Many Through" association between Self and the /// destination type. /// /// struct Country: TableRecord { /// static let passports = hasMany(Passport.self) /// static let citizens = hasMany(Citizen.self, through: passports, using: Passport.citizen) /// } /// /// struct Passport: TableRecord { /// static let citizen = belongsTo(Citizen.self) /// } /// /// struct Citizen: TableRecord { } /// /// The association will let you define requests that load both the source /// and the destination type: /// /// // A request for all (country, citizen) pairs: /// let request = Country.including(required: Coutry.citizens) /// /// To consume those requests, define a type that adopts both the /// FetchableRecord and Decodable protocols: /// /// struct Citizenship: FetchableRecord, Decodable { /// var country: Country /// var citizen: Citizen /// } /// /// let citizenships = try dbQueue.read { db in /// return try Citizenship.fetchAll(db, request) /// } /// for citizenship in citizenships { /// print("\(citizenship.citizen.name) is a citizen of \(citizenship.country.name)") /// } /// /// It is recommended that you define, alongside the static association, a /// property with the same name: /// /// struct Country: TableRecord, EncodableRecord { /// static let passports = hasMany(Passport.self) /// static let citizens = hasMany(Citizen.self, through: passports, using: Passport.citizen) /// var citizens: QueryInterfaceRequest { /// return request(for: Country.citizens) /// } /// } /// /// This property will let you navigate from the source type to the /// destination type: /// /// try dbQueue.read { db in /// let country: Country = ... /// let citizens = try country.citizens.fetchAll(db) // [Country] /// } /// /// - parameters: /// - destination: The record type at the other side of the association. /// - pivot: An association from Self to the intermediate type. /// - target: A target association from the intermediate type to the /// destination type. /// - key: An eventual decoding key for the association. By default, it /// is the same key as the target. public static func hasMany( _ destination: Target.RowDecoder.Type, through pivot: Pivot, using target: Target, key: String? = nil) -> HasManyThroughAssociation where Pivot: Association, Target: Association, Pivot.OriginRowDecoder == Self, Pivot.RowDecoder == Target.OriginRowDecoder { let association = HasManyThroughAssociation( sqlAssociation: target._sqlAssociation.through(pivot._sqlAssociation)) if let key = key { return association.forKey(key) } else { return association } } /// Creates a "Has one" association between Self and the destination type, /// based on a database foreign key. /// /// struct Demographics: TableRecord { ... } /// struct Country: TableRecord { /// static let demographics = hasOne(Demographics.self) /// } /// /// The association will let you define requests that load both the source /// and the destination type: /// /// // A request for all countries with their demographic profile: /// let request = Country.including(optional: Country.demographics) /// /// To consume those requests, define a type that adopts both the /// FetchableRecord and Decodable protocols: /// /// struct CountryInfo: FetchableRecord, Decodable { /// var country: Country /// var demographics: Demographics? /// } /// /// let countryInfos = try dbQueue.read { db in /// return try CountryInfo.fetchAll(db, request) /// } /// for countryInfo in countryInfos { /// print("\(countryInfo.country.name) has \(countryInfo.demographics.population) citizens") /// } /// /// It is recommended that you define, alongside the static association, a /// property with the same name: /// /// struct Country: TableRecord, EncodableRecord { /// static let demographics = hasOne(Demographics.self) /// var demographics: QueryInterfaceRequest { /// return request(for: Country.demographics) /// } /// } /// /// This property will let you navigate from the source type to the /// destination type: /// /// try dbQueue.read { db in /// let country: Country = ... /// let demographics = try country.demographics.fetchOne(db) // Demographics? /// } /// /// - parameters: /// - destination: The record type at the other side of the association. /// - key: An eventual decoding key for the association. By default, it /// is `destination.databaseTableName`. /// - foreignKey: An eventual foreign key. You need to provide an /// explicit foreign key when GRDB can't infer one from the database /// schema. This happens when the schema does not define any foreign /// key from the destination table, or when the schema defines several /// foreign keys from the destination table. public static func hasOne( _ destination: Destination.Type, key: String? = nil, using foreignKey: ForeignKey? = nil) -> HasOneAssociation where Destination: TableRecord { HasOneAssociation( from: databaseTableName, to: Destination.relationForAll, key: key, using: foreignKey) } /// Creates a "Has One Through" association between Self and the /// destination type. /// /// struct Book: TableRecord { /// static let library = belongsTo(Library.self) /// static let returnAddress = hasOne(Address.self, through: library, using: Library.address) /// } /// /// struct Library: TableRecord { /// static let address = hasOne(Address.self) /// } /// /// struct Address: TableRecord { ... } /// /// The association will let you define requests that load both the source /// and the destination type: /// /// // A request for all (book, returnAddress) pairs: /// let request = Book.including(required: Book.returnAddress) /// /// To consume those requests, define a type that adopts both the /// FetchableRecord and Decodable protocols: /// /// struct Todo: FetchableRecord, Decodable { /// var book: Book /// var address: Address /// } /// /// let todos = try dbQueue.read { db in /// return try Todo.fetchAll(db, request) /// } /// for todo in todos { /// print("Please return \(todo.book) to \(todo.address)") /// } /// /// It is recommended that you define, alongside the static association, a /// property with the same name: /// /// struct Book: TableRecord, EncodableRecord { /// static let library = belongsTo(Library.self) /// static let returnAddress = hasOne(Address.self, through: library, using: library.address) /// var returnAddress: QueryInterfaceRequest
{ /// return request(for: Book.returnAddress) /// } /// } /// /// This property will let you navigate from the source type to the /// destination type: /// /// try dbQueue.read { db in /// let book: Book = ... /// let address = try book.returnAddress.fetchOne(db) // Address? /// } /// /// - parameters: /// - destination: The record type at the other side of the association. /// - pivot: An association from Self to the intermediate type. /// - target: A target association from the intermediate type to the /// destination type. /// - key: An eventual decoding key for the association. By default, it /// is the same key as the target. public static func hasOne( _ destination: Target.RowDecoder.Type, through pivot: Pivot, using target: Target, key: String? = nil) -> HasOneThroughAssociation where Pivot: AssociationToOne, Target: AssociationToOne, Pivot.OriginRowDecoder == Self, Pivot.RowDecoder == Target.OriginRowDecoder { let association = HasOneThroughAssociation( sqlAssociation: target._sqlAssociation.through(pivot._sqlAssociation)) if let key = key { return association.forKey(key) } else { return association } } } /// A ForeignKey helps building associations when GRDB can't infer a foreign /// key from the database schema. /// /// Sometimes the database schema does not define any foreign key between two /// tables. And sometimes, there are several foreign keys from a table /// to another: /// /// | Table book | | Table person | /// | ------------ | | ------------ | /// | id | +-->• id | /// | authorId •---+ | name | /// | translatorId •---+ /// | title | /// /// When this happens, associations can't be automatically inferred from the /// database schema. GRDB will complain with a fatal error such as "Ambiguous /// foreign key from book to person", or "Could not infer foreign key from book /// to person". /// /// Your help is needed. You have to instruct GRDB which foreign key to use: /// /// struct Book: TableRecord { /// // Define foreign keys /// static let authorForeignKey = ForeignKey(["authorId"])) /// static let translatorForeignKey = ForeignKey(["translatorId"])) /// /// // Use foreign keys to define associations: /// static let author = belongsTo(Person.self, using: authorForeignKey) /// static let translator = belongsTo(Person.self, using: translatorForeignKey) /// } /// /// Foreign keys are always defined from the table that contains the columns at /// the origin of the foreign key. Person's symmetric HasMany associations reuse /// Book's foreign keys: /// /// struct Person: TableRecord { /// static let writtenBooks = hasMany(Book.self, using: Book.authorForeignKey) /// static let translatedBooks = hasMany(Book.self, using: Book.translatorForeignKey) /// } /// /// Foreign keys can also be defined from query interface columns: /// /// struct Book: TableRecord { /// enum Columns: String, ColumnExpression { /// case id, title, authorId, translatorId /// } /// /// static let authorForeignKey = ForeignKey([Columns.authorId])) /// static let translatorForeignKey = ForeignKey([Columns.translatorId])) /// } /// /// When the destination table of a foreign key does not define any primary key, /// you need to provide the full definition of a foreign key: /// /// struct Book: TableRecord { /// static let authorForeignKey = ForeignKey(["authorId"], to: ["id"])) /// static let author = belongsTo(Person.self, using: authorForeignKey) /// } public struct ForeignKey { var originColumns: [String] var destinationColumns: [String]? /// Creates a ForeignKey intended to define a record association. /// /// struct Book: TableRecord { /// // Define foreign keys /// static let authorForeignKey = ForeignKey(["authorId"])) /// static let translatorForeignKey = ForeignKey(["translatorId"])) /// /// // Use foreign keys to define associations: /// static let author = belongsTo(Person.self, using: authorForeignKey) /// static let translator = belongsTo(Person.self, using: translatorForeignKey) /// } /// /// - parameter originColumns: The columns at the origin of the foreign key. /// - parameter destinationColumns: The columns at the destination of the /// foreign key. When nil (the default), GRDB automatically uses the /// primary key. public init(_ originColumns: [String], to destinationColumns: [String]? = nil) { self.originColumns = originColumns self.destinationColumns = destinationColumns } /// Creates a ForeignKey intended to define a record association. /// /// struct Book: TableRecord { /// // Define columns /// enum Columns: String, ColumnExpression { /// case id, title, authorId, translatorId /// } /// /// // Define foreign keys /// static let authorForeignKey = ForeignKey([Columns.authorId])) /// static let translatorForeignKey = ForeignKey([Columns.translatorId])) /// /// // Use foreign keys to define associations: /// static let author = belongsTo(Person.self, using: authorForeignKey) /// static let translator = belongsTo(Person.self, using: translatorForeignKey) /// } /// /// - parameter originColumns: The columns at the origin of the foreign key. /// - parameter destinationColumns: The columns at the destination of the /// foreign key. When nil (the default), GRDB automatically uses the /// primary key. public init(_ originColumns: [ColumnExpression], to destinationColumns: [ColumnExpression]? = nil) { self.init(originColumns.map(\.name), to: destinationColumns?.map(\.name)) } } extension TableRecord where Self: EncodableRecord { /// Creates a request that fetches the associated record(s). /// /// For example: /// /// struct Team: TableRecord, EncodableRecord { /// static let players = hasMany(Player.self) /// var players: QueryInterfaceRequest { /// return request(for: Team.players) /// } /// } /// /// let team: Team = ... /// let players = try team.players.fetchAll(db) // [Player] public func request(for association: A) -> QueryInterfaceRequest where A.OriginRowDecoder == Self { switch association._sqlAssociation.pivot.condition { case .expression: // TODO: find a use case? fatalError("Not implemented: request association without any foreign key") case let .foreignKey(request: foreignKeyRequest, originIsLeft: originIsLeft): let destinationRelation = association ._sqlAssociation .map(\.pivot.relation, { pivotRelation in pivotRelation.filter { db in // Filter the pivot on self try foreignKeyRequest .fetchForeignKeyMapping(db) .joinMapping(originIsLeft: originIsLeft) .joinExpression(leftRows: [PersistenceContainer(db, self)]) } }) .destinationRelation() return QueryInterfaceRequest(relation: destinationRelation) } } } extension TableRecord { // MARK: - Associations /// Creates a request that prefetches an association. public static func including(all association: A) -> QueryInterfaceRequest where A.OriginRowDecoder == Self { all().including(all: association) } /// Creates a request that includes an association. The columns of the /// associated record are selected. The returned association does not /// require that the associated database table contains a matching row. public static func including(optional association: A) -> QueryInterfaceRequest where A.OriginRowDecoder == Self { all().including(optional: association) } /// Creates a request that includes an association. The columns of the /// associated record are selected. The returned association requires /// that the associated database table contains a matching row. public static func including(required association: A) -> QueryInterfaceRequest where A.OriginRowDecoder == Self { all().including(required: association) } /// Creates a request that includes an association. The columns of the /// associated record are not selected. The returned association does not /// require that the associated database table contains a matching row. public static func joining(optional association: A) -> QueryInterfaceRequest where A.OriginRowDecoder == Self { all().joining(optional: association) } /// Creates a request that includes an association. The columns of the /// associated record are not selected. The returned association requires /// that the associated database table contains a matching row. public static func joining(required association: A) -> QueryInterfaceRequest where A.OriginRowDecoder == Self { all().joining(required: association) } // MARK: - Association Aggregates /// Creates a request with *aggregates* appended to the selection. /// /// // SELECT player.*, COUNT(DISTINCT book.id) AS bookCount /// // FROM player LEFT JOIN book ... /// var request = Player.annotated(with: Player.books.count) public static func annotated(with aggregates: AssociationAggregate...) -> QueryInterfaceRequest { all().annotated(with: aggregates) } /// Creates a request with *aggregates* appended to the selection. /// /// // SELECT player.*, COUNT(DISTINCT book.id) AS bookCount /// // FROM player LEFT JOIN book ... /// var request = Player.annotated(with: [Player.books.count]) public static func annotated(with aggregates: [AssociationAggregate]) -> QueryInterfaceRequest { all().annotated(with: aggregates) } /// Creates a request with the provided aggregate *predicate*. /// /// // SELECT player.* /// // FROM player LEFT JOIN book ... /// // HAVING COUNT(DISTINCT book.id) = 0 /// var request = Player.all() /// request = request.having(Player.books.isEmpty) /// /// The selection defaults to all columns. This default can be changed for /// all requests by the `TableRecord.databaseSelection` property, or /// for individual requests with the `TableRecord.select` method. public static func having(_ predicate: AssociationAggregate) -> QueryInterfaceRequest { all().having(predicate) } }