FetchRequest

public protocol FetchRequest : DatabaseRegionConvertible

The protocol for all requests that fetch database rows, and tell how those rows should be interpreted.

struct Player: FetchableRecord { ... }
let request: ... // Some FetchRequest that fetches Player
try request.fetchCursor(db) // Cursor of Player
try request.fetchAll(db)    // [Player]
try request.fetchOne(db)    // Player?
  • The type that tells how fetched database rows should be interpreted.

    Declaration

    Swift

    associatedtype RowDecoder
  • This method is deprecated. Use makePreparedRequest(_:forSingleResult:) instead.

    Returns a tuple that contains a prepared statement that is ready to be executed, and an eventual row adapter.

    Declaration

    Swift

    func prepare(_ db: Database, forSingleResult singleResult: Bool) throws -> (SelectStatement, RowAdapter?)

    Parameters

    db

    A database connection.

    singleResult

    A hint that a single result row will be consumed. Implementations can optionally use this to optimize the prepared statement.

    Return Value

    A prepared statement and an eventual row adapter.

  • Returns a PreparedRequest that is ready to be executed.

    Declaration

    Swift

    func makePreparedRequest(_ db: Database, forSingleResult singleResult: Bool) throws -> PreparedRequest

    Parameters

    db

    A database connection.

    singleResult

    A hint that a single result row will be consumed. Implementations can optionally use this to optimize the prepared statement.

    Return Value

    A prepared request.

  • fetchCount(_:) Default implementation

    Returns the number of rows fetched by the request.

    The default implementation builds a naive SQL query based on the statement returned by the prepare method: SELECT COUNT(*) FROM (...).

    Adopting types can refine this method in order to use more efficient SQL.

    Default Implementation

    Returns the number of rows fetched by the request.

    This default implementation builds a naive SQL query based on the statement returned by the prepare method: SELECT COUNT(*) FROM (...).

    Declaration

    Swift

    func fetchCount(_ db: Database) throws -> Int

    Parameters

    db

    A database connection.

FetchRequest

Observation

  • observationForCount() Extension method

    Creates a ValueObservation which observes request, and notifies its count whenever it is modified by a database transaction.

    For example:

    let request = Player.all()
    let observation = request.observationForCount()
    
    let observer = try observation.start(in: dbQueue) { count: Int in
        print("Number of players has changed")
    }
    

    The returned observation has the default configuration:

    • When started with the start(in:onError:onChange:) method, a fresh value is immediately notified on the main queue.
    • Upon subsequent database changes, fresh values are notified on the main queue.
    • The observation lasts until the observer returned by start is deallocated.

    Declaration

    Swift

    public func observationForCount() ->
        ValueObservation<ValueReducers.RemoveDuplicates<ValueReducers.Fetch<Int>>>

    Return Value

    a ValueObservation.

Fetching Values

  • fetchCursor(_:) Extension method

    A cursor over fetched values.

    let request: ... // Some FetchRequest that fetches String
    let strings = try request.fetchCursor(db) // Cursor of String
    while let string = try strings.next() {   // String
        ...
    }
    

    If the database is modified during the cursor iteration, the remaining elements are undefined.

    The cursor must be iterated in a protected dispath queue.

    Throws

    A DatabaseError is thrown whenever an SQLite error occurs.

    Declaration

    Swift

    public func fetchCursor(_ db: Database) throws -> DatabaseValueCursor<RowDecoder>

    Parameters

    db

    A database connection.

    Return Value

    A cursor over fetched values.

  • fetchAll(_:) Extension method

    An array of fetched values.

    let request: ... // Some FetchRequest that fetches String
    let strings = try request.fetchAll(db) // [String]
    

    Throws

    A DatabaseError is thrown whenever an SQLite error occurs.

    Declaration

    Swift

    public func fetchAll(_ db: Database) throws -> [RowDecoder]

    Parameters

    db

    A database connection.

    Return Value

    An array of values.

  • fetchOne(_:) Extension method

    The first fetched value.

    The result is nil if the request returns no row, or if no value can be extracted from the first row.

    let request: ... // Some FetchRequest that fetches String
    let string = try request.fetchOne(db) // String?
    

    Throws

    A DatabaseError is thrown whenever an SQLite error occurs.

    Declaration

    Swift

    public func fetchOne(_ db: Database) throws -> RowDecoder?

    Parameters

    db

    A database connection.

    Return Value

    An optional value.

