pgkiln 0.47.0 → 0.49.0

package/docs/guide/13-rest-api.md

@@ -1,17 +1,17 @@
 # 13. REST APIs
 
-pgkiln offers two ways to expose data securely over REST (mobile apps, integrations, scripts),
+pgkiln offers three ways to expose data securely over REST (mobile apps, integrations, scripts),
 which can be combined:
 
-| | [REST modules](#rest-modules-in-the-builder) | [PostgREST](#how-it-works) |
-|---|---|---|
-| What | Endpoints you define in the builder: a method, a path and the SQL | A separate service that turns a schema of views and functions into an API |
-| Served by | pgkiln itself, under `/a/<alias>/rest/<module>/` | PostgREST, next to pgkiln |
-| Runs as | the application's database role (like its pages) | a dedicated API role |
-| Good for | a handful of tailored endpoints, field apps, integrations | broad data access with filtering, sorting and embedding |
+| | [REST modules](#rest-modules-in-the-builder) | [AutoREST](#autorest-tables-and-views-from-the-sql-workshop) | [PostgREST](#how-it-works) |
+|---|---|---|---|
+| What | Endpoints you define in the builder: a method, a path and the SQL | A table or view published as it is: rows, one row, insert, update, delete | A separate service that turns a schema of views and functions into an API |
+| Served by | pgkiln itself, under `/a/<alias>/rest/<module>/` | pgkiln itself, under `/a/<alias>/autorest/<object>/` | PostgREST, next to pgkiln |
+| Runs as | the application's database role (like its pages) | the application's database role | a dedicated API role |
+| Good for | a handful of tailored endpoints, field apps, integrations | quick CRUD access to a table, prototypes, simple integrations | broad data access with filtering, sorting and embedding |
 
-Both use the same tokens (App → REST API: tokens and OAuth clients), the same accounts and the
-same row level security, and both publish an OpenAPI description.
+All three use the same tokens (App → REST API: tokens and OAuth clients), the same accounts and the
+same row level security, and all publish an OpenAPI description.
 
 ## REST modules in the builder
 
@@ -31,11 +31,12 @@ answer 404.
 |---|---|
 | `method` | `GET`, `POST`, `PUT`, `PATCH` or `DELETE` |
 | `path` | Segments with `:parameters`, e.g. `orders/:id/lines` |
-| `type` | `collection`: a SELECT, returned page by page as `{items, offset, limit, has_more}` (`?limit=` up to 500, `?offset=`, `page_size` for the default); the page streams from a cursor as a chunked JSON array (an error before the first rows is still a 4xx/5xx, a failure after them ends the response short) · `item`: one row as an object, 404 when there is none · `sql`: statements; the first row of the last one is the response (201 for POST, 204 without a row; `status` overrides) |
+| `type` | `collection`: a SELECT, returned page by page as `{items, offset, limit, has_more}` (`?limit=` up to 500, `?offset=`, `page_size` for the default); the page streams from a cursor as a chunked JSON array (an error before the first rows is still a 4xx/5xx, a failure after them ends the response short) · `item`: one row as an object, 404 when there is none · `sql`: statements; the first row of the last one is the response (201 for POST, 204 without a row; `status` overrides) · `plpgsql` (sprint 104): a PL/pgSQL block that answers with `meta.rest_reply(body, status)` ([below](#modules-templates-and-handlers-in-the-sql-workshop)) · `media`: a query whose row has `content_type`, `content` and optionally `filename`, sent as that content |
 | `source` | The SQL. Binds: path parameters, query parameters and the fields of a JSON (or form) body, upper case (`:ID`, `:CUSTOMER`); `:BODY` is the whole JSON body. `:APP_USER` (the caller), `:APP_ID` and `:APP_ALIAS` are set by the server: a parameter of that name (or `APP_SESSION`, `APP_PAGE_ID`, `REQUEST`, `APP_LANGUAGE`) is ignored, and can't be a path parameter |
 | `roles` | The caller needs one of these roles (as `meta.has_role()` sees them) |
 | `auth` | `token` (default) or `public` (no token; the SQL runs with `meta.app_user()` = `nobody`) |
 | `description` | For the OpenAPI description |
+| `params` | (sprint 104) Documented parameters: `[{"name": "start_date", "in": "body", "type": "string", "required": true, "description": "…"}]` (`in`: `query` or `body`; types `string`, `integer`, `number`, `boolean`). They go into the OpenAPI document; a required one that is missing or empty answers 400 |
 
 **Calling them.** Send `Authorization: Bearer <token>` with a token from **App → REST API**: a token
 issued for an account, or one from `POST /oauth/token` for an OAuth client ([below](#tokens)). An
@@ -63,6 +64,128 @@ curl -X POST http://127.0.0.1:3100/a/hr/rest/v1/leave -H "Authorization: Bearer
      -H "Content-Type: application/json" -d '{"start_date": "2027-05-03", "end_date": "2027-05-04", "reason": "dentist"}'
 ```
 
+## Modules, templates and handlers in the SQL Workshop
+
+**SQL Workshop → RESTful Services → Modules** (sprint 104; Oracle Database Actions / ORDS: REST › Modules) edits
+the same REST modules the ORDS way, for every application of the workspace:
+
+- a **module** is a base path, `/a/<alias>/rest/<name>/`, with a title, a description, *Enabled* and its
+  **privilege**: application roles (as `meta.has_role()` sees them) of which a caller needs one for *every*
+  handler of the module, public ones included;
+- a **template** is a URI below it with `:parameters`, e.g. `emp/:id`, with a description for the OpenAPI document
+  (a template can exist before its first handler; renaming it moves its handlers);
+- a **handler** answers one method of a template: its source type (*collection query*, *single row*, *SQL*,
+  *PL/pgSQL*, *media*), the source, who may call it (a token, or explicitly *public*), further roles, the page size
+  or status, and documented parameters, one per line: `start_date body string required First day`.
+
+The tree on the left of each page shows module › templates › handlers. A Run only or locked application refuses
+changes. The module's page checks the role the handlers run as and links the module's **OpenAPI** document.
+
+**PL/pgSQL handlers** run their block as a `DO` statement as the application's database role. A `DO` block takes
+no parameters, so pgkiln sets the request's binds as transaction-local settings (with query parameters: values
+never become SQL text) and turns `:NAME` in the block into `meta.rest_param('NAME')` (text, NULL when absent):
+
+```sql
+declare
+  v_id int;
+begin
+  v_id := sales.create_order(:CUSTOMER, :TOTAL::numeric);
+  perform meta.rest_reply(jsonb_build_object('id', v_id), 201);
+end
+```
+
+`meta.rest_reply(body jsonb, status int)` sets the response (status 200–599, also 4xx for your own errors; the
+transaction is still committed); without it the handler answers 204. A `raise exception` answers 400 with its
+message and rolls back. Statements without `begin … end` are wrapped in one.
+
+**Media handlers** run a query whose first row has `content_type`, `content` (bytea or text) and optionally
+`filename`; the response is that content, sent with `X-Content-Type-Options: nosniff` and a sandboxing
+Content-Security-Policy, so HTML or SVG from a table can't run script in the application's origin. No row: 404.
+
+**Try it.** A handler's page sends a request to the real endpoint, with path parameters, a query string and a JSON
+body, either without a token (to see the 401) or *as* an account of the application with a short-lived token (the
+same as issuing one on App → REST API). A PUT, POST or DELETE changes data. The response's status and body are
+shown in the page; it works without JavaScript.
+
+**Example:** the HR example's module `hr` (`examples/hr/hr_62_rest_module.sql`): `GET emp/:id` (single row),
+`GET emp/:id/photo` (media), `POST leave` (PL/pgSQL with body parameters) and `GET payroll/:deptno` (roles manager or
+admin):
+
+```bash
+curl http://127.0.0.1:3100/a/hr/rest/hr/emp/7839 -H "Authorization: Bearer $TOKEN"
+curl -X POST http://127.0.0.1:3100/a/hr/rest/hr/leave -H "Authorization: Bearer $TOKEN" \
+     -H "Content-Type: application/json" -d '{"start_date": "2027-05-03", "end_date": "2027-05-04", "reason": "dentist"}'
+# {"id": 12, "status": "requested"}
+```
+
+Handlers never run as a superuser, a role that bypasses row level security or pgkiln's owner: such a request
+answers 403 (set `RUNTIME_DATABASE_URL` and give the application its own database role).
+
+## AutoREST: tables and views from the SQL Workshop
+
+**SQL Workshop → RESTful Services** (`/builder/sql/rest`; Database Actions: a table's *REST › Enable*, ORDS
+AutoREST), or **REST › Enable / Disable** in a table's or view's ⋯ menu (SQL Worksheet navigator, Object Browser).
+Choose:
+
+| Setting | Meaning |
+|---|---|
+| Table or view | Any table, partitioned table, view, materialized view or foreign table of a schema the SQL Workshop may use (not `meta`) |
+| Application | An application of the current workspace with a database role. It decides how requests run (below) and gives the URL |
+| URL name | The segment in `/a/<alias>/autorest/<name>/`: lower case letters, digits, `_` and `-`; the object's name by default |
+| Methods | `GET` (rows and one row), `POST` (insert), `PUT` (update), `DELETE`. `PUT` and `DELETE` need a primary key; a materialized view answers `GET` only |
+| Who may call it | **A bearer token of the application** (the default), or **public**: anyone, without a token. Public is never implied: it is a choice on the form |
+| Roles | Optional application roles; the caller needs one of them (`meta.has_role()`), else 403 |
+| Page size | Rows per page without `?limit=` (1–500, default 25) |
+
+The object's page shows the checks (the role is not the owner and doesn't bypass row level security; its grants per
+method; row level security on or off; for a view whether it is `security_invoker`; the primary key; columns the role
+may not read), the endpoints with their URLs, cURL and `fetch` examples, and the OpenAPI link. Its settings can be
+changed, the object disabled (404) or removed (*Disable REST*). The table itself is never changed.
+
+**Endpoints** (`/a/hr/autorest/dept/` for `hr.dept` published through `hr`):
+
+| Request | Answer |
+|---|---|
+| `GET …/dept/` | `{"items": […], "offset": 0, "limit": 25, "has_more": true}`. `?limit=` (1–500) and `?offset=` page; `?<column>=<value>` keeps rows whose column equals the value (several are combined with AND); `?q=<text>` keeps rows where a text column contains the text (case-insensitive; `%` and `_` are literal); `?order=dname,deptno.desc` sorts (default: the primary key). An unknown parameter or column is a 400 |
+| `GET …/dept/10` | The row as an object, or 404. A composite key is comma separated: `…/pair/1,x` (URL-encode a comma inside a value) |
+| `POST …/dept/` | A JSON object of column values → 201 with the new row and a `Location` header. Columns left out get their defaults; an unknown column is a 400 |
+| `PUT …/dept/10` | A JSON object of the columns to change → 200 with the row, or 404 (also when row level security hides it). Columns left out keep their values |
+| `DELETE …/dept/10` | 204, or 404 |
+| `GET /a/hr/autorest/openapi.json` | OpenAPI 3 of the application's published objects: without a token the public ones, with a valid token all of them; column types as JSON Schema |
+
+A method that isn't enabled answers 405 with an `Allow` header. Errors are JSON `{"error": "…"}`, as for REST modules:
+400 for invalid input, a check or unique constraint, or a `raise exception`; 403 for a missing role or grant
+(including column grants and a row level security `with check`).
+
+**How a request runs.** As for [REST modules](#rest-modules-in-the-builder): the token is checked (signature, expiry,
+the application, an active account with access or a client that isn't revoked) at every request; a browser session is
+not accepted. The statement then runs in a transaction **as the application's database role**, with
+`meta.app_user()` = the caller (`nobody` for a public object without a token), `meta.has_role()` reading the caller's
+roles, and a 30-second statement timeout. So the role's grants, column grants and the table's row level security
+apply exactly as on the application's pages. Columns the role may not select are left out of every answer and can't
+be filtered or sorted on. AutoREST refuses, when the object is enabled and again at every request (after `SET ROLE`),
+a role that owns the object or is a member of its owner (row level security doesn't apply to the owner), a superuser
+and a role with `BYPASSRLS`. An application without a database role can't publish objects. Names come from the
+catalog and are quoted; filter values, keys and bodies are query parameters, never SQL text.
+
+The workspace preference *Enable RESTful services* turns AutoREST off with the REST modules (404), and the
+application's availability applies too.
+
+```bash
+TOKEN=…   # App → REST API → Issue a token for king
+curl "http://127.0.0.1:3100/a/hr/autorest/dept/?limit=2" -H "Authorization: Bearer $TOKEN"
+# {"items":[{"deptno":10,"dname":"ACCOUNTING",…},{"deptno":20,…}],"offset":0,"limit":2,"has_more":true}
+curl "http://127.0.0.1:3100/a/hr/autorest/dept/?limit=2"            # 401: no token
+```
+
+**Views.** A view without `security_invoker = true` runs with its owner's rights, so the row level security of the
+tables beneath it does not apply to the caller; the page warns about it. Views have no primary key: they publish the
+collection (`GET`, and `POST` when PostgreSQL can insert into the view).
+
+**Export.** The published objects are installation data, like OAuth clients: they name objects of this database and
+are not part of an application export; an in-place import (`pgkiln import --replace`) keeps them. Tailored endpoints
+that travel with the application are [REST modules](#rest-modules-in-the-builder).
+
 ## PostgREST
 
 [PostgREST](https://postgrest.org) runs as a separate service **next to** pgkiln and turns

package/docs/guide/15-extensions.md

@@ -19,7 +19,7 @@ setup`) and on practically every managed service. Install with `create extension
 | **unaccent** | Accent-insensitive search (`café` finds `cafe`), essential in multilingual apps | Text search options |
 | **citext** | Case-insensitive text columns (e-mail addresses, codes) without `lower()` everywhere | NLS_COMP=LINGUISTIC |
 | **btree_gist** | Exclusion constraints on ranges, e.g. **no overlapping bookings/leave** enforced by the database, race-free | Custom PL/SQL checks |
-| **pg_stat_statements** | Which SQL is slow or called most, per role, so per app (`db_role`) | Monitor Activity → Top SQL |
+| **pg_stat_statements** | Which SQL is slow or called most, per role, so per app (`db_role`) | Monitor Activity → Top SQL; SQL Workshop → SQL Monitor (Top SQL, a statement's totals) |
 | **tablefunc** | `crosstab()` for pivot tables | Interactive report *Pivot* |
 | **ltree** | Hierarchies (org charts, categories, menus) with fast subtree queries | Tree region, `CONNECT BY` |
 | **postgres_fdw**, **file_fdw** | Query another PostgreSQL database, or a CSV file, as if it were a table | Remote servers / database links |

package/examples/hr/hr_62_rest_module.sql

@@ -0,0 +1,39 @@
+-- =====================================================================
+-- HR example, part 62: a REST module built in SQL Workshop › RESTful
+-- Services (sprint 104; docs/guide/13-rest-api.md → Modules, templates
+-- and handlers). Module "hr" at /a/hr/rest/hr/, with a token from
+-- App › REST API:
+--
+--   emp/                 GET   collection query: the active employees
+--   emp/:id              GET   single row: one employee
+--   emp/:id/photo        GET   media: the employee's photo
+--   leave                POST  PL/pgSQL: request leave with
+--                              {"start_date": "…", "end_date": "…", "reason": "…"}
+--   payroll/:deptno      GET   collection query; managers and administrators only
+-- =====================================================================
+insert into meta.rest_module (app_id, name, title, description, templates, handlers)
+select id, 'hr', 'HR (RESTful Services)', 'Employees and leave requests: a module of templates and handlers.',
+$t$[
+  {"uri": "emp", "description": "The employees"},
+  {"uri": "emp/:id", "description": "One employee by number"},
+  {"uri": "emp/:id/photo", "description": "An employee's photo"},
+  {"uri": "leave", "description": "Leave requests of the caller"},
+  {"uri": "payroll/:deptno", "description": "Payroll of a department"}
+]$t$::jsonb,
+$h$[
+  {"method": "GET", "path": "emp", "type": "collection", "description": "The active employees",
+   "source": "select empno, initcap(ename) as name, initcap(job) as job, deptno from hr.emp where active order by empno"},
+  {"method": "GET", "path": "emp/:id", "type": "item", "description": "One employee",
+   "source": "select empno, initcap(ename) as name, initcap(job) as job, deptno, hiredate, mgr from hr.emp where empno = :ID::int"},
+  {"method": "GET", "path": "emp/:id/photo", "type": "media", "description": "The employee's photo",
+   "source": "select photo_mime as content_type, photo as content, photo_name as filename from hr.emp where empno = :ID::int and photo is not null"},
+  {"method": "POST", "path": "leave", "type": "plpgsql", "description": "Request leave (as the caller)",
+   "params": [{"name": "start_date", "in": "body", "type": "string", "required": true, "description": "First day (YYYY-MM-DD)"},
+              {"name": "end_date", "in": "body", "type": "string", "required": true, "description": "Last day (YYYY-MM-DD)"},
+              {"name": "reason", "in": "body", "type": "string"}],
+   "source": "declare\n  v_id int;\nbegin\n  v_id := hr.request_leave(:START_DATE::date, :END_DATE::date, :REASON);\n  perform meta.rest_reply(jsonb_build_object('id', v_id, 'status', 'requested'), 201);\nend"},
+  {"method": "GET", "path": "payroll/:deptno", "type": "collection", "roles": ["manager", "admin"], "description": "Salaries of a department",
+   "source": "select empno, initcap(ename) as name, sal from hr.emp where deptno = :DEPTNO::int and active order by empno"}
+]$h$::jsonb
+  from meta.app where alias = 'hr'
+on conflict (app_id, name) do nothing;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pgkiln",
-  "version": "0.47.0",
+  "version": "0.49.0",
   "description": "Open source low-code, SQL-driven application builder for PostgreSQL, inspired by Oracle APEX",
   "keywords": [
     "postgresql",

package/public/app.css

@@ -416,7 +416,7 @@ dialog.region-inline_drawer:target { inset: 0 0 0 auto; }
 .req { color: var(--danger); margin-left: 0.2em; }
 input:not([type=checkbox]):not([type=radio]), select, textarea {
   font: inherit; color: var(--text); background: var(--surface);
-  border: 1px solid var(--border); border-radius: calc(var(--radius) * 0.75); padding: 0.45rem 0.6rem; width: 100%; min-width: 0;
+  border: 1px solid var(--field-border, var(--border)); border-radius: calc(var(--radius) * 0.75); padding: 0.45rem 0.6rem; width: 100%; min-width: 0;
 }
 input:disabled, select:disabled, textarea:disabled { opacity: 0.6; }
 textarea.code { font-family: var(--mono); font-size: 0.84rem; line-height: 1.45; tab-size: 2; }

package/public/builder-icons.svg

@@ -30,4 +30,6 @@
   <symbol id="b-save" viewBox="0 0 24 24"><path d="M5 4h11l3 3v13H5z"/><path d="M8 4v5h7V4M8 20v-6h8v6"/></symbol>
   <symbol id="b-dots" viewBox="0 0 24 24"><path d="M5 12h.01M12 12h.01M19 12h.01" stroke-width="3.2"/></symbol>
   <symbol id="b-pages" viewBox="0 0 24 24"><path d="M8 3h8l4 4v11H8z"/><path d="M16 3v4h4"/><path d="M4 7v14h11"/></symbol>
+  <!-- (sprint 105) the pgkiln brand mark: an ember flame with a hollow core; filled, unlike the stroke icons -->
+  <symbol id="b-kiln" viewBox="0 0 24 24"><path fill="currentColor" stroke="none" fill-rule="evenodd" d="M12.3 1.8c.6 3.1 2.5 4.7 4.2 6.6 1.8 1.9 3.1 4 3.1 6.7a7.6 7.6 0 0 1-15.2 0c0-2.6 1.1-4.6 2.8-6.1.2 1.6 1 2.8 2.2 3.4C9.2 8.6 10.5 4.7 12.3 1.8zM12 20.4a2.9 2.9 0 0 0 2.9-2.9c0-1.4-.5-2.9-1.4-4-.8.8-1.3 1.8-1.4 3-.7-.3-1.1-.9-1.3-1.6-.9.9-1.8 1.9-1.8 3.3a3 3 0 0 0 3 2.2z"/></symbol>
 </svg>