Overview

Module esqlcipher

• Description
• Data Types
• Function Index
• Function Details

Copyright © 2011 - 2021 Maas-Maarten Zeeman, Felix Kiunke

Version: 2.0.0-rc.3

Authors: Maas-Maarten Zeeman (mmzeeman@xs4all.nl), Felix Kiunke (dev@fkiunke.de).

Description

Erlang API for sqlite3 and sqlcipher databases. This is an adaptation of Maas-Maarten Zeeman's esqlite package for sqlcipher encrypted sqlite3 databases.

All functions (except is_encrypted/1) take an optional Timeout argument. The default value for this timeout is 5 seconds (5000). Note that Timeout is merely a lower bound. Several functions call multiple lower level calls, in which case each of those has is given that timeout. Thus, the actual timeout might be several times the value of Timeout for some functions.

To open or create a database, use either open/2 or open_encrypted/3. These return a database connection that can be used in the other functions and should be closed afterwards using close/2.

Queries

One-off queries that do not return anything can be executed using exec/3, exec/4 (with Query Parameters), or insert/3 (which returns the row id of the row inserted last).

In most cases, however, you'll want to use prepared statemtents that can contain Query Parameters. These statements are created using prepare/3. If it contains parameters, you can then bind values to those using bind/3 (you can do both in one step using prepare_bind/4. Afterwards, you can run the statement using run/2 (if you don't care about any rows that are possibly returned), or the fetch family (fetch_one/2, fetch_chunk/3, fetch_all/3). You can use column_names/2 and column_types/2 on a prepared statement to get the actual names and types of the columns that will be returned by it. Using reset/3, the prepared statement's initial state will be restored and you can run it once more.

Additionally, there is the q/4 and the foreach/5 and map/5 higher-order functions. These do not return {ok, _} or {error, _} tuples; if errors occur, they are thrown.

Query Parameters

