Statement

public final class Statement

extension Statement: Sequence

extension Statement: IteratorProtocol

A compiled SQL statement with support for SQL parameter binding and result row processing.

Creation

A statement is not created directly but is obtained from a Database.

let statement = try db.prepare(sql: "select count(*) from t1;")

Parameter Binding

A statement supports binding values to SQL parameters by index or by name.

Note

Parameter indexes are 1-based. The leftmost parameter in a statement has index 1.

let statement = try db.prepare(sql: "insert into t1(a, b, c, d, e, f) values (?, ?, ?, :d, :e, :f);")
try statement.bind(value: 30, toParameter: 3)
try statement.bind(value: 40, toParameter: ":d")
try statement.bind(parameterValues: 10, 20)
try statement.bind(parameters: [":f": 60, ":e": 50])

Result Rows

When executed a statement provides zero or more result rows.

try statement.results { row in
    // Do something with `row`
}

for row in statement {
    // Do something with `row`
}

It is generally preferred to use the block-based method because any errors may be explicitly handled instead of silently discarded.

database
The owning database
Declaration
Swift

public let database: Database
isReadOnly
true if this statement makes no direct changes to the database, false otherwise.

Seealso
Read-only statements in SQLite
Declaration
Swift

public lazy var isReadOnly: Bool { get set }
parameterCount
The number of SQL parameters in this statement
Declaration
Swift

public lazy var parameterCount: Int { get set }
sql
The original SQL text of the statement
Declaration
Swift

public lazy var sql: String { get set }
expandedSQL
The SQL text of the statement with bound parameters expanded
Declaration
Swift

public var expandedSQL: String { get }
columnCount
The number of columns in the result set
Declaration
Swift

public lazy var columnCount: Int { get set }


                    
                    
                    name(ofColumn:)

Returns the name of the column at index.

Note

Column indexes are 0-based. The leftmost column in a result row has index 0.

Requires

index >= 0

Requires

index < self.columnCount

Throws

An error if index is out of bounds

Declaration

Swift

public func name(ofColumn index: Int) throws -> String

Parameters


                                index

The index of the desired column

Return Value

The name of the column for the specified index


                    
                    
                    index(ofColumn:)

Returns the index of the column name.

Throws

An error if the column doesn’t exist

Declaration

Swift

public func index(ofColumn name: String) throws -> Int

Parameters


                                name

The name of the desired column

Return Value

The index of the column with the specified name

execute()
Executes the statement.

Requires

The statement does not return any result rows

Throws

An error if the statement returned any result rows or did not successfully run to completion
Declaration
Swift

public func execute() throws


                    
                    
                    results(_:)

Executes the statement and applies block to each result row.

Throws

Any error thrown in block or an error if the statement did not successfully run to completion

Declaration

Swift

public func results(_ block: ((_ row: Row) throws -> ())) throws

Parameters

`block`	A closure applied to each result row
`row`	A result row of returned data

nextRow()
Returns the next result row or nil if none.

Throws

An error if the statement encountered an execution error
Declaration
Swift

public func nextRow() throws -> Row?
Return Value

The next result row of returned data
reset()
Resets the statement to its initial state, ready to be re-executed.

Note

This function does not change the value of any bound SQL parameters.

Throws

An error if the statement could not be reset
Declaration
Swift

public func reset() throws
clearBindings()
Clears all statement bindings by setting SQL parameters to null.

Throws
An error if the bindings could not be cleared
Declaration
Swift

public func clearBindings() throws


                    
                    
                    withUnsafeRawSQLiteStatement(block:)

Performs a low-level SQLite statement operation.

Use of this function should be avoided whenever possible

Throws

Any error thrown in block

Declaration

Swift

public func withUnsafeRawSQLiteStatement<T>(block: (_ stmt: SQLitePreparedStatement) throws -> (T)) rethrows -> T

Parameters

`block`	A closure performing the operation
`stmt`	The raw `sqlite3_stmt *` statement object

Return Value

The value returned by block


                    
                    
                    columns(_:)

Returns the values of the columns at indexes for each row in the result set.

Note

Column indexes are 0-based. The leftmost column in a row has index 0.

Requires

indexes.min() >= 0

Requires

indexes.max() < self.columnCount

Throws

An error if any element of indexes is out of bounds

Declaration

