Service: PostgREST - EyevinnOSC/community GitHub Wiki
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.
- 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.
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).
| 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.
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;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"}