pREST v2.6 turns a Postgres database into a REST API with login in about five minutes. One command creates a user. Tokens expire when you say. Requests with a forged Host header get a 400. Every response carries an ID you can find in the logs.
Install v2.6.0 and follow the steps below. Every output is from a real run.
Upgrade first. v2.6.0 includes the three fixes from v2.5.3. Earlier releases run a
DELETEorPUTwith no filter against the whole table (GHSA-r867-ghgv-mrp9, CVSS 8.1). They also ignore write-field limits (GHSA-h25q-9rmj-646h, 7.1) and leak restricted columns through_count(GHSA-48r9-g6f9-x3gm, 7.5).
pREST v2 series: Architecture (rc6) → v2.0.0 / v2.1.0 GA → MCP tutorial → AI plugins → v2.2.0 → v2.3.0 → v2.4.0 → v2.4.1 + v2.4.2 → v2.5: MySQL → v2.5.2 → This post (v2.6)
New to pREST? The pREST v2 guide lists every release and where to start.
Table of Contents
- What you get
- Quickstart
- Lock it down
- Trace a request
- Filter arrays and feed charts
- Ship the config as one env var
- What’s different
- Versions and limits
- Also in v2.6
- FAQ
- Sources
- Also from Insurgency Labs
What you get
prestd auth create-user adaadds a login user and hashes the password for you.auth.token_ttl = "30m"sets how long a token lives. The default is still 6 hours.http.allowed_hostsanswers forgedHostheaders with a 400.http.request_id_headerputs an ID on every response and every log line.?tags=$contains.giftfilters on Postgres array columns._renderer=rows,columnsormsgpackreturn compact output for charts and grids.PREST_CONFIG_JSONreplacesprest.tomlwith one env var.
It fits teams with an existing Postgres database who need login and limits before sharing an API over it. On MySQL most of it applies, but $contains and the time zone setting are Postgres only.
Quickstart
You need Docker, curl and jq. Start Postgres and add a table:
docker network create prest-demo
docker run -d --name pg --network prest-demo \
-e POSTGRES_USER=prest -e POSTGRES_PASSWORD=prest -e POSTGRES_DB=shop \
postgres:18
# wait until Postgres accepts connections
until docker exec pg pg_isready -h 127.0.0.1 -U prest -d shop -q; do sleep 1; done
docker exec -i pg psql -U prest -d shop <<'SQL'
CREATE TABLE orders (
id serial PRIMARY KEY,
customer text NOT NULL,
total numeric(10,2) NOT NULL,
tags text[] NOT NULL DEFAULT '{}',
created_at timestamptz NOT NULL DEFAULT now()
);
INSERT INTO orders (customer, total, tags) VALUES
('ada', 42.50, '{gift,express}'),
('linus', 18.00, '{express}'),
('grace', 120.00, '{gift}'),
('ada', 7.25, '{}');
SQL
Start pREST with auth on and the new settings:
docker run -d --name prest --network prest-demo -p 3000:3000 \
-e PREST_PG_HOST=pg -e PREST_PG_PORT=5432 \
-e PREST_PG_USER=prest -e PREST_PG_PASS=prest -e PREST_PG_DATABASE=shop \
-e PREST_AUTH_ENABLED=true -e PREST_JWT_DEFAULT=true \
-e PREST_JWT_KEY='replace-with-a-random-secret-of-at-least-32-bytes' \
-e PREST_AUTH_TOKEN_TTL=30m \
-e PREST_HTTP_ALLOWED_HOSTS=localhost,127.0.0.1 \
-e PREST_HTTP_REQUEST_ID_HEADER=X-Request-Id \
-e PREST_PG_TIMEZONE=America/Sao_Paulo \
prest/prest:v2.6.0
until docker logs prest 2>&1 | grep -q 'listening and serving'; do sleep 1; done
The first start takes about 15 seconds. pREST creates the prest_users table on its own when auth is on. Add a user and log in:
# add a user; the password comes from stdin, never from a flag
printf '%s' 's3cret-pass' | docker exec -i prest prestd auth create-user ada --name "Ada" --password-stdin
# created user "ada" (id 1)
curl -s localhost:3000/shop/public/orders
# {"error": "authorization token is empty"}
TOKEN=$(curl -s -X POST localhost:3000/auth -H 'Content-Type: application/json' \
-d '{"username":"ada","password":"s3cret-pass"}' | jq -r .token)
curl -s localhost:3000/shop/public/orders -H "Authorization: Bearer $TOKEN"
# [{"id": 1, "tags": ["gift", "express"], "total": 42.50, "customer": "ada", "created_at": "2026-11-19T13:12:59.617868-03:00"},
# {"id": 2, "tags": ["express"], "total": 18.00, "customer": "linus", "created_at": "2026-11-19T13:12:59.617868-03:00"}, ...]
The path is /{database}/{schema}/{table}. The command prints a few log lines before the last one; I trimmed them. The -03:00 offset is the PREST_PG_TIMEZONE setting at work.
Before v2.6 this step took htpasswd, a bcrypt hash and an INSERT by hand. The CLI stores names in lower case, the way /auth looks them up. A hand-written INSERT of ADA made a user who could never log in. Now create-user ADA fails with user already exists: ada.
Lock it down
Check the token lifetime. The token carries nbf and exp:
echo "$TOKEN" | jq -rR 'split(".")[1] | @base64d | fromjson | (.exp - .nbf) / 60'
# 30
The value takes a Go duration (30m, 12h) or seconds. A typo such as 5mins stops startup instead of falling back to 6 hours.
A forged Host never reaches auth or your tables:
curl -s -i localhost:3000/shop/public/orders -H 'Host: evil.example.com' -H "Authorization: Bearer $TOKEN"
# HTTP/1.1 400 Bad Request
# X-Request-Id: dd88a829cf4b4f05dfbe5a68bb299076
#
# {"error": "invalid Host header"}
A write with no filter is refused, which is the v2.5.3 fix:
curl -s -X DELETE localhost:3000/shop/public/orders -H "Authorization: Bearer $TOKEN"
# {"error":"refusing DELETE without a WHERE condition: add a filter query parameter"}
In production, add the host your load balancer and health checks use to allowed_hosts, often an IP address. A leading dot allows subdomains: .example.com matches api.example.com.
Trace a request
With http.request_id_header set, pREST keeps the ID a client sends, or makes one:
curl -s -i localhost:3000/shop/public/nope -H 'X-Request-Id: checkout-7f3a' -H "Authorization: Bearer $TOKEN"
# HTTP/1.1 404 Not Found
# X-Request-Id: checkout-7f3a
The same ID ends the access log line, so a support ticket leads straight to the request:
docker logs prest 2>&1 | grep negroni | tail -2
# [negroni] 2026-11-19T16:22:17Z | 400 | 177.541µs | localhost:3000 | DELETE /shop/public/orders | dce0bf053fd7d984d0ad3907b4681a8e
# [negroni] 2026-11-19T16:22:17Z | 404 | 3.906042ms | localhost:3000 | GET /shop/public/nope | checkout-7f3a
On the database side, pREST’s connections now name themselves. With log_connections on, Postgres logs:
LOG: connection authorized: user=prest database=shop application_name=prestd
Change it with PREST_PG_APPLICATION_NAME, or set it empty to turn it off.
Filter arrays and feed charts
$contains matches rows whose array holds every listed value:
curl -s 'localhost:3000/shop/public/orders?tags=$contains.gift&_select=id,customer,tags' -H "Authorization: Bearer $TOKEN"
# [{"id": 1, "tags": ["gift", "express"], "customer": "ada"}, {"id": 3, "tags": ["gift"], "customer": "grace"}]
curl -s 'localhost:3000/shop/public/orders?tags=$contains.gift,express&_select=id,customer' -H "Authorization: Bearer $TOKEN"
# [{"id": 1, "customer": "ada"}]
It compiles to Postgres @>, so a GIN index on the column helps. On a text column it returns a 400.
Chart and grid libraries take arrays as input. _renderer now returns that shape:
# one row per order
curl -s 'localhost:3000/shop/public/orders?_select=customer,total&_renderer=rows' -H "Authorization: Bearer $TOKEN"
# {"metadata":["total","customer"],"rows":[[42.50,"ada"],[18.00,"linus"],[120.00,"grace"],[7.25,"ada"]]}
# one array per column, works with _groupby too
curl -s 'localhost:3000/shop/public/orders?_select=customer,total&_renderer=columns' -H "Authorization: Bearer $TOKEN"
# {"metadata":["total","customer"],"columns":[[42.50,18.00,120.00,7.25],["ada","linus","grace","ada"]]}
Read the order from metadata. It follows jsonb key order, so _select=customer,total came back as total, customer. Set [json.agg] type = "json_agg" to keep the query’s order.
_renderer=msgpack returns the same data as MessagePack with Content-Type: application/vnd.msgpack. On this table the body went from 468 bytes to 367.
Ship the config as one env var
Some platforms make mounting a prest.toml awkward. Export the file to JSON once:
# prest.toml
[auth]
enabled = true
token_ttl = "30m"
[jwt]
default = true
[access]
restrict = true
[[access.tables]]
name = "orders"
permissions = ["read"]
fields = ["id", "customer", "total"]
docker run --rm -v "$PWD/prest.toml:/app/prest.toml:ro" --entrypoint prestd \
prest/prest:v2.6.0 config export-json -f prest.toml 2>/dev/null > app-config.json
cat app-config.json
# {"access":{"restrict":true,"tables":[{"fields":["id","customer","total"],"name":"orders","permissions":["read"]}]},"auth":{"enabled":true,"token_ttl":"30m"},"jwt":{"default":true}}
Then pass it as PREST_CONFIG_JSON. Database settings and the key stay in their usual variables:
docker run -d --name prest-json --network prest-demo -p 3001:3000 \
-e PREST_PG_HOST=pg -e PREST_PG_PORT=5432 \
-e PREST_PG_USER=prest -e PREST_PG_PASS=prest -e PREST_PG_DATABASE=shop \
-e PREST_JWT_KEY='replace-with-a-random-secret-of-at-least-32-bytes' \
-e PREST_CONFIG_JSON="$(cat app-config.json)" \
prest/prest:v2.6.0
until docker logs prest-json 2>&1 | grep -q 'listening and serving'; do sleep 1; done
TOKEN=$(curl -s -X POST localhost:3001/auth -H 'Content-Type: application/json' \
-d '{"username":"ada","password":"s3cret-pass"}' | jq -r .token)
curl -s localhost:3001/shop/public/orders -H "Authorization: Bearer $TOKEN"
# [{"id": 1, "total": 42.50, "customer": "ada"}, {"id": 2, "total": 18.00, "customer": "linus"}, ...]
curl -s 'localhost:3001/shop/public/orders?_select=tags' -H "Authorization: Bearer $TOKEN"
# {"error":"you don't have permission for this action, please check the permitted fields for this table"}
Connection settings stay in env vars. A pg key in the JSON is dropped with WARN config json: ignoring infrastructure key (use env vars) key=pg. The export can hold jwt.key, so store it as a secret. Use PREST_CONFIG_JSON_B64 where multi-line values get mangled.
What’s different
| Before v2.6 | v2.6 | |
|---|---|---|
| Add a login user | htpasswd plus a SQL INSERT |
prestd auth create-user |
| Token lifetime | Fixed at 6 hours | auth.token_ttl |
Forged Host header |
Served | 400 with http.allowed_hosts |
| Request IDs | None | http.request_id_header on responses and logs |
| Array filter | None | $contains (Postgres) |
| Output formats | JSON, XML | Plus rows, columns, msgpack |
| Config without a file | Env vars only | PREST_CONFIG_JSON |
| Session time zone | Server default | pg.timezone |
Full list: v2.6.0 release notes.
Versions and limits
$containsandpg.timezoneare Postgres only. MySQL answersunsupported operatoror ignores the zone.- Unset, every new setting keeps the old behavior. The one visible change: connections report
application_name=prestd. create-userneeds the auth table. pREST creates it on start when auth is on.- Docker images run on amd64 and arm64.
Also in v2.6
- Filter values with a
$inside, likecost$usd, now match as written (#1093). PATCHorDELETEwith_returningreturns a 400 on a database error instead of a panic (#1103)./_mcpnegotiates the MCP protocol version and accepts_metafields (#1117).
Thanks to officialasishkumar, who wrote most of the new features, and to samithiwat and dhananjay6561.
Upgrading? Pull prest/prest:v2.6.0. From v2.5.2 or earlier, unfiltered writes and some field-restricted requests now fail; the v2 guide lists them.
FAQ
How do I add a user to a pREST REST API?
Run prestd auth create-user <name> --password-stdin and pipe the password in. It hashes the password with your auth.encrypt setting and stores the user in lower case. It needs pREST v2.6.0 or newer.
How long do pREST JWT tokens last?
Six hours by default. Set auth.token_ttl or PREST_AUTH_TOKEN_TTL to a duration such as 30m or 12h. An invalid value stops startup.
How do I protect a REST API from Host header attacks?
In pREST, list your host names in http.allowed_hosts. Requests for any other host get a 400 before they reach auth. Include the host your load balancer uses for health checks.
How do I filter a PostgreSQL array column over REST?
Use ?column=$contains.a,b in pREST v2.6. It returns rows whose array holds every listed value. It runs as @>, so a GIN index helps.
Can pREST return data for charts?
Yes. _renderer=rows returns column names once plus an array per row. _renderer=columns returns one array per column.
Is pREST free?
Yes. It’s MIT licensed, and the Docker images are free.
Sources
- Release notes: v2.6.0, v2.5.3. Code: github.com/prest/prest.
- Docs: auth, parameters and
_renderer, permissions, sample config. - Related: pREST in 10 minutes, pREST v2 guide, MySQL walkthrough, pREST vs PostgREST.
Also from Insurgency Labs
Running an API team on GitHub? DeliveryCompass shows PR cycle time and review patterns, with read-only access. See the DeliveryCompass overview. It’s free during Early Access.