Swift

public func columns<S, T>(_ indexes: S) throws -> [[T]] where S : Collection, T : ColumnConvertible, S.Element == Int

Parameters


                                indexes

The indexes of the desired columns


                    
                    
                    column(_:)

Returns the value of the column at index for each row in the result set.

Note

Column indexes are 0-based. The leftmost column in a row has index 0.

Requires

index >= 0

Requires

index < self.columnCount

Throws

An error if index is out of bounds or the column contains a null or illegal value

Declaration

Swift

public func column<T>(_ index: Int) throws -> [T] where T : ColumnConvertible

Parameters


                                index

The index of the desired column

leftmostColumn()
Returns the value of the leftmost column for each row in the result set.

This is a shortcut for column(0).

Throws

An error if there are no columns
Declaration
Swift

public func leftmostColumn<T>() throws -> [T] where T : ColumnConvertible
Return Value

An array containing the leftmost column’s values
front()
Returns the value of the leftmost column in the first row.

Throws

An error if there are no columns or the column contains an illegal value
Declaration
Swift

public func front<T>() throws -> T? where T : ColumnConvertible
Return Value

The value of the leftmost column in the first row
front()
Returns the value of the leftmost column in the first row.

Throws

An error if there are no rows, no columns, or the column contains a null or illegal value
Declaration
Swift

public func front<T>() throws -> T where T : ColumnConvertible
Return Value

The value of the leftmost column in the first row


                    
                    
                    columns(_:)

Returns the values of the columns at indexes for each row in the result set.

Note

Column indexes are 0-based. The leftmost column in a row has index 0.

Requires

indexes.min() >= 0

Requires

indexes.max() < self.columnCount

Throws

An error if any element of indexes is out of bounds

Declaration

Swift

public func columns<S, T>(_ indexes: S) throws -> [[T]] where S : Collection, T : DatabaseSerializable, S.Element == Int

Parameters


                                indexes

The indexes of the desired columns


                    
                    
                    column(_:)

Returns the value of the column at index for each row in the result set.

Note

Column indexes are 0-based. The leftmost column in a row has index 0.

Requires

index >= 0

Requires

index < self.columnCount

Throws

An error if index is out of bounds or the column contains a null or illegal value

Declaration

Swift

public func column<T>(_ index: Int) throws -> [T] where T : DatabaseSerializable

Parameters


                                index

The index of the desired column

leftmostColumn()
Returns the value of the leftmost column for each row in the result set.

This is a shortcut for column(0).

Throws

An error if there are no columns
Declaration
Swift

public func leftmostColumn<T>() throws -> [T] where T : DatabaseSerializable
Return Value

An array containing the leftmost column’s values
front()
Returns the value of the leftmost column in the first row.

Throws

An error if there are no columns or the column contains an illegal value
Declaration
Swift

public func front<T>() throws -> T? where T : DatabaseSerializable
Return Value

The value of the leftmost column in the first row
front()
Returns the value of the leftmost column in the first row.

Throws

An error if there are no rows, no columns, or the column contains an illegal value
Declaration
Swift

public func front<T>() throws -> T where T : DatabaseSerializable
Return Value

The value of the leftmost column in the first row


                    
                    
                    columns(_:)

Returns the values of the columns at indexes for each row in the result set.

Note

Column indexes are 0-based. The leftmost column in a row has index 0.

Requires

indexes.min() >= 0

Requires

indexes.max() < self.columnCount

Throws

An error if any element of indexes is out of bounds

Declaration

Swift

public func columns<S>(_ indexes: S) throws -> [[DatabaseValue]] where S : Collection, S.Element == Int

Parameters


                                indexes

The indexes of the desired columns


                    
                    
                    column(_:)

Returns the value of the column at index for each row in the result set.

Note

Column indexes are 0-based. The leftmost column in a row has index 0.

Requires

index >= 0

Requires

index < self.columnCount

Throws

An error if index is out of bounds

Declaration

Swift

public func column(_ index: Int) throws -> [DatabaseValue]

Parameters


                                index

The index of the desired column

leftmostColumn()
Returns the value of the leftmost column for each row in the result set.

This is a shortcut for column(0).

Throws

An error if there are no columns
Declaration
Swift

public func leftmostColumn() throws -> [DatabaseValue]
Return Value

