SQLPage: building a data web UI from .sql files

The gap SQLPage fills between a query console and a web app

Most teams have data that lives in a database and people who need to look at it, filter it and sometimes edit it. The usual answers are a BI tool, a hand-written internal app, or a shared query console. The first two take time to stand up, and the third gives non-technical users a way to run arbitrary SQL. SQLPage takes a different position: a page is a .sql file, and the result set of that file is the page. The README describes it as an SQL-only webapp builder that transforms "simple database queries into interactive websites". The audience is anyone who is comfortable writing SQL and does not want to write HTML, a JavaScript build, or a REST layer to expose a table. That includes analysts building a dashboard for their own team, backend engineers who need a quick admin screen, and people who want to publish a small public dataset without maintaining a web stack. It is not aimed at product teams shipping a customer-facing application with custom interaction design.

How a query becomes a component on the page

The mechanism is a convention on the result set. A query whose first column is a literal string naming a component, aliased as component, declares that component. Additional columns in that row become the component's properties, and subsequent rows become its data. The README's list example does exactly this: a first SELECT returns 'list' as component and 'Popular websites' as title, then a second SELECT returns name as title, url as link, and a CASE expression as color. The chart example is the same shape, with 'chart' as component, 'Quarterly Revenue' as title and 'area' as type, followed by a query that returns quarter AS x and SUM(revenue) AS y. A single .sql file can declare several components in sequence, and they render in order, which is how the tab example composes tabs, cards and a text block in one file. The server is written in Rust, uses actix-web for HTTP and handlebars for templates, and the frontend assets are Tabler, ApexCharts and tom-select according to package.json. The practical consequence is that there is no template language to learn for the common case: the structure of your result set is the structure of the page.

Installing SQLPage and rendering a first page

On macOS the README calls the Homebrew package the recommended installation method, including on Intel Macs. The commands are two lines, and after that you run sqlpage from the folder that holds your .sql files.

brew install sqlpage
brew update && brew upgrade sqlpage

The second line is the documented way to update an existing installation. On a server, the README recommends the Docker image and gives this command, where the volume mount lets SQLPage serve .sql files from your current working directory.

docker run -it --name sqlpage -p 8080:8080 --volume "$(pwd):/var/www" --rm lovasoa/sqlpage

If you also want a configuration file, custom components and migrations, the README shows mounting a second directory read-only at /etc/sqlpage. After the container is running, the README says to create a file called index.sql and open the server in a browser. A first page that proves the pipeline end to end is the list component: the first statement declares the component and the second supplies the rows.

SELECT 'list' as component, 'Popular websites' as title;
SELECT name as title, url as link, description, icon
FROM website;

What you should see is a titled list where each database row becomes an entry, with the link column rendered as the target. If the page renders empty, the usual cause is that the component declaration and the data query disagree about column names, because the column aliases are the API.

Forms, variables and where the SQL-only model gets awkward

Forms follow the same pattern with one addition: submitted values arrive as variables prefixed with a dollar sign. The README's form example declares 'form' as component with a validate label, selects the field definitions from a table, and then runs an INSERT that reads $first_name, $last_name and $birth_date, guarded by a WHERE clause so the insert only happens when the first name is present. That guard matters. Without it, the insert statement runs on the initial page load as well as on submit, and you get empty rows. This is the sharpest edge of the approach: the same file both describes the form and handles its submission, so every statement in the file is a statement the server will execute on every request. The README does not document a rollback or transaction control mechanism for multi-statement writes, so a form that needs to write to several tables atomically is a case where you should verify the behaviour yourself before relying on it. The same applies to authorization. The examples directory contains a CRUD authentication example, but authentication is not part of the core component set described in the README, so treat it as something you wire up rather than something you get.

Database coverage and the ODBC escape hatch

SQLPage ships native drivers for SQLite, PostgreSQL, MySQL and Microsoft SQL Server. The README lists compatible databases for each: YugabyteDB, CockroachDB and Aurora alongside PostgreSQL; MariaDB and TiDB alongside MySQL; Azure SQL and Amazon RDS alongside SQL Server. Anything else goes through ODBC, and the README names ClickHouse, MongoDB, DuckDB, Oracle, Snowflake, BigQuery and IBM DB2 as examples that work through their respective ODBC drivers. That is a wide net, but the cost is uneven. A native driver means the connection string is a URL and the feature set is whatever the sqlx-based layer supports. ODBC means you install a driver, and the repository's Dockerfile contains a separate Debian-based image variant for DuckDB specifically because the minimal busybox image will not carry an ODBC driver. The README also warns against using the raw SQLPage image as a base for your own, describing it as "extremely stripped down", and instead suggests copying the binary out of it into a Debian base. If you are on ODBC, budget for that image work.

SQLPage compared with a full web framework

The obvious alternative is a conventional stack: a framework such as Django, Rails or Express, a template layer, and an ORM. The difference is not speed of the runtime, it is where the page definition lives. In a framework, the route, the view function, the template and the model are separate artifacts, and the template is where presentation logic accumulates. In SQLPage, the query is the page, and presentation is expressed as column aliases and component names. That collapses a lot of boilerplate for read-mostly screens, and it collapses just as hard against anything that needs custom interaction. A framework gives you middleware, sessions, background jobs, a migration tool and a test story; SQLPage gives you a web root of .sql files and a configuration directory. The repository does carry a migrations concept, mentioned in the Docker section alongside the configuration directory, but the README does not describe it in detail, so if schema migration is a requirement, read configuration.md before deciding. The honest framing is that SQLPage replaces the view layer of an internal tool, not the application architecture around it.

Licence, maintenance and the cost of upgrading

SQLPage is MIT licensed, stated in Cargo.toml, package.json and the repository's LICENSE.txt. That is permissive: you can use it commercially, modify it and redistribute it, provided the copyright notice and permission notice are kept. It is not legal advice, and if you are embedding it in a product with unusual distribution terms, have someone check the notice requirements. On maintenance, the repository is not archived and the last push was on 2026-09-28. The release cadence visible in the release list is tight: v0.46.1 on 2026-09-03, v0.46.2 on 2026-09-12, v0.46.3 on 2026-09-17. Those are patch releases under a 0.x version, which is worth noting for upgrade cost. Pre-1.0 projects can change component names and configuration keys between minor versions, so pin the version you deploy rather than tracking latest. The Homebrew path makes upgrades a single command, and the Docker path makes them a tag change, but neither tells you whether a component's columns were renamed. Read CHANGELOG.md before each bump.

Editorial conclusion

Adopt SQLPage if you already have the data in a supported database and want a browsable, filterable interface without writing a frontend. Do not adopt it if you need custom client-side interaction, an ORM, or a component library you control at the pixel level. Before committing, run the Homebrew or Docker install against a copy of your real schema, load one page that joins several tables, and check in configuration.md how the connection string and the configuration directory are set, because that is where a deployment either works or does not.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. sqlpage/SQLPage on GitHub