Environment Variables Reference

This page provides a comprehensive reference of all environment variables that can be used to configure SQLPage.

Variable Naming

All configuration parameters can be set via environment variables using these rules:

Case insensitive - Use uppercase or lowercase
Optional prefix - Can be prefixed with SQLPAGE_
Same name as JSON key - Variable name matches the configuration file key

Examples:

DATABASE_URL="..."
SQLPAGE_DATABASE_URL="..."
database_url="..."
sqlpage_database_url="..."

All four forms above are equivalent. The SQLPAGE_ prefix is recommended to avoid conflicts with other applications.

Server Configuration

LISTEN_ON

string

default:"0.0.0.0:8080"

Interface and port on which the web server should listen.

LISTEN_ON="0.0.0.0:8080"
LISTEN_ON="127.0.0.1:3000"
LISTEN_ON="[::]:8080"  # IPv6

PORT

integer

default:"8080"

Port number to listen on. Overrides the port in LISTEN_ON.

PORT=3000

UNIX_SOCKET

string

Path to a UNIX socket to listen on instead of TCP port. Mutually exclusive with LISTEN_ON and PORT.

UNIX_SOCKET="/var/run/sqlpage.sock"

HOST

string

The web address where your application is accessible. Used for OIDC redirects.

HOST="myapp.example.com"

SITE_PREFIX

string

default:"/"

Base path of the site. Useful when hosting SQLPage behind a reverse proxy alongside other applications.

SITE_PREFIX="/sqlpage/"
SITE_PREFIX="/apps/myapp/"

Database Configuration

DATABASE_URL

string

default:"sqlite://sqlpage.db?mode=rwc"

Database connection URL. Supports SQLite, PostgreSQL, MySQL, MSSQL, and ODBC connection strings.

# SQLite
DATABASE_URL="sqlite://sqlpage.db?mode=rwc"
DATABASE_URL="sqlite://:memory:?cache=shared"

# PostgreSQL
DATABASE_URL="postgres://user:pass@localhost:5432/dbname"
DATABASE_URL="postgres://user:pass@localhost/db?sslmode=require"

# MySQL
DATABASE_URL="mysql://user:pass@localhost:3306/dbname"

# MSSQL
DATABASE_URL="mssql://user:pass@localhost:1433/dbname"

# ODBC
DATABASE_URL="DSN=MyDatabase"
DATABASE_URL="Driver={PostgreSQL};Server=localhost;Database=mydb"

DATABASE_PASSWORD

string

Database password. Overrides any password in DATABASE_URL. Does not need percent-encoding.

DATABASE_URL="postgres://myuser@localhost/mydb"
DATABASE_PASSWORD="my_secure_p@ssw0rd"

MAX_DATABASE_POOL_CONNECTIONS

integer

Maximum number of simultaneous database connections.Defaults:

PostgreSQL: 50
MySQL: 75
SQLite: 16
MSSQL: 100

MAX_DATABASE_POOL_CONNECTIONS=50

DATABASE_CONNECTION_IDLE_TIMEOUT_SECONDS

number

Close idle connections after this many seconds. Set to 0 to disable.Defaults:

SQLite: No timeout
Others: 1800 (30 minutes)

DATABASE_CONNECTION_IDLE_TIMEOUT_SECONDS=600

DATABASE_CONNECTION_MAX_LIFETIME_SECONDS

number

Close all connections after this many seconds. Set to 0 to disable.Defaults:

SQLite: No limit
Others: 3600 (60 minutes)

DATABASE_CONNECTION_MAX_LIFETIME_SECONDS=1800

DATABASE_CONNECTION_ACQUIRE_TIMEOUT_SECONDS

number

default:"10"

Timeout when acquiring a connection from the pool.

DATABASE_CONNECTION_ACQUIRE_TIMEOUT_SECONDS=5

DATABASE_CONNECTION_RETRIES

integer

default:"6"

Connection attempts at startup before giving up. Retries happen every 5 seconds.

DATABASE_CONNECTION_RETRIES=12  # Wait up to 60 seconds

SQLITE_EXTENSIONS

string

Space-separated list of SQLite extensions to load.

SQLITE_EXTENSIONS="mod_spatialite crypto define regexp"

Directory Configuration

WEB_ROOT

string

default:"."

Root directory where .sql files are located.

WEB_ROOT="/var/www/sqlpage"
WEB_ROOT="./website"

CONFIGURATION_DIRECTORY

string

default:"./sqlpage/"

Directory containing sqlpage.json, templates/, migrations/, etc.

This can only be set via environment variable or command-line argument, not in the configuration file.

CONFIGURATION_DIRECTORY="/etc/sqlpage"
SQLPAGE_CONFIGURATION_DIRECTORY="./config"

HTTPS Configuration

HTTPS_DOMAIN

string

Domain name for automatic HTTPS certificate via Let’s Encrypt.

HTTPS_DOMAIN="myapp.example.com"

HTTPS_CERTIFICATE_EMAIL

string

Email for Let’s Encrypt certificate notifications. Defaults to contact@<https_domain>.

HTTPS_CERTIFICATE_EMAIL="admin@example.com"

HTTPS_CERTIFICATE_CACHE_DIR

string

default:"./sqlpage/https"

Directory to cache HTTPS certificates.

HTTPS_CERTIFICATE_CACHE_DIR="/var/cache/sqlpage/https"

HTTPS_ACME_DIRECTORY_URL

string

default:"https://acme-v02.api.letsencrypt.org/directory"

ACME directory URL for certificate requests.

# Production (default)
HTTPS_ACME_DIRECTORY_URL="https://acme-v02.api.letsencrypt.org/directory"

# Staging (for testing)
HTTPS_ACME_DIRECTORY_URL="https://acme-staging-v02.api.letsencrypt.org/directory"

OIDC Authentication

OIDC_ISSUER_URL

string

OpenID Connect provider base URL. Required for enabling Single Sign-On.

# Google
OIDC_ISSUER_URL="https://accounts.google.com"

# Microsoft
OIDC_ISSUER_URL="https://login.microsoftonline.com/{tenant}/v2.0"

# Keycloak
OIDC_ISSUER_URL="https://keycloak.example.com/auth/realms/myrealm"

OIDC_CLIENT_ID

string

default:"sqlpage"

Client ID from your OIDC provider.

OIDC_CLIENT_ID="my-sqlpage-app"

OIDC_CLIENT_SECRET

string

Client secret from your OIDC provider. Keep this confidential.

OIDC_CLIENT_SECRET="your-secret-here"

OIDC_SCOPES

string

default:"openid email profile"

Space-separated list of OAuth scopes to request.

OIDC_SCOPES="openid email profile groups"

OIDC_PROTECTED_PATHS

string

default:"/"

Space-separated list of URL prefixes that require authentication.

OIDC_PROTECTED_PATHS="/admin /users/settings"
OIDC_PROTECTED_PATHS="/"  # Protect all paths

OIDC_PUBLIC_PATHS

string

Space-separated list of URL prefixes that are publicly accessible.

OIDC_PUBLIC_PATHS="/public /assets /api/health"

OIDC_ADDITIONAL_TRUSTED_AUDIENCES

string

Space-separated list of additional trusted JWT audiences beyond the client ID.

OIDC_ADDITIONAL_TRUSTED_AUDIENCES="audience1 audience2"

Security Configuration

ALLOW_EXEC

boolean

default:"false"

Allow sqlpage.exec() function to execute shell commands.

Only enable if you trust all SQL query authors.

ALLOW_EXEC=true
ALLOW_EXEC=false

MAX_UPLOADED_FILE_SIZE

integer

default:"5242880"

Maximum size of uploaded files in bytes (default: 5 MiB).

MAX_UPLOADED_FILE_SIZE=10485760  # 10 MiB
MAX_UPLOADED_FILE_SIZE=52428800  # 50 MiB

CONTENT_SECURITY_POLICY

string

default:"script-src 'self' 'nonce-{NONCE}'"

Content Security Policy header value.

CONTENT_SECURITY_POLICY="script-src 'self' 'nonce-{NONCE}'; style-src 'self'"
CONTENT_SECURITY_POLICY=""  # Disable CSP

SYSTEM_ROOT_CA_CERTIFICATES

boolean

default:"false"

Use system root CA certificates for sqlpage.fetch() SSL validation.

SYSTEM_ROOT_CA_CERTIFICATES=true

MARKDOWN_ALLOW_DANGEROUS_HTML

boolean

default:"false"

Allow raw HTML in markdown content.

Only enable for trusted markdown content.

MARKDOWN_ALLOW_DANGEROUS_HTML=true

MARKDOWN_ALLOW_DANGEROUS_PROTOCOL

boolean

default:"false"

Allow dangerous protocols like javascript: in markdown links.

Only enable for trusted markdown content.

MARKDOWN_ALLOW_DANGEROUS_PROTOCOL=true

Performance Configuration

ENVIRONMENT

string

default:"development"

Runtime environment: development or production.In production:

Errors are hidden from users
SQL files are cached in memory
Cache stale duration defaults to 1 second

ENVIRONMENT=production
ENVIRONMENT=development

CACHE_STALE_DURATION_MS

integer

Milliseconds before checking if a cached file is fresh. Defaults to 1000ms in production, 0ms in development.

CACHE_STALE_DURATION_MS=5000  # 5 seconds
CACHE_STALE_DURATION_MS=0     # Always check

MAX_PENDING_ROWS

integer

default:"256"

Maximum rendered rows queued in memory for slow clients.

MAX_PENDING_ROWS=512

COMPRESS_RESPONSES

boolean

default:"false"

Compress HTTP response bodies when supported by the client.

COMPRESS_RESPONSES=true

MAX_RECURSION_DEPTH

integer

default:"10"

Maximum recursion depth for run_sql() function.

MAX_RECURSION_DEPTH=20

Debugging

RUST_LOG

string

Control logging verbosity. Not a SQLPage-specific variable, but very useful for debugging.

RUST_LOG=sqlpage=debug     # Debug SQLPage only
RUST_LOG=debug             # Debug everything
RUST_LOG=info              # Info and above
RUST_LOG=sqlpage=trace     # Very verbose

SSL_CERT_FILE

string

Path to SSL certificate file for sqlpage.fetch() to use.

SSL_CERT_FILE="/etc/ssl/certs/ca-certificates.crt"

SSL_CERT_DIR

string

Directory containing SSL certificates for sqlpage.fetch() to use.

SSL_CERT_DIR="/etc/ssl/certs"

Example .env Files

Basic Setup

# Basic .env file
DATABASE_URL="sqlite://sqlpage.db?mode=rwc"
LISTEN_ON="0.0.0.0:8080"
ENVIRONMENT="development"

Production with PostgreSQL

# Production .env file
DATABASE_URL="postgres://sqlpage_user@localhost/sqlpage_db"
DATABASE_PASSWORD="your_secure_password"
MAX_DATABASE_POOL_CONNECTIONS=50
DATABASE_CONNECTION_IDLE_TIMEOUT_SECONDS=600

HTTPS_DOMAIN="myapp.example.com"
HTTPS_CERTIFICATE_EMAIL="admin@example.com"

ENVIRONMENT="production"
COMPRESS_RESPONSES=true
CACHE_STALE_DURATION_MS=5000

CONTENT_SECURITY_POLICY="script-src 'self' 'nonce-{NONCE}'; style-src 'self' 'unsafe-inline'"

With OIDC Authentication

# OIDC .env file
DATABASE_URL="postgres://user@localhost/db"
DATABASE_PASSWORD="password"

HTTPS_DOMAIN="myapp.example.com"

OIDC_ISSUER_URL="https://accounts.google.com"
OIDC_CLIENT_ID="123456789.apps.googleusercontent.com"
OIDC_CLIENT_SECRET="your_client_secret"
OIDC_SCOPES="openid email profile"
OIDC_PROTECTED_PATHS="/admin /dashboard"
OIDC_PUBLIC_PATHS="/public /api/health"

ENVIRONMENT="production"

Docker Deployment

# Docker .env file
DATABASE_URL="postgres://sqlpage:password@db:5432/sqlpage"
LISTEN_ON="0.0.0.0:8080"
CONFIGURATION_DIRECTORY="/etc/sqlpage"
WEB_ROOT="/var/www"
ENVIRONMENT="production"
RUST_LOG=info

Tips

Use .env files for local development

Create a .env file in your project root and add it to .gitignore. SQLPage automatically loads it.

echo ".env" >> .gitignore

Use SQLPAGE_ prefix in shared environments

The SQLPAGE_ prefix prevents conflicts with other applications:

SQLPAGE_DATABASE_URL="..."
SQLPAGE_PORT=8080

Override configuration file with environment variables

Environment variables take precedence over configuration files, making it easy to override settings in different environments:

# Development
ENVIRONMENT=development DATABASE_URL="sqlite::memory:" sqlpage

# Production
ENVIRONMENT=production DATABASE_URL="$PROD_DB_URL" sqlpage

Use DATABASE_PASSWORD for secrets

Keep passwords separate from connection strings:

DATABASE_URL="postgres://user@localhost/db"
DATABASE_PASSWORD="$(cat /run/secrets/db_password)"

Enable debug logging when troubleshooting

See exactly what SQLPage is doing:

RUST_LOG=sqlpage=debug sqlpage

Configuration Overview

Learn about all configuration methods

Database Connections

Configure database connections

HTTPS & SSL

Set up automatic HTTPS

Deployment

Deploy SQLPage to production

Get Started

Core Concepts

Configuration

Guides

​Variable Naming

​Server Configuration

​LISTEN_ON

​PORT

​UNIX_SOCKET

​HOST

​SITE_PREFIX

​Database Configuration

​DATABASE_URL

​DATABASE_PASSWORD

​MAX_DATABASE_POOL_CONNECTIONS

​DATABASE_CONNECTION_IDLE_TIMEOUT_SECONDS

​DATABASE_CONNECTION_MAX_LIFETIME_SECONDS

​DATABASE_CONNECTION_ACQUIRE_TIMEOUT_SECONDS

​DATABASE_CONNECTION_RETRIES

​SQLITE_EXTENSIONS

​Directory Configuration

​WEB_ROOT

​CONFIGURATION_DIRECTORY

​HTTPS Configuration

​HTTPS_DOMAIN

​HTTPS_CERTIFICATE_EMAIL

​HTTPS_CERTIFICATE_CACHE_DIR

​HTTPS_ACME_DIRECTORY_URL

​OIDC Authentication

​OIDC_ISSUER_URL

​OIDC_CLIENT_ID

​OIDC_CLIENT_SECRET

​OIDC_SCOPES

​OIDC_PROTECTED_PATHS

​OIDC_PUBLIC_PATHS

​OIDC_ADDITIONAL_TRUSTED_AUDIENCES

​Security Configuration

​ALLOW_EXEC

​MAX_UPLOADED_FILE_SIZE

​CONTENT_SECURITY_POLICY

​SYSTEM_ROOT_CA_CERTIFICATES

​MARKDOWN_ALLOW_DANGEROUS_HTML

​MARKDOWN_ALLOW_DANGEROUS_PROTOCOL

​Performance Configuration

​ENVIRONMENT

​CACHE_STALE_DURATION_MS

​MAX_PENDING_ROWS

​COMPRESS_RESPONSES

​MAX_RECURSION_DEPTH

​Debugging

​RUST_LOG

​SSL_CERT_FILE

​SSL_CERT_DIR

​Example .env Files

​Basic Setup

​Production with PostgreSQL

​With OIDC Authentication

​Docker Deployment

​Tips

​Related Topics

Configuration Overview

Database Connections

HTTPS & SSL

Deployment

Build docs developers (and LLMs) love

Variable Naming

Server Configuration

LISTEN_ON

PORT

UNIX_SOCKET

HOST

SITE_PREFIX

Database Configuration

DATABASE_URL

DATABASE_PASSWORD

MAX_DATABASE_POOL_CONNECTIONS

DATABASE_CONNECTION_IDLE_TIMEOUT_SECONDS

DATABASE_CONNECTION_MAX_LIFETIME_SECONDS

DATABASE_CONNECTION_ACQUIRE_TIMEOUT_SECONDS

DATABASE_CONNECTION_RETRIES

SQLITE_EXTENSIONS

Directory Configuration

WEB_ROOT

CONFIGURATION_DIRECTORY

HTTPS Configuration

HTTPS_DOMAIN

HTTPS_CERTIFICATE_EMAIL

HTTPS_CERTIFICATE_CACHE_DIR

HTTPS_ACME_DIRECTORY_URL

OIDC Authentication

OIDC_ISSUER_URL

OIDC_CLIENT_ID

OIDC_CLIENT_SECRET

OIDC_SCOPES

OIDC_PROTECTED_PATHS

OIDC_PUBLIC_PATHS

OIDC_ADDITIONAL_TRUSTED_AUDIENCES

Security Configuration

ALLOW_EXEC

MAX_UPLOADED_FILE_SIZE

CONTENT_SECURITY_POLICY

SYSTEM_ROOT_CA_CERTIFICATES

MARKDOWN_ALLOW_DANGEROUS_HTML

MARKDOWN_ALLOW_DANGEROUS_PROTOCOL

Performance Configuration

ENVIRONMENT

CACHE_STALE_DURATION_MS

MAX_PENDING_ROWS

COMPRESS_RESPONSES

MAX_RECURSION_DEPTH

Debugging

RUST_LOG

SSL_CERT_FILE

SSL_CERT_DIR

Example .env Files

Basic Setup

Production with PostgreSQL

With OIDC Authentication

Docker Deployment

Tips

Related Topics