Filesystem-backed SQL loader and executor.

Convention

Statements live at priv/queries/<domain>/<operation>.sql and use PostgreSQL positional parameters ($1..$n). Each file is keyed by {Domain, Operation}, so priv/queries/jobs/insert.sql becomes {jobs, insert}:

ergon_sql:query({jobs, insert}, [Queue, Worker, Payload, MaxAttempts, Dedup])

This gen_server walks the query roots once at boot and caches every statement in a read-optimised ETS table, so executing a named statement is a lock-free ets:lookup/2 plus a ergon_repo:query/3. It is supervised ahead of every consumer that depends on it.

Host query directories

Host applications register additional priv/queries-style directories through application environment, so one loader serves both Ergon's statements and host-owned domains (assets, telemetry, spatial, ...). The default is Ergon's own priv/queries only:

{ergon, [{ergon_sql, [{extra_roots, [
    {priv, my_app, "queries"},        %% <my_app>/priv/queries
    {app, my_app, "priv/queries"},    %% <my_app>/priv/queries, spelled the long way
    "/absolute/path/to/queries"       %% used verbatim
]}]}]}

Keys from extra roots share the {Domain, Operation} namespace; a collision across roots is rejected at load time exactly like one inside a single root.

Naming

find/1 returns {ok, SQL} | error; fetch/1 returns the statement or raises. That is the maps:find/2 / maps:get/2 pairing, and the raising form carries an EEP-54 error_info so a mistyped key prints the known keys and the path the file was expected at, rather than a bare badkey.