Module esqlite3

Description
Data Types
Function Index
Function Details

Erlang API for sqlite3 databases.

Authors: Maas-Maarten Zeeman (mmzeeman@xs4all.nl).

Data Types

backup()

backup() = #backup{raw_connection = esqlite3_nif:raw_connection(), raw_backup = esqlite3_nif:raw_backup()}

cell_type()

cell_type() = undefined | integer() | binary() | float()

connection()

connection() = #connection{raw_connection = esqlite3_nif:raw_connection()}

statement()

statement() = #statement{raw_connection = esqlite3_nif:raw_connection(), raw_statement = esqlite3_nif:raw_statement()}

Function Index

open/1	Opens a sqlite3 database mentioned in Filename.
open/2	Like open/1, but with an additional timeout.
close/1	Close the database.
close/2	Close the database.
flush/0	Flush any stale answers left in the mailbox of the current process.
set_update_hook/2	Subscribe to database notifications.
set_update_hook/3	Same as set_update_hook/2, but with an additional timeout parameter.
q/2	Execute a sql statement, returns a list with tuples.
q/3	Execute statement, bind args and return a list with tuples as result.
q/4	Execute statement, bind args and return a list with tuples as result restricted by timeout.
map/3	Execute statement and return a list with the result of F for each row.
map/4	Execute statement, bind args and return a list with the result of F for each row.
foreach/3	Execute statement and call F with each row.
foreach/4	Execute statement, bind args and call F with each row.
fetchone/1
fetchall/1	Fetch all records.
fetchall/2	Fetch all records.
fetchall/3	Fetch all records.
exec/2	Execute Sql statement.
exec/3
exec/4
changes/1	Return the number of affected rows of last statement.
changes/2
insert/2	Insert records, returns the last rowid.
insert/3	Like insert/2, but with extra timeout parameter.
last_insert_rowid/1	Get the last insert rowid, using the default timeout.
get_autocommit/1	Check if the connection is in auto-commit mode.
get_autocommit/2	Like autocommit/1, but with an extra timeout attribute.
prepare/2	Compile a SQL statement.
prepare/3	Like prepare/2, but with an extra timeout value.
step/1	Step.
step/2	.
reset/1	Reset the prepared statement back to its initial state.
bind/2	Bind values to prepared statements.
bind/3	Bind values to prepared statements.
column_names/1	Return the column names of the prepared statement.
column_names/2
column_types/1	Return the column types of the prepared statement.
column_types/2
backup_init/4	Initialize a backup procedure.
backup_init/5	Like backup_init/4, but with an extra timeout value.
backup_finish/1	Release the resources held by the backup.
backup_finish/2	Like backup_finish/1, but with an extra timeout.
backup_step/2	Do a backup step.
backup_step/3	Do a backup step.
backup_remaining/1	Get the remaining number of pages which need to be backed up.
backup_remaining/2	Get the remaining number of pages which need to be backed up.
backup_pagecount/1	Get the remaining number of pages which need to be backed up.
backup_pagecount/2	Get the remaining number of pages which need to be backed up.

Function Details

open/1

open(Filename::string()) -> {ok, connection()} | {error, term()}

Opens a sqlite3 database mentioned in Filename.

The standard supplied sqlite3 library supports uri filenames, which makes it possible to open the connection to the database in read-only mode. More information about this can be found here: https://sqlite.org/uri.html

Example:

     open("file:data.db")

Opens "data.db" in the current working directory

     open("file:data.db?mode=ro&cache=private")

Opens "data.db" in read only mode with a private cache

     open("file:memdb1?mode=memory&cache=shared")

Opens a shared memory database named memdb1 with a shared cache.

open/2

open(Filename::string(), Timeout::timeout()) -> {ok, connection()} | {error, term()}

Like open/1, but with an additional timeout.

close/1

close(Connection::connection()) -> ok | {error, term()}

Close the database

close/2

close(Connection::connection(), Timeout::timeout()) -> ok | {error, term()}

Close the database

flush/0

flush() -> ok

Flush any stale answers left in the mailbox of the current process. This can happen if there has been a timeout. Normally the nif functions are called with the default 'infinite' timeout, so calling this is not needed.

set_update_hook/2

set_update_hook(Pid::pid(), Connection::connection()) -> ok | {error, term()}

Subscribe to database notifications. When rows are inserted deleted or updates, the process will receive messages:

     {insert, string(), rowid()}

When a new row has been inserted.

     {delete, string(), rowid()}

When a new row has been deleted.

     {update, string(), rowid()}

When a row has been updated.

set_update_hook/3

set_update_hook(Pid::pid(), Connection::connection(), Timeout::timeout()) -> ok | {error, term()}

Same as set_update_hook/2, but with an additional timeout parameter.

q/2

q(Sql::sql(), Connection::connection()) -> [row()] | {error, term()}

Execute a sql statement, returns a list with tuples.

q/3

q(Sql::sql(), Args::list(), Connection::connection()) -> [row()] | {error, term()}

Execute statement, bind args and return a list with tuples as result.

q/4

q(Sql::sql(), Args::list(), Connection::connection(), Timeout::timeout()) -> [row()] | {error, term()}

