配置#

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

vbl.使用 配置重新加载 您可以修改参数，而无需重新启动服务器。

最小参数#

服务器可以在没有任何配置参数的情况下启动，但如果没有配置参数，则无法为请求提供服务 a role to serve anonymous requests with -或 a secret to use for JWT authentication 。

配置文件#

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

./postgrest /path/to/postgrest.conf

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

# postgrest.conf

# The standard connection URI format, documented at
# https://www.postgresql.org/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 environment variables 也支持构造连接字符串，请参见 Db-uri 。

上查看环境变量名称的完整列表 参数列表 。

数据库内配置#

还可以使用数据库设置来配置服务器 pre-config 功能。例如，您可以配置 DB-架构 和 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 。

备注

为了向后兼容，您可以通过修改 authenticator role 。不再建议这样做，因为它需要超级用户。

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的配置。你可以做到的 via signal 或 via notification 。

  • 对 配置文件 将在重新加载期间应用。

  • 对 数据库内配置 将在重新加载期间应用。

  • 并非所有设置都可重新加载，请参阅上的可重新加载列表 参数列表 。

  • 是不可能改变的 环境变量 对于正在运行的进程，因此重新加载Docker容器配置将不起作用。在这些情况下，您可以重新启动该过程或使用 数据库内配置 。

使用信号重新加载配置#

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

killall -SIGUSR2 postgrest

使用通知重新加载配置#

要从数据库中重新加载配置，可以使用NOTIFY命令。

NOTIFY pgrst, 'reload config'

这个 "pgrst" 默认情况下启用通知通道。您可以使用以下命令命名频道 DB-通道 并使用以下命令启用或禁用它 数据库通道已启用 。

参数列表#

管理-服务器-端口#

Type

整型

Default

n/a

Reloadable

N

Environment

PGRST_ADMIN_SERVER_PORT

In-Database

n/a

指定的端口 运行状况检查 终端。

app.settings.*#

Type

细绳

Default

n/a

Reloadable

&

Environment

PGRST_APP_SETTINGS_*

In-Database

n/a

可用于直接作为字符串或通过OS环境变量传递密钥的任意设置。例如： app.settings.jwt_secret = "$(MYAPP_JWT_SECRET)" 将耗费 MYAPP_JWT_SECRET 并使其可用于PostgreSQL函数 current_setting('app.settings.jwt_secret') 。

数据库-已启用聚合#

Type

布尔型

Default

错误

Reloadable

Y

Environment

PGRST_DB_AGGREGATES_ENABLED

In-Database

pgrst.db_aggregates_enabled

如果将其设置为 true ，使用 聚合函数 是被允许的。

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

适当的保障措施可包括：

DB-anon-角色#

Type

细绳

Default

n/a

Reloadable

Y

Environment

PGRST_DB_ANON_ROLE

In-Database

pgrst.db_anon_role

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

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

DB-通道#

Type

细绳

Default

程序

Reloadable

Y

Environment

PGRST_DB_CHANNEL

In-Database

n/a

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

数据库通道已启用#

Type

布尔型

Default

千真万确

Reloadable

Y

Environment

PGRST_DB_CHANNEL_ENABLED

In-Database

n/a

如果将其设置为 true 中指定的通知通道 DB-通道 已启用。

您应该将其设置为 false 在外部连接池(如在事务池模式下工作的PgBouner)后面使用PostgresSQL时。看见 this section 以获取更多信息。

数据库配置#

Type

布尔型

Default

千真万确

Reloadable

Y

Environment

PGRST_DB_CONFIG

In-Database

n/a

启用数据库内配置。

数据库-预配置#

Type

细绳

Default

n/a

Reloadable

Y

Environment

PGRST_DB_PRE_CONFIG

In-Database

pgrst.db_pre_config

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

数据库额外搜索路径#

Type

细绳

Default

公共的

Reloadable

Y

Environment

PGRST_DB_EXTRA_SEARCH_PATH

In-Database

pgrst.db_extra_search_path

要添加到 search_path 每一个请求。这些架构表、视图和函数 don't get API endpoints ，它们只能从您的 DB-架构 。

此参数旨在使其更易于使用 PostgreSQL extensions (如PostGIS)位于 DB-架构 。

可以在逗号分隔的字符串中添加多个架构，例如 public, extensions 。

数据库最大行数#

Type

整型

Default

∞

Reloadable

Y

Environment

PGRST_DB_MAX_ROWS

In-Database

pgrst.db_max_rows

For backwards compatibility, this config parameter is also available without prefix as "max-rows".

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

数据库-计划已启用#

Type

布尔型

Default

错误

Reloadable

Y

Environment

