教程 0 - 运行它

作者:: begriffs

欢迎来到 PostgREST！在这个预教程中，我们将让一切运行起来，这样你就可以创建你的第一个简单的 API。

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

为了创建一个 API，我们只需构建一个数据库。所有端点和权限都来自数据库对象，例如表、视图、角色和函数。这些教程将涵盖许多常见场景以及如何在数据库中对其进行建模。

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

步骤 1. 放松，我们会帮助你

当你开始本教程时，请在另一个选项卡中打开项目聊天室。项目中有一群活跃的人，如果你遇到困难，我们会帮助你。

步骤 2. 安装 PostgreSQL

如果你已经熟悉使用 PostgreSQL 并在你的系统上安装了它，你可以使用现有的安装（有关最低要求，请参阅支持的 PostgreSQL 版本）。在本教程中，我们将描述如何在 Docker 中使用数据库，因为数据库配置对于简单的教程来说过于复杂。

如果 Docker 未安装，你可以从这里获取它。接下来，让我们拉取并启动数据库镜像

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.

在这种情况下，您需要将两个 5432 中的 **第一个** 更改为其他内容，例如 5433:5432。请记住在步骤 5 中的配置文件中也调整端口！

步骤 3. 安装 PostgREST

使用包管理器

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

您可以从 Homebrew 官方仓库安装 PostgREST。

brew install postgrest

您可以从官方端口安装 PostgREST。

pkg install hs-postgrest

您可以从社区仓库安装 PostgREST。

pacman -S postgrest

您可以从 nixpkgs 安装 PostgREST。

nix-env -i haskellPackages.postgrest

您可以使用 Chocolatey 或 Scoop 安装 PostgREST。

choco install postgrest
scoop install postgrest

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

postgrest -h

它应该打印帮助页面，其中包含其版本和可用选项。

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

PostgREST 也以单个二进制文件的形式分发，其中包含针对 macOS、Windows、Linux 和 FreeBSD 的主要发行版的编译版本。访问最新版本以获取下载列表。如果您使用的平台不在预构建的平台中，请参阅从源代码构建以获取有关如何自行构建它的说明。也请告知我们，以便在下一个版本中添加您的平台。

可供下载的预构建二进制文件是 .tar.xz 压缩文件（Windows 除外，它是一个 zip 文件）。要解压缩二进制文件，请进入终端并运行

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

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

结果将是一个名为 postgrest（或 Windows 上的 postgrest.exe）的文件。此时，尝试使用以下命令运行它

./postgrest -h

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

注意

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

Ubuntu 或 Debian

sudo apt-get install libpq-dev

Fedora、CentOS 或 Red Hat

sudo yum install postgresql-libs

macOS

brew install postgresql

Windows

运行 PostgREST 所需的所有 DLL 文件都包含在 PostgreSQL 服务器的 Windows 安装中。安装后，它们位于 BIN 文件夹中，例如：C:\Program Files\PostgreSQL\10\bin。将此目录添加到您的 PATH 变量中。从管理员命令提示符运行以下命令（当然需要调整实际的 BIN 路径）

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

我们将做的第一件事是为将在 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"

配置文件还有其他选项，但这些是我们需要的全部。如果您没有使用 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

现在它已准备好为 Web 请求提供服务。您可以使用许多不错的图形 API 探索工具，但对于本教程，我们将使用 curl，因为它很可能已安装在您的系统上。打开一个新的终端（保留 PostgREST 正在运行的终端）。尝试对 todos 发出 HTTP 请求。

curl http://localhost:3000/todos

API 回复

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

使用当前的角色权限，匿名请求对 todos 表具有只读访问权限。如果我们尝试添加新的 todo，我们将无法做到。

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 - 金钥匙