Fetching Optional values

  • fetchCursor(_:) Extension method

    A cursor over fetched optional values.

    let request: ... // Some FetchRequest that fetches Optional<String>
    let strings = try request.fetchCursor(db) // Cursor of String?
    while let string = try strings.next() {   // String?
        ...
    }
    

    If the database is modified during the cursor iteration, the remaining elements are undefined.

    The cursor must be iterated in a protected dispath queue.

    Throws

    A DatabaseError is thrown whenever an SQLite error occurs.

    Declaration

    Swift

    public func fetchCursor(_ db: Database) throws -> NullableDatabaseValueCursor<RowDecoder._Wrapped>

    Parameters

    db

    A database connection.

    Return Value

    A cursor over fetched values.

  • fetchAll(_:) Extension method

    An array of fetched optional values.

    let request: ... // Some FetchRequest that fetches Optional<String>
    let strings = try request.fetchAll(db) // [String?]
    

    Throws

    A DatabaseError is thrown whenever an SQLite error occurs.

    Declaration

    Swift

    public func fetchAll(_ db: Database) throws -> [RowDecoder._Wrapped?]

    Parameters

    db

    A database connection.

    Return Value

    An array of values.

Fetching Rows

  • fetchCursor(_:) Extension method

    A cursor over fetched rows.

    let request: ... // Some FetchRequest that fetches Row
    let rows = try request.fetchCursor(db) // RowCursor
    while let row = try rows.next() {  // Row
        let id: Int64 = row[0]
        let name: String = row[1]
    }
    

    Fetched rows are reused during the cursor iteration: don’t turn a row cursor into an array with Array(rows) or rows.filter { ... } since you would not get the distinct rows you expect. Use Row.fetchAll(...) instead.

    For the same reason, make sure you make a copy whenever you extract a row for later use: row.copy().

    If the database is modified during the cursor iteration, the remaining elements are undefined.

    The cursor must be iterated in a protected dispath queue.

    Throws

    A DatabaseError is thrown whenever an SQLite error occurs.

    Declaration

    Swift

    public func fetchCursor(_ db: Database) throws -> RowCursor

    Parameters

    db

    A database connection.

    Return Value

    A cursor over fetched rows.

  • fetchAll(_:) Extension method

    An array of fetched rows.

    let request: ... // Some FetchRequest that fetches Row
    let rows = try request.fetchAll(db)
    

    Throws

    A DatabaseError is thrown whenever an SQLite error occurs.

    Declaration

    Swift

    public func fetchAll(_ db: Database) throws -> [Row]

    Parameters

    db

    A database connection.

    Return Value

    An array of fetched rows.

  • fetchOne(_:) Extension method

    The first fetched row.

    let request: ... // Some FetchRequest that fetches Row
    let row = try request.fetchOne(db)
    

    Throws

    A DatabaseError is thrown whenever an SQLite error occurs.

    Declaration

    Swift

    public func fetchOne(_ db: Database) throws -> Row?

    Parameters

    db

    A database connection.

    Return Value

    An optional row.

Fetching Values

  • fetchCursor(_:) Extension method

    A cursor over fetched values.

    let request: ... // Some FetchRequest that fetches String
    let strings = try request.fetchCursor(db) // Cursor of String
    while let string = try strings.next() {   // String
        ...
    }
    

    If the database is modified during the cursor iteration, the remaining elements are undefined.

    The cursor must be iterated in a protected dispath queue.

    Throws

    A DatabaseError is thrown whenever an SQLite error occurs.

    Declaration

    Swift

    public func fetchCursor(_ db: Database) throws -> FastDatabaseValueCursor<RowDecoder>

    Parameters

    db

    A database connection.

    Return Value

    A cursor over fetched values.

  • fetchAll(_:) Extension method

    An array of fetched values.

    let request: ... // Some FetchRequest that fetches String
    let strings = try request.fetchAll(db) // [String]
    

    Throws

    A DatabaseError is thrown whenever an SQLite error occurs.

    Declaration

    Swift

    public func fetchAll(_ db: Database) throws -> [RowDecoder]

    Parameters

    db

    A database connection.

    Return Value

    An array of values.

  • fetchOne(_:) Extension method

    The first fetched value.

    The result is nil if the request returns no row, or if no value can be extracted from the first row.

    let request: ... // Some FetchRequest that fetches String
    let string = try request.fetchOne(db) // String?
    

    Throws

    A DatabaseError is thrown whenever an SQLite error occurs.

    Declaration

    Swift

    public func fetchOne(_ db: Database) throws -> RowDecoder?

    Parameters

    db

    A database connection.

    Return Value

    An optional value.

