配置

配置参数可以通过以下方式提供：

配置文件.
环境变量，覆盖配置文件中的值。
数据库内配置，覆盖配置文件和环境变量中的值。

使用配置重新加载，您可以在不重启服务器的情况下修改参数。

最小参数

服务器可以在没有任何配置参数的情况下启动，但它无法提供请求，除非它有用于处理匿名请求的角色 - 或者用于 JWT 身份验证的密钥。

配置文件

配置文件没有预定义的位置，您必须将文件路径指定为服务器的唯一参数。

./postgrest /path/to/postgrest.conf

配置文件必须包含一组键值对。

# postgrest.conf

# The standard connection URI format, documented at
# https://postgresql.ac.cn/docs/current/libpq-connect.html#LIBPQ-CONNSTRING
db-uri       = "postgres://user:pass@host:5432/dbname"

# The database role to use when no client authentication is provided.
# Should differ from authenticator
db-anon-role = "anon"

# The secret to verify the JWT for authenticated requests with.
# Needs to be 32 characters minimum.
jwt-secret           = "reallyreallyreallyreallyverysafe"
jwt-secret-is-base64 = false

# Port the postgrest process is listening on for http requests
server-port = 3000

您可以运行 postgrest --example 来显示所有可能的配置参数以及如何在配置文件中使用它们。

环境变量

环境变量使用大写字母，带有 PGRST_ 前缀，并使用下划线。例如：PGRST_DB_URI 对应于 db-uri，而 PGRST_APP_SETTINGS_* 对应于 app.settings.*。

libpq 环境变量也支持构建连接字符串，请参阅 db-uri。

请参阅参数列表上的环境变量名称完整列表。

数据库内配置

您也可以使用预配置函数来配置服务器的数据库设置。例如，您可以像这样配置数据库模式和 JWT 密钥

# postgrest.conf

db-pre-config  = "postgrest.pre_config"

# or env vars

PGRST_DB_PRE_CONFIG = "postgrest.pre_config"

-- create a dedicated schema, hidden from the API
create schema postgrest;
-- grant usage on this schema to the authenticator
grant usage on schema postgrest to authenticator;

-- the function can configure postgREST by using set_config
create or replace function postgrest.pre_config()
returns void as $$
  select
      set_config('pgrst.db_schemas', 'schema1, schema2', true)
    , set_config('pgrst.jwt_secret', 'REALLYREALLYREALLYREALLYVERYSAFE', true);
$$ language sql;

请注意，对于数据库内配置参数，需要使用下划线（_）而不是连字符（-）。有关数据库内名称的完整列表，请参阅参数列表。

您可以通过将数据库配置设置为 false 来禁用数据库内配置。

注意

为了向后兼容，您可以通过修改身份验证器角色来进行数据库内配置。但这不再推荐，因为它需要 SUPERUSER 权限。

ALTER ROLE authenticator SET pgrst.db_schemas = "tenant1, tenant2, tenant3"
ALTER ROLE authenticator IN DATABASE <your_database_name> SET pgrst.db_schemas = "tenant4, tenant5" -- database-specific setting, overrides the previous setting

配置重新加载

可以在不重启服务器的情况下重新加载 PostgREST 的配置。您可以通过信号或通知来实现。

对配置文件的任何修改将在重新加载期间应用。
对数据库内配置的任何修改将在重新加载期间应用。
并非所有设置都可重新加载，请参阅参数列表中的可重新加载列表。
无法更改运行进程的环境变量，因此重新加载 Docker 容器配置将不起作用。在这种情况下，您可以重启进程或使用数据库内配置。

使用信号重新加载配置

要通过信号重新加载配置，请向服务器进程发送 SIGUSR2 信号。

killall -SIGUSR2 postgrest

使用 NOTIFY 重新加载配置

要从数据库内重新加载配置，可以使用 NOTIFY 命令。请参阅监听器。

NOTIFY pgrst, 'reload config'

参数列表

admin-server-port

类型

Int

默认值

n/a

可重新加载

N

环境

PGRST_ADMIN_SERVER_PORT

数据库内

n/a

指定管理服务器的端口。

app.settings.*

类型

字符串

默认值

n/a

可重新加载

&

环境

