@spec bind(
  statement(),
  [bind_value()] | %{optional(String.t()) => bind_value()} | nil
) :: :ok

Resets a prepared statement and binds values to it.

iex> {:ok, conn} = Sqlite3.open(":memory:", [:readonly])
iex> {:ok, stmt} = Sqlite3.prepare(conn, "SELECT ?, ?, ?, ?, ?")
iex> Sqlite3.bind(stmt, [42, 3.14, "Alice", {:blob, <<0, 0, 0>>}, nil])
iex> Sqlite3.step(conn, stmt)
{:row, [42, 3.14, "Alice", <<0, 0, 0>>, nil]}

iex> {:ok, conn} = Sqlite3.open(":memory:", [:readonly])
iex> {:ok, stmt} = Sqlite3.prepare(conn, "SELECT :42, @pi, $name, @blob, :null")
iex> Sqlite3.bind(stmt, %{":42" => 42, "@pi" => 3.14, "$name" => "Alice", :"@blob" => {:blob, <<0, 0, 0>>}, ~c":null" => nil})
iex> Sqlite3.step(conn, stmt)
{:row, [42, 3.14, "Alice", <<0, 0, 0>>, nil]}

iex> {:ok, conn} = Sqlite3.open(":memory:", [:readonly])
iex> {:ok, stmt} = Sqlite3.prepare(conn, "SELECT ?")
iex> Sqlite3.bind(stmt, [42, 3.14, "Alice"])
** (ArgumentError) expected 1 arguments, got 3

iex> {:ok, conn} = Sqlite3.open(":memory:", [:readonly])
iex> {:ok, stmt} = Sqlite3.prepare(conn, "SELECT ?, ?")
iex> Sqlite3.bind(stmt, [42])
** (ArgumentError) expected 2 arguments, got 1

iex> {:ok, conn} = Sqlite3.open(":memory:", [:readonly])
iex> {:ok, stmt} = Sqlite3.prepare(conn, "SELECT ?")
iex> Sqlite3.bind(stmt, [:erlang.list_to_pid(~c"<0.0.0>")])
** (ArgumentError) unsupported type: #PID<0.0.0>

@spec bind_blob(statement(), non_neg_integer(), binary()) :: :ok

Binds a blob value to a prepared statement.

iex> {:ok, conn} = Sqlite3.open(":memory:", [:readonly])
iex> {:ok, stmt} = Sqlite3.prepare(conn, "SELECT ?")
iex> Sqlite3.bind_blob(stmt, 1, <<0, 0, 0>>)
:ok

@spec bind_float(statement(), non_neg_integer(), float()) :: :ok

Binds a float value to a prepared statement.

iex> {:ok, conn} = Sqlite3.open(":memory:", [:readonly])
iex> {:ok, stmt} = Sqlite3.prepare(conn, "SELECT ?")
iex> Sqlite3.bind_float(stmt, 1, 3.14)
:ok

@spec bind_integer(statement(), non_neg_integer(), integer()) :: :ok

Binds an integer value to a prepared statement.

iex> {:ok, conn} = Sqlite3.open(":memory:", [:readonly])
iex> {:ok, stmt} = Sqlite3.prepare(conn, "SELECT ?")
iex> Sqlite3.bind_integer(stmt, 1, 42)
:ok

@spec bind_null(statement(), non_neg_integer()) :: :ok

Binds a null value to a prepared statement.

iex> {:ok, conn} = Sqlite3.open(":memory:", [:readonly])
iex> {:ok, stmt} = Sqlite3.prepare(conn, "SELECT ?")
iex> Sqlite3.bind_null(stmt, 1)
:ok

@spec bind_parameter_count(statement()) :: non_neg_integer() | {:error, reason()}

Returns number of SQL parameters in a prepared statement.

iex> {:ok, conn} = Sqlite3.open(":memory:", [:readonly])
iex> {:ok, stmt} = Sqlite3.prepare(conn, "SELECT ?, ?")
iex> Sqlite3.bind_parameter_count(stmt)
2

@spec bind_text(statement(), non_neg_integer(), String.t()) :: :ok

Binds a text value to a prepared statement.

iex> {:ok, conn} = Sqlite3.open(":memory:", [:readonly])
iex> {:ok, stmt} = Sqlite3.prepare(conn, "SELECT ?")
iex> Sqlite3.bind_text(stmt, 1, "Alice")
:ok

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

Cancel a running query: wake any busy handler sleep and interrupt VDBE execution.

This is a superset of interrupt/1 — it sets a cancel flag that the busy and progress handlers observe, and also calls sqlite3_interrupt(). After a cancel, the connection can be reused normally.

Use this when a query might be blocked either inside SQLite bytecode execution or inside the busy handler waiting for a lock.

@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.

@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.

@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.

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

Interrupt a long-running query.

This calls sqlite3_interrupt() and is effective while SQLite is actively executing a statement. It does not wake the custom busy handler while the connection is sleeping and waiting on a lock. Use cancel/1 when you need to abort both statement execution and busy waits.

@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 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.

@spec reset(statement()) :: :ok | {:error, atom()}

Resets a prepared statement.

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

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

Serialize the contents of the database to a binary.

@spec set_authorizer(db(), [atom()]) :: :ok | {:error, reason()}

Set an authorizer that denies specific SQL operations.

Accepts a list of action atoms to deny. Any SQL statement that triggers a denied action will fail with a "not authorized" error during preparation.

Pass an empty list to clear the authorizer.

Action atoms

:attach, :detach, :pragma, :insert, :update, :delete, :create_table, :drop_table, :create_index, :drop_index, :create_trigger, :drop_trigger, :create_view, :drop_view, :alter_table, :reindex, :analyze, :function, :savepoint, :transaction, :read, :select, :recursive, :create_temp_table, :create_temp_index, :create_temp_trigger, :create_temp_view, :drop_temp_table, :drop_temp_index, :drop_temp_trigger, :drop_temp_view, :create_vtable, :drop_vtable

Examples

# Block ATTACH and DETACH (prevent cross-database reads)
:ok = Sqlite3.set_authorizer(conn, [:attach, :detach])

# Clear the authorizer
:ok = Sqlite3.set_authorizer(conn, [])

@spec set_busy_timeout(db(), integer()) :: :ok | {:error, reason()}

Set the busy timeout in milliseconds without destroying the custom busy handler.

Unlike PRAGMA busy_timeout (which internally calls sqlite3_busy_timeout() and replaces any custom handler), this function only updates the timeout value that the custom busy handler reads. This preserves the ability to cancel busy waits via cancel/1.

A timeout of 0 makes lock contention fail immediately with SQLITE_BUSY. Larger values let SQLite keep retrying until the timeout expires or the wait is cancelled.

This is the low-level API behind the :busy_timeout connection option.

@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:

• rc is an integer result code or an extended result code
• message is a string representing the log message

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

@spec set_progress_handler_steps(db(), integer()) :: :ok | {:error, reason()}

Configure how often SQLite invokes the progress handler during statement execution.

The default is 1000 virtual machine steps.

Values less than 1 disable the progress handler. Larger values reduce the overhead of cancellation checks at the cost of slower response to cancel/1 and interrupt/1 while a query is running.

This is the low-level API behind the :progress_handler_steps connection option.

@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.