sqlitex v1.7.1 Sqlitex.Server View Source
Sqlitex.Server provides a GenServer to wrap a sqlitedb. This makes it easy to share a SQLite database between multiple processes without worrying about concurrency issues. You can also register the process with a name so you can query by name later.
Unsupervised Example
iex> {:ok, pid} = Sqlitex.Server.start_link(":memory:", [name: :example])
iex> Sqlitex.Server.exec(pid, "CREATE TABLE t (a INTEGER, b INTEGER)")
:ok
iex> Sqlitex.Server.exec(pid, "INSERT INTO t (a, b) VALUES (1, 1), (2, 2), (3, 3)")
:ok
iex> Sqlitex.Server.query(pid, "SELECT * FROM t WHERE b = 2")
{:ok, [[a: 2, b: 2]]}
iex> Sqlitex.Server.query(:example, "SELECT * FROM t ORDER BY a LIMIT 1", into: %{})
{:ok, [%{a: 1, b: 1}]}
iex> Sqlitex.Server.query_rows(:example, "SELECT * FROM t ORDER BY a LIMIT 2")
{:ok, %{rows: [[1, 1], [2, 2]], columns: [:a, :b], types: [:INTEGER, :INTEGER]}}
iex> Sqlitex.Server.prepare(:example, "SELECT * FROM t")
{:ok, %{columns: [:a, :b], types: [:INTEGER, :INTEGER]}}
# Subsequent queries using this exact statement will now operate more efficiently
# because this statement has been cached.
iex> Sqlitex.Server.prepare(:example, "INVALID SQL")
{:error, {:sqlite_error, 'near "INVALID": syntax error'}}
iex> Sqlitex.Server.stop(:example)
:ok
iex> :timer.sleep(10) # wait for the process to exit asynchronously
iex> Process.alive?(pid)
false
Supervised Example
import Supervisor.Spec
children = [
worker(Sqlitex.Server, ["priv/my_db.sqlite3", [name: :my_db])
]
Supervisor.start_link(children, strategy: :one_for_one)
Link to this section Summary
Functions
Returns a specification to start this module under a supervisor.
Same as Sqlitex.exec/3
but using the shared db connections saved in the GenServer state.
Invoked when the server is started. start_link/3
or start/3
will
block until it returns.
Prepares a SQL statement for future use.
Same as Sqlitex.Query.query/3
but using the shared db connections saved in the GenServer state.
Same as Sqlitex.Query.query_rows/3
but using the shared db connections saved in the GenServer state.
Starts a SQLite Server (GenServer) instance.
Link to this section Functions
child_spec(init_arg) View Source
Returns a specification to start this module under a supervisor.
See Supervisor
.
create_table(pid, name, table_opts \\ [], cols) View Source
exec(pid, sql, opts \\ []) View Source
Same as Sqlitex.exec/3
but using the shared db connections saved in the GenServer state.
Returns the results otherwise.
init(arg) View Source
Invoked when the server is started. start_link/3
or start/3
will
block until it returns.
init_arg
is the argument term (second argument) passed to start_link/3
.
Returning {:ok, state}
will cause start_link/3
to return
{:ok, pid}
and the process to enter its loop.
Returning {:ok, state, timeout}
is similar to {:ok, state}
,
except that it also sets a timeout. See the "Timeouts" section
in the module documentation for more information.
Returning {:ok, state, :hibernate}
is similar to {:ok, state}
except the process is hibernated before entering the loop. See
c:handle_call/3
for more information on hibernation.
Returning {:ok, state, {:continue, continue}}
is similar to
{:ok, state}
except that immediately after entering the loop
the c:handle_continue/2
callback will be invoked with the value
continue
as first argument.
Returning :ignore
will cause start_link/3
to return :ignore
and
the process will exit normally without entering the loop or calling
c:terminate/2
. If used when part of a supervision tree the parent
supervisor will not fail to start nor immediately try to restart the
GenServer
. The remainder of the supervision tree will be started
and so the GenServer
should not be required by other processes.
It can be started later with Supervisor.restart_child/2
as the child
specification is saved in the parent supervisor. The main use cases for
this are:
- The
GenServer
is disabled by configuration but might be enabled later. - An error occurred and it will be handled by a different mechanism than the
Supervisor
. Likely this approach involves callingSupervisor.restart_child/2
after a delay to attempt a restart.
Returning {:stop, reason}
will cause start_link/3
to return
{:error, reason}
and the process to exit with reason reason
without
entering the loop or calling c:terminate/2
.
Callback implementation for GenServer.init/1
.
prepare(pid, sql, opts \\ []) View Source
Prepares a SQL statement for future use.
This causes a call to sqlite3_prepare_v2
to be executed in the Server process. To protect the reference to the corresponding
sqlite3_stmt
struct from misuse in other
processes, that reference is not passed back. Instead, prepared statements are
cached in the Server process. If a subsequent call to query/3
or query_rows/3
is made with a matching SQL statement, the prepared statement is reused.
Prepared statements are purged from the cache when the cache exceeds a preset limit (20 statements by default).
Returns summary information about the prepared statement.
{:ok, %{columns: [:column1_name, :column2_name,... ], types: [:column1_type, ...]}}
on success or {:error, {:reason_code, 'SQLite message'}}
if the statement
could not be prepared.
query(pid, sql, opts \\ []) View Source
Same as Sqlitex.Query.query/3
but using the shared db connections saved in the GenServer state.
Returns the results otherwise.
query_rows(pid, sql, opts \\ []) View Source
Same as Sqlitex.Query.query_rows/3
but using the shared db connections saved in the GenServer state.
Returns the results otherwise.
set_update_hook(server_pid, notification_pid, opts \\ []) View Source
start_link(db_path, opts \\ []) View Source
Starts a SQLite Server (GenServer) instance.
In addition to the options that are typically provided to GenServer.start_link/3
,
you can also specify:
stmt_cache_size: (positive_integer)
to override the default limit (20) of statements that are cached when callingprepare/3
.db_timeout: (positive_integer)
to override:esqlite3
's default timeout of 5000 ms for interactions with the database. This can also be set inconfig.exs
asconfig :sqlitex, db_timeout: 5_000
.db_chunk_size: (positive_integer)
to override:esqlite3
's default chunk_size of 5000 rows to read from native sqlite and send to erlang process in one bulk. This can also be set inconfig.exs
asconfig :sqlitex, db_chunk_size: 5_000
.