教程0-使其运行#

作者:

begriffs

欢迎来到PostgREST！在这篇前教程中，我们将启动程序，这样您就可以创建第一个简单的API。

PostgREST是一个独立的Web服务器，可以将PostgreSQL数据库转换为REST风格的API。它提供基于底层数据库结构定制的API。

../_images/tut0-request-flow.png

要制作一个API，我们只需构建一个数据库。所有终结点和权限都来自数据库对象，如表、视图、角色和函数。这些教程将介绍许多常见场景以及如何在数据库中对它们进行建模。

在本教程结束时，您将拥有一个可用的数据库、PostgREST服务器和一个简单的单用户待办事项列表API。

第一步.放松点，我们会帮忙的#

当您开始本教程时，打开项目 chat room 在另一个选项卡中。有一群很好的人在这个项目中很活跃，如果你陷入困境，我们会帮助你。

步骤2.安装PostgreSQL#

如果您已经熟悉使用PostgreSQL并将其安装在您的系统上，则可以使用现有安装(请参见 支持的PostgreSQL版本 用于最低要求)。在本教程中，我们将介绍如何在Docker中使用数据库，因为对于简单的教程来说，数据库配置太复杂了。

如果没有安装Docker，您可以获取它 here 。接下来，让我们拉入并启动数据库映像：

sudo docker run --name tutorial -p 5432:5432 \
                -e POSTGRES_PASSWORD=notused \
                -d postgres

这将把Docker实例作为守护进程运行，并向主机系统公开端口5432，以便它在系统的其余部分看起来像一个普通的PostgreSQL服务器。

备注

仅当您的计算机上的默认端口上没有其他PostgreSQL实例运行时，这才起作用。如果此端口已在使用中，您将收到类似以下内容的消息：

docker: Error response from daemon: [...]: Bind for 0.0.0.0:5432 failed: port is already allocated.

在这种情况下，您需要更改 first 两个5432中的其他元素，例如 5433:5432 。记住还要在步骤5中调整配置文件中的端口！

步骤3.安装PostgREST#

使用包管理器#

您可以使用操作系统包管理器来安装PostgREST。

可以从以下位置安装PostgREST Homebrew official repo 。

brew install postgrest

然后，尝试使用以下命令运行它：

postgrest -h

它应该打印带有其版本和可用选项的帮助页面。

下载预构建的二进制文件#

PostgREST也是以单一二进制文件的形式分发的，其版本针对MacOS、Windows、Linux和FreeBSD的主要分发版本进行了编译。访问 latest release 获取下载列表。如果您的平台不在已预先构建的平台中，请参见 从源开始构建 获取如何自己构建它的说明。也请让我们知道在下一个版本中添加您的平台。

供下载的预编译二进制文件有 .tar.xz 压缩文件(Windows除外，它是一个压缩文件)。要解压缩二进制文件，请进入终端并运行

# download from https://github.com/PostgREST/postgrest/releases/latest

tar xJf postgrest-<version>-<platform>.tar.xz

结果将是一个名称简单的文件 postgrest (或 postgrest.exe 在Windows上)。此时，尝试使用以下命令运行它

./postgrest -h

如果一切正常，它将打印出它的版本和可用的选项。您可以继续从下载的位置运行此二进制文件，或将其复制到系统目录中，如 /usr/local/bin 这样你就可以在任何目录下运行它了。

备注

PostgREST要求在您的系统上安装PostgreSQL C库libpq。如果没有该库，您将收到类似“加载共享库时出错：libpq.so.5”的错误。以下是如何修复它的方法：

Ubuntu or Debian 
sudo apt-get install libpq-dev
Fedora, CentOS, or Red Hat 
sudo yum install postgresql-libs
macOS 
brew install postgresql
Windows

