Skip to content

Configuration

Docker ENV VAR name Component Default
OpenResty
DB_SCHEMA OpenResty public
DB_HOST OpenResty localhost
DB_PORT OpenResty 5432
DB_NAME OpenResty app
DB_USER OpenResty authenticator
DB_PASS OpenResty
DB_ANON_ROLE OpenResty anonymous
DEVELOPMENT OpenResty 1
ENABLE_CACHE OpenResty 0
RELAY_ID_COLUMN OpenResty id
ERR_LOGLEVEL OpenResty error
PostgREST+
PGRST_DB_URI PostgREST+
PGRST_DB_READ_REPLICAS_URI PostgREST+
PGRST_DB_SCHEMA PostgREST+ public
PGRST_DB_ANON_ROLE PostgREST+ anonymous
PGRST_DB_POOL PostgREST+ 100
PGRST_DB_POOL_TIMEOUT PostgREST+ 10
PGRST_DB_EXTRA_SEARCH_PATH PostgREST+ public
PGRST_DB_CHANNEL PostgREST+ pgrst
PGRST_DB_CHANNEL_ENABLED PostgREST+ true
PGRST_SERVER_HOST PostgREST+ !4
PGRST_SERVER_PORT PostgREST+ 3000
PGRST_SERVER_UNIX_SOCKET PostgREST+
PGRST_SERVER_UNIX_SOCKET_MODE PostgREST+ 660
PGRST_OPENAPI_SERVER_PROXY_URI PostgREST+
PGRST_JWT_SECRET PostgREST+
PGRST_JWT_AUD PostgREST+
PGRST_SECRET_IS_BASE64 PostgREST+ False
PGRST_MAX_ROWS PostgREST+
PGRST_PRE_REQUEST PostgREST+
PGRST_APP.SETTINGS.* PostgREST+
PGRST_ROLE_CLAIM_KEY PostgREST+ .role
PGRST_RAW_MEDIA_TYPES PostgREST+
PGRST_CUSTOM_RELATIONS PostgREST+
PGRST_DB_SAFE_FUNCTIONS PostgREST+
OAuth
OAUTH_SUCCESS_URI OpenResty /rest/rpc/on_oauth_login
OAUTH_GOOGLE_CLIENT_ID OpenResty
OAUTH_GOOGLE_CLIENT_SECRET OpenResty
OAUTH_GOOGLE_AUTHORIZATION_URL OpenResty
OAUTH_GOOGLE_TOKEN_URL OpenResty
OAUTH_GOOGLE_USERINFO_URL OpenResty
OAUTH_GOOGLE_SCOPE OpenResty
OAUTH_GITHUB_CLIENT_ID OpenResty
OAUTH_GITHUB_CLIENT_SECRET OpenResty
OAUTH_GITHUB_AUTHORIZATION_URL OpenResty
OAUTH_GITHUB_TOKEN_URL OpenResty
OAUTH_GITHUB_USERINFO_URL OpenResty
OAUTH_GITHUB_SCOPE OpenResty
OAUTH_FACEBOOK_CLIENT_ID OpenResty
OAUTH_FACEBOOK_CLIENT_SECRET OpenResty
OAUTH_FACEBOOK_AUTHORIZATION_URL OpenResty
OAUTH_FACEBOOK_TOKEN_URL OpenResty
OAUTH_FACEBOOK_USERINFO_URL OpenResty
OAUTH_FACEBOOK_SCOPE OpenResty

OpenResty

DB_SCHEMA

The database schema to expose to REST (and GraphQL) clients. Tables, views and stored procedures in this schema will get API endpoints.

DB_HOST

Database host name

DB_PORT

Database port (usually 5432)

DB_NAME

The name of the database

DB_USER

