docs: a to-do app as the example schema in the docs, fixtures and tests

This commit is contained in:
2026-11-02 22:19:20 +01:00
parent 93427d8cb6
commit 8fc42bc33b
18 changed files with 215 additions and 215 deletions
+28 -28
View File
@@ -1,8 +1,8 @@
IF OBJECT_ID('demo.assets_tagged') IS NOT NULL DROP FUNCTION demo.assets_tagged;
IF OBJECT_ID('demo.incidents') IS NOT NULL DROP TABLE demo.incidents;
IF OBJECT_ID('demo.asset_tags') IS NOT NULL DROP TABLE demo.asset_tags;
IF OBJECT_ID('demo.todos_tagged') IS NOT NULL DROP FUNCTION demo.todos_tagged;
IF OBJECT_ID('demo.steps') IS NOT NULL DROP TABLE demo.steps;
IF OBJECT_ID('demo.todo_tags') IS NOT NULL DROP TABLE demo.todo_tags;
IF OBJECT_ID('demo.tags') IS NOT NULL DROP TABLE demo.tags;
IF OBJECT_ID('demo.assets') IS NOT NULL DROP TABLE demo.assets;
IF OBJECT_ID('demo.todos') IS NOT NULL DROP TABLE demo.todos;
IF OBJECT_ID('demo.users') IS NOT NULL DROP TABLE demo.users;
IF SCHEMA_ID('demo') IS NOT NULL DROP SCHEMA demo;
GO
@@ -17,13 +17,13 @@ CREATE TABLE demo.users (
manager_id INT REFERENCES demo.users (id)
);
CREATE TABLE demo.assets (
CREATE TABLE demo.todos (
id INT PRIMARY KEY,
name NVARCHAR(100) NOT NULL,
status NVARCHAR(20) NOT NULL,
owner_id INT REFERENCES demo.users (id),
cost DECIMAL(10, 2),
active BIT NOT NULL DEFAULT 1,
estimate DECIMAL(10, 2),
pinned BIT NOT NULL DEFAULT 1,
created_at DATETIMEOFFSET(0) NOT NULL
);
@@ -32,18 +32,18 @@ CREATE TABLE demo.tags (
name NVARCHAR(100) NOT NULL UNIQUE
);
CREATE TABLE demo.asset_tags (
asset_id INT NOT NULL REFERENCES demo.assets (id),
CREATE TABLE demo.todo_tags (
todo_id INT NOT NULL REFERENCES demo.todos (id),
tag_id INT NOT NULL REFERENCES demo.tags (id),
PRIMARY KEY (asset_id, tag_id)
PRIMARY KEY (todo_id, tag_id)
);
CREATE TABLE demo.incidents (
CREATE TABLE demo.steps (
id INT PRIMARY KEY,
title NVARCHAR(200) NOT NULL,
asset_id INT NOT NULL REFERENCES demo.assets (id),
severity INT NOT NULL,
opened_on DATE NOT NULL
todo_id INT NOT NULL REFERENCES demo.todos (id),
priority INT NOT NULL,
due_on DATE NOT NULL
);
INSERT INTO demo.users (id, name, email, password_hash, [limit], manager_id) VALUES
@@ -51,24 +51,24 @@ INSERT INTO demo.users (id, name, email, password_hash, [limit], manager_id) VAL
(2, 'Grace', 'grace@example.com', 'x', NULL, 1),
(3, 'Linus', NULL, 'x', 2, 1);
INSERT INTO demo.assets (id, name, status, owner_id, cost, active, created_at) VALUES
(1, 'vpn gateway', 'open', 1, 1200.50, 1, '2026-01-02T10:00:00+00:00'),
(2, 'mail relay', 'open', 2, 300.00, 1, '2026-01-05T09:30:00+00:00'),
(3, 'old wiki', 'retired', NULL, NULL, 0, '2025-06-01T00:00:00+00:00'),
(4, 'payroll db', 'open', 3, 4000.00, 1, '2026-02-11T16:45:00+00:00');
INSERT INTO demo.todos (id, name, status, owner_id, estimate, pinned, created_at) VALUES
(1, 'water plants', 'open', 1, 2.50, 1, '2026-01-02T10:00:00+00:00'),
(2, 'file taxes', 'open', 2, 1.00, 1, '2026-01-05T09:30:00+00:00'),
(3, 'fix bike', 'done', NULL, NULL, 0, '2025-06-01T00:00:00+00:00'),
(4, 'pay rent', 'open', 3, 4.00, 1, '2026-02-11T16:45:00+00:00');
INSERT INTO demo.tags (id, name) VALUES (1, 'pci'), (2, 'gdpr'), (3, 'internal');
INSERT INTO demo.tags (id, name) VALUES (1, 'work'), (2, 'home'), (3, 'urgent');
INSERT INTO demo.asset_tags (asset_id, tag_id) VALUES (1, 1), (1, 3), (2, 2), (4, 1), (4, 2);
INSERT INTO demo.todo_tags (todo_id, tag_id) VALUES (1, 1), (1, 3), (2, 2), (4, 1), (4, 2);
INSERT INTO demo.incidents (id, title, asset_id, severity, opened_on) VALUES
(1, 'VPN outage', 1, 3, '2026-01-10'),
(2, 'Spoofed mail', 2, 2, '2026-02-01'),
(3, 'Brute force', 1, 4, '2026-03-05');
INSERT INTO demo.steps (id, title, todo_id, priority, due_on) VALUES
(1, 'Water the ferns', 1, 3, '2026-01-10'),
(2, 'Find the receipts', 2, 2, '2026-02-01'),
(3, 'Buy a watering can', 1, 4, '2026-03-05');
GO
CREATE FUNCTION demo.assets_tagged(@tag NVARCHAR(100)) RETURNS TABLE AS RETURN (
SELECT a.* FROM demo.assets a
JOIN demo.asset_tags t ON t.asset_id = a.id
CREATE FUNCTION demo.todos_tagged(@tag NVARCHAR(100)) RETURNS TABLE AS RETURN (
SELECT a.* FROM demo.todos a
JOIN demo.todo_tags t ON t.todo_id = a.id
JOIN demo.tags g ON g.id = t.tag_id
WHERE g.name = @tag
);
+26 -26
View File
@@ -12,13 +12,13 @@ CREATE TABLE demo.users (
FOREIGN KEY (manager_id) REFERENCES demo.users (id)
);
CREATE TABLE demo.assets (
CREATE TABLE demo.todos (
id INT AUTO_INCREMENT PRIMARY KEY,
name VARCHAR(100) NOT NULL,
status VARCHAR(20) NOT NULL,
owner_id INT,
cost DECIMAL(10, 2),
active TINYINT(1) NOT NULL DEFAULT 1,
estimate DECIMAL(10, 2),
pinned TINYINT(1) NOT NULL DEFAULT 1,
created_at TIMESTAMP NOT NULL,
FOREIGN KEY (owner_id) REFERENCES demo.users (id)
);
@@ -28,21 +28,21 @@ CREATE TABLE demo.tags (
name VARCHAR(100) NOT NULL UNIQUE
);
CREATE TABLE demo.asset_tags (
asset_id INT NOT NULL,
CREATE TABLE demo.todo_tags (
todo_id INT NOT NULL,
tag_id INT NOT NULL,
PRIMARY KEY (asset_id, tag_id),
FOREIGN KEY (asset_id) REFERENCES demo.assets (id),
PRIMARY KEY (todo_id, tag_id),
FOREIGN KEY (todo_id) REFERENCES demo.todos (id),
FOREIGN KEY (tag_id) REFERENCES demo.tags (id)
);
CREATE TABLE demo.incidents (
CREATE TABLE demo.steps (
id INT PRIMARY KEY,
title VARCHAR(200) NOT NULL,
asset_id INT NOT NULL,
severity INT NOT NULL,
opened_on DATE NOT NULL,
FOREIGN KEY (asset_id) REFERENCES demo.assets (id)
todo_id INT NOT NULL,
priority INT NOT NULL,
due_on DATE NOT NULL,
FOREIGN KEY (todo_id) REFERENCES demo.todos (id)
);
SET time_zone = '+00:00';
@@ -52,23 +52,23 @@ INSERT INTO demo.users (id, name, email, password_hash, `limit`, manager_id) VAL
(2, 'Grace', 'grace@example.com', 'x', NULL, 1),
(3, 'Linus', NULL, 'x', 2, 1);
INSERT INTO demo.assets (id, name, status, owner_id, cost, active, created_at) VALUES
(1, 'vpn gateway', 'open', 1, 1200.50, 1, '2026-01-02 10:00:00'),
(2, 'mail relay', 'open', 2, 300.00, 1, '2026-01-05 09:30:00'),
(3, 'old wiki', 'retired', NULL, NULL, 0, '2025-06-01 00:00:00'),
(4, 'payroll db', 'open', 3, 4000.00, 1, '2026-02-11 16:45:00');
INSERT INTO demo.todos (id, name, status, owner_id, estimate, pinned, created_at) VALUES
(1, 'water plants', 'open', 1, 2.50, 1, '2026-01-02 10:00:00'),
(2, 'file taxes', 'open', 2, 1.00, 1, '2026-01-05 09:30:00'),
(3, 'fix bike', 'done', NULL, NULL, 0, '2025-06-01 00:00:00'),
(4, 'pay rent', 'open', 3, 4.00, 1, '2026-02-11 16:45:00');
INSERT INTO demo.tags (id, name) VALUES (1, 'pci'), (2, 'gdpr'), (3, 'internal');
INSERT INTO demo.tags (id, name) VALUES (1, 'work'), (2, 'home'), (3, 'urgent');
INSERT INTO demo.asset_tags (asset_id, tag_id) VALUES (1, 1), (1, 3), (2, 2), (4, 1), (4, 2);
INSERT INTO demo.todo_tags (todo_id, tag_id) VALUES (1, 1), (1, 3), (2, 2), (4, 1), (4, 2);
INSERT INTO demo.incidents (id, title, asset_id, severity, opened_on) VALUES
(1, 'VPN outage', 1, 3, '2026-01-10'),
(2, 'Spoofed mail', 2, 2, '2026-02-01'),
(3, 'Brute force', 1, 4, '2026-03-05');
INSERT INTO demo.steps (id, title, todo_id, priority, due_on) VALUES
(1, 'Water the ferns', 1, 3, '2026-01-10'),
(2, 'Find the receipts', 2, 2, '2026-02-01'),
(3, 'Buy a watering can', 1, 4, '2026-03-05');
CREATE FUNCTION demo.retire_asset(asset INT, reason TEXT) RETURNS INT MODIFIES SQL DATA
CREATE FUNCTION demo.complete_todo(todo INT, note TEXT) RETURNS INT MODIFIES SQL DATA
BEGIN
UPDATE demo.assets SET status = 'retired' WHERE id = asset;
RETURN asset;
UPDATE demo.todos SET status = 'done' WHERE id = todo;
RETURN todo;
END;
+25 -25
View File
@@ -10,13 +10,13 @@ CREATE TABLE demo.users (
manager_id integer REFERENCES demo.users (id)
);
CREATE TABLE demo.assets (
CREATE TABLE demo.todos (
id integer PRIMARY KEY,
name text NOT NULL,
status text NOT NULL,
owner_id integer REFERENCES demo.users (id),
cost numeric(10, 2),
active boolean NOT NULL DEFAULT true,
estimate numeric(10, 2),
pinned boolean NOT NULL DEFAULT true,
created_at timestamptz NOT NULL
);
@@ -25,18 +25,18 @@ CREATE TABLE demo.tags (
name text NOT NULL UNIQUE
);
CREATE TABLE demo.asset_tags (
asset_id integer NOT NULL REFERENCES demo.assets (id),
CREATE TABLE demo.todo_tags (
todo_id integer NOT NULL REFERENCES demo.todos (id),
tag_id integer NOT NULL REFERENCES demo.tags (id),
PRIMARY KEY (asset_id, tag_id)
PRIMARY KEY (todo_id, tag_id)
);
CREATE TABLE demo.incidents (
CREATE TABLE demo.steps (
id integer PRIMARY KEY,
title text NOT NULL,
asset_id integer NOT NULL REFERENCES demo.assets (id),
severity integer NOT NULL,
opened_on date NOT NULL
todo_id integer NOT NULL REFERENCES demo.todos (id),
priority integer NOT NULL,
due_on date NOT NULL
);
INSERT INTO demo.users (id, name, email, password_hash, "limit", manager_id) VALUES
@@ -44,27 +44,27 @@ INSERT INTO demo.users (id, name, email, password_hash, "limit", manager_id) VAL
(2, 'Grace', 'grace@example.com', 'x', NULL, 1),
(3, 'Linus', NULL, 'x', 2, 1);
INSERT INTO demo.assets (id, name, status, owner_id, cost, active, created_at) VALUES
(1, 'vpn gateway', 'open', 1, 1200.50, true, '2026-01-02T10:00:00Z'),
(2, 'mail relay', 'open', 2, 300.00, true, '2026-01-05T09:30:00Z'),
(3, 'old wiki', 'retired', NULL, NULL, false, '2025-06-01T00:00:00Z'),
(4, 'payroll db', 'open', 3, 4000.00, true, '2026-02-11T16:45:00Z');
INSERT INTO demo.todos (id, name, status, owner_id, estimate, pinned, created_at) VALUES
(1, 'water plants', 'open', 1, 2.50, true, '2026-01-02T10:00:00Z'),
(2, 'file taxes', 'open', 2, 1.00, true, '2026-01-05T09:30:00Z'),
(3, 'fix bike', 'done', NULL, NULL, false, '2025-06-01T00:00:00Z'),
(4, 'pay rent', 'open', 3, 4.00, true, '2026-02-11T16:45:00Z');
INSERT INTO demo.tags (id, name) VALUES (1, 'pci'), (2, 'gdpr'), (3, 'internal');
INSERT INTO demo.tags (id, name) VALUES (1, 'work'), (2, 'home'), (3, 'urgent');
INSERT INTO demo.asset_tags (asset_id, tag_id) VALUES (1, 1), (1, 3), (2, 2), (4, 1), (4, 2);
INSERT INTO demo.todo_tags (todo_id, tag_id) VALUES (1, 1), (1, 3), (2, 2), (4, 1), (4, 2);
INSERT INTO demo.incidents (id, title, asset_id, severity, opened_on) VALUES
(1, 'VPN outage', 1, 3, '2026-01-10'),
(2, 'Spoofed mail', 2, 2, '2026-02-01'),
(3, 'Brute force', 1, 4, '2026-03-05');
INSERT INTO demo.steps (id, title, todo_id, priority, due_on) VALUES
(1, 'Water the ferns', 1, 3, '2026-01-10'),
(2, 'Find the receipts', 2, 2, '2026-02-01'),
(3, 'Buy a watering can', 1, 4, '2026-03-05');
CREATE FUNCTION demo.retire_asset(asset integer, reason text DEFAULT NULL) RETURNS integer
LANGUAGE sql AS $$ UPDATE demo.assets SET status = 'retired' WHERE id = asset RETURNING id $$;
CREATE FUNCTION demo.complete_todo(todo integer, note text DEFAULT NULL) RETURNS integer
LANGUAGE sql AS $$ UPDATE demo.todos SET status = 'done' WHERE id = todo RETURNING id $$;
CREATE FUNCTION demo.assets_tagged(tag text) RETURNS SETOF demo.assets
CREATE FUNCTION demo.todos_tagged(tag text) RETURNS SETOF demo.todos
LANGUAGE sql STABLE AS $$
SELECT a.* FROM demo.assets a JOIN demo.asset_tags t ON t.asset_id = a.id JOIN demo.tags g ON g.id = t.tag_id
SELECT a.* FROM demo.todos a JOIN demo.todo_tags t ON t.todo_id = a.id JOIN demo.tags g ON g.id = t.tag_id
WHERE g.name = tag ORDER BY a.id $$;
CREATE TABLE demo.notes (
+21 -21
View File
@@ -7,13 +7,13 @@ CREATE TABLE demo.users (
manager_id INTEGER REFERENCES users (id)
);
CREATE TABLE demo.assets (
CREATE TABLE demo.todos (
id INTEGER PRIMARY KEY,
name TEXT NOT NULL,
status TEXT NOT NULL,
owner_id INTEGER REFERENCES users (id),
cost NUMERIC,
active BOOLEAN NOT NULL DEFAULT 1,
estimate NUMERIC,
pinned BOOLEAN NOT NULL DEFAULT 1,
created_at TIMESTAMP NOT NULL
);
@@ -22,18 +22,18 @@ CREATE TABLE demo.tags (
name TEXT NOT NULL UNIQUE
);
CREATE TABLE demo.asset_tags (
asset_id INTEGER NOT NULL REFERENCES assets (id),
CREATE TABLE demo.todo_tags (
todo_id INTEGER NOT NULL REFERENCES todos (id),
tag_id INTEGER NOT NULL REFERENCES tags (id),
PRIMARY KEY (asset_id, tag_id)
PRIMARY KEY (todo_id, tag_id)
);
CREATE TABLE demo.incidents (
CREATE TABLE demo.steps (
id INTEGER PRIMARY KEY,
title TEXT NOT NULL,
asset_id INTEGER NOT NULL REFERENCES assets (id),
severity INTEGER NOT NULL,
opened_on DATE NOT NULL
todo_id INTEGER NOT NULL REFERENCES todos (id),
priority INTEGER NOT NULL,
due_on DATE NOT NULL
);
INSERT INTO demo.users (id, name, email, password_hash, "limit", manager_id) VALUES
@@ -41,17 +41,17 @@ INSERT INTO demo.users (id, name, email, password_hash, "limit", manager_id) VAL
(2, 'Grace', 'grace@example.com', 'x', NULL, 1),
(3, 'Linus', NULL, 'x', 2, 1);
INSERT INTO demo.assets (id, name, status, owner_id, cost, active, created_at) VALUES
(1, 'vpn gateway', 'open', 1, 1200.50, 1, '2026-01-02T10:00:00+00:00'),
(2, 'mail relay', 'open', 2, 300.00, 1, '2026-01-05T09:30:00+00:00'),
(3, 'old wiki', 'retired', NULL, NULL, 0, '2025-06-01T00:00:00+00:00'),
(4, 'payroll db', 'open', 3, 4000.00, 1, '2026-02-11T16:45:00+00:00');
INSERT INTO demo.todos (id, name, status, owner_id, estimate, pinned, created_at) VALUES
(1, 'water plants', 'open', 1, 2.50, 1, '2026-01-02T10:00:00+00:00'),
(2, 'file taxes', 'open', 2, 1.00, 1, '2026-01-05T09:30:00+00:00'),
(3, 'fix bike', 'done', NULL, NULL, 0, '2025-06-01T00:00:00+00:00'),
(4, 'pay rent', 'open', 3, 4.00, 1, '2026-02-11T16:45:00+00:00');
INSERT INTO demo.tags (id, name) VALUES (1, 'pci'), (2, 'gdpr'), (3, 'internal');
INSERT INTO demo.tags (id, name) VALUES (1, 'work'), (2, 'home'), (3, 'urgent');
INSERT INTO demo.asset_tags (asset_id, tag_id) VALUES (1, 1), (1, 3), (2, 2), (4, 1), (4, 2);
INSERT INTO demo.todo_tags (todo_id, tag_id) VALUES (1, 1), (1, 3), (2, 2), (4, 1), (4, 2);
INSERT INTO demo.incidents (id, title, asset_id, severity, opened_on) VALUES
(1, 'VPN outage', 1, 3, '2026-01-10'),
(2, 'Spoofed mail', 2, 2, '2026-02-01'),
(3, 'Brute force', 1, 4, '2026-03-05');
INSERT INTO demo.steps (id, title, todo_id, priority, due_on) VALUES
(1, 'Water the ferns', 1, 3, '2026-01-10'),
(2, 'Find the receipts', 2, 2, '2026-02-01'),
(3, 'Buy a watering can', 1, 4, '2026-03-05');
+7 -7
View File
@@ -2,8 +2,8 @@
export const PAGES = ['query-grammar.md', 'writes.md'];
const PROCEDURES = {
'assets/{asset}/retire': { function: 'demo.retire_asset' },
'tags/{tag}/assets': { function: 'demo.assets_tagged' },
'todos/{todo}/complete': { function: 'demo.complete_todo' },
'tags/{tag}/todos': { function: 'demo.todos_tagged' },
};
/**
@@ -12,18 +12,18 @@ const PROCEDURES = {
*/
const AVAILABLE = {
postgres: Object.keys(PROCEDURES),
mssql: ['tags/{tag}/assets'],
mysql: ['assets/{asset}/retire'],
mssql: ['tags/{tag}/todos'],
mysql: ['todos/{todo}/complete'],
sqlite: [],
};
export const OPTIONS = {
expose: { schemas: ['demo'] },
resources: {
asset_tags: { expose: false },
todo_tags: { expose: false },
tags: { write: true },
assets: { write: { create: ['name', 'status', 'owner_id', 'cost'], update: ['name', 'status', 'owner_id'], delete: false } },
incidents: { write: { create: true, update: true, delete: true, bulk: true } },
todos: { write: { create: ['name', 'status', 'owner_id', 'estimate'], update: ['name', 'status', 'owner_id'], delete: false } },
steps: { write: { create: true, update: true, delete: true, bulk: true } },
},
};
+7 -7
View File
@@ -33,8 +33,8 @@ for (const page of PAGES) {
describe('postgres procedures outside the exposed schemas', { skip: !url && 'RESTLOOM_PG_URL is not set' }, () => {
test('a declared function is read even when only tables are exposed', async () => {
await pool.query(fixture);
const rest = createREST({ db: postgres(pool), expose: { tables: ['demo.tags'] }, procedures: { 'assets/{asset}/retire': { function: 'demo.retire_asset' } } });
const res = await rest.handle({ method: 'POST', path: '/assets/3/retire', query: new URLSearchParams(), headers: {}, body: {}, context: undefined });
const rest = createREST({ db: postgres(pool), expose: { tables: ['demo.tags'] }, procedures: { 'todos/{todo}/complete': { function: 'demo.complete_todo' } } });
const res = await rest.handle({ method: 'POST', path: '/todos/3/complete', query: new URLSearchParams(), headers: {}, body: {}, context: undefined });
assert.equal(res.status, 200);
assert.equal(res.body, 3);
});
@@ -44,7 +44,7 @@ describe('postgres arrays, regular expressions and GET procedures', { skip: !url
let rest;
before(async () => {
await pool.query(fixture);
rest = createREST({ db: postgres(pool), expose: { schemas: ['demo'] }, procedures: { 'tags/{tag}/assets': { function: 'demo.assets_tagged', method: 'GET' } } });
rest = createREST({ db: postgres(pool), expose: { schemas: ['demo'] }, procedures: { 'tags/{tag}/todos': { function: 'demo.todos_tagged', method: 'GET' } } });
});
const get = (path, qs = '') => rest.handle({ method: 'GET', path, query: new URLSearchParams(qs), headers: {}, context: undefined });
@@ -52,7 +52,7 @@ describe('postgres arrays, regular expressions and GET procedures', { skip: !url
assert.deepEqual((await get('/notes', 'select=id&labels=ov.{a,z}')).body, [{ id: 1 }, { id: 3 }]);
assert.deepEqual((await get('/notes', 'select=id&labels=cs.{b}')).body, [{ id: 1 }, { id: 2 }]);
assert.deepEqual((await get('/notes', 'select=id&labels=cd.{a,b,z}')).body, [{ id: 1 }, { id: 3 }]);
assert.equal((await get('/assets', 'name=ov.{a}')).body.error, 'bad_operator');
assert.equal((await get('/todos', 'name=ov.{a}')).body.error, 'bad_operator');
});
test('regular expressions, with and without case', async () => {
@@ -61,10 +61,10 @@ describe('postgres arrays, regular expressions and GET procedures', { skip: !url
});
test('a GET procedure takes its arguments from the query and refuses POST', async () => {
const rows = (await get('/tags/gdpr/assets', 'select=ignored')).body;
const rows = (await get('/tags/home/todos', 'select=ignored')).body;
assert.equal(rows.error, 'unknown_argument');
assert.deepEqual((await get('/tags/gdpr/assets')).body.map((r) => r.id), [2, 4]);
const post = await rest.handle({ method: 'POST', path: '/tags/gdpr/assets', query: new URLSearchParams(), headers: {}, body: {}, context: undefined });
assert.deepEqual((await get('/tags/home/todos')).body.map((r) => r.id), [2, 4]);
const post = await rest.handle({ method: 'POST', path: '/tags/home/todos', query: new URLSearchParams(), headers: {}, body: {}, context: undefined });
assert.equal(post.status, 405);
});
});