# bier v0.1.0 - Table of Contents

> A RESTful API generated on the fly from PostgreSQL introspection — a PostgREST-inspired Elixir library.

## Pages

- [Bier](readme.md)
- [Changelog](changelog.md)
- [Contributing to Bier](contributing.md)

- Tutorials
  - [Getting Started](getting-started.md)
  - [Authentication](authentication.md)
  - [Realtime: a live check-ins board](realtime.md)

- Reference
  - [REST API Reference](api.md)
  - [Configuration](configuration.md)
  - [Observability](observability.md)
  - [Realtime events (SSE)](realtime_events.md)
  - [Injection safety](injection_safety.md)

## Modules

- [Bier](Bier.md): Public entry point for a Bier instance.
- [Bier.Auth](Bier.Auth.md): Per-request authentication context: JWT verification, role resolution, and the
PostgREST request GUCs.
- [Bier.CLI](Bier.CLI.md): Command-line interface for running Bier as a standalone, drop-in
PostgREST-compatible service.
- [Bier.CLI.Config](Bier.CLI.Config.md): The PostgREST config dialect ↔ Bier boundary.
- [Bier.CLI.ConfigFile](Bier.CLI.ConfigFile.md): Parses the PostgREST-compatible config-file subset into a
`%{kebab_key => raw_value}` map: `key = value` lines, `#` comments (whole
lines or trailing a value, as configurator-pg allows), blank lines,
double-quoted strings (with `\"` escapes and configurator's `$$` escape for
a literal `$`), bare integers, and bare `true`/`false`. A `#` inside a quoted
string is literal. Raw values are returned untyped; `Bier.CLI.Config` coerces
them per the target key.
- [Bier.CLI.DbSettings](Bier.CLI.DbSettings.md): The in-database config source (PostgREST `Config/Database.hs`
`queryDbSettings`): reads `pgrst.*` settings from
`pg_catalog.pg_db_role_setting` for the connecting role — cluster-wide and
current-database-specific, the latter winning — filtered to the
`Bier.CLI.Config.db_settings_names/0` whitelist, and returns them as a
`%{kebab_key => raw_string}` map for `Bier.CLI.Config.load/4`'s `db` source.

