View Source Exqlite.Sqlite3 (Exqlite v0.23.0)

The interface to the NIF implementation.

Summary

Functions

Get the number of changes recently.

Closes the database and releases any underlying resources.

Disconnect from database and then reopen as an in-memory database based on the serialized binary.

Allow loading native extensions.

Executes an sql script. Multiple stanzas can be passed at once.

Interrupt a long-running query.

Opens a new sqlite database at the Path provided.

Once finished with the prepared statement, call this to release the underlying resources.

Serialize the contents of the database to a binary.

Send log messages to a process.

Send data change notifications to a process.

Causes the database connection to free as much memory as it can. This is useful if you are on a memory restricted system.

Types

@type db() :: reference()
@type open_mode() :: :readwrite | :readonly | :nomutex
@type open_opt() :: {:mode, :readwrite | :readonly | [open_mode()]}
@type reason() :: atom() | String.t()
@type row() :: list()
@type statement() :: reference()

Functions

Link to this function

bind(conn, statement, args)

View Source
@spec bind(db(), statement(), nil) :: :ok | {:error, reason()}
@spec bind(db(), statement(), list()) :: :ok | {:error, reason()}
@spec changes(db()) :: {:ok, integer()} | {:error, reason()}

Get the number of changes recently.

Note: If triggers are used, the count may be larger than expected.

See: https://sqlite.org/c3ref/changes.html

@spec close(db() | nil) :: :ok | {:error, reason()}

Closes the database and releases any underlying resources.

Link to this function

columns(conn, statement)

View Source
@spec columns(db(), statement()) :: {:ok, [binary()]} | {:error, reason()}
Link to this function

deserialize(conn, database \\ "main", serialized)

View Source
@spec deserialize(db(), String.t(), binary()) :: :ok | {:error, reason()}

Disconnect from database and then reopen as an in-memory database based on the serialized binary.

Link to this function

enable_load_extension(conn, flag)

View Source
@spec enable_load_extension(db(), boolean()) :: :ok | {:error, reason()}

Allow loading native extensions.

@spec execute(db(), String.t()) :: :ok | {:error, reason()}

Executes an sql script. Multiple stanzas can be passed at once.

Link to this function

fetch_all(conn, statement)

View Source
@spec fetch_all(db(), statement()) :: {:ok, [row()]} | {:error, reason()}
Link to this function

fetch_all(conn, statement, chunk_size)

View Source
@spec fetch_all(db(), statement(), integer()) :: {:ok, [row()]} | {:error, reason()}
@spec interrupt(db() | nil) :: :ok | {:error, reason()}

Interrupt a long-running query.

@spec last_insert_rowid(db()) :: {:ok, integer()}
Link to this function

multi_step(conn, statement)

View Source
@spec multi_step(db(), statement()) ::
  :busy | {:rows, [row()]} | {:done, [row()]} | {:error, reason()}
Link to this function

multi_step(conn, statement, chunk_size)

View Source
@spec multi_step(db(), statement(), integer()) ::
  :busy | {:rows, [row()]} | {:done, [row()]} | {:error, reason()}
@spec open(String.t(), [open_opt()]) :: {:ok, db()} | {:error, reason()}

Opens a new sqlite database at the Path provided.

path can be ":memory" to keep the sqlite database in memory.

Options

  • :mode - use :readwrite to open the database for reading and writing , :readonly to open it in read-only mode or [:readonly | :readwrite, :nomutex] to open it with no mutex mode. :readwrite will also create the database if it doesn't already exist. Defaults to :readwrite. Note: [:readwrite, :nomutex] is not recommended.
@spec prepare(db(), String.t()) :: {:ok, statement()} | {:error, reason()}
Link to this function

release(conn, statement)

View Source
@spec release(db(), statement()) :: :ok | {:error, reason()}

Once finished with the prepared statement, call this to release the underlying resources.

This should be called whenever you are done operating with the prepared statement. If the system has a high load the garbage collector may not clean up the prepared statements in a timely manner and causing higher than normal levels of memory pressure.

If you are operating on limited memory capacity systems, definitely call this.

Link to this function

serialize(conn, database \\ "main")

View Source
@spec serialize(db(), String.t()) :: {:ok, binary()} | {:error, reason()}

Serialize the contents of the database to a binary.

@spec set_log_hook(pid()) :: :ok | {:error, reason()}

Send log messages to a process.

Each time a message is logged in SQLite a message will be sent to the pid provided as the argument.

The message is of the form: {:log, rc, message}, where:

See SQLITE_CONFIG_LOG and "The Error And Warning Log" for more details.

Restrictions

  • Only one pid can listen to the log messages at a time. If this function is called multiple times, only the last pid will receive the notifications
Link to this function

set_update_hook(conn, pid)

View Source
@spec set_update_hook(db(), pid()) :: :ok | {:error, reason()}

Send data change notifications to a process.

Each time an insert, update, or delete is performed on the connection provided as the first argument, a message will be sent to the pid provided as the second argument.

The message is of the form: {action, db_name, table, row_id}, where:

  • action is one of :insert, :update or :delete
  • db_name is a string representing the database name where the change took place
  • table is a string representing the table name where the change took place
  • row_id is an integer representing the unique row id assigned by SQLite

Restrictions

  • There are some conditions where the update hook will not be invoked by SQLite. See the documentation for more details
  • Only one pid can listen to the changes on a given database connection at a time. If this function is called multiple times for the same connection, only the last pid will receive the notifications
  • Updates only happen for the connection that is opened. For example, there are two connections A and B. When an update happens on connection B, the hook set for connection A will not receive the update, but the hook for connection B will receive the update.
@spec shrink_memory(db()) :: :ok | {:error, reason()}

Causes the database connection to free as much memory as it can. This is useful if you are on a memory restricted system.

@spec step(db(), statement()) :: :done | :busy | {:row, row()} | {:error, reason()}
Link to this function

transaction_status(conn)

View Source
@spec transaction_status(db()) :: {:ok, :idle | :transaction}