Service: PostgREST - EyevinnOSC/community GitHub Wiki

PostgREST

PostgREST (serviceId postgrest-postgrest) is a standalone web server that turns a PostgreSQL database directly into a RESTful API. The structure and permissions of the database determine the API endpoints and operations. In Eyevinn Open Source Cloud (OSC) it is a long-running service instance. License: MIT. Source: PostgREST/postgrest.

What it can do

  • Expose tables and views of the schemas you choose as REST endpoints without writing backend code.
  • Enforce access with PostgreSQL roles: requests without a valid JWT run as the anonymous role, so GRANTs on that role define what unauthenticated clients may do.
  • Serve as the data API for applications on top of an OSC PostgreSQL instance.

Creating an instance

Create the database first and confirm it is running: a PostgreSQL instance (serviceId birme-osc-postgresql). Use describe-service-instance on it to get its address and port, so the URI is postgres://postgres:<password>@<IP>:<PORT>/postgres. Connect with psql and prepare the database (see "Prepare the database" below).

Store the connection URI of the dedicated role as a service secret: create-service-secret with serviceId: "postgrest-postgrest", name dburl, value postgres://authenticator:<password>@<IP>:<PORT>/postgres. Then call create-service-instance with serviceId: "postgrest-postgrest":

{
  "name": "guide",
  "DbUri": "{{secrets.dburl}}",
  "DbAnonRole": "web_anon",
  "DbSchemas": "api"
}

Verify with wait-for-service-ready or get-instance-status; describe-service-instance gives the URL (of the form https://<tenant>-<name>.postgrest-postgrest.auto.prod-se.osaas.io).

Options

Option Required Type Meaning
name Yes string Name of the instance. Alphanumeric/underscore only (^\w+$), at most 20 characters.
DbUri Yes string, sensitive PostgreSQL connection string PostgREST uses to reach the database (upstream PGRST_DB_URI), for example postgresql://user:password@host:5432/dbname. Not reloadable at runtime. Store as a secret and pass {{secrets.NAME}}.
DbAnonRole No string Database role PostgREST switches to for requests without a valid JWT (upstream PGRST_DB_ANON_ROLE). It is the permission boundary for unauthenticated clients, so give it minimal privileges. If unset, anonymous access is blocked.
DbSchemas No string Comma-separated list of database schemas exposed through the REST API (upstream PGRST_DB_SCHEMAS, upstream default public), for example public,api.

{{secrets.NAME}} only works as the entire field value. Overwriting a secret does not restart a running instance.

Prepare the database

Run these in psql against the PostgreSQL instance (psql -h <IP> -p <PORT> -U postgres).

Create a named schema for the objects to expose, and an example table:

create schema api;

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');

Create the role used for anonymous requests; PostgREST switches into it to run queries:

create role web_anon nologin;

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

Create a dedicated login role for PostgREST instead of using the highly privileged postgres role, and let it switch to web_anon:

create role authenticator noinherit login password '<password>';
grant web_anon to authenticator;

Using the instance

Request the todos:

% curl https://<instance-url>/todos
[{"id":1,"done":false,"task":"finish tutorial 0","due":null},
 {"id":2,"done":false,"task":"pat self on back","due":null}]

With these permissions anonymous requests are read-only. Writing is rejected:

% curl -X POST -H 'Content-Type: application/json' \
  -d '{"task": "do bad thing"}' \
  https://<instance-url>/todos
{"code":"42501","details":null,"hint":null,"message":"permission denied for table todos"}

Resources

⚠️ **GitHub.com Fallback** ⚠️