An array containing the leftmost column’s values
front()
Returns the value of the leftmost column in the first result row.

Throws

An error if there are no columns
Declaration
Swift

public func front() throws -> DatabaseValue?
Return Value

The value of the leftmost column in the first result row
front()
Returns the value of the leftmost column in the first result row.

Throws

An error if there are no rows or columns
Declaration
Swift

public func front() throws -> DatabaseValue
Return Value

The value of the leftmost column in the first result row


                    
                    
                    bindNull(toParameter:)

Binds database NULL to the SQL parameter at index.

Note

Parameter indexes are 1-based. The leftmost parameter in a statement has index 1.

Requires

index > 0

Requires

index < parameterCount

Throws

An error if NULL couldn’t be bound

Declaration

Swift

public func bindNull(toParameter index: Int) throws

Parameters


                                index

The index of the SQL parameter to bind


                    
                    
                    bindNull(toParameter:)

Binds database NULL to the SQL parameter name.

Throws

An error if the SQL parameter name doesn’t exist or NULL couldn’t be bound

Declaration

Swift

public func bindNull(toParameter name: String) throws

Parameters


                                name

The name of the SQL parameter to bind


                    
                    
                    bind(value:toParameter:)

Binds value to the SQL parameter at index.

Note

Parameter indexes are 1-based. The leftmost parameter in a statement has index 1.

Requires

index > 0

Requires

index < parameterCount

Throws

An error if value couldn’t be bound

Declaration

Swift

public func bind<T>(value: T, toParameter index: Int) throws where T : ParameterBindable

Parameters

`value`	The desired value of the SQL parameter
`index`	The index of the SQL parameter to bind


                    
                    
                    bind(value:toParameter:)

Binds value to the SQL parameter at index.

Note

Parameter indexes are 1-based. The leftmost parameter in a statement has index 1.

Requires

index > 0

Requires

index < parameterCount

Throws

An error if value couldn’t be bound

Declaration

Swift

public func bind<T>(value: T?, toParameter index: Int) throws where T : ParameterBindable

Parameters

`value`	The desired value of the SQL parameter
`index`	The index of the SQL parameter to bind


                    
                    
                    bind(value:toParameter:)

Binds value to the SQL parameter name.

Throws

An error if the SQL parameter name doesn’t exist or value couldn’t be bound

Declaration

Swift

public func bind<T>(value: T, toParameter name: String) throws where T : ParameterBindable

Parameters

`value`	The desired value of the SQL parameter
`name`	The name of the SQL parameter to bind


                    
                    
                    bind(value:toParameter:)

Binds value to the SQL parameter name.

Throws

An error if the SQL parameter name doesn’t exist or value couldn’t be bound

Declaration

Swift

public func bind<T>(value: T?, toParameter name: String) throws where T : ParameterBindable

Parameters

`value`	The desired value of the SQL parameter
`name`	The name of the SQL parameter to bind


                    
                    
                    bind(parameterValues:)

Binds the n parameters in values to the first n SQL parameters of self.

Throws

An error if one of values couldn’t be bound

Declaration

Swift

@discardableResult
public func bind<C>(parameterValues values: C) throws -> Statement where C : Collection, C.Element : ParameterBindable

Parameters


                                values

A collection of values to bind to SQL parameters

Return Value

self


                    
                    
                    bind(parameters:)

Binds value to SQL parameter name for each (name, value) in parameters.

Throws

An error if the SQL parameter name doesn’t exist or value couldn’t be bound

Declaration

Swift

@discardableResult
public func bind<C>(parameters: C) throws -> Statement where C : Collection, C.Element == (String, V: ParameterBindable)

Parameters


                                parameters

A collection of name and value pairs to bind to SQL parameters

Return Value

self


                    
                    
                    bind(parameterValues:)

Binds the n parameters in values to the first n SQL parameters of self.

Requires

values.count <= self.parameterCount

Throws

An error if one of values couldn’t be bound

Declaration

Swift

@discardableResult
public func bind(parameterValues values: [ParameterBindable?]) throws -> Statement

Parameters


                                values

A series of values to bind to SQL parameters

Return Value

self


                    
                    
                    bind(parameters:)

Binds value to SQL parameter name for each (name, value) in parameters.

Throws

An error if the SQL parameter name doesn’t exist or value couldn’t be bound

