使用PostgREST的配置教程

使用PostgREST的配置教程

 

配置

PostgREST读取配置文件以确定有关数据库以及如何满足客户端请求的信息。该文件没有预定义的位置，您必须将文件路径指定为服务器的唯一参数：

./postgrest /path/to/postgrest.conf

配置文件必须包含一组键值对。至少您必须包括以下密钥：

# postgrest.conf

# The standard connection URI format, documented at
# https://www.postgresql.org/docs/current/static/libpq-connect.html#AEN45347
db-uri       = "postgres://user:pass@host:5432/dbname"

# The name of which database schema to expose to REST clients
db-schema    = "api"

# The database role to use when no client authentication is provided.
# Can (and should) differ from user in db-uri
db-anon-role = "anon"

在db-uri中指定的用户也称为验证者角色。有关匿名角色与身份验证者角色的更多信息，请参见角色系统概述。

这是配置参数的完整列表。

Name	Type	Default	Required
db-uri	String		Y
db-schema	String		Y
db-anon-role	String		Y
db-pool	Int	10
db-pool-timeout	Int	10
db-extra-search-path	String	public
server-host	String	!4
server-port	Int	3000
server-unix-socket	String
server-proxy-uri	String
jwt-secret	String
jwt-aud	String
secret-is-base64	Bool	False
max-rows	Int	∞
pre-request	String
app.settings.*	String
role-claim-key	String	.role
raw-media-types	String

 

db

标准连接PostgreSQL URI格式。密码或其他字段中的符号和不寻常字符应按百分比编码，以避免解析错误。如果需要强制与数据库建立SSL连接，则可以在URI中使用sslmode，例如postgres://user:pass@host:5432/dbname?sslmode=require。

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

在较旧的系统（如Centos 6）和旧版本的libpq上，必须使用不同的db-uri语法。在这种情况下，URI是由空格分隔的键/值对（key = value）的字符串，因此上面的示例将是。"host=host user=user port=5432 dbname=dbname password=pass"

为该参数选择一个以at符号开头的值，例如@filename（例如@./configs/my-config）会将密钥从外部文件中加载出来。

db

向REST客户端公开的数据库架构。此架构中的表，视图和存储过程将获取API端点。

该模式被添加到每个请求的search_path中。

db-anon

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

db

在PostgREST的数据库池中保持打开状态的连接数。在此处具有足够的数量以实现最大的预期同时客户端连接可以提高性能。请注意，将其设置为高于max_connections数据库中的GUC 是没有意义的。

db-pool

空闲数据库池连接的生存时间（以秒为单位）。如果达到超时，连接将关闭。一旦新的请求到达，新的连接就会开始。

db-extra-search

要添加到每个请求的search_path的额外模式。这些模式表，视图和存储过程没有API端点，只能从db-schema内部的数据库对象引用它们。

此参数旨在使使用db-schema之外的PostgreSQL扩展（例如PostGIS）更加容易。

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

服务器主机

绑定PostgREST Web服务器的位置。除了常用的地址选项外，PostgREST还使用特殊含义解释这些保留的地址：

• * -任何IPv4或IPv6主机名
• *4 -任何IPv4或IPv6主机名，首选IPv4
• !4 -任何IPv4主机名
• *6 -任何IPv4或IPv6主机名，首选IPv6
• !6 -任何IPv6主机名

服务器端口

绑定Web服务器的TCP端口。

服务器-unix

绑定PostgREST Web服务器的Unix域套接字。如果指定，则优先于server-port。例：

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

server-proxy

覆盖在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"
  ]
}

jwt

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

AUD 

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

base64 

设置true为时，从派生的值jwt-secret将被视为base64编码的密码。

MAX

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

预请求

切换客户端请求角色后立即调用的架构限定的存储过程名称。这提供了修改SQL变量或引发异常以阻止请求完成的机会。

app.settings

可以用于直接将秘密密钥作为字符串或通过OS环境变量传递的任意设置。例如：将从环境中获取，并使其可用于postgresql函数。app.settings.jwt_secret = "$(MYAPP_JWT_SECRET)"MYAPP_JWT_SECRETcurrent_setting('app.settings.jwt_secret')

角色声明密钥

role在JWT声明中指定密钥位置的JSPath DSL 。这可用于使用由Auth0，Okta或Keycloak等第三方服务提供的JWT。用法示例：

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

原始介质类型

这用于扩展PostgREST当前通过标头接受的媒体类型Accept。

可以遵循与Binary Output中定义的规则相同的规则来请求这些媒体类型。

例如，下面的配置将允许您分别通过与 和进行请求来请求图像和xml。Accept: image/pngAccept: text/xml

raw-media-types="image/png, text/xml"