Fetching Optional values

  • fetchCursor(_:) Extension method

    A cursor over fetched optional values.

    let request: ... // Some FetchRequest that fetches Optional<String>
    let strings = try request.fetchCursor(db) // Cursor of String?
    while let string = try strings.next() {   // String?
        ...
    }
    

    If the database is modified during the cursor iteration, the remaining elements are undefined.

    The cursor must be iterated in a protected dispath queue.

    Throws

    A DatabaseError is thrown whenever an SQLite error occurs.

    Declaration

    Swift

    public func fetchCursor(_ db: Database) throws -> FastNullableDatabaseValueCursor<RowDecoder._Wrapped>

    Parameters

    db

    A database connection.

    Return Value

    A cursor over fetched values.

  • fetchAll(_:) Extension method

    An array of fetched optional values.

    let request: ... // Some FetchRequest that fetches Optional<String>
    let strings = try request.fetchAll(db) // [String?]
    

    Throws

    A DatabaseError is thrown whenever an SQLite error occurs.

    Declaration

    Swift

    public func fetchAll(_ db: Database) throws -> [RowDecoder._Wrapped?]

    Parameters

    db

    A database connection.

    Return Value

    An array of values.

Fetching Records

  • fetchCursor(_:) Extension method

    A cursor over fetched records.

    let request: ... // Some FetchRequest that fetches Player
    let players = try request.fetchCursor(db) // Cursor of Player
    while let player = try players.next() {   // Player
        ...
    }
    

    If the database is modified during the cursor iteration, the remaining elements are undefined.

    The cursor must be iterated in a protected dispath queue.

    Throws

    A DatabaseError is thrown whenever an SQLite error occurs.

    Declaration

    Swift

    public func fetchCursor(_ db: Database) throws -> RecordCursor<RowDecoder>

    Parameters

    db

    A database connection.

    Return Value

    A cursor over fetched records.

  • fetchAll(_:) Extension method

    An array of fetched records.

    let request: ... // Some FetchRequest that fetches Player
    let players = try request.fetchAll(db) // [Player]
    

    Throws

    A DatabaseError is thrown whenever an SQLite error occurs.

    Declaration

    Swift

    public func fetchAll(_ db: Database) throws -> [RowDecoder]

    Parameters

    db

    A database connection.

    Return Value

    An array of records.

  • fetchOne(_:) Extension method

    The first fetched record.

    let request: ... // Some FetchRequest that fetches Player
    let player = try request.fetchOne(db) // Player?
    

    Throws

    A DatabaseError is thrown whenever an SQLite error occurs.

    Declaration

    Swift

    public func fetchOne(_ db: Database) throws -> RowDecoder?

    Parameters

    db

    A database connection.

    Return Value

    An optional record.