Execute statement, bind args and return a list with tuples as result restricted by timeout.

map/3

map(Fun, Sql::sql(), Connection::connection()) -> [Type]

Fun = fun((Row) -> Type) | fun((ColumnNames, Row) -> Type)
Row = row()
ColumnNames = tuple()
Type = any()

Execute statement and return a list with the result of F for each row.

map/4

map(F, Sql::sql(), Args::list(), Connection::connection()) -> [Type]

F = fun((Row) -> Type) | fun((ColumnNames, Row) -> Type)
Row = tuple()
ColumnNames = tuple()
Type = any()

Execute statement, bind args and return a list with the result of F for each row.

foreach/3

foreach(Fun, Sql::sql(), Connection::connection()) -> ok

Fun = fun((Row) -> any()) | fun((ColumnNames, Row) -> any())
Row = tuple()
ColumnNames = tuple()

Execute statement and call F with each row.

foreach/4

foreach(Fun, Sql::sql(), Args::list(), Connection::connection()) -> ok

Fun = fun((Row) -> any()) | fun((ColumnNames, Row) -> any())
Row = row()
ColumnNames = tuple()

Execute statement, bind args and call F with each row.

fetchone/1

fetchone(Statement::statement()) -> tuple()

fetchall/1

fetchall(Statement::statement()) -> [row()] | {error, term()}

Statement: is prepared sql statement

Fetch all records

fetchall/2

fetchall(Statement::statement(), ChunkSize::pos_integer()) -> [row()] | {error, term()}

Statement: is prepared sql statement
ChunkSize: is a count of rows to read from sqlite and send to erlang process in one bulk. Decrease this value if rows are heavy. Default value is 5000 (DEFAULT_CHUNK_SIZE).

Fetch all records

fetchall/3

fetchall(Statement::statement(), ChunkSize::pos_integer(), Timeout::timeout()) -> [row()] | {error, term()}

Fetch all records

exec/2

exec(Sql::sql(), Connection::connection()) -> ok | {error, term()}

Execute Sql statement.

exec/3

exec(Sql::sql(), Connection::[cell_type()] | connection(), Timeout::connection() | timeout()) -> ok | {error, term()}

exec/4

exec(Sql::sql(), Params::[cell_type()], Connection::connection(), Timeout::timeout()) -> ok | {error, term()}

changes/1

changes(Connection::connection()) -> non_neg_integer()

Return the number of affected rows of last statement.

changes/2

changes(Connection::connection(), Timeout::timeout()) -> non_neg_integer()

insert/2

insert(Sql::sql(), Connection::connection()) -> {ok, rowid()} | {error, term()}

Insert records, returns the last rowid.

insert/3

insert(Sql::sql(), Connection::connection(), Timeout::timeout()) -> {ok, rowid()} | {error, term()}

Like insert/2, but with extra timeout parameter.

last_insert_rowid/1

last_insert_rowid(Connection::connection()) -> {ok, rowid()} | {error, term()}

Get the last insert rowid, using the default timeout.

get_autocommit/1

get_autocommit(Connection::connection()) -> true | false

Check if the connection is in auto-commit mode. See: https://sqlite.org/c3ref/get_autocommit.html for more details.

get_autocommit/2

get_autocommit(Connection::connection(), Timeout::timeout()) -> true | false

Like autocommit/1, but with an extra timeout attribute.

prepare/2

prepare(Sql::sql(), Connection::connection()) -> {ok, statement()} | {error, term()}

Compile a SQL statement. Returns a cached compiled statement which can be used in queries.

prepare/3

prepare(Sql::sql(), Connection::connection(), Timeout::timeout()) -> {ok, statement()} | {error, term()}

Like prepare/2, but with an extra timeout value.

step/1

step(Stmt::statement()) -> tuple() | '$busy' | '$done'

Step

step/2

step(Statement::statement(), Timeout::timeout()) -> tuple() | '$busy' | '$done'

reset/1

reset(Statement::statement()) -> ok | {error, term()}

Reset the prepared statement back to its initial state.

bind/2

bind(Stmt::statement(), Args::[cell_type()]) -> ok | {error, term()}

Bind values to prepared statements

bind/3

bind(Statement::statement(), Args::[cell_type()], Timeout::timeout()) -> ok | {error, term()}

Bind values to prepared statements

column_names/1

column_names(Stmt::statement()) -> {atom()}

Return the column names of the prepared statement.

column_names/2

column_names(Statement::statement(), Timeout::timeout()) -> {atom()}

column_types/1

column_types(Statement::statement()) -> {atom()}

Return the column types of the prepared statement.

column_types/2

column_types(Statement::statement(), Timeout::timeout()) -> {atom()}

backup_init/4

backup_init(Dest::connection(), DestName::string(), Src::connection(), SrcName::string()) -> {ok, backup()} | {error, term()}

Initialize a backup procedure.

backup_init/5

backup_init(Connection::connection(), DestName::string(), X3::connection(), SrcName::string(), Timeout::timeout()) -> {ok, backup()} | {error, term()}

Like backup_init/4, but with an extra timeout value.