PGRST_APP_SETTINGS_*

数据库内

n/a

任意设置，可用于直接以字符串形式传递密钥，或通过操作系统环境变量传递。例如：app.settings.jwt_secret = "$(MYAPP_JWT_SECRET)" 将从环境中获取 MYAPP_JWT_SECRET，并将其作为 current_setting('app.settings.jwt_secret') 提供给 PostgreSQL 函数。

db-aggregates-enabled

类型

布尔值

默认值

False

可重新加载

Y

环境

PGRST_DB_AGGREGATES_ENABLED

数据库内

pgrst.db_aggregates_enabled

当此设置为 true 时，允许使用聚合函数。

建议将其设置为 false，除非已采取适当的保护措施来防止潜在的性能问题。例如，用户可能会请求一个包含数百万行的表中未索引列的 max()。最好的情况是，这会导致查询速度变慢，最坏的情况是，它可能被滥用以阻止其他用户访问您的 API（即一种拒绝服务攻击）。

适当的保护措施可能包括

使用语句超时。请参阅模拟角色设置。

使用 pg_plan_filter 扩展来阻止过于昂贵的查询。

db-anon-role

类型

字符串

默认值

n/a

可重新加载

Y

环境

PGRST_DB_ANON_ROLE

数据库内

pgrst.db_anon_role

在代表未经身份验证的客户端执行命令时使用的数据库角色。有关更多信息，请参见角色系统概述.

未设置时，匿名访问将被阻止。

db-channel

类型

字符串

默认值

pgrst

可重新加载

Y

环境

PGRST_DB_CHANNEL

数据库内

n/a

PostgREST 用于使用 NOTIFY 重新加载模式缓存和使用 NOTIFY 重新加载配置的通知通道的名称。

db-channel-enabled

类型

布尔值

默认值

True

可重新加载

Y

环境

PGRST_DB_CHANNEL_ENABLED

数据库内

n/a

当此设置为 true 时，将启用在 db-channel 中指定的通知通道。

当使用在事务池模式下工作的外部连接池（例如 PgBouncer）后面的 PostgresSQL 时，应将其设置为 false。有关更多信息，请参见本节。

db-config

类型

布尔值

默认值

True

可重新加载

Y

环境

PGRST_DB_CONFIG

数据库内

n/a

启用数据库内配置。

db-pre-config

类型

字符串

默认值

n/a

可重新加载

Y

环境

PGRST_DB_PRE_CONFIG

数据库内

pgrst.db_pre_config

执行数据库内配置的函数的名称。

db-extra-search-path

类型

字符串

默认值

public

可重新加载

Y

环境

PGRST_DB_EXTRA_SEARCH_PATH

数据库内

pgrst.db_extra_search_path

额外的模式，需要添加到每个请求的 search_path 中。这些模式中的表、视图和函数 **不会生成 API 端点**，它们只能被您 db-schemas 中的数据库对象引用。

此参数旨在简化使用 **PostgreSQL 扩展**（如 PostGIS）的操作，这些扩展位于 db-schemas 之外。

多个模式可以使用逗号分隔的字符串添加，例如 public, extensions。

db-hoisted-tx-settings

类型

字符串

默认值

statement_timeout, plan_filter.statement_cost_limit, default_transaction_isolation

可重新加载

Y

环境

PGRST_DB_HOISTED_TX_SETTINGS

数据库内

pgrst.db_hoisted_tx_settings

允许将提升的设置应用为事务范围的函数设置。多个设置可以使用逗号分隔的字符串添加，例如 work_mem, statement_timeout。

db-max-rows

类型

Int

默认值

∞

可重新加载

Y

环境

PGRST_DB_MAX_ROWS

数据库内

pgrst.db_max_rows

为了向后兼容，此配置参数也可以在没有前缀的情况下使用，例如“max-rows”。

PostgREST 从视图、表或函数中获取的行数的硬性限制。限制意外或恶意请求的有效负载大小。

db-plan-enabled

类型

布尔值

默认值

False

可重新加载

Y

环境

PGRST_DB_PLAN_ENABLED

数据库内

pgrst.db_plan_enabled

当此设置为 true 时，可以使用 Accept: application/vnd.pgrst.plan 标头检索请求的执行计划。请参阅执行计划。

