使用PostgREST的RestAPI操作之安装教程
二进制版本
[ 从发行页面下载 ]
该发行页面具有针对Mac OS X,Windows和多个Linux发行版的预编译二进制文件。解压缩tarball并运行带有--help
标志的二进制文件以查看用法说明:
# Untar the release (available at https://github.com/PostgREST/postgrest/releases/latest)
$ tar Jxf postgrest-[version]-[platform].tar.xz
# Try running it
$ ./postgrest --help
# You should see a usage help message
注意
如果您在Windows上看到这样的对话框,则可能是该pg_config
程序不在系统路径中。
它通常居住在。看到这个文章有关如何修改系统路径。C:\Program Files\PostgreSQL\<version>\bin
PostgreSQL依赖项
要使用PostgREST,您将需要一个基础数据库(需要PostgreSQL 9.5或更高版本)。您可以使用Amazon RDS之类的工具,但在本地安装自己的方法更便宜,而且开发更方便。
在Windows上,除非PostgreSQL二进制文件位于系统路径上,否则PostgREST将无法运行。要测试是否存在这种情况,请从命令行运行pg_config
。您应该看到它输出路径列表。
运行服务器
PostgREST将基本请求日志记录输出到stdout。在SSH会话中运行它时,必须将其与stdout分离,否则它将在会话关闭时终止。最简单的技术是将输出重定向到日志文件或syslog:
ssh foo@example.com \
'postgrest foo.conf </dev/null >/var/log/postgrest.log 2>&1 &'
# another option is to pipe the output into "logger -t postgrest"
泊坞窗
您可以通过以下方式获得官方的PostgREST Docker映像:
docker pull postgrest/postgrest
图像查阅内部/etc/postgrest.conf
文件。要自定义此文件,您可以将替换配置文件安装到容器中,也可以使用环境变量。环境变量将被插入到默认配置文件中。
这些变量与我们的“ 配置”部分中显示的选项匹配,但它们均为大写字母,具有PGRST_
前缀并使用下划线。要获取可用环境变量的列表,请运行以下命令:
docker inspect -f "{{.Config.Env}}" postgrest/postgrest
有两种方式运行PostgREST容器:使用现有的外部数据库或通过docker-compose。
集装箱PostgREST与本地的PostgreSQL
在Docker中运行PostgREST的第一种方法是将其连接到主机上的现有本机数据库。
# Run the server
docker run --rm --net=host -p 3000:3000 \
-e PGRST_DB_URI="postgres://postgres@localhost/postgres" \
-e PGRST_DB_ANON_ROLE="postgres" \
postgrest/postgrest
上面的数据库连接字符串只是一个示例。根据需要调整角色和密码。您可能需要编辑PostgreSQL pg_hba.conf
来授予用户本地登录访问权限。
注意
Mac上的Docker不支持该--net=host
标志。相反,您需要为主机创建IP地址别名。来自容器内部的IP地址请求无法解析,并由主机还原为解析状态。
sudo ifconfig lo0 10.0.0.10 alias
然后,应使用10.0.0.10作为数据库连接字符串中的主机。还要记住listen_address
在postgresql.conf中包含IP地址。例如:
listen_addresses = 'localhost,10.0.0.10'
您可能还需要在pg_hba.conf中添加一个新的IPv4本地连接。例如:
host all all 10.0.0.10/32 trust
带有docker -compose的容器化PostgREST 和数据库
为了避免完全安装数据库,您可以在容器中运行它和服务器,并使用docker-compose将它们链接在一起。使用以下配置:
# docker-compose.yml
version: '3'
services:
server:
image: postgrest/postgrest
ports:
- "3000:3000"
links:
- db:db
environment:
PGRST_DB_URI: postgres://app_user:password@db:5432/app_db
PGRST_DB_SCHEMA: public
PGRST_DB_ANON_ROLE: app_user #In production this role should not be the same as the one used for the connection
depends_on:
- db
db:
image: postgres
ports:
- "5432:5432"
environment:
POSTGRES_DB: app_db
POSTGRES_USER: app_user
POSTGRES_PASSWORD: password
# Uncomment this if you want to persist the data.
# volumes:
# - "./pgdata:/var/lib/postgresql/data"
进入保存此文件的目录并运行。您将看到数据库和PostgREST的日志,并能够在端口3000上访问后者。docker-compose up
如果要在浏览器中直观地查看API,可以将swagger-ui添加到您的docker-compose.yml
:
swagger:
image: swaggerapi/swagger-ui
ports:
- "8080:8080"
expose:
- "8080"
environment:
API_URL: http://localhost:3000/
这样,您就可以在浏览器的8080端口上看到swagger-ui。
部署到Heroku的
假设您在本地进行修改,然后推送到GitHub,则很容易将其部署到Heroku。
- 在Heroku上创建一个新应用
- 在设置中添加以下buildpack
https://github.com/PostgREST/postgrest-heroku
- 在Heroku中添加require Config Vars(有关更多详细信息,请参见https://github.com/PostgREST/postgrest/blob/master/app.json#L7-L57)
- 根据需要修改postgrest.conf文件以匹配Heroku中的Config Vars
- 创建您的
Procfile
并添加./env-to-config ./postgrest postgrest.conf
- 将您的更改推送到GitHub
- 将Heroku设置为从Master自动部署,然后为第一个构建手动部署分支
从源代码编译
注意
我们建议不要在Alpine Linux上构建和使用PostgREST,因为据报道该平台上存在GHC内存泄漏。
如果系统不存在预构建的二进制文件,则可以从源代码构建项目。如果您想帮助开发,则还需要执行此操作。堆叠使之变得容易。它将在系统上安装任何必要的Haskell依赖项。
-
为您的平台安装Stack
-
安装库依赖关系
操作系统 依存关系 Ubuntu / Debian的 libpq-dev,libgmp-dev CentOS / Fedora / Red Hat PostgreSQL开发,zlib开发,gmp开发 BSD postgresql95客户端 OS X libpq,gmp -
生成并安装二进制文件
git clone https://github.com/PostgREST/postgrest.git cd postgrest # adjust local-bin-path to taste stack build --install-ghc --copy-bins --local-bin-path /usr/local/bin
注意
如果构建失败,并且系统内存不足1GB,请尝试添加交换文件。
- 检查服务器是否已安装:。
postgrest --help
PostgREST测试套件
创建测试数据库
要正确运行postgrest测试,需要创建一个数据库。要做到这一点,使用测试创建脚本create_test_database
中test/
的文件夹。
该脚本需要以下参数:
test/create_test_db connection_uri database_name [test_db_user] [test_db_user_password]
使用连接URI指定用户,密码,主机和端口。不要在连接URI中提供数据库。您用于连接的PostgreSQL角色必须能够创建新数据库。
的database_name
是,该数据库的名称将连接到。如果服务器上已经存在相同名称的数据库,则脚本将首先删除它,然后重新创建它。stack test
(可选)指定数据库用户将使用。每次测试运行后,都将向用户授予必要的权限以重置数据库。stack test
如果未指定用户,则脚本将生成postgrest_test_
以所选数据库名称为后缀的角色名称,并为其生成随机密码。
可选地,如果指定要用于测试连接的现有用户,则可以指定该用户具有的密码。
该脚本将返回要在测试中使用的db uri –此uri对应db-uri
于配置文件中将在生产环境中使用的参数。
生成用户和密码允许用户创建数据库并针对任何PostgreSQL服务器运行测试,而无需对该服务器进行任何修改。(例如,允许没有密码的帐户或设置信任身份验证,或要求服务器位于运行测试的同一本地主机上)。
运行测试
要运行测试,必须在环境变量中提供数据库uri POSTGREST_TEST_CONNECTION
。
通常,将使用postgres超级用户创建数据库并在同一命令行中运行测试:
POSTGREST_TEST_CONNECTION=$(test/create_test_db "postgres://postgres:pwd@database-host" test_db) stack test
为了在同一数据库上重复运行,应导出连接变量:
export POSTGREST_TEST_CONNECTION=$(test/create_test_db "postgres://postgres:pwd@database-host" test_db)
stack test
stack test
...
如果环境变量为空或未指定,那么测试运行程序将默认为连接uri
postgres://postgrest_test@localhost/postgrest_test
此连接假定localhost:code:
用户为postgrest_test的测试服务器上没有密码,并且数据库名称相同。
销毁数据库
测试后,测试数据库将保留,并且在PostgreSQL服务器上创建了四个新角色。要永久删除创建的数据库和角色,请test/delete_test_database
使用用于创建数据库的相同超级用户角色运行脚本:
test/destroy_test_db connection_uri database_name
使用Docker进行测试
连接到非本地PostgreSQL的能力简化了测试设置。一种优雅的测试方法是在docker中使用一次性PostgreSQL。
例如,如果本地开发是在装有Docker for Mac的Mac上:
$ docker run --name db-scripting-test -e POSTGRES_PASSWORD=pwd -p 5434:5432 -d postgres
$ POSTGREST_TEST_CONNECTION=$(test/create_test_db "postgres://postgres:pwd@localhost:5434" test_db) stack test
此外,如果创建了一个docker容器来运行堆栈测试(在GHC低于8.0.1的Mac OS Sierra上,这是必需的(失败),则可以在单独的链接容器中运行PostgreSQL,或使用本地安装的PostgreSQL应用。stack test
用以下命令构建测试容器test/Dockerfile.test
:
$ docker build -t pgst-test - < test/Dockerfile.test
$ mkdir .stack-work-docker ~/.stack-linux
在缓存依赖项时,测试容器的第一次运行将花费很长时间。创建~/.stack-linux
文件夹并将其作为卷映射到容器中可确保我们可以在一次性模式下运行该容器,而不必担心后续运行缓慢。.stack-work-docker
也被映射到容器中,并且在使用Linux中的堆栈时必须指定它,以免干扰.stack-work
本地开发。(在Sierra上有效,而在GHC 8.0.1上无效)。stack build
stack test
链接的容器:
$ docker run --name pg -e POSTGRES_PASSWORD=pwd -d postgres
$ docker run --rm -it -v `pwd`:`pwd` -v ~/.stack-linux:/root/.stack --link pg:pg -w="`pwd`" -v `pwd`/.stack-work-docker:`pwd`/.stack-work pgst-test bash -c "POSTGREST_TEST_CONNECTION=$(test/create_test_db "postgres://postgres:pwd@pg" test_db) stack test"
在Mac上的Docker for Mac和Mac上的PostgreSQL应用程序中进行堆栈测试:
$ host_ip=$(ifconfig en0 | grep 'inet ' | cut -f 2 -d' ')
$ export POSTGREST_TEST_CONNECTION=$(test/create_test_db "postgres://postgres@$HOST" test_db)
$ docker run --rm -it -v `pwd`:`pwd` -v ~/.stack-linux:/root/.stack -v `pwd`/.stack-work-docker:`pwd`/.stack-work -e "HOST=$host_ip" -e "POSTGREST_TEST_CONNECTION=$POSTGREST_TEST_CONNECTION" -w="`pwd`" pgst-test bash -c "stack test"
$ test/destroy_test_db "postgres://postgres@localhost" test_db