PGRST_DB_PLAN_ENABLED

In-Database

pgrst.db_plan_enabled

如果将其设置为 true 方法检索请求的执行计划 Accept: application/vnd.pgrst.plan 标题。看见 执行计划 。

数据库池#

Type

整型

Default

10

Reloadable

N

Environment

PGRST_DB_POOL

In-Database

不适用

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

DB-POOL-获取-超时#

Type

整型

Default

10

Reloadable

N

Environment

PGRST_DB_POOL_ACQUISITION_TIMEOUT

In-Database

n/a

指定请求等待池释放数据库连接插槽的最长时间(以秒为单位)。

数据库池最大空闲时间#

Type

整型

Default

30

Reloadable

N

Environment

PGRST_DB_POOL_MAX_IDLETIME

In-Database

n/a

For backwards compatibility, this config parameter is also available as “db-pool-timeout”.

关闭空闲池连接的时间(秒)。

数据库池最长生存期#

Type

整型

Default

1800

Reloadable

N

Environment

PGRST_DB_POOL_MAX_LIFETIME

In-Database

n/a

指定池中现有连接的最长时间(以秒为单位)。

数据库池-自动-恢复#

Type

布尔型

Default

千真万确

Reloadable

Y

Environment

PGRST_DB_POOL_AUTOMATIC_RECOVERY

In-Database

n/a

启用或禁用连接重试。

如果禁用，PostgREST将在连接中断后立即终止，而不是无限期重试。看见 this section 以获取更多信息。

数据库-请求前#

Type

细绳

Default

n/a

Reloadable

Y

Environment

PGRST_DB_PRE_REQUEST

In-Database

pgrst.db_pre_request

For backwards compatibility, this config parameter is also available without prefix as "pre-request".

调用的架构限定函数名。 事务作用域设置 都准备好了。看见 预请求 。

DB-准备好的语句#

Type

布尔型

Default

千真万确

Reloadable

Y

Environment

PGRST_DB_PREPARED_STATEMENTS

In-Database

pgrst.db_prepared_statements

启用或禁用预准备语句。

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

您应该仅将其设置为 false 在外部连接池(如在事务池模式下工作的PgBouner)后面使用PostgresSQL时。看见 this section 以获取更多信息。

数据库根规范#

Type

细绳

Default

n/a

Reloadable

Y

Environment

PGRST_DB_ROOT_SPEC

In-Database

pgrst.db_root_spec

函数覆盖OpenAPI响应。看见 覆盖完整的OpenAPI响应 。

DB-架构#

Type

细绳

Default

公共的

Reloadable

Y

Environment

PGRST_DB_SCHEMAS

In-Database

pgrst.db_schemas

For backwards compatibility, this config parameter is also available in singular as "db-schema".

要向客户端公开的数据库架构列表。看见 模式 。

DB-TX-END#

Type

细绳

Default

提交

Reloadable

N

Environment

PGRST_DB_TX_END

In-Database

n/a

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

# 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#

Type

细绳

Default

PostgreSQL：//

Reloadable

N

Environment

PGRST_DB_URI

In-Database

n/a

标准 PostgreSQL connection string ，有不同的方式来指定它：

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 socket 以及 Peer Authentication method 作为使用密码进行TCP/IP通信和身份验证的替代方案，这也提供了更高的性能。要这样做，您可以省略主机和密码，例如 postgres://user@/dbname ，请参阅 libpq connection string 文档以了解更多详细信息。

关键字/值格式#

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

LIBPQ环境变量#

PGHOST=localhost PGPORT=5433 PGUSER=authenticator PGDATABASE=postgres

任何未以上述格式设置的参数都将从 libpq environment variables 。默认连接字符串为 postgresql:// ，其内容为 all 来自环境的参数。

外部配置文件#

为此参数选择一个以at符号开头的值，例如 @filename (例如： @./configs/my-config )从外部文件加载连接字符串。

JWT-澳元#

Type

细绳

Default

n/a

Reloadable

Y

Environment

PGRST_JWT_AUD

In-Database

pgrst.jwt_aud

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

警告

使用此设置只会拒绝具有不同受众声明的令牌。代币 without 观众申领仍将被接受。

JWT-角色-声明-密钥#

Type

细绳

Default

.角色

Reloadable

Y

Environment

PGRST_JWT_ROLE_CLAIM_KEY

In-Database

pgrst.jwt_role_claim_key

For backwards compatibility, this config parameter is also available without prefix as "role-claim-key".

JSPath DSL，它指定 role 输入JWT的索赔。这可以用来消费由第三方服务提供的JWT，如Auth0、Okta或Keyloak。使用示例：

# {"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-机密#

