Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Upgrading to v2

This guide covers migrating from pREST v1 to v2.

  • Latest stable v2: v2.4.2

  • Docker: prest/prest:v2.4.2

See Releases for the full changelog and v2.4.2 release notes. If you are still on v2.2.0 or earlier, note that v2.3.0 included a critical _select SQL-injection fix — upgrade promptly.

Before deploying v2.4.2, check your jwt.key length. From v2.4.2 an HMAC key below the RFC 7518 minimum (32 bytes for HS256, 48 for HS384, 64 for HS512) is discarded at startup. pREST does not refuse to start — it unregisters /auth and serves requests unauthenticated. See Auth — HMAC key requirements and v2.4.2 — Upgrading.

MCP over HTTP requires v2.1.0 or later. Studio requires v2.2.0 or later — pREST Studio. For Cursor, Claude Desktop, and other stdio clients, install the pREST MCP Adapter (brew install prest/tap/prest-mcp).

1. Choose your build

v2.4.2 (recommended):

  • Binary: v2.4.2 release assets

  • Docker: prest/prest:v2.4.2

  • Go install: go install github.com/prest/prest/v2/cmd/prestd@v2.4.2

v2.4.0:

  • Binary: v2.4.0 release assets

  • Docker: prest/prest:v2.4.0

  • Go install: go install github.com/prest/prest/v2/cmd/prestd@v2.4.0

v2.3.0:

  • Binary: v2.3.0 release assets

  • Docker: prest/prest:v2.3.0

  • Go install: go install github.com/prest/prest/v2/cmd/prestd@v2.3.0

v2.2.0:

  • Binary: v2.2.0 release assets

  • Docker: prest/prest:v2.2.0

  • Go install: go install github.com/prest/prest/v2/cmd/prestd@v2.2.0

v2.1.0:

  • Binary: v2.1.0 release assets

  • Docker: prest/prest:v2.1.0

  • Go install: go install github.com/prest/prest/v2/cmd/prestd@v2.1.0

v2.0.0:

  • Binary: v2.0.0 release assets

  • Docker: prest/prest:v2.0.0

  • Go install: go install github.com/prest/prest/v2/cmd/prestd@v2.0.0

Tip of main branch (for development only):

Note: Windows ARM binaries are not published (#970).

2. Set PREST_VERSION=2

Set the environment variable PREST_VERSION=2 (recommended for all new v2 deployments). This enables v2 naming conventions for configuration, especially PostgreSQL SSL settings.

3. Migrate SSL environment variables

v2 removed the deprecated PREST_SSL_* variables (rc2, #919). Rename them to the PREST_PG_SSL_* equivalents:

v1 (removed)
v2

PREST_SSL_MODE

PREST_PG_SSL_MODE

PREST_SSL_CERT

PREST_PG_SSL_CERT

PREST_SSL_KEY

PREST_PG_SSL_KEY

PREST_SSL_ROOTCERT

PREST_PG_SSL_ROOTCERT

In TOML, use [pg.ssl] instead of the top-level [ssl] block:

Default change: when no config file is found, v2 defaults pg.ssl.mode to disable (v1 used require). Set PREST_PG_SSL_MODE=require explicitly if you relied on the v1 default.

4. Configure JWT verification

JWT behavior depends on which build you run:

Build

Missing JWT key when jwt.default = true

v2.0.0+ (current)

JWT middleware auto-disabled with error log (#974)

v2.0.0-rc6 tag (historical)

Server refuses to start (#960)

In v2+, jwt.default defaults to false — set jwt.default = true explicitly to enable JWT enforcement.

Options for production:

  1. Provide verification material (recommended):

Or configure JWKS / well-known URL via PREST_JWT_JWKS / PREST_JWT_WELLKNOWNURL.

  1. Disable JWT middleware:

  1. Use debug mode (development only):

Always check startup logs to confirm JWT and auth are in the expected state.

The JWT whitelist default is regex ^\/auth$ (v1 used [/auth]). Review your whitelist if you customized it.

See Configuring pREST — JWT and Auth.

5. Multi-database

v2.0.0 includes full multi-database support. Configure a database registry for multi-cluster routing. See the Multi-database guide.

Set pg.single = false and define [[databases]] entries or DATABASE_ALIAS_N / DATABASE_URL_N environment pairs.

Use GET /_ready for Kubernetes readiness probes when running multiple databases.

6. Review identifier validation

rc4 hardened identifier validation (GHSA-p46v-f2x8-qp98). Invalid field or table names in query parameters are now rejected. Test your existing API calls.

7. Review auth encryption default

v2 defaults auth.encrypt to bcrypt (v1 used MD5). If you use the built-in /auth endpoint with existing password hashes, ensure compatibility or update the encrypt setting.

8. Test new v2 features

If applicable, verify:

  • OR filtering: _or=field=$eq.a||field=$eq.b (see Parameters)

  • Per-user permissions: [[access.users]] (see Permissions)

  • Multi-database: alias routing (see Multi-database)

  • MCP over HTTP: GET / POST /_mcp (v2.1.0+; see MCP over HTTP)

  • pREST Studio: open /_studio/ (v2.2.0+; see pREST Studio)

  • Database-backed queries: optional queries.storage = "database" (v2.2.0+; see Custom Queries)

  • Logging: PREST_LOG_LEVEL=debug for structured JSON logs

9. Docker-specific checklist

For local development without JWT, add -e PREST_DEBUG=true.

In v2+, the server starts even without PREST_JWT_KEY, but JWT will be auto-disabled — check logs.

See Deploying with Docker.

PreviousConnect Claude Desktop to pREST MCP
NextCORS Support

Last updated