All of the DLL files that are required to run PostgREST are available in the windows installation of PostgreSQL server. Once installed they are found in the BIN folder, e.g: C:\Program Files\PostgreSQL\10\bin. Add this directory to your PATH variable. Run the following from an administrative command prompt (adjusting the actual BIN path as necessary of course) 

setx /m PATH "%PATH%;C:\Program Files\PostgreSQL\10\bin"

步骤4.为API创建数据库#

连接到容器内部的SQL控制台(Psql)。要执行此操作，请从命令行运行以下命令：

sudo docker exec -it tutorial psql -U postgres

您应该会看到psql命令提示符：

psql (16.2)
Type "help" for help.

postgres=#

我们要做的第一件事是创建一个 named schema 用于将在API中公开的数据库对象。我们可以选择任何我们喜欢的名称，所以“API”怎么样？在启动的psql提示符内执行这条语句和其他SQL语句。

create schema api;

我们的API将有一个端点， /todos ，它将来自一张桌子。

create table api.todos (
  id int primary key generated by default as identity,
  done boolean not null default false,
  task text not null,
  due timestamptz
);

insert into api.todos (task) values
  ('finish tutorial 0'), ('pat self on back');

接下来，创建一个用于匿名Web请求的角色。当请求进入时，PostgREST将切换到数据库中的此角色以运行查询。

create role web_anon nologin;

grant usage on schema api to web_anon;
grant select on api.todos to web_anon;

这个 web_anon 角色有权访问中的内容 api 架构中的行，并读取 todos 桌子。

最好创建用于连接到数据库的专用角色，而不是使用具有高度特权的 postgres 角色。所以我们要这样做，给角色命名 authenticator 并授予它切换到 web_anon 角色：

create role authenticator noinherit login password 'mysecretpassword';
grant web_anon to authenticator;

现在退出psql；是时候启动API了！

\q

步骤5.运行PostgREST#

PostgREST可以使用配置文件告诉它如何连接到数据库。创建文件 tutorial.conf 里面有这个：

db-uri = "postgres://authenticator:mysecretpassword@localhost:5432/postgres"
db-schemas = "api"
db-anon-role = "web_anon"

配置文件有其他 options ，但这就是我们所需要的。如果您使用的不是Docker，请确保您的端口号正确并替换 postgres 使用添加了TODOS表的数据库的名称。

备注

如果您必须在步骤2中调整端口，请记住在此处也调整端口！

现在运行服务器：

# Running postgrest installed from a package manager
postgrest tutorial.conf

# Running postgrest binary
./postgrest tutorial.conf

您应该会看到类似以下内容：

Starting PostgREST 12.0.2...
Attempting to connect to the database...
Connection successful
Listening on port 3000
Config reloaded
Listening for notifications on the pgrst channel
Schema cache loaded

现在，它已经准备好为网络请求提供服务。您可以使用许多很好的图形API探索工具，但在本教程中，我们将使用 curl 因为它很可能已经安装在您的系统上了。打开一个新的终端(使正在运行PostgREST的终端保持打开状态)。尝试对待办事项执行一个HTTP请求。

curl http://localhost:3000/todos

接口回复：

[
  {
    "id": 1,
    "done": false,
    "task": "finish tutorial 0",
    "due": null
  },
  {
    "id": 2,
    "done": false,
    "task": "pat self on back",
    "due": null
  }
]

使用当前角色权限，匿名请求对 todos 桌子。如果我们试图添加一个新的待办事项，我们将无法做到。

curl http://localhost:3000/todos -X POST \
     -H "Content-Type: application/json" \
     -d '{"task": "do bad thing"}'

回复为401未经授权：

{
  "code": "42501",
  "details": null,
  "hint": null,
  "message": "permission denied for table todos"
}

我们有了它，一个位于数据库顶部的基本API！在接下来的教程中，我们将了解如何使用更复杂的用户访问控制以及更多的表和查询来扩展该示例。

现在您已经运行了PostgREST，请尝试下一个教程， 教程1-金钥匙