• ?: Unnamed/anonymous parameters,
• ?NNN, where NNN is a positive integer: Numbered parameters, and
• :AAA, where AAA is an alphanumeric identifier. (sqlite's @AAA and $AAA forms are also supported but discouraged).

Prefer numbered or named over anonymous parameters and do not mix named and numbered parameters! See bind/3 for further details!

• INTEGER: for these, just use regular Erlang integers
• REAL: Erlang floats
• TEXT: Only utf-8 encoded binaries, not strings/charlists should be used for these! iolists are allowed.
• BLOB: Any binary can be stored exactly as is into a blob. The can be passed as {'$blob', <<"binary data">>}.
• NULL: These are translated to the atom nil.

Data Types

bind_value()

bind_value() = sql_value() | {pos_integer() | atom(), sql_value()}

List of values for statement parameters (see bind/3).

connection()

connection() = {connection, reference(), plaintext | encrypted}

Database connection type. Returned by open/2 and open_encrypted/3.

connection_enc()

connection_enc() = {connection, reference(), encrypted}

Encrypted database connection type.

connection_plain()

connection_plain() = {connection, reference(), plaintext}

Unencrypted database connection type.

foreach_function()

foreach_function() = fun((Row::row()) -> any()) | fun((ColNames::[binary()], Row::row()) -> any())

Type of functions used in foreach/5.

map_function()

map_function(ReturnType) = fun((Row::row()) -> ReturnType) | fun((ColNames::[binary()], Row::row()) -> ReturnType)

Type of functions used in map/5.

row()

row() = [sql_value()]

SQL row type.

sql()

sql() = iodata()

SQL string type.

sql_value()

sql_value() = number() | nil | iodata() | {'$blob', iodata()}

SQL value type.

sqlite_error()

sqlite_error() = {error, {atom(), string()}}

Error return type. Contains an error id atom and a reason/error message.

statement()

statement() = {statement, reference(), connection()}

Prepared statement type. Returned by prepare/3 or prepare_bind/4.

Function Index

Function Details

bind/2

Equivalent to bind(Statement, Args, 5000).

bind/3

Bind values to a prepared statement created by prepare/3. Note that you can also use prepare_bind/4 to prepare and bind a statement in one step.

nil will be interpreted as NULL. Use {'$blob', <<binary>>} for sqlite BLOBs. Since sqlite does not have a true boolean type, true and false are invalid; use 1 and 0, respectively.

• ?: Unnamed/anonymous parameters (these will implicitly be assigned a number that is the previously largest assigned number + 1; numbering begins at 1),
• ?NNN, where 1 ≤ NNN ≤ 32766: Numbered parameters, and
• :AAA, where AAA is an alphanumeric identifier. These will internally be assigned a number similarly to anonymous parameters, so do not mix named and numbered parameters or you will probably get unexpected results.
  Sqlite3 also supports the forms @AAA and $AAA but since the initial character (@/$) is part of the name, you would actually need to pass {'@name', Value} or {'$name', Value}. {name, Value} is automatically interpreted as {':name', Value}, so the :AAA form should be preferred. Do not use $blob as a parameter name as {'$blob', _} tuple will be interpreted as the sqlite BLOB datatype.

Anonymous parameters of the form ? are discouraged; prefer named or numbered parameters.

changes/1

Equivalent to changes(Connection, 5000).

changes/2

Return the number of the rows that have been modified, inserted, or deleted by the last statement (see the sqlite3 docs for further information).

close/1

Equivalent to close(Connection, 5000).

close/2

Close the database connection.

column_names/1

Equivalent to column_names(Statement, 5000).

column_names/2

Return the column names of the prepared statement.

column_types/1

Equivalent to column_types(Statement, 5000).

column_types/2

Return the declared column types of the prepared statement. Note that since sqlite3 is dynamically typed, actual column values need not necessarily conform to the declared type

exec/2

Equivalent to exec(Sql, Connection, 5000).

exec/3

Execute (simple or prepared) SQL statement without returning anything.

exec/4

Execute prepared SQL statement without returning anything.

fetch_all/1

Equivalent to fetch_all(Statement, 5000, 5000).

fetch_all/2

Equivalent to fetch_all(Statement, ChunkSize, 5000).

fetch_all/3

Fetch all records

fetch_chunk/2

Equivalent to fetch_chunk(Statement, ChunkSize, 5000).

fetch_chunk/3

fetch a number of rows. Can be called multiple times to fetch more rows.

fetch_one/1

Equivalent to fetch_one(Statement, 5000).

fetch_one/2

fetch exactly one row of results. Returns ok if the result is empty.

foreach/3

throws sqlite_error()

Equivalent to foreach(F, Sql, [], Connection, 5000).

foreach/4

throws sqlite_error()

Equivalent to foreach(F, Sql, Args, Connection, 5000).

foreach/5

throws sqlite_error()

Execute a function for all rows returned by the SQL query Sql.

get_autocommit/1

Equivalent to get_autocommit(Connection, 5000).

get_autocommit/2

Returns whether the database is in autocommit mode. Autocommit is normally enabled, except within transactions.

insert/2

Equivalent to insert(Sql, Connection, 5000).

insert/3

Insert records, returns the last inserted rowid. Sql can be any INSERT statement. If the table has a column of type INTEGER PRIMARY KEY, the returned rowid will equal that primary key. See also the sqlite3 docs for sqlite3_last_insert_rowid.

is_encrypted/1

Whether a database is encrypted. Returns true if the database connection is to an encrypted database, false if it's a plaintext database

map/3

throws sqlite_error()

Equivalent to map(F, Sql, [], Connection, 5000).

map/4

throws sqlite_error()

Equivalent to map(F, Sql, [], Connection, 5000).

map/5

throws sqlite_error()

Map over all rows returned by the SQL query Sql.

open/1

Equivalent to open(Filename, 5000).

open/2

Open an unencrypted database connection. If Filename doesn't exist, it will be created. You can also open an in-memory database that will be destroyed after closing by giving :memory: as the Filename. URI filenames are allowed as well.

The database will be checked by testing whether sqlite_master is readable. Unreadable, corrupted or encrypted databases will return an error of the form {error, {baddb, _}}.

open_encrypted/2

Equivalent to open_encrypted(Filename, Key, 5000).

open_encrypted/3

Open an encrypted database connection. If Filename doesn't exist, it will be created.

The database will be checked by testing whether sqlite_master is readable. Unreadable or corrupted databases as well as an incorrect Key will return an error of the form {error, {baddb, _}}.

Normally, the actual database key will be derived from Key using PBKDF2 key derivation by sqlcipher. However, it's possible to specify a raw byte sequence as a key. This key has to be hex-encoded and can be used by passing "x'A0B1C2(...)D3E4F5'" using a 64 character hex string for a resulting 32 byte key (256 bits). Finally, an exact database salt can be specified as well by passing a 96 character hex string (the last 32 characters will be used as the salt). If the salt is not explicitly provided, it will be generated randomly and stored in the first 16 bytes of the database.

prepare/2

Equivalent to prepare(Sql, Connection, Timeout).

prepare/3

Prepare (that is, compile) an SQL statement. Value placeholder can then be bound using bind/3. Or, you can do both in one step using prepare_bind/4!

prepare_bind/3

Equivalent to prepare_bind(Sql, Values, Connection, 5000).

prepare_bind/4

Prepare an SQL statement and bind values to it. This is simply prepare/3 and bind/3 in a single step.

q/2

throws sqlite_error()

Equivalent to q(Sql, [], Connection, 5000).

q/3

throws sqlite_error()

Equivalent to q(Sql, Args, Connection, 5000).

q/4

throws sqlite_error()

Prepare statement, bind args and return a list of rows as result. Errors are thrown, not returned.

rekey/2

Equivalent to rekey(Key, Connection, 5000).

rekey/3

Change the database key. This function cannot be used to encrypt an unencrypted database and will return an error {error, {rekey_plaintext, _}} if called on one.

See also: open_encrypted/3.

reset/1

Equivalent to reset(Statement, false, 5000).

reset/2

Equivalent to reset(Statemennt, ClearValues, 5000).

reset/3

Reset the prepared statement back to its initial state. Once the statement has been reset, you can run it once more. By default, any values bound to the statement will be retained. Set ClearValues to true to change this.

run/1

Equivalent to run(Statement, 5000).

run/2

run a prepared statement, ignoring any possible results. If you want to ensure that a query finishes correctly, returning exactly zero rows, use:

set_update_hook/2

Equivalent to set_update_hook(Pid, Connection, 5000).

set_update_hook/3

Subscribe to notifications for row updates, insertions and deletions. Messages will come in the shape of {Action, Database :: binary(), Table :: binary(), Id :: integer()}, where Action will be either insert, update or delete and Id will be the affected row id (i.e. the INTEGER PRIMARY KEY if the table has one). Database contains the name of the database on which the update occurred, usually main.

Overview

Generated by EDoc