Skip to main content
SQLPage can be configured through multiple methods, giving you flexibility in how you manage your application settings. Configuration options control everything from database connections to security settings and server behavior.

​
Configuration Methods

SQLPage supports three ways to set configuration options, listed in order of priority (highest to lowest):
  1. Command-line arguments - Override specific settings when starting SQLPage
  2. Environment variables - Set via your shell or .env file
  3. Configuration file - JSON, JSON5, TOML, or YAML file in sqlpage/sqlpage.json

​
Configuration File

Place a configuration file at sqlpage/sqlpage.json (or use .json5, .toml, or .yaml extensions). Example JSON configuration: 
{
  "database_url": "postgres://user:password@localhost:5432/mydb",
  "listen_on": "0.0.0.0:8080",
  "environment": "production",
  "max_database_pool_connections": 50,
  "allow_exec": false
}
Example YAML configuration: 
database_url: postgres://user:password@localhost:5432/mydb
listen_on: 0.0.0.0:8080
environment: production
max_database_pool_connections: 50
allow_exec: false

​
Environment Variables

All configuration parameters can be set via environment variables. Variable names are the same as the JSON configuration keys, but in UPPERCASE. You can optionally prefix variable names with SQLPAGE_. Example: 
export DATABASE_URL="postgres://user:password@localhost:5432/mydb"
export SQLPAGE_LISTEN_ON="0.0.0.0:8080"
export ENVIRONMENT="production"

​
.env File Support

SQLPage automatically loads environment variables from a .env file in the current directory or any parent directory. Example .env file: 
DATABASE_URL="postgres://my_user@localhost:5432/my_database"
DATABASE_PASSWORD="my_secure_password"
SQLITE_EXTENSIONS="mod_spatialite crypto define regexp"
ENVIRONMENT="production"

​
Key Configuration Parameters

​
Server Settings

​
listen_on
string
default:"0.0.0.0:8080"
Interface and port on which the web server should listen. Use 0.0.0.0 to listen on all interfaces.
​
port
integer
default:"8080"
Like listen_on, but specifies only the port. This option overrides the port in listen_on.
​
unix_socket
string
Path to a UNIX socket to listen on instead of a TCP port. If specified, SQLPage will accept HTTP connections only on this socket and not on any TCP port. This option is mutually exclusive with listen_on and port.
​
host
string
The web address where your application is accessible (e.g., “myapp.example.com”). Used for login redirects with OIDC.
​
site_prefix
string
default:"/"
Base path of the site. If you want to host SQLPage at https://example.com/sqlpage/, set this to /sqlpage/. When using a reverse proxy, this allows hosting SQLPage together with other applications on the same subdomain.

​
Directory Settings

​
web_root
string
default:"."
The root directory of the web server, where the index.sql file is located. All .sql files served by SQLPage should be in this directory.
​
configuration_directory
string
default:"./sqlpage/"
The directory where the sqlpage.json file is located. This is used to find the path to templates/, migrations/, and on_connect.sql. This parameter can only be set through environment variables or command-line arguments.
Be careful not to use a path that is accessible from the public web_root.

​
Environment Mode

​
environment
string
default:"development"
The environment in which SQLPage is running. Can be either development or production.In production mode:
  • Error messages and stack traces are hidden from users
  • SQL files are cached in memory to avoid reloading from disk
  • Cache stale duration defaults to 1 second (vs 0 in development)
​
cache_stale_duration_ms
integer
The duration in milliseconds that a file can be cached before its freshness is checked against the filesystem. Defaults to 1000ms (1 second) in production and 0ms in development.

​
Security Settings

​
allow_exec
boolean
default:"false"
Allow usage of the sqlpage.exec function. Only enable this if all users with write access to SQLPage query files and to the optional sqlpage_files table on the database are trusted.
Enabling this gives SQL queries the ability to execute arbitrary shell commands on the server.
​
content_security_policy
string
default:"script-src 'self' 'nonce-{NONCE}'"
The Content Security Policy to set in the HTTP headers. If you get CSP errors in the browser console, you can set this to an empty string to disable CSP. If you want a custom CSP that contains a nonce, include the 'nonce-{NONCE}' directive and it will be populated with a random value per request.
​
max_uploaded_file_size
integer
default:"5242880"
Maximum size of forms and uploaded files in bytes. Defaults to 5 MiB (5,242,880 bytes).

​
Performance Settings

​
max_pending_rows
integer
default:"256"
Maximum number of rendered rows that can be queued up in memory when a client is slow to receive them. This prevents a single request from using up all available memory.
​
compress_responses
boolean
default:"false"
When the client supports it, compress the HTTP response body. This can save bandwidth and speed up page loading on slow connections, but can also increase CPU usage and cause rendering delays on pages that take time to render (because streaming responses are buffered for longer than necessary).
​
max_recursion_depth
integer
default:"10"
Maximum depth of recursion allowed in the run_sql function.

​
Markdown Settings

​
markdown_allow_dangerous_html
boolean
default:"false"
Whether to allow raw HTML in markdown content. Only enable this if the markdown content is fully trusted (not user generated).
Enabling this with untrusted content can lead to XSS vulnerabilities.
​
markdown_allow_dangerous_protocol
boolean
default:"false"
Whether to allow dangerous protocols (like javascript:) in markdown links. Only enable this if the markdown content is fully trusted (not user generated).

​
SSL/TLS Settings

​
system_root_ca_certificates
boolean
default:"false"
Whether to use the system root CA certificates to validate SSL certificates when making HTTP requests with sqlpage.fetch. If set to false, SQLPage will use its own set of root CA certificates. If the SSL_CERT_FILE or SSL_CERT_DIR environment variables are set, they will be used instead of the system root CA certificates.

​
Debugging Configuration

To see detailed logs about what SQLPage is doing, set the RUST_LOG environment variable: 
export RUST_LOG=sqlpage=debug
This will show you:
  • Which configuration file is being loaded
  • How configuration values are resolved
  • Database connection details
  • Request routing information
  • And much more

​
Configuration Directory Structure

The configuration directory (default: ./sqlpage/) can contain:
  • sqlpage.json (or .json5, .toml, .yaml) - Configuration file
  • templates/ - Custom component templates
  • migrations/ - Database migration scripts
  • on_connect.sql - SQL to run when opening database connections
  • on_reset.sql - SQL to run when returning connections to the pool
  • https/ - HTTPS certificate cache (when using automatic HTTPS)

Database Connections

Configure database connections and connection pooling

HTTPS & SSL

Set up automatic HTTPS with Let’s Encrypt

Environment Variables

Complete reference of all environment variables

Custom Components

Create custom UI components

Build docs developers (and LLMs) love

Get started for freeTalk to us