Declaration

Swift

@discardableResult
public func bind(parameters: [String : ParameterBindable?]) throws -> Statement

Parameters


                                parameters

A series of name and value pairs to bind to SQL parameters

Return Value

self

Int32


                    
                    
                    bind(array:toParameter:)

Binds the values in array to the SQL parameter at index using the sqlite3 Carray extension

When using the Carray extension in FeistyDB the number of array elements must be explicitly bound:

let primes = [ 3, 5, 7 ]
let statement = try db.prepare(sql: "SELECT * FROM numbers WHERE value IN carray(?1,?2,'int32');")
try statement.bind(array: primes, toParameter: 1)
try statement.bind(value: primes.count, toParameter: 2)

Note

Parameter indexes are 1-based. The leftmost parameter in a statement has index 1.

Requires

index > 0

Requires

index < parameterCount

Throws

An error if array couldn’t be bound

Seealso

The Carray() Table-Valued Function

Declaration

Swift

public func bind<S>(array: S, toParameter index: Int) throws where S : Collection, S.Element == Int32

Parameters

`array`	An array of values to bind to the SQL parameter
`index`	The index of the SQL parameter to bind


                    
                    
                    bind(array:toParameter:)

Binds the values in array to SQL parameter name using the sqlite3 Carray extension

When using the Carray extension in FeistyDB the number of array elements must be explicitly bound:

let primes = [ 3, 5, 7 ]
let statement = try db.prepare(sql: "SELECT * FROM numbers WHERE value IN carray(:primes,?2,'int32');")
try statement.bind(array: primes, toParameter: ":primes")
try statement.bind(value: primes.count, toParameter: 2)

Throws

An error if the SQL parameter name doesn’t exist or array couldn’t be bound

Seealso

The Carray() Table-Valued Function

Declaration

Swift

public func bind<S>(array: S, toParameter name: String) throws where S : Collection, S.Element == Int32

Parameters

`array`	An array of values to bind to the SQL parameter
`name`	The name of the SQL parameter to bind

Int64


                    
                    
                    bind(array:toParameter:)

Binds the values in array to the SQL parameter at index using the sqlite3 Carray extension

When using the Carray extension in FeistyDB the number of array elements must be explicitly bound:

let primes = [ 87178291199, 99194853094755497 ]
let statement = try db.prepare(sql: "SELECT * FROM numbers WHERE value IN carray(?1,?2,'int64');")
try statement.bind(array: primes, toParameter: 1)
try statement.bind(value: primes.count, toParameter: 2)

Note

Parameter indexes are 1-based. The leftmost parameter in a statement has index 1.

Requires

index > 0

Requires

index < parameterCount

Throws

An error if array couldn’t be bound

Seealso

The Carray() Table-Valued Function

Declaration

Swift

public func bind<S>(array: S, toParameter index: Int) throws where S : Collection, S.Element == Int64

Parameters

`array`	An array of values to bind to the SQL parameter
`index`	The index of the SQL parameter to bind


                    
                    
                    bind(array:toParameter:)

Binds the values in array to SQL parameter name using the sqlite3 Carray extension

When using the Carray extension in FeistyDB the number of array elements must be explicitly bound:

let primes = [ 87178291199, 99194853094755497 ]
let statement = try db.prepare(sql: "SELECT * FROM numbers WHERE value IN carray(:primes,?2,'int64');")
try statement.bind(array: primes, toParameter: ":primes")
try statement.bind(value: primes.count, toParameter: 2)

Throws

An error if the SQL parameter name doesn’t exist or array couldn’t be bound

Seealso

The Carray() Table-Valued Function

Declaration

Swift

public func bind<S>(array: S, toParameter name: String) throws where S : Collection, S.Element == Int64

Parameters

`array`	An array of values to bind to the SQL parameter
`name`	The name of the SQL parameter to bind

Double


                    
                    
                    bind(array:toParameter:)

Binds the values in array to the SQL parameter at index using the sqlite3 Carray extension

When using the Carray extension in FeistyDB the number of array elements must be explicitly bound:

let specials = [ Double.pi, Double.nan, Double.infinity ]
let statement = try db.prepare(sql: "SELECT * FROM numbers WHERE value IN carray(?1,?2,'double');")
try statement.bind(array: specials, toParameter: 1)
try statement.bind(value: specials.count, toParameter: 2)

