fosm-rails 0.2.1.1 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 28f26f433fce210f3d83b05e743813e00af06799377202f38d0607fe8035d225
-  data.tar.gz: a41302a39d9f2d563bd79d1979447ef5349c7e3a83b5b8a5883f30bcbb8b3026
+  metadata.gz: 4c993eea70daa26a211f4fa1bfda6750bbbf97389af2f621d673b12f58e41bac
+  data.tar.gz: 45b2cc6617e618c7500dccdf81ccf6bce49821307bad13e0f30374a95c9cbd04
 SHA512:
-  metadata.gz: 9efdc72240a07c07533a251a7d853db7a548b2190978354011de4f43cf0355df53c05a26e8e0318c47389f04b7af00dbcd3ea9d21faed23b9e9dee1b455d6c48
-  data.tar.gz: 39023f14ea79e8a5e09be3f00ac9aff8c1ad76ffaeccd128015baefae3517bf21193b5740faf80b5e8ae23e5560e9130acd5e24734d657d9367ff4d5aec8e610
+  metadata.gz: 4e1fa8d26f70a0ff09add103cf8fe0fbb95a63986a5dd4b1e1f052ff22b6cb28fb04e38d3b5e3e5a8be4a0a3d370bf80dc07447f0a1d6bb8292a9ce9d8de189a
+  data.tar.gz: 32a6f160c73a05def43c6a31bdd48975060557987f205f89edab4754b8a410ab505eb8917fa7338931695f261c47c4b52b01b15979de48314efe96cc9fd40ebc

data/AGENTS.md

@@ -409,6 +409,67 @@ end
 
 ---
 
+## Database configuration and connection pools
+
+### Single-database apps (the common case)
+
+`Fosm::ApplicationRecord` does **not** create a separate Active Record connection pool unless the host app explicitly opts in. This is the correct default for any app with a single database (SQLite, PostgreSQL, MySQL).
+
+Do not add a `primary:` database role expecting FOSM to use it — the name `primary` is what Rails assigns to **every** database.yml entry by default, so that condition would fire for all apps and create a redundant pool on the same database.
+
+### Why a redundant pool deadlocks
+
+When two separate pools both write to the same database inside nested transactions — which happens automatically when a `Fosm::*` model with `has_one_attached` / `has_many_attached` is saved, or when `ActiveRecord::Base.transaction` wraps a `Fosm::*` save — the result is a structural cross-pool deadlock:
+
+```
+Fosm pool  →  BEGIN TRANSACTION          # holds write lock
+Fosm pool  →  INSERT INTO fosm_*         # succeeds
+Fosm pool  →  [after_save] ActiveStorage # needs App pool write lock
+App pool   →  BEGIN TRANSACTION          # blocked waiting for Fosm pool
+Fosm pool  →  waiting for after_save…    # blocked waiting for App pool
+→ DEADLOCK — neither pool can proceed
+```
+
+This is deterministic, not a race condition. `busy_timeout` and WAL mode do not resolve it because neither mechanism can break a structural deadlock between two pools.
+
+### Opting in to a dedicated FOSM database
+
+If your app requires FOSM models on a separate database (e.g., a read replica, a separate shard, or a compliance-isolated store), declare a `fosm` role in `database.yml`:
+
+```yaml
+# config/database.yml
+default: &default
+  adapter: sqlite3
+  pool: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>
+
+development:
+  <<: *default
+  database: db/development.sqlite3
+
+fosm:
+  <<: *default
+  database: db/fosm.sqlite3   # separate file / separate PostgreSQL URL
+```
+
+`Fosm::ApplicationRecord` detects the `fosm` role at boot via `find_db_config("fosm")` and calls `connects_to database: { writing: :fosm }`. Without this entry, FOSM shares the host app's default pool.
+
+### Workaround for apps affected by the old behavior (pre-0.2.2)
+
+If you are on a version earlier than 0.2.2 and cannot upgrade immediately, create this file in your host app to override the gem's class. Zeitwerk gives app files precedence over engine files:
+
+```ruby
+# app/models/fosm/application_record.rb  (in the HOST app, not the gem)
+module Fosm
+  class ApplicationRecord < ::ApplicationRecord
+    self.abstract_class = true
+  end
+end
+```
+
+This collapses the Fosm pool into the app's default pool, eliminating the deadlock. Upgrade to 0.2.2 and remove this file when possible.
+
+---
+
 ## Contributing guidelines
 
 1. **Read the design principles above** before writing any code

