Database-backed, cached, cluster-aware system configuration for Phoenix.

Usage

Define a configuration module in your application:

defmodule MyApp.SystemConfig do
  use PhoenixFlags,
    otp_app: :my_app,
    repo: MyApp.Repo

  def benefits_enabled?, do: get("enable_benefits", false)
end

Add it to your supervision tree:

children = [
  MyApp.Repo,
  MyApp.SystemConfig,
  # ...
]

Read configuration values:

MyApp.SystemConfig.get("enable_benefits")        #=> true
MyApp.SystemConfig.get("max_retries", 3)         #=> 3
MyApp.SystemConfig.benefits_enabled?()            #=> true

Testing

In test environment, a Test submodule is generated with process-scoped overrides:

MyApp.SystemConfig.Test.stub("enable_benefits", true)
MyApp.SystemConfig.Test.insert_entry("enable_benefits", true)

Architecture

• Storage: system_flags table in PostgreSQL (source of truth)
• Cache: Single :persistent_term key holding a pre-built %{key => value} map
• Reads: :persistent_term.get + Map.get — zero-copy, no process calls
• Writes: GenServer updates DB, reloads local cache, notifies peer nodes
• Cluster: After a write, the GenServer sends :reload to its counterpart on all connected nodes — no PubSub dependency. A periodic jittered cache refresh (refresh_interval, default 60s) heals nodes that missed a notification.