- [Bier.CLI.Ready](Bier.CLI.Ready.md): The client half of the `--ready` flag (PostgREST `Client.hs`): GET the admin
server's `/ready` endpoint and report the outcome the way PostgREST's
http-client wrapper does — `OK: <url>` on a 2xx, `ERROR: <url>` on any other
response, `ERROR: connection refused to <url>` when the request fails.
- [Bier.Cancellation](Bier.Cancellation.md): Cancels the in-flight Postgres query when the HTTP client disconnects (#82).
- [Bier.Config](Bier.Config.md): Defines and validates the internal configuration needed by `Bier` processes.
- [Bier.CustomMedia](Bier.CustomMedia.md): PostgREST custom media-type handlers.
- [Bier.Embed](Bier.Embed.md): Resource embedding (PostgREST `select=...,rel(...)`) for the read pipeline.
- [Bier.ErrorLogger](Bier.ErrorLogger.md): Structured JSON diagnostics for database-client and schema-cache failures.
- [Bier.ErrorPayload](Bier.ErrorPayload.md): Serializes PostgREST's error envelope to its exact wire bytes.
- [Bier.Events](Bier.Events.md): Request handler for the realtime events endpoint (`GET /<events_path>`).
- [Bier.Events.Listener](Bier.Events.Listener.md): Per-instance LISTEN connection for the realtime events endpoint.
- [Bier.Events.Registry](Bier.Events.Registry.md): Node-shared pub/sub registry for the realtime events endpoint.
- [Bier.Events.SSE](Bier.Events.SSE.md): Pure Server-Sent Events wire encoding for the realtime events endpoint.
- [Bier.Fuzzy](Bier.Fuzzy.md): Approximate name matching for PostgREST's "Perhaps you meant …" hints.
- [Bier.Guc](Bier.Guc.md): Reads and applies the PostgREST response GUCs a function or trigger may set
during a request
- [Bier.Health](Bier.Health.md): Health checks backing the per-instance admin endpoints.
- [Bier.HttpServerStarter](Bier.HttpServerStarter.md): Sets up the initial router based on the DB introspection process

- [Bier.Introspection](Bier.Introspection.md): Database introspection.
- [Bier.Introspection.Relation](Bier.Introspection.Relation.md): A single exposed relation (table or view) with its structure.
- [Bier.JWT](Bier.JWT.md): Minimal JWT verification for the auth pipeline.
- [Bier.JWT.RoleClaim](Bier.JWT.RoleClaim.md): The `jwt-role-claim-key` JSON Path: where in the JWT claims the database role
lives (default `$.role`).
- [Bier.JwtCache](Bier.JwtCache.md): Per-instance JWT verification-result cache (PostgREST jwt-cache-max-entries).
- [Bier.MediaType](Bier.MediaType.md): Accept/Content-Type media-type negotiation, mirroring PostgREST's
`PostgREST.MediaType`.
- [Bier.Mutation](Bier.Mutation.md): Write pipeline for `POST` / `PATCH` / `PUT` / `DELETE` on a relation.
- [Bier.Negotiation](Bier.Negotiation.md): Resolves the response media type for a request by negotiating the `Accept`
header against the producers available in the request's context (relation,
RPC, or root), mirroring PostgREST's content negotiation.
- [Bier.OpenAPI](Bier.OpenAPI.md): Builds the Swagger 2.0 (OpenAPI 2.0) root document from an introspection
snapshot. Wire-format match to PostgREST `Bier.postgrest_version/0` is the
contract; see
spec/openapi.yaml and spec/conformance/cases/16*.yaml. An opt-in
OpenAPI 3.0.3 translation of this document is available via the
`openapi_version: "3.0"` config option (`Bier.OpenAPI.V3`).

