Thanks for your interest in Bier! This guide collects the project-specific
rules that are easy to trip over; the README covers the
architecture and docs/CONFORMANCE_IMPL.md covers the
conformance build in depth.
Everything below assumes a git checkout — several files it refers to
(mise.toml, spec/, docs/CONFORMANCE_IMPL.md) are repository-only and are
not part of the published package or documentation.
Elixir/OTP versions are pinned in mise.toml (Elixir 1.20 / OTP 29), matching
CI. mix.exs declares the lower bound at ~> 1.18. With
mise installed:
mise install
mix deps.get
git submodule update --init # fetch the spec/ conformance submoduleA local PostgreSQL (15+) reachable at localhost:5432 is required for the
test suite. The PostGIS extension must be installed as well — the fixture
chain's spec/fixtures/04_postgis.sql depends on it (CI uses the
postgis/postgis images). Connection parameters come from the standard PG*
environment variables (PGHOST, PGPORT, PGUSER, PGPASSWORD).
The WAL change-feed tests (test/bier/wal/) additionally need
wal_level=logical on that instance — it defaults to replica and cannot
be changed without a restart:
psql -c "ALTER SYSTEM SET wal_level = logical;"
pg_ctl restart # or: brew services restart postgresql / systemctl restart postgresqlCI sets this via POSTGRES_INITDB_ARGS: "-c wal_level=logical" on the
postgres service (see .github/workflows/elixir.yml).
mix test # loads the fixture DB, runs everything
mix test test/path/to/file_test.exs:LINE # a single test
mix test --only area:operators # one conformance areamix test is aliased to ["bier.fixtures.load", "test"]: it force-drops
(terminating every session still attached, including one you have open in
psql) and recreates a local bier_test database and runs the spec/ submodule's
numbered fixture chain (spec/fixtures/01_roles.sql through
07_analyze.sql) before running, so it is always safe to re-run.
The conformance suite (762 cases in spec/, executed by
test/conformance/conformance_test.exs) encodes real PostgREST v16.0
behavior, with each case citing its upstream source. It is ground truth:
- Fix
lib/to match the cases — never edittest/**orspec/**. - If a case looks wrong, re-check the cited PostgREST source before assuming the test is at fault.
spec/ is a git submodule of
milmazz/postgrest-conformance,
so the freeze above is absolute here: there is no in-repo escape hatch for it
at all. Case/behavior changes and fixture edits happen upstream, in that
repo, through its own reviewed process — never as part of a bier PR.
lib/bier/query_parser.ex is generated from its
lib/bier/query_parser.ex.exs template. Edit the template, run
mix gen.parsers, and commit both the template and the regenerated .ex.
Never edit the generated .ex directly. Credo analyzes the template
(the file you edit) but skips the generated output.
Run all of CI's gates with one command:
mix precommitIt is an alias (see mix.exs) for the individual gates, in order:
mix deps.unlock --check-unused
mix format --check-formatted
mix hex.audit
mix compile --warnings-as-errors
mix credo --strict
mix docs --warnings-as-errors
mix testCI runs the same steps individually (not the alias) so each gate reports its
result separately. The test step is a plain mix test with no tolerated
baseline: the suite passes today, and any failure fails the job.
mix formatsettles formatting arguments; Credo (.credo.exs) settles the rest. Both run in CI.- Serialize JSON through
Bier.json_library(), never by calling a JSON module directly, so host applications can swap the encoder. - New error shapes belong in
Bier.Plugs.FallbackControlleras additionalcall/2clauses, not inline in the controllers. - Public modules carry a
@moduledocexplaining why the module exists and which PostgREST behavior it mirrors; keep that bar for new code.