db-pool

类型

Int

默认值

10

可重新加载

N

环境

PGRST_DB_POOL

数据库内

n/a

PostgREST 数据库池中保持打开的最大连接数。

db-pool-acquisition-timeout

类型

Int

默认值

10

可重新加载

N

环境

PGRST_DB_POOL_ACQUISITION_TIMEOUT

数据库内

n/a

指定请求等待池释放数据库连接槽的最大时间（以秒为单位）。

db-pool-max-idletime

类型

Int

默认值

30

可重新加载

N

环境

PGRST_DB_POOL_MAX_IDLETIME

数据库内

n/a

为了向后兼容，此配置参数也可以作为“db-pool-timeout”使用。

关闭空闲池连接的时间（以秒为单位）。

db-pool-max-lifetime

类型

Int

默认值

1800

可重新加载

N

环境

PGRST_DB_POOL_MAX_LIFETIME

数据库内

n/a

指定池中现有连接的最大时间（以秒为单位）。

db-pool-automatic-recovery

类型

布尔值

默认值

True

可重新加载

Y

环境

PGRST_DB_POOL_AUTOMATIC_RECOVERY

数据库内

n/a

启用或禁用连接重试。

禁用后，PostgREST 会在连接丢失后立即终止，而不是无限期重试。有关更多信息，请参见此部分。

db-pre-request

类型

字符串

默认值

n/a

可重新加载

Y

环境

PGRST_DB_PRE_REQUEST

数据库内

pgrst.db_pre_request

为了向后兼容，此配置参数也可以在没有前缀的情况下作为“pre-request”使用。

在设置事务范围设置后立即调用的限定模式函数名称。请参见请求前。

db-prepared-statements

类型

布尔值

默认值

True

可重新加载

Y

环境

PGRST_DB_PREPARED_STATEMENTS

数据库内

pgrst.db_prepared_statements

启用或禁用预备语句。

禁用后，生成的查询将被参数化（不受 SQL 注入影响），但不会被预备（在数据库会话中缓存）。不使用预备语句会显着降低性能，因此建议始终启用此设置。

仅当在使用 PostgresSQL 作为外部连接池（例如在事务池模式下工作的 PgBouncer）时，才应将其设置为 false。有关更多信息，请参见此部分。

db-root-spec

类型

字符串

默认值

n/a

可重新加载

Y

环境

PGRST_DB_ROOT_SPEC

数据库内

pgrst.db_root_spec

用于覆盖 OpenAPI 响应的函数。请参见覆盖完整 OpenAPI 响应。

db-schemas

类型

字符串

默认值

public

可重新加载

Y

环境

PGRST_DB_SCHEMAS

数据库内

pgrst.db_schemas

为了向后兼容，此配置参数也可以在单数形式中作为“db-schema”使用。

要公开给客户端的数据库模式列表。请参见模式。

db-tx-end

类型	字符串
默认值	提交
可重新加载	N
环境	PGRST_DB_TX_END
数据库内	pgrst.db_tx_end

指定如何终止数据库事务。

# The transaction is always committed
db-tx-end = "commit"

# The transaction is committed unless a "Prefer: tx=rollback" header is sent
db-tx-end = "commit-allow-override"

# The transaction is always rolled back
db-tx-end = "rollback"

# The transaction is rolled back unless a "Prefer: tx=commit" header is sent
db-tx-end = "rollback-allow-override"

db-uri

类型

字符串

默认值

postgresql://

可重新加载

N

环境

PGRST_DB_URI

数据库内

n/a

标准的 PostgreSQL 连接字符串，有多种方法可以指定它

URI 格式

"postgres://authenticator:mysecretpassword@localhost:5433/postgres?parameters=val"
在此格式下，密码或其他字段中的符号和非标准字符应进行百分比编码，以避免解析错误。

如果需要强制对数据库进行 SSL 连接，可以使用 sslmode 在 URI 中，例如 postgres://user:pass@host:5432/dbname?sslmode=require。

PostgREST 连接到数据库的用户也被称为 authenticator 角色。有关更多信息，请参见角色系统概述.