- [Bier.OpenAPI.Types](Bier.OpenAPI.Types.md): PostgreSQL type -> Swagger 2.0 schema mapping (mirrors PostgREST OpenAPI.hs:59-115).
- [Bier.OpenAPI.V3](Bier.OpenAPI.V3.md): Converts the generated Swagger 2.0 root document (`Bier.OpenAPI.build/1`)
into an OpenAPI 3.0.3 document.
- [Bier.Pagination](Bier.Pagination.md): Pagination semantics for the read pipeline: the `Range`/`Range-Unit` request
headers, the `Prefer: count=` modes, and the resulting `Content-Range`
response header and HTTP status (200/206/416).
- [Bier.PgError](Bier.PgError.md): Translates a `Postgrex.Error` (a Postgres `ServerError`) into the PostgREST
HTTP response: status code, JSON error envelope, extra response headers, and
an optional custom reason phrase.
- [Bier.Plan](Bier.Plan.md): Serves the `application/vnd.pgrst.plan` media type by running `EXPLAIN` over
the request's read query and returning the planner output (JSON or text).
- [Bier.Plugs.ActionController](Bier.Plugs.ActionController.md): Request-time controller for the read + mutation pipeline.
- [Bier.Plugs.AdminRouter](Bier.Plugs.AdminRouter.md): Minimal plug for a `Bier` instance's admin server (PostgREST admin server).
- [Bier.Plugs.Cors](Bier.Plugs.Cors.md): CORS middleware mirroring PostgREST's `server-cors-allowed-origins`
(PostgREST `src/PostgREST/Cors.hs`).
- [Bier.Plugs.FallbackController](Bier.Plugs.FallbackController.md): Renders errors using PostgREST's JSON envelope `{code, message, details, hint}`
and maps internal error reasons / Postgres `SQLSTATE`s to HTTP statuses and
`PGRST*` codes.
- [Bier.Plugs.Observability](Bier.Plugs.Observability.md): Cross-cutting observability middleware, applied to every request before it
reaches `Bier.Plugs.ActionController`. It mirrors PostgREST's two
request/response-spanning concerns
- [Bier.Plugs.ReadBody](Bier.Plugs.ReadBody.md): Reads the full raw request body once, caching it in
`conn.assigns[:bier_raw_body]`, and JSON-parses it into `conn.body_params`
when the request `Content-Type` is JSON.
- [Bier.Plugs.Vary](Bier.Plugs.Vary.md): Appends PostgREST v16.0's default `Vary` header to every non-error response.
- [Bier.Plugs.Warning](Bier.Plugs.Warning.md): Emits PostgREST v16.0's deprecation `Warning` header for legacy embed target
names.
- [Bier.PoolMonitor](Bier.PoolMonitor.md): Per-instance poller that samples the Postgrex connection pool and emits the
`[:bier, :pool, :status]` gauge event (see `Bier.Telemetry`).
- [Bier.Preferences](Bier.Preferences.md): Parsing and validation of the `Prefer` request header for the **read** path
(the write path's `Prefer` handling lives in `Bier.Mutation`).
- [Bier.PrivilegesCache](Bier.PrivilegesCache.md): Per-instance, per-role cache of `Bier.Introspection.privileges/3` results
for the root OpenAPI document (`openapi-mode = follow-privileges`).
- [Bier.QueryExecutor](Bier.QueryExecutor.md): Turns a parsed request plan (`Bier.QueryParser.parse_request/1`) plus a target
relation into ONE parameterized SQL statement that returns the result set as
JSON text, then executes it through the per-instance Postgrex pool.
- [Bier.QueryParser](Bier.QueryParser.md): Parser for the PostgREST-style request query string.
- [Bier.Registry](Bier.Registry.md): Local key-value process storage for Bier instances

- [Bier.Render](Bier.Render.md): Renders a JSON-array result body (the text produced by `Bier.QueryExecutor`)
into the negotiated output format: CSV, a singular object, a nulls-stripped
array/object, or plain JSON.
- [Bier.RequestLog](Bier.RequestLog.md): Access-log formatting and the per-request SQL accumulator behind `log-level`
and `log-query` (#28), mirroring PostgREST v14.12 `Logger.hs`.
- [Bier.Response](Bier.Response.md): Shared response rendering for read, RPC, and mutation paths: applies the
negotiated media-type transform (`Bier.Render`), sets the `Content-Type` and
`Content-Range`, and emits the right status.

- [Bier.RouterBuilder](Bier.RouterBuilder.md): Builds the per-instance router module.
- [Bier.Rpc](Bier.Rpc.md): Dispatches `/rpc/<fn>` calls across the function return kinds PostgREST
supports: set-of-relation, set-of-scalar, scalar, scalar array, composite,
record / TABLE / OUT-params, void, and the special single-unnamed-parameter
functions whose argument is the raw request body (scalar / json).
- [Bier.SchemaCache](Bier.SchemaCache.md): The per-instance, in-memory snapshot of the database introspection results.
- [Bier.SchemaCacheListener](Bier.SchemaCacheListener.md): Subscribes to the instance's `db_channel` Postgres notification channel and
reloads the schema cache on PostgREST's reload signals
(`NOTIFY <db_channel>, 'reload schema'`).
- [Bier.ServerTiming](Bier.ServerTiming.md): Per-request accumulator for the real per-phase durations reported in the
`Server-Timing` response header (`Bier.Plugs.Observability`).
- [Bier.Telemetry](Bier.Telemetry.md): `:telemetry` events emitted by Bier.

## Mix Tasks

- [mix bier.fixtures.load](Mix.Tasks.Bier.Fixtures.Load.md): Loads the conformance fixture database.