Database user (in the docs it's referred to as authenticator user)

DB_PASS

Database user password

DB_ANON_ROLE

The database role to use when executing commands on behalf of unauthenticated clients.

DEVELOPMENT

A flag to enable/disable some debugging information in logs and response headers when in development mode use 0 as a value for production deployments

ENABLE_CACHE

A flag to enable the caching subsystem (note that you still need to define a few lua functions to specify what and when to cache)

RELAY_ID_COLUMN

ERR_LOGLEVEL

The nginx error (log level)[https://nginx.org/en/docs/ngx_core_module.html#error_log]

PostgREST+

PGRST_DB_URI

The standard connection PostgreSQL URI format.

PGRST_DB_READ_REPLICAS_URI

A list of connection strings, separated by ,. Read requests (GET) will be directed to one of the read replicas using a round-robin algorithm.

PGRST_DB_SCHEMA

The database schema to expose to REST clients. Tables, views and stored procedures in this schema will get API endpoints.

    db-schema = "api"
You can also specify a list of schemas that can be used for schema-based multitenancy and api versioning

    db-schema = "tenant1, tenant2"

Warning

Never expose private schemas in this way.

PGRST_DB_ANON_ROLE

The database role to use when executing commands on behalf of unauthenticated clients.

PGRST_DB_POOL

Number of connections to keep open in the database pool. Having enough here for the maximum expected simultaneous client connections can improve performance.

PGRST_DB_POOL_TIMEOUT

Time to live, in seconds, for an idle database pool connection. If the timeout is reached the connection will be closed. Once a new request arrives a new connection will be started.

PGRST_DB_EXTRA_SEARCH_PATH

Extra schemas to add to the search_path of every request. These schemas tables, views and stored procedures don't get API endpoints, they can only be referred from the database objects inside your db-schema.

Multiple schemas can be added in a comma-separated string, e.g. public, extensions.

PGRST_DB_CHANNEL

The name of the notification channel to listen to (default pgrst) for schema refresh messages. Executing NOTIFY pgrst, '' will trigger a "schema cache refresh"

PGRST_DB_CHANNEL_ENABLED

A boolean flag (default true) to enable/disable listening on the notifications channel.

PGRST_SERVER_HOST

Where to bind the web server. In addition to the usual address options, PostgREST+ interprets these reserved addresses with special meanings:

  • * - any IPv4 or IPv6 hostname
  • *4 - any IPv4 or IPv6 hostname, IPv4 preferred
  • !4 - any IPv4 hostname
  • *6 - any IPv4 or IPv6 hostname, IPv6 preferred
  • !6 - any IPv6 hostname

Note

in the standard container distribution, where openresty and postgrest+ run in the same container, postgrest+ is configured to listen on a unix socket for improved throughput and security

PGRST_SERVER_PORT

The TCP port to bind the web server.

PGRST_SERVER_UNIX_SOCKET

Unix domain socket where to bind the web server. If specified, this takes precedence over server-port. Example:

server-unix-socket = "/tmp/pgrst.sock"

PGRST_SERVER_UNIX_SOCKET_MODE

Unix file mode to be set for the socket specified in server-unix-socket Needs to be a valid octal between 600 and 777.

server-unix-socket-mode = "660"

PGRST_OPENAPI_SERVER_PROXY_URI

Overrides the base URL used within the OpenAPI self-documentation hosted at the API root path. Use a complete URI syntax scheme:[//[user:password@]host[:port]][/]path[?query][#fragment].

PGRST_JWT_SECRET

The secret or JSON Web Key (JWK) (or set) used to decode JWT tokens clients provide for authentication. For security the key must be at least 32 characters long. If this parameter is not specified then authentication requests will be refused. Choosing a value for this parameter beginning with the at sign such as @filename loads the secret out of an external file. This is useful for automating deployments. Note that any binary secrets must be base64 encoded. Both symmetric and asymmetric cryptography are supported.

PGRST_JWT_AUD

Specifies the JWT audience claim. If this claim is present in the client provided JWT then you must set this to the same value as in the JWT, otherwise verifying the JWT will fail.

PGRST_SECRET_IS_BASE64

When this is set to true, the value derived from jwt-secret will be treated as a base64 encoded secret.

PGRST_MAX_ROWS

A hard limit to the number of rows PostgREST+ will fetch from a view, table, or stored procedure. Limits payload size for accidental or malicious requests.

PGRST_PRE_REQUEST

A schema-qualified stored procedure name to call right after switching roles for a client request. This provides an opportunity to modify SQL variables or raise an exception to prevent the request from completing.

PGRST_APP.SETTINGS.*

Arbitrary settings that can be used to pass in secret keys directly as strings, or via OS environment variables. For instance: app.settings.jwt_secret = "$(MYAPP_JWT_SECRET)" will take MYAPP_JWT_SECRET from the environment and make it available to postgresql functions as current_setting('app.settings.jwt_secret').

PGRST_ROLE_CLAIM_KEY

A JSPath DSL that specifies the location of the role key in the JWT claims. This can be used to consume a JWT provided by a third party service like Auth0, Okta or Keycloak.

# {"postgrest":{"roles": ["other", "author"]}}
# the DSL accepts characters that are alphanumerical or one of "_$@" as keys
role-claim-key = ".postgrest.roles[1]"

# {"https://www.example.com/role": { "key": "author }}
# non-alphanumerical characters can go inside quotes(escaped in the config value)
role-claim-key = ".\"https://www.example.com/role\".key"

PGRST_RAW_MEDIA_TYPES

PGRST_CUSTOM_RELATIONS

Specify additional custom foreign key relations between tables/views when auto-detection does not work

The json format is

[
    ...
    {"schema":"api", "table":"projects", "fkColumns":["client_id"], "fSchema":"api", "fTable":"clients", "pkColumns":["id"]},
    ...
]
Which says api.projects.client_id references api.clients.id

It's possible also to load the json from a file custom-relations = "@custom-relations.json"

PGRST_DB_SAFE_FUNCTIONS

A list of function names separated by , that can be called in the context of the select parameter. By default these are the allowed functions

avg, count, every, max, min, sum, array_agg, json_agg, jsonb_agg, json_object_agg, jsonb_object_agg, string_agg,
corr, covar_pop, covar_samp, regr_avgx, regr_avgy, regr_count, regr_intercept, regr_r2, regr_slope, regr_sxx, regr_sxy, regr_syy,
mode, percentile_cont, percentile_cont, percentile_disc, percentile_disc,
row_number, rank,  dense_rank, cume_dist, percent_rank, first_value, last_value, nth_value,
lower, trim, upper, concat, concat_ws, format, substr

OAuth

OAUTH_SUCCESS_URI

The internal uri to call after a successful login. subZero will make a POST request, with the payload containing the id of the auth provider and the profile of the signed in user

OAUTH_GOOGLE_CLIENT_ID

OAUTH_GOOGLE_CLIENT_SECRET

OAUTH_GOOGLE_AUTHORIZATION_URL

default https://accounts.google.com/o/oauth2/v2/auth

OAUTH_GOOGLE_TOKEN_URL

default https://www.googleapis.com/oauth2/v4/token

OAUTH_GOOGLE_USERINFO_URL

default https://www.googleapis.com/oauth2/v3/userinfo

OAUTH_GOOGLE_SCOPE

default email profile

OAUTH_GITHUB_CLIENT_ID

OAUTH_GITHUB_CLIENT_SECRET

OAUTH_GITHUB_AUTHORIZATION_URL

default https://github.com/login/oauth/authorize

OAUTH_GITHUB_TOKEN_URL

default https://github.com/login/oauth/access_token

OAUTH_GITHUB_USERINFO_URL

default https://api.github.com/user

OAUTH_GITHUB_SCOPE

default user:email

OAUTH_FACEBOOK_CLIENT_ID

OAUTH_FACEBOOK_CLIENT_SECRET

OAUTH_FACEBOOK_AUTHORIZATION_URL

default https://www.facebook.com/v3.2/dialog/oauth

OAUTH_FACEBOOK_TOKEN_URL

default https://graph.facebook.com/v3.2/oauth/access_token

OAUTH_FACEBOOK_USERINFO_URL

default https://graph.facebook.com/v3.2/me

OAUTH_FACEBOOK_SCOPE

default email