SwiftData

Simple and Effective SQLite Handling in Swift

Download .zip Download .tar.gz View on GitHub

SwiftData API Documentation

Public Functions

public static func executeChange(sqlStr: String) -> Int?

Execute a non-query SQL statement (e.g. INSERT, UPDATE, DELETE, etc.)

This function will execute the provided SQL and return an Int with the error code, or nil if there was no error. It is recommended to always verify that the return value is nil to ensure that the operation was successful.

Possible errors returned by this function are:

  • SQLite errors (0 - 101)

Parameters:

  • sqlStr -> The non-query string of SQL to be executed (INSERT, UPDATE, DELETE, etc.)

Returns:

  • An Int with the error code, or nil if there was no error

public static func executeChange(sqlStr: String, withArgs: [AnyObject?]) -> Int?

Execute a non-query SQL statement (e.g. INSERT, UPDATE, DELETE, etc.) along with arguments to be bound to the characters "?" (for values) and "i?" (for identifiers e.g. table or column names).

The objects in the provided array of arguments will be bound, in order, to the "i?" and "?" characters in the SQL string. The quantity of "i?"s and "?"s in the SQL string must be equal to the quantity of arguments provided. Objects that are to bind as an identifier ("i?") must be of type String. Identifiers should be bound and escaped if provided by the user. If "nil" is provided as an argument, the NULL value will be bound to the appropriate value in the SQL string. For more information on how the objects will be escaped, refer to the functions "escapeValue()" and "escapeIdentifier()". Note that the "escapeValue()" and "escapeIdentifier()" include the necessary quotations ' ' or " " to the arguments when being bound to the SQL.

It is recommended to always verify that the return value is nil to ensure that the operation was successful.

Possible errors returned by this function are:

  • SQLite errors (0 - 101)
  • binding errors (201 - 203)

Parameters:

  • sqlStr -> The non-query string of SQL to be executed (INSERT, UPDATE, DELETE, etc.)
  • withArgs -> An array of objects to bind to the "?" and "i?" characters in the sqlStr

Returns:

  • An Int with the error code, or nil if there was no error

public static func executeMultipleChanges(sqlArr: [String]) -> Int?

Execute multiple SQL statements (non-queries e.g. INSERT, UPDATE, DELETE, etc.)

This function will execute each SQL statment in the provided array, in order, and return an Int with the error code, or nil if there was no error.

Possible errors returned by this function are:

  • SQLite errors (0 - 101)

Parameters:

  • sqlArr -> An array of non-query strings of SQL to be executed (INSERT, UPDATE, DELETE, etc.)

Returns:

  • An Int with the error code, or nil if there was no error

public static func executeQuery(sqlStr: String) -> (result: [SDRow], error: Int?)

Execute a SQLite query statement (e.g. SELECT)

This function will execute the provided SQL and return a tuple of:

  • an Array of SDRow objects
  • an Int with the error code, or nil if there was no error

The value for each column in an SDRow can be obtained using the column name in the subscript format similar to a Dictionary, along with the function to obtain the value in the appropriate type (.asString(), .asDate(), .asData(), .asInt(), .asDouble(), and .asBool()). Without the function call to return a specific type, the SDRow will return an object with type AnyObject. Note: NULL values in the SQLite database will be returned as 'nil'.

Possible errors returned by this function are:

  • SQLite errors (0 - 101)

Parameters:

  • sqlStr -> The query String of SQL to be executed (e.g. SELECT)

Returns:

  • A tuple containing an Array of "SDRow"s, and an Int with the error code or nil if there was no error

public static func executeQuery(sqlStr: String, withArgs: [AnyObject?]) -> (result: [SDRow], error: Int?)

Execute a SQL query statement (e.g. SELECT) with arguments to be bound to the characters "?" (for values) and "i?" (for identifiers e.g. table or column names).

See the "executeChange(sqlStr: String, withArgs: [AnyObject?])" function for more information on the arguments provided and binding.

See the "executeQuery(sqlStr: String)" function for more information on the return value.

Possible errors returned by this function are:

  • SQLite errors (0 - 101)
  • binding errors (201 - 203)

Parameters:

  • sqlStr -> The query String of SQL to be executed (e.g. SELECT)
  • withArgs -> An array of objects that will be bound, in order, to the characters "?" (for values) and "i?" (for identifiers, e.g. table or column names) in the sqlStr.

Returns:

  • A tuple containing an Array of "SDRow"s, and an Int with the error code or nil if there was no error

public static func executeWithConnection(flags: SD.Flags, closure: ()->Void) -> Int?

Execute functions in a closure on a single custom connection

Note: This function cannot be nested within itself, or inside a transaction/savepoint.

Possible errors returned by this function are:

  • custom connection errors (301 - 306)

Parameters:

  • flags -> The custom flag associated with the connection. Can be one of .ReadOnly, .ReadWrite, or .ReadWriteCreate
  • closure -> A closure containing functions that will be executed on the custom connection

Returns:

  • An Int with the error code, or nil if there was no error

public static func escapeValue(obj: AnyObject?) -> String

Escape an object to be inserted into a SQLite statement as a value

NOTE: Supported object types are: String, Int, Double, Bool, NSData, NSDate, and nil. All other data types will return the String value "NULL", and a warning message will be printed.

Parameters:

  • obj -> The value to be escaped

