Pass timeouts via keyword opts

Also changed to use :db_timeout as the key in most places,
for brevity. Retained :esqlite3_timeout in the Application env.

Author: marramgrass

lib/sqlitex.ex

@@ -30,7 +30,7 @@ defmodule Sqlitex do
   Sqlitex uses the Erlang library [esqlite](https://github.com/mmzeeman/esqlite)
   which accepts a timeout parameter for almost all interactions with the database.
   The default value for this timeout is 5000 ms. Many functions in Sqlitex accept
-  a timeout parameter that is passed on to the esqlite calls and that also defaults
+  a `:db_timeout` option that is passed on to the esqlite calls and that also defaults
   to 5000 ms. If required, this default value can be overridden globally with the
   following in your `config.exs`:
 
@@ -40,29 +40,32 @@ defmodule Sqlitex do
   ```
   """
 
-  @esqlite3_timeout Application.get_env(:sqlitex, :esqlite3_timeout, 5_000)
+  alias Sqlitex.Config
 
-  @spec close(connection, integer()) :: :ok
-  def close(db, timeout \\ @esqlite3_timeout) do
+  @spec close(connection, Keyword.t) :: :ok
+  def close(db, opts \\ []) do
+    timeout = Keyword.get(opts, :db_timeout, Config.esqlite3_timeout())
     :esqlite3.close(db, timeout)
   end
 
-  @spec open(charlist | String.t, integer()) :: {:ok, connection} | {:error, {atom, charlist}}
-  def open(path, timeout \\ @esqlite3_timeout)
-  def open(path, timeout) when is_binary(path), do: open(string_to_charlist(path), timeout)
-  def open(path, timeout) do
+  @spec open(charlist | String.t, Keyword.t) :: {:ok, connection} | {:error, {atom, charlist}}
+  def open(path, opts \\ [])
+  def open(path, opts) when is_binary(path), do: open(string_to_charlist(path), opts)
+  def open(path, opts) do
+    timeout = Keyword.get(opts, :db_timeout, Config.esqlite3_timeout())
     :esqlite3.open(path, timeout)
   end
 
-  def with_db(path, fun, timeout \\ @esqlite3_timeout) do
-    {:ok, db} = open(path, timeout)
+  def with_db(path, fun, opts \\ []) do
+    {:ok, db} = open(path, opts)
     res = fun.(db)
-    close(db, timeout)
+    close(db, opts)
     res
   end
 
-  @spec exec(connection, string_or_charlist, integer()) :: :ok | sqlite_error
-  def exec(db, sql, timeout \\ @esqlite3_timeout) do
+  @spec exec(connection, string_or_charlist, Keyword.t) :: :ok | sqlite_error
+  def exec(db, sql, opts \\ []) do
+    timeout = Keyword.get(opts, :db_timeout, Config.esqlite3_timeout())
     :esqlite3.exec(sql, db, timeout)
   end
 
@@ -89,9 +92,9 @@ defmodule Sqlitex do
   **id: :integer, name: {:text, [:not_null]}**
 
   """
-  def create_table(db, name, table_opts \\ [], cols, timeout \\ @esqlite3_timeout) do
+  def create_table(db, name, table_opts \\ [], cols, call_opts \\ []) do
     stmt = Sqlitex.SqlBuilder.create_table(name, table_opts, cols)
-    exec(db, stmt, timeout)
+    exec(db, stmt, call_opts)
   end
 
  if Version.compare(System.version, "1.3.0") == :lt do

lib/sqlitex/config.ex

@@ -0,0 +1,9 @@
+defmodule Sqlitex.Config do
+  @moduledoc false
+
+  def esqlite3_timeout do
+    Application.get_env(:sqlitex, :esqlite3_timeout, default_esqlite3_timeout())
+  end
+
+  def default_esqlite3_timeout, do: 5_000
+end

lib/sqlitex/query.ex

@@ -15,7 +15,7 @@ defmodule Sqlitex.Query do
   * `bind` - If your query has parameters in it, you should provide the options
     to bind as a list.
   * `into` - The collection to put results into.  This defaults to a list.
-  * `timeout` - The timeout (in ms) to apply to each of the underlying SQLite operations. Defaults
+  * `db_timeout` - The timeout (in ms) to apply to each of the underlying SQLite operations. Defaults
     to 5000, or to `Application.get_env(:sqlitex, :esqlite3_timeout)` if set.
 
   ## Returns
@@ -30,7 +30,10 @@ defmodule Sqlitex.Query do
   @spec query(Sqlitex.connection, String.t | charlist) :: {:ok, [[]]} | {:error, term()}
   @spec query(Sqlitex.connection, String.t | charlist, [{atom, term}]) :: {:ok, [[]]} | {:error, term()}
   def query(db, sql, opts \\ []) do
-    do_query(db, sql, opts, Keyword.get(opts, :timeout, nil))
+    with {:ok, stmt} <- Statement.prepare(db, sql, opts),
+         {:ok, stmt} <- Statement.bind_values(stmt, Keyword.get(opts, :bind, []), opts),
+         {:ok, res} <- Statement.fetch_all(stmt, Keyword.get(opts, :into, [])),
+    do: {:ok, res}
   end
 
   @doc """
@@ -39,27 +42,14 @@ defmodule Sqlitex.Query do
   Returns the results otherwise.
   """
   @spec query!(Sqlitex.connection, String.t | charlist) :: [[]]
-  @spec query!(Sqlitex.connection, String.t | charlist, [bind: [], into: Enum.t, timeout: integer()]) :: [Enum.t]
+  @spec query!(Sqlitex.connection, String.t | charlist, [bind: [], into: Enum.t, db_timeout: integer()]) :: [Enum.t]
   def query!(db, sql, opts \\ []) do
     case query(db, sql, opts) do
       {:error, reason} -> raise Sqlitex.QueryError, reason: reason
       {:ok, results} -> results
     end
   end
 
-  defp do_query(db, sql, opts, nil) do
-    with {:ok, stmt} <- Statement.prepare(db, sql),
-         {:ok, stmt} <- Statement.bind_values(stmt, Keyword.get(opts, :bind, [])),
-         {:ok, res} <- Statement.fetch_all(stmt, Keyword.get(opts, :into, [])),
-    do: {:ok, res}
-  end
-  defp do_query(db, sql, opts, timeout) do
-    with {:ok, stmt} <- Statement.prepare(db, sql, timeout),
-         {:ok, stmt} <- Statement.bind_values(stmt, Keyword.get(opts, :bind, []), timeout),
-         {:ok, res} <- Statement.fetch_all(stmt, Keyword.get(opts, :into, [])),
-    do: {:ok, res}
-  end
-
   @doc """
   Runs a query and returns the results as a list of rows each represented as
   a list of column values.
@@ -74,7 +64,7 @@ defmodule Sqlitex.Query do
 
   * `bind` - If your query has parameters in it, you should provide the options
     to bind as a list.
-  * `timeout` - The timeout (in ms) to apply to each of the underlying SQLite operations. Defaults
+  * `db_timeout` - The timeout (in ms) to apply to each of the underlying SQLite operations. Defaults
     to 5000, or to `Application.get_env(:sqlitex, :esqlite3_timeout)` if set.
 
   ## Returns
@@ -83,9 +73,12 @@ defmodule Sqlitex.Query do
   """
 
   @spec query_rows(Sqlitex.connection, String.t | charlist) :: {:ok, %{}} | Sqlitex.sqlite_error
-  @spec query_rows(Sqlitex.connection, String.t | charlist, [bind: [], timeout: integer()]) :: {:ok, %{}} | Sqlitex.sqlite_error
+  @spec query_rows(Sqlitex.connection, String.t | charlist, [bind: [], db_timeout: integer()]) :: {:ok, %{}} | Sqlitex.sqlite_error
   def query_rows(db, sql, opts \\ []) do
-    do_query_rows(db, sql, opts, Keyword.get(opts, :timeout, nil))
+    with {:ok, stmt} <- Statement.prepare(db, sql, opts),
+         {:ok, stmt} <- Statement.bind_values(stmt, Keyword.get(opts, :bind, []), opts),
+         {:ok, rows} <- Statement.fetch_all(stmt, :raw_list),
+    do: {:ok, %{rows: rows, columns: stmt.column_names, types: stmt.column_types}}
   end
 
   @doc """
@@ -94,24 +87,11 @@ defmodule Sqlitex.Query do
   Returns the results otherwise.
   """
   @spec query_rows!(Sqlitex.connection, String.t | charlist) :: %{}
-  @spec query_rows!(Sqlitex.connection, String.t | charlist, [bind: [], timeout: integer()]) :: %{}
+  @spec query_rows!(Sqlitex.connection, String.t | charlist, [bind: [], db_timeout: integer()]) :: %{}
   def query_rows!(db, sql, opts \\ []) do
     case query_rows(db, sql, opts) do
       {:error, reason} -> raise Sqlitex.QueryError, reason: reason
       {:ok, results} -> results
     end
   end
-
-  defp do_query_rows(db, sql, opts, nil) do
-    with {:ok, stmt} <- Statement.prepare(db, sql),
-         {:ok, stmt} <- Statement.bind_values(stmt, Keyword.get(opts, :bind, [])),
-         {:ok, rows} <- Statement.fetch_all(stmt, :raw_list),
-    do: {:ok, %{rows: rows, columns: stmt.column_names, types: stmt.column_types}}
-  end
-  defp do_query_rows(db, sql, opts, timeout) do
-    with {:ok, stmt} <- Statement.prepare(db, sql, timeout),
-         {:ok, stmt} <- Statement.bind_values(stmt, Keyword.get(opts, :bind, []), timeout),
-         {:ok, rows} <- Statement.fetch_all(stmt, :raw_list),
-    do: {:ok, %{rows: rows, columns: stmt.column_names, types: stmt.column_types}}
-  end
 end

lib/sqlitex/server.ex

@@ -47,6 +47,7 @@ defmodule Sqlitex.Server do
 
   alias Sqlitex.Statement
   alias Sqlitex.Server.StatementCache, as: Cache
+  alias Sqlitex.Config
 
   @doc """
   Starts a SQLite Server (GenServer) instance.
@@ -56,13 +57,13 @@ defmodule Sqlitex.Server do
 
   - `stmt_cache_size: (positive_integer)` to override the default limit (20) of statements
     that are cached when calling `prepare/3`.
-  - `esqlite3_timeout: (positive_integer)` to override `:esqlite3`'s default timeout of 5000 ms for
+  - `db_timeout: (positive_integer)` to override `:esqlite3`'s default timeout of 5000 ms for
     interactions with the database. This can also be set in `config.exs` as
     `config :sqlitex, esqlite3_timeout: 5_000`.
   """
   def start_link(db_path, opts \\ []) do
     stmt_cache_size = Keyword.get(opts, :stmt_cache_size, 20)
-    timeout = Keyword.get(opts, :esqlite3_timeout, Application.get_env(:sqlitex, :esqlite3_timeout, 5_000))
+    timeout = Keyword.get(opts, :db_timeout, Config.esqlite3_timeout())
     GenServer.start_link(__MODULE__, {db_path, stmt_cache_size, timeout}, opts)
   end
 
@@ -71,14 +72,14 @@ defmodule Sqlitex.Server do
   def init({db_path, stmt_cache_size, timeout})
     when is_integer(stmt_cache_size) and stmt_cache_size > 0
   do
-    case Sqlitex.open(db_path, timeout) do
+    case Sqlitex.open(db_path, [db_timeout: timeout]) do
       {:ok, db} -> {:ok, {db, __MODULE__.StatementCache.new(db, stmt_cache_size), timeout}}
       {:error, reason} -> {:stop, reason}
     end
   end
 
   def handle_call({:exec, sql}, _from, {db, stmt_cache, timeout}) do
-    result = Sqlitex.exec(db, sql, timeout)
+    result = Sqlitex.exec(db, sql, [db_timeout: timeout])
     {:reply, result, {db, stmt_cache, timeout}}
   end
 
@@ -104,7 +105,7 @@ defmodule Sqlitex.Server do
   end
 
   def handle_call({:create_table, name, table_opts, cols}, _from, {db, stmt_cache, timeout}) do
-    result = Sqlitex.create_table(db, name, table_opts, cols, timeout)
+    result = Sqlitex.create_table(db, name, table_opts, cols, [db_timeout: timeout])
     {:reply, result, {db, stmt_cache, timeout}}
   end
 
@@ -163,24 +164,28 @@ defmodule Sqlitex.Server do
 
   ## Helpers
 
-  defp query_impl(sql, opts, stmt_cache, esqlite3_timeout) do
-    with {%Cache{} = new_cache, stmt} <- Cache.prepare(stmt_cache, sql, esqlite3_timeout),
-         {:ok, stmt} <- Statement.bind_values(stmt, Keyword.get(opts, :bind, []), esqlite3_timeout),
+  defp query_impl(sql, opts, stmt_cache, db_timeout) do
+    db_opts = [db_timeout: db_timeout]
+
+    with {%Cache{} = new_cache, stmt} <- Cache.prepare(stmt_cache, sql, db_opts),
+         {:ok, stmt} <- Statement.bind_values(stmt, Keyword.get(opts, :bind, []), db_opts),
          {:ok, rows} <- Statement.fetch_all(stmt, Keyword.get(opts, :into, [])),
     do: {:ok, rows, new_cache}
   end
 
-  defp query_rows_impl(sql, opts, stmt_cache, esqlite3_timeout) do
-    with {%Cache{} = new_cache, stmt} <- Cache.prepare(stmt_cache, sql, esqlite3_timeout),
-         {:ok, stmt} <- Statement.bind_values(stmt, Keyword.get(opts, :bind, []), esqlite3_timeout),
+  defp query_rows_impl(sql, opts, stmt_cache, db_timeout) do
+    db_opts = [db_timeout: db_timeout]
+
+    with {%Cache{} = new_cache, stmt} <- Cache.prepare(stmt_cache, sql, db_opts),
+         {:ok, stmt} <- Statement.bind_values(stmt, Keyword.get(opts, :bind, []), db_opts),
          {:ok, rows} <- Statement.fetch_all(stmt, :raw_list),
     do: {:ok,
          %{rows: rows, columns: stmt.column_names, types: stmt.column_types},
          new_cache}
   end
 
-  defp prepare_impl(sql, stmt_cache, esqlite3_timeout) do
-    with {%Cache{} = new_cache, stmt} <- Cache.prepare(stmt_cache, sql, esqlite3_timeout),
+  defp prepare_impl(sql, stmt_cache, db_timeout) do
+    with {%Cache{} = new_cache, stmt} <- Cache.prepare(stmt_cache, sql, [db_timeout: db_timeout]),
     do: {:ok, %{columns: stmt.column_names, types: stmt.column_types}, new_cache}
   end
 

lib/sqlitex/server/statement_cache.ex

@@ -25,17 +25,17 @@ defmodule Sqlitex.Server.StatementCache do
 
   Will return `{:error, reason}` if SQLite is unable to prepare the statement.
   """
-  def prepare(%__MODULE__{cached_stmts: cached_stmts} = cache, sql, timeout)
+  def prepare(%__MODULE__{cached_stmts: cached_stmts} = cache, sql, opts \\ [])
     when is_binary(sql) and byte_size(sql) > 0
   do
     case Map.fetch(cached_stmts, sql) do
       {:ok, stmt} -> {update_cache_for_read(cache, sql), stmt}
-      :error -> prepare_new_statement(cache, sql, timeout)
+      :error -> prepare_new_statement(cache, sql, opts)
     end
   end
 
-  defp prepare_new_statement(%__MODULE__{db: db} = cache, sql, timeout) do
-    case Sqlitex.Statement.prepare(db, sql, timeout) do
+  defp prepare_new_statement(%__MODULE__{db: db} = cache, sql, opts \\ []) do
+    case Sqlitex.Statement.prepare(db, sql, opts) do
       {:ok, prepared} ->
         cache = cache
           |> store_new_stmt(sql, prepared)

lib/sqlitex/statement.ex

@@ -73,7 +73,7 @@ defmodule Sqlitex.Statement do
             column_names: [],
             column_types: []
 
-  @esqlite3_timeout Application.get_env(:sqlitex, :esqlite3_timeout, 5_000)
+  alias Sqlitex.Config
 
   @doc """
   Prepare a Sqlitex.Statement
@@ -82,14 +82,19 @@ defmodule Sqlitex.Statement do
 
   * `db` - The database to prepare the statement for.
   * `sql` - The SQL of the statement to prepare.
-  * `timeout` - The time in ms allowed for the statement to run. Defaults to 5000, or the :esqlite3_timeout value in Application env.
+
+  Also accepts the following keyword options:
+
+  * `db_timeout` - The time in ms allowed for the statement to run. Defaults to 5000, or the :esqlite3_timeout value in Application env.
 
   ## Returns
 
   * `{:ok, statement}` on success
   * See `:esqlite3.prepare` for errors.
   """
-  def prepare(db, sql, timeout \\ @esqlite3_timeout) do
+  def prepare(db, sql, opts \\ []) do
+    timeout = Keyword.get(opts, :db_timeout, Config.esqlite3_timeout)
+
     with {:ok, stmt} <- do_prepare(db, sql, timeout),
          {:ok, stmt} <- get_column_names(stmt, timeout),
          {:ok, stmt} <- get_column_types(stmt, timeout),
@@ -102,8 +107,8 @@ defmodule Sqlitex.Statement do
 
   Returns a new statement otherwise.
   """
-  def prepare!(db, sql, timeout \\ @esqlite3_timeout) do
-    case prepare(db, sql, timeout) do
+  def prepare!(db, sql, opts \\ []) do
+    case prepare(db, sql, opts) do
       {:ok, statement} -> statement
       {:error, reason} -> raise Sqlitex.Statement.PrepareError, reason: reason
     end
@@ -116,7 +121,10 @@ defmodule Sqlitex.Statement do
 
   * `statement` - The statement to bind values into.
   * `values` - A list of values to bind into the statement.
-  * `timeout` - The time in ms allowed for the statement to run. Defaults to 5000, or the :esqlite3_timeout value in Application env.
+
+  Also accepts the following keyword options:
+
+  * `db_timeout` - The time in ms allowed for the statement to run. Defaults to 5000, or the :esqlite3_timeout value in Application env.
 
   ## Returns
 
@@ -133,7 +141,9 @@ defmodule Sqlitex.Statement do
   * `datetime` - Converted into a string.  See datetime_to_string
   * `%Decimal` -  Converted into a number.
   """
-  def bind_values(statement, values, timeout \\ @esqlite3_timeout) do
+  def bind_values(statement, values, opts \\ []) do
+    timeout = Keyword.get(opts, :db_timeout, Config.esqlite3_timeout)
+
     case :esqlite3.bind(statement.statement, translate_bindings(values), timeout) do
       {:error, _} = error -> error
       :ok -> {:ok, statement}
@@ -145,8 +155,8 @@ defmodule Sqlitex.Statement do
 
   Returns the statement otherwise.
   """
-  def bind_values!(statement, values, timeout \\ @esqlite3_timeout) do
-    case bind_values(statement, values, timeout) do
+  def bind_values!(statement, values, opts \\ []) do
+    case bind_values(statement, values, opts) do
       {:ok, statement} -> statement
       {:error, reason} -> raise Sqlitex.Statement.BindValuesError, reason: reason
     end
@@ -202,14 +212,19 @@ defmodule Sqlitex.Statement do
   ## Parameters
 
   * `statement` - The statement to run.
-  * `timeout` - The time in ms allowed for the statement to run. Defaults to 5000, or the :esqlite3_timeout value in Application env.
+
+  Also accepts the following keyword options:
+
+  * `db_timeout` - The time in ms allowed for the statement to run. Defaults to 5000, or the :esqlite3_timeout value in Application env.
 
   ## Returns
 
   * `:ok`
   * `{:error, error}`
   """
-  def exec(statement, timeout \\ @esqlite3_timeout) do
+  def exec(statement, opts \\ []) do
+    timeout = Keyword.get(opts, :db_timeout, Config.esqlite3_timeout)
+
     case :esqlite3.step(statement.statement, timeout) do
       # esqlite3.step returns some odd values, so lets translate them:
       :"$done" -> :ok
@@ -223,8 +238,8 @@ defmodule Sqlitex.Statement do
 
   Returns :ok otherwise.
   """
-  def exec!(statement, timeout \\ @esqlite3_timeout) do
-    case exec(statement, timeout) do
+  def exec!(statement, opts \\ []) do
+    case exec(statement, opts) do
       :ok -> :ok
       {:error, reason} -> raise Sqlitex.Statement.ExecError, reason: reason
     end