pgkiln documentation
pgkiln is a low-code, SQL-driven application builder for PostgreSQL, modeled on Oracle APEX. This guide explains how everything works, from installing it to building, securing and deploying applications, and how to extend pgkiln itself.
User guide
| # | Chapter | What you will learn |
|---|---|---|
| 1 | Installation and configuration | Requirements, quick start, every configuration option, production deployment, upgrades, backups |
| 2 | Concepts: how pgkiln works | Architecture, the metadata repository, the request lifecycle, session state, bind variables, substitutions |
| 3 | Using the builder | Creating apps, the page wizards, the page designer, shared components, SQL Workshop, export/import |
| 4 | Pages and regions | Page properties and every region type (reports, grids, forms, charts, cards, calendar, facets, static/dynamic content) with all attributes |
| 5 | Items | Every item type, lists of values, cascading lists, read-only conditions, multi-value items |
| 6 | Buttons, validations, processes and page logic | Menu buttons and badges, what happens when a page is submitted, form and grid DML, calling PL/pgSQL, error handling, computations, conditional branches, build options, application processes |
| 7 | Dynamic actions | Client-side behaviour: show/hide, set values from SQL, refresh regions, cascading lists |
| 8 | Users, authentication and authorization | Sign-in, users and roles, passwords and My account, authorization schemes, row level security, session state protection |
| 9 | SQL API and metadata reference | meta.* functions, every metadata table and column, URL parameters |
| 10 | Tutorial: build a Tasks app | A complete app with RLS, PL/pgSQL, validations and dynamic actions, step by step |
| 11 | Coming from Oracle APEX | Concept mapping, porting PL/SQL to PL/pgSQL, users per app vs workspace, ORDS vs PostgREST |
| 12 | Developing pgkiln | Code structure, tests, adding a region or item type, release process |
| 13 | REST APIs with PostgREST | PostgREST next to pgkiln, the api schema pattern, tokens, one set of RLS policies for UI and API |
| 14 | Globalization | Languages, translating an app (XLIFF/CSV), text messages, date formats, light/dark |
| 15 | Useful PostgreSQL extensions | Extensions for search, scheduling, auditing, maps, AI search, Oracle compatibility and web services, mapped to APEX features, with security notes |
| 16 | Files, data loading and printing | File upload items, loading CSV/Excel/JSON into tables (SQL Workshop and pages), report PDFs, document templates and printing |
| 17 | Mobile and field work | Progressive Web Apps: installing, offline pages, forms sent offline, location, camera and barcode items |
| 18 | The command line and application files | pgkiln CLI: migrate, export/import, one file per component for git, static ids, diff, updating an app in place |
| 19 | REST data sources and web credentials | Regions and lists of values on web services, web credentials (basic, API key, bearer, OAuth2) with write-only secrets, the invoke_api process, the server's allow-list |
| 20 | AI coding agents (MCP) | pgkiln mcp: let Claude Code, Cursor and others read, explain, change, diff and import applications |
Other documents
Conventions in this guide
coderefers to SQL, file names, configuration keys or UI labels you type.- Builder → App → Shared Components describes a path through the builder's menus.
- Examples often use the HR example application (
/a/hr,npm run example:hr); it is not part of pgkiln.