fix: address sqlite open mode review feedback

Author: dl-alexandre

lib/exqlite/connection.ex

@@ -98,11 +98,11 @@ defmodule Exqlite.Connection do
     * `:default_transaction_mode` - one of `deferred` (default), `immediate`,
       or `exclusive`. If a mode is not specified in a call to `Repo.transaction/2`,
       this will be the default transaction mode.
-    * `: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.
+    * `:mode` - controls the sqlite3_open_v2 flags. Defaults to
+      `[:readwrite, :create]` (read/write + create if needed). Use
+      `:readwrite` for read/write without create, `:readonly` for read-only, or
+      a list such as `[:readwrite, :create]` or `[:readonly, :nomutex]`.
+      Note: `[:readwrite, :nomutex]` is not recommended.
     * `:journal_mode` - Sets the journal mode for the sqlite connection. Can be
       one of the following `:delete`, `:truncate`, `:persist`, `:memory`,
       `:wal`, or `:off`. Defaults to `:delete`. It is recommended that you use

lib/exqlite/sqlite3.ex

@@ -20,7 +20,7 @@ defmodule Exqlite.Sqlite3 do
   @type reason() :: atom() | String.t()
   @type row() :: list()
   @type open_mode :: :readwrite | :readonly | :nomutex | :create
-  @type open_opt :: {:mode, :readwrite | :readonly | [open_mode()]}
+  @type open_opt :: {:mode, :readwrite | :readonly | :create | [open_mode()]}
 
   @doc """
   Opens a new sqlite database at the Path provided.
@@ -31,25 +31,26 @@ defmodule Exqlite.Sqlite3 do
 
     * `:mode` - controls the flags for sqlite3_open_v2 (see
       https://www.sqlite.org/c3ref/c_open_autoproxy.html). Defaults to
-      `:readwrite` (opens for reading and writing and creates the file if it
-      does not exist — this atom form is preserved for backward compatibility).
+      `[:readwrite, :create]` (opens for reading and writing and creates the
+      file if it does not exist).
 
-      Finer-grained control (to align with sqlite3_open_v2 flags, see
-      https://github.com/elixir-sqlite/exqlite/issues/347):
+      Single modes are permitted:
+      - `:readwrite` - read/write to the database. Does not create the database
+        if it is not present. Use in combination with `:create` to create the
+        database if it does not exist.
+      - `:readonly` - read-only (file must exist).
+      - `:create` - creates the database if it does not exist.
 
-      - `:readwrite` (atom) — read/write + create if needed (compat default).
-      - `:readonly` — read-only (file must exist).
-      - Lists (recommended for new code):
-        - `[:readwrite]` — read/write only; will *not* create the file.
-        - `[:readwrite, :create]` — read/write + create if needed.
-        - `[:readonly, :nomutex]`, `[:readwrite, :nomutex]`, `[:create]` (in lists), etc.
-      - `:create` is now a valid list element to request the CREATE flag.
+      Combinations are permitted:
+      - `[:readwrite, :create]` - read/write + create if needed. This is the
+        default if not specified.
+      - `[:readonly, :nomutex]`
 
       Note: `[:readwrite, :nomutex]` is not recommended.
   """
   @spec open(String.t(), [open_opt()]) :: {:ok, db()} | {:error, reason()}
   def open(path, opts \\ []) do
-    mode = Keyword.get(opts, :mode, :readwrite)
+    mode = opts[:mode] || [:readwrite, :create]
     Sqlite3NIF.open(path, flags_from_mode(mode))
   end
 
@@ -58,13 +59,8 @@ defmodule Exqlite.Sqlite3 do
           "expected mode to be `:readwrite` or `:readonly`, can't use a single :nomutex mode"
   end
 
-  # Atom `:readwrite` keeps the historical "also create the file" behavior
-  # for backward compatibility (most existing code and the default rely on it).
-  defp flags_from_mode(:readwrite),
-    do: do_flags_from_mode([:readwrite, :create], [])
-
-  defp flags_from_mode(:readonly),
-    do: do_flags_from_mode([:readonly], [])
+  defp flags_from_mode(mode) when mode in [:readwrite, :readonly, :create],
+    do: do_flags_from_mode(List.wrap(mode), [])
 
   defp flags_from_mode([_ | _] = modes),
     do: do_flags_from_mode(modes, [])

test/exqlite/sqlite3_test.exs

@@ -109,13 +109,14 @@ defmodule Exqlite.Sqlite3Test do
       end
     end
 
-    test "opens with list [:readwrite] (no implicit create) vs default atom (creates)" do
+    test "opens with default create but explicit readwrite does not create" do
       {:ok, path} = Temp.path()
 
-      # Pure :readwrite list should not create the file
+      # Pure readwrite modes should not create the file.
+      assert {:error, _reason} = Sqlite3.open(path, mode: :readwrite)
       assert {:error, _reason} = Sqlite3.open(path, mode: [:readwrite])
 
-      # Atom default (and [:readwrite, :create]) still create for compat
+      # The default (and [:readwrite, :create]) still creates.
       {:ok, conn} = Sqlite3.open(path)
       :ok = Sqlite3.close(conn)
       assert File.exists?(path)