当在与 PostgreSQL 相同的机器上运行 PostgREST 时，也可以使用 Unix 套接字和对等身份验证方法连接到数据库，作为 TCP/IP 通信和使用密码进行身份验证的替代方案，这也提供了更高的性能。为此，您可以省略主机和密码，例如 postgres://user@/dbname，有关更多详细信息，请参见 libpq 连接字符串文档。

关键字/值格式

"host=localhost port=5433 user=authenticator password=mysecretpassword dbname=postgres"

LIBPQ 环境变量

PGHOST=localhost PGPORT=5433 PGUSER=authenticator PGDATABASE=postgres
在上述格式中未设置的任何参数都将从 libpq 环境变量中读取。默认连接字符串为 postgresql://，它从环境中读取所有参数。

外部配置文件

选择以“@”符号开头的参数值，例如 @filename（例如 @./configs/my-config）会从外部文件加载连接字符串。

jwt-aud

类型

字符串

默认值

n/a

可重新加载

Y

环境

PGRST_JWT_AUD

数据库内

pgrst.jwt_aud

指定 JWT 观众声明。如果客户端提供的 JWT 中存在此声明，则必须将其设置为与 JWT 中的值相同，否则验证 JWT 将失败。

警告

使用此设置只会拒绝具有不同受众声明的令牌。没有受众声明的令牌仍将被接受。

jwt-role-claim-key

类型

字符串

默认值

.role

可重新加载

Y

环境

PGRST_JWT_ROLE_CLAIM_KEY

数据库内

pgrst.jwt_role_claim_key

为了向后兼容，此配置参数也可以在没有前缀的情况下使用，例如“role-claim-key”。

一个 JSPath DSL，它指定 JWT 声明中 role 键的位置。这可以用来使用由 Auth0、Okta 或 Keycloak 等第三方服务提供的 JWT。使用示例
# {"postgrest":{"roles": ["other", "author"]}}
# the DSL accepts characters that are alphanumerical or one of "_$@" as keys
jwt-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)
jwt-role-claim-key = ".\"https://www.example.com/role\".key"

jwt-secret

类型

字符串

默认值

n/a

可重新加载

Y

环境

PGRST_JWT_SECRET

数据库内

pgrst.jwt_secret

用于解码客户端提供的用于身份验证的 JWT 令牌的密钥或 JSON Web Key (JWK)（或集合）。出于安全原因，密钥必须至少 32 个字符长。如果未指定此参数，则 PostgREST 会拒绝身份验证请求。选择以“@”符号开头的参数值，例如 @filename 会从外部文件加载密钥。这对于自动化部署很有用。请注意，任何二进制密钥都必须进行 Base64 编码。对称和非对称加密都受支持。有关更多信息，请参见非对称密钥。

选择以“@”符号开头的参数值，例如 @filename（例如 @./configs/my-config）会从外部文件加载密钥。

警告

仅当使用配置文件时，如果 jwt-secret 本身包含 $ 字符，则会报错。在这种情况下，请使用 $$，PostgREST 会将其解释为单个 $ 字符。

jwt-secret-is-base64

类型

布尔值

默认值

False

可重新加载

Y

环境

PGRST_JWT_SECRET_IS_BASE64

数据库内

pgrst.jwt_secret_is_base64

当此选项设置为 true 时，从 jwt-secret 派生的值将被视为 Base64 编码的密钥。

jwt-cache-max-lifetime

类型

Int

默认值

0

可重新加载

Y

环境

PGRST_JWT_CACHE_MAX_LIFETIME

数据库内

pgrst.jwt_cache_max_lifetime

缓存条目最大生存时间（秒）。默认值为 0，禁用缓存。请参阅 JWT 缓存。

log-level

类型	字符串
默认值	error
可重新加载	N
环境	PGRST_LOG_LEVEL
数据库内	n/a

指定运行 PostgREST 时要记录的信息级别。

# Only startup and db connection recovery messages are logged
log-level = "crit"

# All the "crit" level events plus server errors (status 5xx) are logged
log-level = "error"

# All the "error" level events plus request errors (status 4xx) are logged
log-level = "warn"

# All the "warn" level events plus all requests (every status code) are logged
log-level = "info"

# All the above plus events for development purposes are logged
# Logs connection pool events and the schema cache parsing time
log-level = "debug"

由于目前日志记录没有缓冲，因此日志记录最少的级别（crit/error）将提高吞吐量。

openapi-mode

类型	字符串
默认值	follow-privileges
可重新加载	Y
环境	PGRST_OPENAPI_MODE
数据库内	pgrst.openapi_mode

指定如何显示 OpenAPI 输出。

# Follows the privileges of the JWT role claim (or from db-anon-role if the JWT is not sent)
# Shows information depending on the permissions that the role making the request has
openapi-mode = "follow-privileges"

# Ignores the privileges of the JWT role claim (or from db-anon-role if the JWT is not sent)
# Shows all the exposed information, regardless of the permissions that the role making the request has
openapi-mode = "ignore-privileges"

# Disables the OpenApi output altogether.
# Throws a `404 Not Found` error when accessing the API root path
openapi-mode = "disabled"

openapi-security-active

类型

布尔值

默认值

False

可重新加载

Y

环境

PGRST_OPENAPI_SECURITY_ACTIVE

数据库内

pgrst.openapi_security_active

当此选项设置为 true 时，安全选项将包含在 OpenAPI 输出中。

openapi-server-proxy-uri

类型

字符串

默认值

n/a

可重新加载

N

环境

PGRST_OPENAPI_SERVER_PROXY_URI

数据库内

pgrst.openapi_server_proxy_uri

覆盖 API 根路径下托管的 OpenAPI 自文档中使用的基本 URL。使用完整的 URI 语法 scheme:[//[user:password@]host[:port]][/]path[?query][#fragment]。例如 https://postgrest.com
{
  "swagger": "2.0",
  "info": {
    "version": "0.4.3.0",
    "title": "PostgREST API",
    "description": "This is a dynamic API generated by PostgREST"
  },
  "host": "postgrest.com:443",
  "basePath": "/",
  "schemes": [
    "https"
  ]
}

server-cors-allowed-origins

类型

字符串

默认值

n/a

可重新加载

N

环境

PGRST_SERVER_CORS_ALLOWED_ORIGINS

数据库内

pgrst.server_cors_allowed_origins

在此配置中指定允许的 CORS 来源。参见 CORS.

当未设置此选项或设置为 "" 时，PostgREST **接受** 来自任何域名的 CORS 请求。

server-host

类型

字符串

默认值

!4

可重新加载

N

环境

PGRST_SERVER_HOST

数据库内

n/a

绑定 PostgREST Web 服务器的位置。除了通常的地址选项外，PostgREST 还将解释这些保留地址，它们具有特殊含义

* - 任何 IPv4 或 IPv6 主机名

*4 - 任何 IPv4 或 IPv6 主机名，优先使用 IPv4

!4 - 任何 IPv4 主机名

*6 - 任何 IPv4 或 IPv6 主机名，优先使用 IPv6

!6 - 任何 IPv6 主机名

server-port

类型

Int

默认值

3000

可重新加载

N

环境

PGRST_SERVER_PORT

数据库内

n/a

绑定 Web 服务器的 TCP 端口。使用 0 自动分配端口。

server-trace-header

类型

字符串

默认值

n/a

可重新加载

Y

环境

PGRST_SERVER_TRACE_HEADER

数据库内

pgrst.server_trace_header

用于跟踪 HTTP 请求的标头名称。参见跟踪标头.

server-timing-enabled

类型

布尔值

默认值

False

可重新加载

Y

环境

PGRST_SERVER_TIMING_ENABLED

数据库内

pgrst.server_timing_enabled

启用 Server-Timing 标头。参见 Server-Timing 标头.

server-unix-socket

类型

字符串

默认值

n/a

可重新加载

N

环境

PGRST_SERVER_UNIX_SOCKET

数据库内

n/a

用于绑定 PostgREST Web 服务器的 Unix 域套接字。如果指定，它将优先于 server-port。示例
server-unix-socket = "/tmp/pgrst.sock"

server-unix-socket-mode

类型

字符串

默认值

660

可重新加载

N

环境

PGRST_SERVER_UNIX_SOCKET_MODE

数据库内

n/a

为在 server-unix-socket 中指定的套接字设置的 Unix 文件模式。需要是 600 到 777 之间的有效八进制数。
server-unix-socket-mode = "660"