Type

细绳

Default

n/a

Reloadable

Y

Environment

PGRST_JWT_SECRET

In-Database

pgrst.jwt_secret

秘诀还是 JSON Web Key (JWK) (or set) 用于解码客户端提供身份验证的JWT令牌。为安全起见，密钥必须为 at least 32 characters long 。如果未指定此参数，则PostgREST拒绝身份验证请求。为此参数选择一个以at符号开头的值，例如 @filename 从外部文件加载机密。这对于自动化部署非常有用。请注意，任何二进制密码都必须采用Base64编码。支持对称和非对称加密。有关更多信息，请参阅 非对称密钥 。

为此参数选择一个以at符号开头的值，例如 @filename (例如： @./configs/my-config )从外部文件加载秘密。

警告

仅当使用 配置文件 ，如果 jwt-secret 包含一个 $ 性格本身就会产生错误。在这种情况下，使用 $$ 而PostgREST会将其解释为一首 $ 性格。

JWT-Secure-is-Base64#

Type

布尔型

Default

错误

Reloadable

Y

Environment

PGRST_JWT_SECRET_IS_BASE64

In-Database

pgrst.jwt_secret_is_base64

如果将其设置为 true ，派生自的值 jwt-secret 将被视为Base64编码的机密。

JWT-缓存-最长生存时间#

Type

整型

Default

0

Reloadable

Y

Environment

PGRST_JWT_CACHE_MAX_LIFETIME

In-Database

pgrst.jwt_cache_max_lifetime

缓存条目的最大生存期秒数。默认设置 0 禁用缓存。看见 JWT缓存 。

日志级#

Type

细绳

Default

错误

Reloadable

N

Environment

PGRST_LOG_LEVEL

In-Database

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"

因为目前没有用于日志记录的缓冲，所以日志记录最少的级别 (crit/error )将增加吞吐量。

Openapi-模式#

Type

细绳

Default

追随特权

Reloadable

Y

Environment

PGRST_OPENAPI_MODE

In-Database

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-安全-活动#

Type

布尔型

Default

错误

Reloadable

Y

Environment

PGRST_OPENAPI_SECURITY_ACTIVE

In-Database

pgrst.openapi_security_active

如果将其设置为 true 、安全选项包含在 OpenAPI output 。

Openapi-服务器-代理-uri#

Type

细绳

Default

n/a

Reloadable

N

Environment

PGRST_OPENAPI_SERVER_PROXY_URI

In-Database

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"
  ]
}

服务器-CORS-允许的来源#

Type

细绳

Default

n/a

Reloadable

N

Environment

PGRST_SERVER_CORS_ALLOWED_ORIGINS

In-Database

pgrst.server_cors_allowed_origins

指定此配置中允许的CORS来源。看见 CORS 。

如果未将其设置或设置为 "" ，PostgREST accepts 来自任何域的CORS请求。

服务器-主机#

Type

细绳

Default

4

Reloadable

N

Environment

PGRST_SERVER_HOST

In-Database

n/a

在何处绑定PostgREST Web服务器。除了通常的地址选项外，PostgREST还解释这些具有特殊含义的保留地址：

  • * -任何IPv4或IPv6主机名

  • *4 -任何IPv4或IPv6主机名，优先选择IPv4

  • !4 -任何IPv4主机名

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

  • !6 -任何IPv6主机名

服务器端口#

Type

整型

Default

3000

Reloadable

N

Environment

PGRST_SERVER_PORT

In-Database

n/a

用于绑定Web服务器的TCP端口。使用 0 要自动分配端口，请执行以下操作。

服务器跟踪标头#

Type

细绳

Default

n/a

Reloadable

Y

Environment

PGRST_SERVER_TRACE_HEADER

In-Database

pgrst.server_trace_header

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

启用服务器计时#

Type

布尔型

Default

错误

Reloadable

Y

Environment

PGRST_SERVER_TIMING_ENABLED

In-Database

pgrst.server_timing_enabled

启用 Server-Timing 标题。看见 服务器计时头 。

服务器-Unix-Socket#

Type

细绳

Default

n/a

Reloadable

N

Environment

PGRST_SERVER_UNIX_SOCKET

In-Database

n/a

Unix domain socket 在何处绑定PostgREST Web服务器。如果指定，则优先于 服务器端口 。示例：

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

服务器-Unix-Socket-模式#

Type

细绳

Default

660

Reloadable

N

Environment

PGRST_SERVER_UNIX_SOCKET_MODE

In-Database

n/a

Unix file mode 中指定的套接字设置 服务器-Unix-Socket 需要是介于600和777之间的有效八进制数。

server-unix-socket-mode = "660"