data/app/models/fosm/application_record.rb

@@ -1,6 +1,32 @@
 module Fosm
   class ApplicationRecord < ActiveRecord::Base
     self.abstract_class = true
-    connects_to database: { writing: :primary } if ActiveRecord::Base.configurations.find_db_config("primary")
+
+    # Only create a dedicated connection pool when the host app has explicitly
+    # declared a "fosm" database role in database.yml.
+    #
+    # The previous guard — find_db_config("primary") — fired for every Rails app
+    # because "primary" is the default role name Rails assigns to every
+    # database.yml entry. This created a redundant second pool targeting the same
+    # database, which caused a structural cross-pool deadlock with ActiveStorage
+    # (and any ActiveRecord::Base.transaction block that touched Fosm::* models)
+    # on all single-database setups (SQLite, PostgreSQL, MySQL):
+    #
+    #   Fosm pool  →  BEGIN TRANSACTION  (holds write lock)
+    #   App pool   →  BEGIN TRANSACTION  (needs write lock — blocked)
+    #   Fosm pool  →  after_save triggers ActiveStorage write via App pool
+    #   → DEADLOCK: each pool waiting for the other to release the write lock
+    #
+    # The fix: only split into a separate pool when the host app opts in by
+    # declaring a "fosm" role in database.yml. Single-database apps share the
+    # default ActiveRecord::Base pool and are not affected.
+    #
+    # To use a dedicated FOSM database, add to database.yml:
+    #
+    #   fosm:
+    #     <<: *default
+    #     database: db/fosm.sqlite3   # or a separate PostgreSQL/MySQL URL
+    #
+    connects_to database: { writing: :fosm } if ActiveRecord::Base.configurations.find_db_config("fosm")
   end
 end

data/lib/fosm/version.rb

@@ -1,3 +1,3 @@
 module Fosm
-  VERSION = "0.2.1.1"
+  VERSION = "0.2.2"
 end

data/lib/generators/fosm/app/app_generator.rb

@@ -64,6 +64,29 @@ module Fosm
           or `app/agents/fosm/`, you **must** read and follow the instructions in:
 
           `#{agents_md_path}`
+
+          ### Database / connection pool (IMPORTANT — read before touching database.yml)
+
+          `Fosm::ApplicationRecord` only creates a separate Active Record connection pool
+          when the host app has a `fosm:` role in `database.yml`. Without it, all FOSM
+          models share the default app pool — this is correct for single-database setups.
+
+          **Do NOT** add a `primary:` database role for FOSM. `primary` is the default role
+          name Rails assigns to every `database.yml` entry, so that condition would create a
+          redundant pool on the same database and cause a deterministic cross-pool deadlock
+          whenever a `Fosm::*` model with `has_one_attached` / `has_many_attached` is saved,
+          or when `ActiveRecord::Base.transaction` wraps a `Fosm::*` save.
+
+          To opt in to a dedicated FOSM database, add this to `database.yml`:
+
+          ```yaml
+          fosm:
+            <<: *default
+            database: db/fosm.sqlite3   # or a separate PostgreSQL/MySQL URL
+          ```
+
+          See the "Database configuration and connection pools" section in AGENTS.md for
+          the full explanation and the pre-0.2.2 workaround.
         MARKDOWN
 
         if File.exist?(claude_md)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fosm-rails
 version: !ruby/object:Gem::Version
-  version: 0.2.1.1
+  version: 0.2.2
 platform: ruby
 authors:
 - Abhishek Parolkar
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-24 00:00:00.000000000 Z
+date: 2026-03-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails