Installation - SQLPage

Overview

SQLPage is distributed as a single executable file with zero dependencies. Choose the installation method that best fits your workflow.

Executables

Download pre-built binaries for instant setup

Docker

Run in containers for easy deployment

Package Managers

Install via Homebrew, Scoop, or Cargo

Build from Source

Compile from the Rust source code

Using Executables

The fastest way to get started. Download the appropriate binary for your operating system.

Linux
macOS
Windows

Download and Extract

# Download the latest release
wget https://github.com/sqlpage/SQLPage/releases/latest/download/sqlpage-linux.tgz

# Extract
tar -xzf sqlpage-linux.tgz

# Make executable
chmod +x sqlpage.bin

# Run SQLPage
./sqlpage.bin

Install System-Wide (Optional)

sudo mv sqlpage.bin /usr/local/bin/sqlpage
sqlpage  # Run from anywhere

Linux binaries are compiled for x86_64. For ARM architectures (Raspberry Pi, ARM cloud instances), use the Docker image.

Download and Extract

# Download the latest release
wget https://github.com/sqlpage/SQLPage/releases/latest/download/sqlpage-macos.tgz

# Extract
tar -xzf sqlpage-macos.tgz

# Make executable
chmod +x sqlpage.bin

# Run SQLPage
./sqlpage.bin

Allow Execution (First Time)

macOS may block the executable. If you see a security warning:

Go to System Preferences → Security & Privacy
Click Allow Anyway next to the sqlpage.bin message
Run ./sqlpage.bin again

Prefer package managers? Use Homebrew instead.

Download and Extract

Download the latest release: sqlpage-windows.zip
Extract the ZIP file to a folder (e.g., C:\sqlpage)
Open Command Prompt or PowerShell in that folder
Run:

.\sqlpage.exe

Add to PATH (Optional)

To run sqlpage from anywhere:

Press Win + X and select System
Click Advanced system settings → Environment Variables
Under System variables, select Path → Edit
Click New and add C:\sqlpage (or your extraction folder)
Click OK and restart your terminal

Windows binaries are digitally signed by SignPath.io for your security.

Using Docker

Run SQLPage in a container with consistent behavior across all platforms. Docker images support x86_64, ARM64, and ARMv7.

Quick Start

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

This mounts your current directory as /var/www inside the container, allowing SQLPage to serve your .sql files.

Docker Compose

Create a docker-compose.yml for more complex setups:

docker-compose.yml

services:
  sqlpage:
    image: lovasoa/sqlpage:latest
    ports:
      - "8080:8080"
    volumes:
      - ./website:/var/www
      - ./config:/etc/sqlpage:ro
    environment:
      - DATABASE_URL=postgres://user:password@db:5432/myapp
    depends_on:
      - db

  db:
    image: postgres:16
    environment:
      - POSTGRES_PASSWORD=password
      - POSTGRES_USER=user
      - POSTGRES_DB=myapp
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:

Run with:

docker compose up

Docker Image Variants

SQLPage provides specialized images for different use cases:

Default (Minimal)
DuckDB

docker pull lovasoa/sqlpage:latest
docker pull lovasoa/sqlpage:main

Busybox-based, minimal size (~20 MB)
Supports SQLite, PostgreSQL, MySQL, SQL Server
No additional database drivers

docker pull lovasoa/sqlpage:latest-duckdb
docker pull lovasoa/sqlpage:main-duckdb

Debian-based with pre-installed DuckDB ODBC driver
Pre-configured to use DuckDB at /var/lib/sqlpage/duckdb.db
Perfect for analytics and data science workloads

Usage:

# Use default DuckDB location
docker run -p 8080:8080 \
  -v ./data:/var/lib/sqlpage \
  lovasoa/sqlpage:latest-duckdb

# Custom DuckDB location
docker run -p 8080:8080 \
  -e DATABASE_URL="Driver=DuckDB;Database=/data/my.duckdb" \
  -v ./my-data:/data \
  lovasoa/sqlpage:latest-duckdb

Custom Docker Image

To add your own dependencies or customize the environment:

Dockerfile

FROM debian:stable-slim

# Copy SQLPage binary from official image
COPY --from=lovasoa/sqlpage:main /usr/local/bin/sqlpage /usr/local/bin/sqlpage

# Add your custom setup
RUN apt-get update && apt-get install -y \
    ca-certificates \
    your-dependencies \
    && rm -rf /var/lib/apt/lists/*

# Copy your application
COPY ./website /var/www
COPY ./config /etc/sqlpage

EXPOSE 8080
CMD ["sqlpage"]

The official SQLPage image is intentionally minimal. Don’t use it as a base image directly—it won’t have the dependencies you need. Use Debian as shown above.

Package Managers

Homebrew (macOS)

The easiest installation method for macOS users:

# Install
brew install sqlpage

# Run
sqlpage

Scoop (Windows)

For Windows users who prefer command-line package management:

# Add the extras bucket (first time only)
scoop bucket add extras

# Install SQLPage
scoop install sqlpage

# Run
sqlpage

Cargo (Rust)

Install from source via Cargo:

# Install Rust if needed
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Install SQLPage
cargo install sqlpage --locked

# Run
sqlpage

Nix

For NixOS or Nix users:

nix-shell -p sqlpage

ODBC Setup (Optional)

SQLPage includes native drivers for SQLite, PostgreSQL, MySQL, and SQL Server. ODBC support is only needed for other databases like DuckDB, Snowflake, Oracle, BigQuery, MongoDB, or ClickHouse.

Skip this section if you’re using SQLite, PostgreSQL, MySQL, or SQL Server.

Linux

SQLPage binaries include a statically-linked unixODBC driver manager. You only need to install database-specific ODBC drivers.

DuckDB
Snowflake
Oracle

# Ubuntu/Debian
wget https://github.com/duckdb/duckdb/releases/latest/download/duckdb_odbc-linux-amd64.zip
unzip duckdb_odbc-linux-amd64.zip -d /opt/duckdb

# Configure connection
export DATABASE_URL="Driver=/opt/duckdb/libduckdb_odbc.so;Database=/path/to/my.duckdb"

Use the lovasoa/sqlpage:latest-duckdb Docker image to skip manual installation.

# Download from Snowflake
wget https://sfc-repo.snowflakecomputing.com/odbc/linux/latest/snowflake-odbc-<version>.x86_64.rpm

# Install (RHEL/CentOS)
sudo rpm -i snowflake-odbc-<version>.x86_64.rpm

# Install (Ubuntu/Debian)
sudo alien -i snowflake-odbc-<version>.x86_64.rpm

# Configure connection
export DATABASE_URL="Driver=/usr/lib/snowflake/odbc/lib/libSnowflake.so;Server=account.snowflakecomputing.com;Database=MY_DB;UID=user;PWD=password"

# Download Oracle Instant Client
wget https://download.oracle.com/otn_software/linux/instantclient/instantclient-odbc-linux.x64.zip
unzip instantclient-odbc-linux.x64.zip -d /opt/oracle

# Configure connection
export DATABASE_URL="Driver=/opt/oracle/instantclient_21_9/libsqora.so.21.1;Server=localhost:1521/XE;UID=user;PWD=password"

macOS

macOS binaries also include a statically-linked unixODBC driver manager:

# Install unixODBC (for driver management tools)
brew install unixodbc

# Install DuckDB ODBC driver example
brew install duckdb

# Configure connection
export DATABASE_URL="Driver=/usr/local/lib/libduckdb_odbc.dylib;Database=/path/to/my.duckdb"

Windows

Windows uses native ODBC drivers:

Download and install the ODBC driver for your database
Configure a DSN (Data Source Name) using ODBC Data Source Administrator:
- Press Win + R, type odbcad32, press Enter
- Go to System DSN tab → Add
- Select your driver and configure connection details
Set the connection string:

$env:DATABASE_URL="DSN=MyDataSource"

Or use a driver string directly:

$env:DATABASE_URL="Driver={PostgreSQL Unicode};Server=localhost;Database=mydb;UID=user;PWD=password"

ODBC Connection String Format

ODBC connection strings follow this pattern:

Driver=/path/to/driver.so;Server=hostname;Database=dbname;UID=user;PWD=password;[Additional=Options]

Examples:

DATABASE_URL="Driver=/opt/duckdb/libduckdb_odbc.so;Database=/data/analytics.duckdb"

Refer to your database’s official ODBC documentation for connection string parameters and driver paths.

Configuration

After installation, configure SQLPage using environment variables or a configuration file.

Environment Variables

Set environment variables before running SQLPage:

export DATABASE_URL="sqlite://myapp.db?mode=rwc"
export SQLPAGE_WEB_ROOT="/var/www/myapp"
export SQLPAGE_PORT=8080
sqlpage

Configuration File

Create sqlpage/sqlpage.json in your web root:

sqlpage/sqlpage.json

{
  "database_url": "postgres://user:password@localhost/myapp",
  "listen_on": "0.0.0.0:8080",
  "web_root": ".",
  "max_uploaded_file_size": 10485760
}

Configuration files support JSON, JSON5, TOML, and YAML formats.

Common Configuration Options

Option	Description	Default
`database_url`	Database connection string	`sqlite://sqlpage.db?mode=rwc`
`listen_on`	IP and port to bind	`0.0.0.0:8080`
`web_root`	Directory containing `.sql` files	`.` (current directory)
`configuration_directory`	Location of `sqlpage/` config folder	`./sqlpage/`
`https_domain`	Domain for automatic HTTPS/SSL	(disabled)
`environment`	`development` or `production`	`development`

See the Configuration Guide for all options.

Verify Installation

Test that SQLPage is working:

# Create a test page
echo "SELECT 'text' as component, 'SQLPage is working!' as contents;" > test.sql

# Start SQLPage
sqlpage

# Visit http://localhost:8080/test.sql

You should see “SQLPage is working!” in your browser.

Running as a Service

systemd (Linux)

Create /etc/systemd/system/sqlpage.service:

[Unit]
Description=SQLPage Web Server
After=network.target

[Service]
Type=simple
User=www-data
WorkingDirectory=/var/www/myapp
Environment="DATABASE_URL=postgres://user:pass@localhost/myapp"
ExecStart=/usr/local/bin/sqlpage
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable sqlpage
sudo systemctl start sqlpage
sudo systemctl status sqlpage

Docker with Restart Policy

docker run -d --name sqlpage \
  --restart unless-stopped \
  -p 8080:8080 \
  -v $(pwd)/website:/var/www \
  -v $(pwd)/data:/var/lib/sqlpage \
  lovasoa/sqlpage:latest

Next Steps

Quickstart Tutorial

Build your first application

Database Connections

Configure your database

HTTPS Setup

Enable automatic SSL certificates

Deployment Guide

Deploy to production

Troubleshooting

Port Already in Use

If port 8080 is occupied:

export SQLPAGE_PORT=3000
sqlpage

Permission Denied (Linux/macOS)

Ensure the binary is executable:

chmod +x sqlpage.bin

Database Connection Fails

Enable debug logging:

export RUST_LOG=sqlpage=debug
sqlpage

This will show detailed connection information.

Docker Volume Permissions

If SQLPage can’t write to mounted volumes:

# Fix ownership
sudo chown -R 1000:1000 ./website

# Or run as root (development only)
docker run --user root ...

Need Help?

Ask questions on GitHub Discussions

Get Started

Core Concepts

Configuration

Guides

​Overview

Executables

Docker

Package Managers

Build from Source

​Using Executables

​Download and Extract

​Install System-Wide (Optional)

​Download and Extract

​Allow Execution (First Time)

​Download and Extract

​Add to PATH (Optional)

​Using Docker

​Quick Start

​Docker Compose

​Docker Image Variants

​Custom Docker Image

​Package Managers

​Homebrew (macOS)

​Scoop (Windows)

​Cargo (Rust)

​Nix

​ODBC Setup (Optional)

​Linux

​macOS

​Windows

​ODBC Connection String Format

​Configuration

​Environment Variables

​Configuration File

​Common Configuration Options

​Verify Installation

​Running as a Service

​systemd (Linux)

​Docker with Restart Policy

​Next Steps

Quickstart Tutorial

Database Connections

HTTPS Setup

Deployment Guide

​Troubleshooting

​Port Already in Use

​Permission Denied (Linux/macOS)

​Database Connection Fails

​Docker Volume Permissions

Need Help?

Build docs developers (and LLMs) love

Overview

Using Executables

Download and Extract

Install System-Wide (Optional)

Download and Extract

Allow Execution (First Time)

Download and Extract

Add to PATH (Optional)

Using Docker

Quick Start

Docker Compose

Docker Image Variants

Custom Docker Image

Package Managers

Homebrew (macOS)

Scoop (Windows)

Cargo (Rust)

Nix

ODBC Setup (Optional)

Linux

macOS

Windows

ODBC Connection String Format

Configuration

Environment Variables

Configuration File

Common Configuration Options

Verify Installation

Running as a Service

systemd (Linux)

Docker with Restart Policy

Next Steps

Troubleshooting

Port Already in Use

Permission Denied (Linux/macOS)

Database Connection Fails

Docker Volume Permissions