First app walkthrough
This page walks you from an empty install to a working app — a sidebar entry that opens a grid backed by a SQL query, with an edit dialog. Everything is done from the in-app Settings UI; nothing is hand-edited in TOML. The whole sequence takes under five minutes once the framework is installed.
You'll touch four configuration types in order — pool → connector → screen → menu — each saved live and reloaded by the framework in the same browser tab.
At a glance
The example uses the built-in SQLite pool (default) and a tiny tasks table — no external database needed.
Step 1 — Make sure the default pool exists
Open Settings → Pools. On a fresh install the default pool already points at the local SQLite file (liberty.db). It's enough for this walkthrough — no changes required.
For a real install, switch to a PostgreSQL or Oracle URL — every connection-string format and option is documented under Configuration → Environment variables.
Then create the example table once via the SQLite shell:
CREATE TABLE tasks (
id INTEGER PRIMARY KEY AUTOINCREMENT,
title TEXT NOT NULL,
status TEXT NOT NULL DEFAULT 'open',
due_date DATE,
created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);
INSERT INTO tasks(title, status, due_date) VALUES
('Draft sprint plan', 'open', '2026-06-10'),
('Review pull request 42', 'done', '2026-06-05'),
('Customer follow-up', 'open', '2026-06-12');
Step 2 — Define a SQL connector
A connector is a named query against a pool. Open Settings → Connectors → ➕ New connector and fill in:
| Field | Value |
|---|---|
| Name | tasks |
| Pool | default |
| Type | sql |
| Read query | SELECT id, title, status, due_date FROM tasks ORDER BY due_date |
| Write — insert | INSERT INTO tasks(title, status, due_date) VALUES (:title, :status, :due_date) |
| Write — update | UPDATE tasks SET title = :title, status = :status, due_date = :due_date WHERE id = :id |
| Write — delete | DELETE FROM tasks WHERE id = :id |
The schema of the read query is discovered at runtime — the framework asks the database "what columns does this return?" the first time the connector is used. No need to declare it ahead of time.
Click Save. The connector appears on the catalog page (open / in another tab to see it). Connectors covers every option and the HTTP / API connector types.
Step 3 — Build a screen on top of the connector
A screen wraps a connector into a grid + edit dialog. Open Settings → Screens → ➕ New screen:
| Field | Value |
|---|---|
| App | tutorial |
| Screen id | tasks |
| Title | Tasks |
| Connector | tasks |
| Key columns | id |
| Editable | ✓ (turns on the Add / Edit / Delete actions) |
The grid columns and the edit dialog auto-derive from the read query's columns. To add localized labels, validation rules or boolean badges, the Dictionary page is the next stop.
Click Save, then open the URL http://127.0.0.1:8000/screens/tutorial/tasks — the grid is already live.
Click any row — the edit dialog opens with the four fields, Save triggers the update query, Delete triggers the delete query, + Add opens an empty form bound to the insert query.
Screens covers tabs, per-field conditions, cross-connector reads/writes and the full set of dialog options.
Step 4 — Wire it into the sidebar menu
Open Settings → Menus → ➕ New leaf (or extend an existing tree):
| Field | Value |
|---|---|
| Parent | Top-level |
| Label | Tasks |
| Type | query |
| Connector | tasks |
| Screen | tutorial/tasks |
| Icon | list-todo (any Lucide icon) |
Save. The sidebar refreshes automatically — the Tasks entry appears with the icon and opens the screen on click. The framework's hot-reload pipeline pushed the new menu tree without a restart; the same is true for every Settings edit. See Hot-reload for the exact mechanics.
What you have now
A working app with:
- A pool that owns the database connection.
- A connector holding the read + write queries.
- A screen that turns the connector into a grid + edit dialog.
- A menu entry that exposes the screen in the sidebar.
Four TOML blocks behind the scenes — the four files were updated in place under liberty-apps/config/, no restart needed. Look at them with git diff to see how a typical edit lands.
What's next
- Project layout — the file map of
liberty-apps. - Concepts → Connectors — HTTP, API, parameterised queries, schema hints.
- Concepts → Dictionary — labels, enums, lookups, format rules.
- Authentication → Roles & permissions — restrict the new screen to a specific role.
- Settings UI — every builder in detail.