chore: better functional repo support, add guide

Author: zachdaniel

README.md

@@ -24,6 +24,7 @@ Welcome! `AshSqlite` is the SQLite data layer for [Ash Framework](https://hexdoc
 ## Topics
 
 - [What is AshSqlite?](documentation/topics/about-ash-sqlite/what-is-ash-sqlite.md)
+- [Transactions](documentation/topics/about-ash-sqlite/transactions.md)
 
 ### Resources
 

documentation/topics/about-ash-sqlite/transactions.md

@@ -0,0 +1,110 @@
+<!--
+SPDX-FileCopyrightText: 2020 Zach Daniel
+
+SPDX-License-Identifier: MIT
+-->
+
+# Transactions
+
+## SQLite's Write Lock Limitation
+
+SQLite allows only one write lock at a time. Any attempt to write while another
+transaction already holds the write lock will immediately fail—there is no waiting
+or queuing built in. This is fundamentally different from PostgreSQL, where
+conflicting transactions queue up and proceed in order.
+
+Because of this, **AshSqlite disables transaction support by default**
+(`can?(:transact)` returns `false`). Without extra configuration, Ash will not
+wrap actions in transactions when using the SQLite data layer.
+
+## Enabling Reliable Concurrent Writes
+
+`ecto_sqlite3` exposes two knobs that together make concurrent writes behave more
+like you would expect:
+
+- **`default_transaction_mode: :immediate`** — SQLite acquires the exclusive
+  write lock at the *start* of each transaction instead of at the first write
+  statement. This prevents the scenario where two transactions both start in
+  deferred mode, both read successfully, and then race to upgrade to a write lock,
+  causing one to fail.
+
+- **`busy_timeout`** — SQLite will retry acquiring the write lock for up to this
+  many milliseconds before returning an error. Set this to a non-zero value so
+  that a brief contention window does not immediately surface as an error to your
+  users.
+
+Example repo configuration:
+
+```elixir
+# config/config.exs
+config :my_app, MyApp.Repo,
+  database: "path/to/my_app.db",
+  pool_size: 1,
+  default_transaction_mode: :immediate,
+  busy_timeout: 5000
+```
+
+> ### Keep pool_size: 1 for writes {: .warning}
+>
+> SQLite does not support parallel writes, so a write pool larger than 1 will only
+> cause contention. Set `pool_size: 1` on any repo that performs writes.
+
+## Separate Read and Write Repos
+
+For applications that need read concurrency, you can configure a dedicated
+read-only repo alongside a write repo. The write repo uses `pool_size: 1` and
+immediate transactions; the read repo opens multiple read-only connections.
+
+```elixir
+# config/config.exs
+config :my_app, MyApp.Repo,
+  database: "path/to/my_app.db",
+  pool_size: 1,
+  default_transaction_mode: :immediate,
+  busy_timeout: 5000
+
+config :my_app, MyApp.Repo.ReadOnly,
+  database: "path/to/my_app.db",
+  pool_size: 10,
+  read_only: true
+```
+
+```elixir
+# lib/my_app/repo.ex
+defmodule MyApp.Repo do
+  use AshSqlite.Repo, otp_app: :my_app
+end
+
+defmodule MyApp.Repo.ReadOnly do
+  use AshSqlite.Repo, otp_app: :my_app
+end
+```
+
+Start both repos in your application supervision tree:
+
+```elixir
+# lib/my_app/application.ex
+children = [
+  MyApp.Repo,
+  MyApp.Repo.ReadOnly,
+  ...
+]
+```
+
+Then route reads and writes to the appropriate repo using a function in the
+`repo` DSL option:
+
+```elixir
+sqlite do
+  repo fn _resource, type ->
+    case type do
+      :mutate -> MyApp.Repo
+      :read -> MyApp.Repo.ReadOnly
+    end
+  end
+  table "posts"
+end
+```
+
+The function receives the resource module and either `:read` or `:mutate` as
+arguments and must return a repo module.

lib/data_layer.ex

@@ -198,10 +198,10 @@ defmodule AshSqlite.DataLayer do
     ],
     schema: [
       repo: [
-        type: :atom,
+        type: {:or, [{:behaviour, Ecto.Repo}, {:fun, 2}]},
         required: true,
         doc:
-          "The repo that will be used to fetch your data. See the `AshSqlite.Repo` documentation for more"
+          "The repo that will be used to fetch your data. See the `AshSqlite.Repo` documentation for more. Can also be a function that takes a resource and a type `:read | :mutate` and returns the repo."
       ],
       migrate?: [
         type: :boolean,
@@ -2016,7 +2016,7 @@ defmodule AshSqlite.DataLayer do
 
   @impl true
   def rollback(resource, term) do
-    AshSqlite.DataLayer.Info.repo(resource).rollback(term)
+    AshSqlite.DataLayer.Info.repo(resource, :mutate).rollback(term)
   end
 
   defp table(resource, changeset) do
@@ -2039,15 +2039,15 @@ defmodule AshSqlite.DataLayer do
   end
 
   defp dynamic_repo(resource, %{__ash_bindings__: %{context: %{data_layer: %{repo: repo}}}}) do
-    repo || AshSqlite.DataLayer.Info.repo(resource)
+    repo || AshSqlite.DataLayer.Info.repo(resource, :read)
   end
 
   defp dynamic_repo(resource, %{context: %{data_layer: %{repo: repo}}}) do
-    repo || AshSqlite.DataLayer.Info.repo(resource)
+    repo || AshSqlite.DataLayer.Info.repo(resource, :read)
   end
 
   defp dynamic_repo(resource, _) do
-    AshSqlite.DataLayer.Info.repo(resource)
+    AshSqlite.DataLayer.Info.repo(resource, :read)
   end
 
   defp resolve_source(resource, changeset) do

lib/data_layer/info.ex

@@ -8,8 +8,14 @@ defmodule AshSqlite.DataLayer.Info do
   alias Spark.Dsl.Extension
 
   @doc "The configured repo for a resource"
-  def repo(resource) do
-    Extension.get_opt(resource, [:sqlite], :repo, nil, true)
+  def repo(resource, type \\ :mutate) do
+    case Extension.get_opt(resource, [:sqlite], :repo, nil, true) do
+      fun when is_function(fun, 2) ->
+        fun.(resource, type)
+
+      repo ->
+        repo
+    end
   end
 
   @doc "The configured table for a resource"

lib/sql_implementation.ex

@@ -335,8 +335,8 @@ defmodule AshSqlite.SqlImplementation do
   end
 
   @impl true
-  def repo(resource, _kind) do
-    AshSqlite.DataLayer.Info.repo(resource)
+  def repo(resource, kind) do
+    AshSqlite.DataLayer.Info.repo(resource, kind)
   end
 
   @impl true