Skip to main content

​
Get SQLPage Running

Let’s get SQLPage up and running with a “Hello World” application.
1

Download SQLPage

Choose your preferred installation method:
Download the latest release for your platform:
# Linux/macOS
wget https://github.com/sqlpage/SQLPage/releases/latest/download/sqlpage-linux.tgz
tar -xzf sqlpage-linux.tgz
chmod +x sqlpage.bin
Windows
# Download from: https://github.com/sqlpage/SQLPage/releases/latest
# Extract the .zip file
# Run sqlpage.exe
SQLPage comes as a single executable with no dependencies. No Node.js, Python, or Ruby required!
2

Create Your First Page

Create a file named index.sql in your working directory:
index.sql
SELECT 'hero' as component,
    'Hello, SQLPage!' as title,
    'You just created your first SQL-powered website.' as description;
This SQL file is your entire web page. SQLPage will execute the query and render it as HTML.
3

Start the Server

Run SQLPage:
./sqlpage.bin
You should see:
SQLPage started successfully.
Listening on http://0.0.0.0:8080
4

View Your Page

Open your browser and navigate to:
http://localhost:8080
You’ll see your “Hello, SQLPage!” hero section rendered beautifully!
SQLPage automatically reloads your .sql files when they change. Edit index.sql and refresh your browser to see updates instantly.

​
Build a Real Application

Let’s create a simple todo list application with full CRUD functionality.
1

Set Up the Database

Create a directory for SQLPage configuration:
mkdir -p sqlpage/migrations
Create the database schema in sqlpage/migrations/0000_init.sql:
sqlpage/migrations/0000_init.sql
CREATE TABLE todos (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    title TEXT NOT NULL,
    completed BOOLEAN DEFAULT FALSE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Add some sample data
INSERT INTO todos (title, completed) VALUES
    ('Learn SQLPage basics', TRUE),
    ('Build a todo app', FALSE),
    ('Deploy to production', FALSE);
SQLPage automatically runs migration files in the sqlpage/migrations/ directory on startup, in alphabetical order.
2

Create the Main Page

Replace your index.sql with this todo list:
index.sql
-- Page header
SELECT 'dynamic' as component,
    sqlpage.run_sql('shell.sql') as properties;

-- Display todos
SELECT 'list' as component,
    'My Todo List' as title,
    'No todos yet!' as empty_title;

SELECT 
    title,
    CASE WHEN completed THEN 'green' ELSE 'gray' END as color,
    'edit.sql?id=' || id as edit_link,
    'delete.sql?id=' || id as delete_link
FROM todos
ORDER BY completed, created_at DESC;

-- Add button
SELECT 'button' as component, 'center' as justify;
SELECT 
    'form.sql' as link,
    'Add New Todo' as title,
    'green' as color,
    'circle-plus' as icon;
3

Create the Add/Edit Form

Create form.sql to add or edit todos:
form.sql
-- Handle form submission
INSERT INTO todos (title, completed)
SELECT $title, COALESCE($completed, FALSE)
WHERE $title IS NOT NULL AND $id IS NULL;

UPDATE todos 
SET title = $title, completed = COALESCE($completed, FALSE)
WHERE id = $id AND $title IS NOT NULL;

-- Redirect back to home page after submission
SELECT 'redirect' as component, '/' as link
WHERE $title IS NOT NULL;

-- Display the form
SELECT 'form' as component,
    COALESCE('Edit Todo', 'Add New Todo') as title,
    'Save' as validate;

SELECT 'title' as name, 
    'text' as type,
    TRUE as required,
    title as value
FROM todos WHERE id = $id
UNION ALL
SELECT 'title', 'text', TRUE, NULL WHERE $id IS NULL;

SELECT 'completed' as name,
    'checkbox' as type,
    'Completed' as label,
    completed as checked
FROM todos WHERE id = $id
UNION ALL
SELECT 'completed', 'checkbox', 'Completed', FALSE WHERE $id IS NULL;
4

Add Delete Functionality

Create delete.sql to remove todos:
delete.sql
DELETE FROM todos WHERE id = $id;

SELECT 'redirect' as component, '/' as link;
5

Optional: Add a Shell

Create shell.sql for consistent page styling:
shell.sql
SELECT 'shell' as component,
    'Todo App' as title,
    'list-check' as icon,
    '/' as link,
    'cyan' as color;

​
What You’ve Learned

Congratulations! You’ve built a complete todo application with:

Database Operations

CREATE, INSERT, SELECT, UPDATE, and DELETE queries

UI Components

Hero, list, form, and button components

Routing

Multiple pages linked together with URL parameters

Redirects

Post-submission redirects for better UX

​
Key Concepts

​
Components

Each query’s first row defines which component to use: 
SELECT 'list' as component,
    'My List' as title;  -- Component properties
Subsequent rows provide the data: 
SELECT 
    name as title,     -- Item properties
    url as link
FROM items;

​
URL Parameters

Form inputs and URL query parameters are available as SQL variables: 
-- For URL: /page.sql?id=123
SELECT * FROM items WHERE id = $id;
SQLPage uses parameterized queries to prevent SQL injection. URL parameters are always safe to use.

​
Migrations

Place numbered SQL files in sqlpage/migrations/ to initialize your database: 
sqlpage/
  migrations/
    0000_init.sql
    0001_add_users.sql
    0002_add_categories.sql
SQLPage runs these once, in order, when starting up.

​
Next Steps

Explore Components

Discover charts, maps, tabs, and more

Learn SQLPage Functions

File uploads, authentication, HTTP requests

Configure Your App

Database connections, HTTPS, environment variables

Deploy to Production

Docker, systemd, and cloud deployment

​
Common Patterns

​
Display Data with Styling

SELECT 'card' as component;

SELECT 
    name as title,
    description,
    CASE status
        WHEN 'active' THEN 'green'
        WHEN 'pending' THEN 'yellow'
        ELSE 'gray'
    END as color,
    image_url as top_image
FROM products;

​
Create Interactive Forms

SELECT 'form' as component,
    'Contact Us' as title,
    'send.sql' as action;

SELECT 'name' as name, 'text' as type, TRUE as required;
SELECT 'email' as name, 'email' as type, TRUE as required;
SELECT 'message' as name, 'textarea' as type, 5 as rows;

​
Build Charts

SELECT 'chart' as component,
    'Monthly Sales' as title,
    'bar' as type;

SELECT 
    month as x,
    SUM(revenue) as y
FROM sales
GROUP BY month
ORDER BY month;
Check out the Examples section for more complete applications, including authentication, file uploads, and data visualization.

Build docs developers (and LLMs) love

Get started for freeTalk to us