Note

Parameter indexes are 1-based. The leftmost parameter in a statement has index 1.

Requires

index > 0

Requires

index < parameterCount

Throws

An error if array couldn’t be bound

Seealso

The Carray() Table-Valued Function

Declaration

Swift

public func bind<S>(array: S, toParameter index: Int) throws where S : Collection, S.Element == Double

Parameters

`array`	An array of values to bind to the SQL parameter
`index`	The index of the SQL parameter to bind


                    
                    
                    bind(array:toParameter:)

Binds the values in array to SQL parameter name using the sqlite3 Carray extension

When using the Carray extension in FeistyDB the number of array elements must be explicitly bound:

let specials = [ Double.pi, Double.nan, Double.infinity ]
let statement = try db.prepare(sql: "SELECT * FROM numbers WHERE value IN carray(:specials,?2,'double');")
try statement.bind(array: specials, toParameter: ":specials")
try statement.bind(value: specials.count, toParameter: 2)

Throws

An error if the SQL parameter name doesn’t exist or array couldn’t be bound

Seealso

The Carray() Table-Valued Function

Declaration

Swift

public func bind<S>(array: S, toParameter name: String) throws where S : Collection, S.Element == Double

Parameters

`array`	An array of values to bind to the SQL parameter
`name`	The name of the SQL parameter to bind

String


                    
                    
                    bind(array:toParameter:)

Binds the values in array to the SQL parameter at index using the sqlite3 Carray extension

When using the Carray extension in FeistyDB the number of array elements must be explicitly bound:

let pets = [ "dog", "dragon", "hedgehog" ]
let statement = try db.prepare(sql: "SELECT * FROM animals WHERE kind IN carray(?1,?2,'char*');")
try statement.bind(array: pets, toParameter: 1)
try statement.bind(value: pets.count, toParameter: 2)

Note

Parameter indexes are 1-based. The leftmost parameter in a statement has index 1.

Requires

index > 0

Requires

index < parameterCount

Throws

An error if array couldn’t be bound

Seealso

The Carray() Table-Valued Function

Declaration

Swift

public func bind<S>(array: S, toParameter index: Int) throws where S : Collection, S.Element == String

Parameters

`array`	An array of values to bind to the SQL parameter
`index`	The index of the SQL parameter to bind


                    
                    
                    bind(array:toParameter:)

Binds the values in array to SQL parameter name using the sqlite3 Carray extension

When using the Carray extension in FeistyDB the number of array elements must be explicitly bound:

let pets = [ "dog", "dragon", "hedgehog" ]
let statement = try db.prepare(sql: "SELECT * FROM animals WHERE kind IN carray(:pets,?2,'char*');")
try statement.bind(array: pets, toParameter: ":pets")
try statement.bind(value: pets.count, toParameter: 2)

Throws

An error if the SQL parameter name doesn’t exist or array couldn’t be bound

Seealso

The Carray() Table-Valued Function

Declaration

Swift

public func bind<S>(array: S, toParameter name: String) throws where S : Collection, S.Element == String

Parameters

`array`	An array of values to bind to the SQL parameter
`name`	The name of the SQL parameter to bind

firstRow()
Returns the first result row or nil if none.

Throws

An error if the statement encountered an execution error
Declaration
Swift

public func firstRow() throws -> Row?
Return Value

The first result row
makeIterator()
Returns an iterator for accessing the result rows.

Because the iterator discards errors, the preferred way of accessing result rows is via nextRow() or results(_:)
Declaration
Swift

public func makeIterator() -> Statement
Return Value

An iterator over the result rows
next()
Returns the next result row or nil if none.

Because the iterator discards errors, the preferred way of accessing result rows is via nextRow() or results(_:)
Declaration
Swift

public func next() -> Row?
Return Value

The next result row of returned data
Counter
Available statement counters.

Seealso
Status Parameters for prepared statements
See more
Declaration
Swift

public enum Counter


                    
                    
                    count(of:reset:)

Returns information on a statement counter.

Seealso

Prepared Statement Status

Declaration

Swift

public func count(of counter: Counter, reset: Bool = false) -> Int

Parameters

`counter`	The desired statement counter
`reset`	If `true` the counter is reset to zero

Return Value

The current value of the counter