Observation

  • observationForAll() Extension method

    Creates a ValueObservation which observes request, and notifies fresh values whenever the request is modified by a database transaction.

    For example:

    let request = Player.select(Column("name"), as: String.self)
    let observation = request.observationForAll()
    
    let observer = try observation.start(in: dbQueue) { names: [String] in
        print("Player names have changed")
    }
    

    The returned observation has the default configuration:

    • When started with the start(in:onError:onChange:) method, a fresh value is immediately notified on the main queue.
    • Upon subsequent database changes, fresh values are notified on the main queue.
    • The observation lasts until the observer returned by start is deallocated.

    Declaration

    Swift

    public func observationForAll() -> ValueObservation<ValueReducers.AllValues<RowDecoder>>

    Return Value

    a ValueObservation.

  • observationForFirst() Extension method

    Creates a ValueObservation which observes request, and notifies a fresh value whenever the request is modified by a database transaction.

    For example:

    let request = Player.select(max(Column("score")), as: Int.self)
    let observation = request.observationForFirst()
    
    let observer = try observation.start(in: dbQueue) { maxScore: Int? in
        print("Maximum score has changed")
    }
    

    The returned observation has the default configuration:

    • When started with the start(in:onError:onChange:) method, a fresh value is immediately notified on the main queue.
    • Upon subsequent database changes, fresh values are notified on the main queue.
    • The observation lasts until the observer returned by start is deallocated.

    Declaration

    Swift

    public func observationForFirst() -> ValueObservation<ValueReducers.OneValue<RowDecoder>>

    Parameters

    request

    the observed request.

    Return Value

    a ValueObservation.

  • observationForAll() Extension method

    Creates a ValueObservation which observes request, and notifies fresh values whenever the request is modified by a database transaction.

    For example:

    let request = Player.select(Column("name"), as: Optional<String>.self)
    let observation = request.observationForAll()
    
    let observer = try observation.start(in: dbQueue) { names: [String?] in
        print("Player names have changed")
    }
    

    The returned observation has the default configuration:

    • When started with the start(in:onError:onChange:) method, a fresh value is immediately notified on the main queue.
    • Upon subsequent database changes, fresh values are notified on the main queue.
    • The observation lasts until the observer returned by start is deallocated.

    Declaration

    Swift

    public func observationForAll() -> ValueObservation<ValueReducers.AllOptionalValues<RowDecoder._Wrapped>>

    Return Value

    a ValueObservation.

  • observationForFirst() Extension method

    Creates a ValueObservation which observes request, and notifies fresh values whenever the request is modified by a database transaction.

    For example:

    let request = Player.select(Column("name"), as: Optional<String>.self)
    let observation = request.observationForAll()
    
    let observer = try observation.start(in: dbQueue) { names: [String?] in
        print("Player names have changed")
    }
    

    The returned observation has the default configuration:

    • When started with the start(in:onError:onChange:) method, a fresh value is immediately notified on the main queue.
    • Upon subsequent database changes, fresh values are notified on the main queue.
    • The observation lasts until the observer returned by start is deallocated.

    Declaration

    Swift

    public func observationForFirst() -> ValueObservation<ValueReducers.OneValue<RowDecoder._Wrapped>>

    Return Value

    a ValueObservation.

  • observationForAll() Extension method

    Creates a ValueObservation which observes request, and notifies fresh records whenever the request is modified by a database transaction.

    For example:

    let request = Player.all()
    let observation = request.observationForAll()
    
    let observer = try observation.start(in: dbQueue) { players: [Player] in
        print("Players have changed")
    }
    

    The returned observation has the default configuration:

    • When started with the start(in:onError:onChange:) method, a fresh value is immediately notified on the main queue.
    • Upon subsequent database changes, fresh values are notified on the main queue.
    • The observation lasts until the observer returned by start is deallocated.

    Declaration

    Swift

    public func observationForAll() -> ValueObservation<ValueReducers.AllRecords<RowDecoder>>

    Return Value

    a ValueObservation.

  • observationForFirst() Extension method

    Creates a ValueObservation which observes request, and notifies a fresh record whenever the request is modified by a database transaction.

    For example:

    let request = Player.filter(key: 1)
    let observation = request.observationForFirst()
    
    let observer = try observation.start(in: dbQueue) { player: Player? in
        print("Player has changed")
    }
    

    The returned observation has the default configuration:

    • When started with the start(in:onError:onChange:) method, a fresh value is immediately notified on the main queue.
    • Upon subsequent database changes, fresh values are notified on the main queue.
    • The observation lasts until the observer returned by start is deallocated.

    Declaration

    Swift

    public func observationForFirst() -> ValueObservation<ValueReducers.OneRecord<RowDecoder>>

    Return Value

    a ValueObservation.

  • observationForAll() Extension method

    Creates a ValueObservation which observes request, and notifies fresh rows whenever the request is modified by a database transaction.

    For example:

    let request = SQLRequest<Row>(sql: "SELECT * FROM player")
    let observation = request.observationForAll()
    
    let observer = try observation.start(in: dbQueue) { rows: [Row] in
        print("Players have changed")
    }
    

    The returned observation has the default configuration:

    • When started with the start(in:onError:onChange:) method, a fresh value is immediately notified on the main queue.
    • Upon subsequent database changes, fresh values are notified on the main queue.
    • The observation lasts until the observer returned by start is deallocated.

    Declaration

    Swift

    public func observationForAll() -> ValueObservation<ValueReducers.AllRows>

    Return Value

    a ValueObservation.

  • observationForFirst() Extension method

    Creates a ValueObservation which observes request, and notifies a fresh row whenever the request is modified by a database transaction.

    For example:

    let request = SQLRequest<Row>(sql: "SELECT * FROM player WHERE id = ?", arguments: [1])
    let observation = request.observationForFirst()
    
    let observer = try observation.start(in: dbQueue) { row: Row? in
        print("Players have changed")
    }
    

    The returned observation has the default configuration:

    • When started with the start(in:onError:onChange:) method, a fresh value is immediately notified on the main queue.
    • Upon subsequent database changes, fresh values are notified on the main queue.
    • The observation lasts until the observer returned by start is deallocated.

    Declaration

    Swift

    public func observationForFirst() -> ValueObservation<ValueReducers.OneRow>

    Return Value

    a ValueObservation.