Returns:

  • The escaped value as a String, ready to be inserted into a SQL statement. Note: Single quotes (') will be placed around the entire value, if necessary.

public static func escapeIdentifier(obj: String) -> String

Escape a string to be inserted into a SQLite statement as an indentifier (e.g. table or column name)

Parameters:

  • obj -> The identifier to be escaped. NOTE: This object must be of type String.

Returns:

  • The escaped identifier as a String, ready to be inserted into a SQL statement. Note: Double quotes (") will be placed around the entire identifier.

public static func createTable(table: String, withColumnNamesAndTypes: [String: SwiftData.DataType]) -> Int?

Create A Table With The Provided Column Names and Types

Note: The ID field is created automatically as "INTEGER PRIMARY KEY AUTOINCREMENT"

Possible errors returned by this function are:

  • SQLite errors (0 - 101)

Parameter:

  • table -> The table name to be created
  • columnNamesAndTypes -> A dictionary where the key = column name, and the value = data type

Returns:

  • An Int with the error code, or nil if there was no error

public static func deleteTable(table: String) -> Int?

Delete a SQLite table by name

Possible errors returned by this function are:

  • SQLite errors (0 - 101)

Parameters:

  • table -> The table name to be deleted

Returns:

  • An Int with the error code, or nil if there was no error

public static func existingTables() -> (result: [String], error: Int?)

Obtain a list of the existing SQLite table names

Possible errors returned by this function are:

  • SQLite errors (0 - 101)
  • Table query error (403)

Returns:

  • A tuple containing an Array of all existing SQLite table names, and an Int with the error code or nil if there was no error

public static func errorMessageForCode(code: Int) -> String

Obtain the error message relating to the provided error code

Parameters:

  • code -> The error code provided

Returns:

  • The error message relating to the provided error code

public static func databasePath() -> String

Obtain the database path

Returns:

  • The path to the SwiftData database

public static func lastInsertedRowID() -> (rowID: Int, error: Int?)

Obtain the last inserted row id

Note: Care should be taken when the database is being accessed from multiple threads. The value could possibly return the last inserted row ID for another operation if another thread executes after your intended operation but before this function call.

Possible errors returned by this function are:

  • SQLite errors (0 - 101)

Returns:

  • A tuple of he ID of the last successfully inserted row's, and an Int of the error code or nil if there was no error

public static func numberOfRowsModified() -> (rowID: Int, error: Int?)

Obtain the number of rows modified by the most recently completed SQLite statement (INSERT, UPDATE, or DELETE)

Note: Care should be taken when the database is being accessed from multiple threads. The value could possibly return the number of rows modified for another operation if another thread executes after your intended operation but before this function call.

Possible errors returned by this function are:

  • SQLite errors (0 - 101)

Returns:

  • A tuple of the number of rows modified by the most recently completed SQLite statement, and an Int with the error code or nil if there was no error

public static func createIndex(#name: String, onColumns: [String], inTable: String, isUnique: Bool = false) -> Int?

Create a SQLite index on the specified table and column(s)

Possible errors returned by this function are:

  • SQLite errors (0 - 101)
  • Index error (401)

Parameters:

  • name -> The index name that is being created
  • onColumns -> An array of column names that the index will be applied to (must be one column or greater)
  • inTable -> The table name where the index is being created
  • isUnique -> True if the index should be unique, false if it should not be unique (defaults to false)

Returns:

  • An Int with the error code, or nil if there was no error

public static func removeIndex(indexName: String) -> Int?

Remove a SQLite index by its name

Possible errors returned by this function are:

  • SQLite errors (0 - 101)

Parameters:

  • indexName -> The name of the index to be removed

Returns:

  • An Int with the error code, or nil if there was no error

public static func existingIndexes() -> (result: [String], error: Int?)

Obtain a list of all existing indexes

Possible errors returned by this function are:

  • SQLite errors (0 - 101)
  • Index error (402)

Returns:

  • A tuple containing an Array of all existing index names on the SQLite database, and an Int with the error code or nil if there was no error

public static func existingIndexesForTable(table: String) -> (result: [String], error: Int?)

Obtain a list of all existing indexes on a specific table

Possible errors returned by this function are:

  • SQLite errors (0 - 101)
  • Index error (402)

Parameters:

  • table -> The name of the table that is being queried for indexes

Returns:

  • A tuple containing an Array of all existing index names in the table, and an Int with the error code or nil if there was no error

public static func transaction(transactionClosure: ()->Bool) -> Int?

Execute commands within a single exclusive transaction

A connection to the database is opened and is not closed until the end of the transaction. A transaction cannot be embedded into another transaction or savepoint.

Possible errors returned by this function are:

  • SQLite errors (0 - 101)
  • Transaction errors (501 - 502)

Parameters:

  • transactionClosure -> A closure containing commands that will execute as part of a single transaction. If the transactionClosure returns true, the changes made within the closure will be committed. If false, the changes will be rolled back and will not be saved.

Returns:

  • An Int with the error code, or nil if there was no error committing or rolling back the transaction

public static func savepoint(savepointClosure: ()->Bool) -> Int?

Execute commands within a single savepoint

A connection to the database is opened and is not closed until the end of the savepoint (or the end of the last savepoint, if embedded).

NOTE: Unlike transactions, savepoints may be embedded into other savepoints or transactions.

Possible errors returned by this function are:

  • SQLite errors (0 - 101)

Parameters:

  • savepointClosure -> A closure containing commands that will execute as part of a single savepoint. If the savepointClosure returns true, the changes made within the closure will be released. If false, the changes will be rolled back and will not be saved.

Returns:

  • An Int with the error code, or nil if there was no error releasing or rolling back the savepoint