Skip to content

Commit

Permalink
Improve configuration documentaition (#153)
Browse files Browse the repository at this point in the history 
* Fix typo

* Add default values for different RDBMS

I optimized for a nicer looking rendered table, but the not rendered
one looks slightly less beautiful now.
  • Loading branch information
@xxorde
xxorde authored Dec 14, 2023
1 parent cb39986 commit b47f703
Showing 1 changed file with 21 additions and 21 deletions.
42 changes: 21 additions & 21 deletions configuration.md
View file
Original file line number Diff line number Diff line change
@@ -1,30 +1,30 @@
# Configuring SQLPage

SQLPage can be configured through either [environment variables](https://en.wikipedia.org/wiki/Environment_variable)
on a [JSON](https://en.wikipedia.org/wiki/JSON) file placed in `sqlpage/sqlpage.json`.
or a [JSON](https://en.wikipedia.org/wiki/JSON) file placed in `sqlpage/sqlpage.json`.

You can find an example configuration file in [`sqlpage/sqlpage.json`](./sqlpage/sqlpage.json).
Here are the available configuration options and their default values:

| variable | default | description |
| ------------------------------------------ | ---------------------------- | ------------------------------------------------------------------------ |
| `listen_on` | 0.0.0.0:8080 | Interface and port on which the web server should listen |
| `database_url` | sqlite://sqlpage.db?mode=rwc | Database connection URL |
| `port` | 8080 | Like listen_on, but specifies only the port. |
| `max_database_pool_connections` | depends on the database | How many simultaneous database connections to open at most |
| `database_connection_idle_timeout_seconds` | depends on the database | Automatically close database connections after this period of inactivity |
| `database_connection_max_lifetime_seconds` | depends on the database | Always close database connections after this amount of time |
| `database_connection_retries` | 6 | Database connection attempts before giving up. Retries will happen every 5 seconds. |
| `database_connection_acquire_timeout_seconds` | 10 | How long to wait when acquiring a database connection from the pool before giving up and returning an error. |
| `sqlite_extensions` | | An array of SQLite extensions to load, such as `mod_spatialite` |
| `web_root` | `.` | The root directory of the web server, where the `index.sql` file is located. |
| `allow_exec` | false | Allow usage of the `sqlpage.exec` function. Do this only if all users with write access to sqlpage query files and to the optional `sqlpage_files` table on the database are trusted. |
| `max_uploaded_file_size` | 5242880 | Maximum size of uploaded files in bytes. Defaults to 5 MiB. |
| `https_domain` | | Domain name to request a certificate for. Setting this parameter will automatically make SQLPage listen on port 443 and request an SSL certificate. The server will take a little bit longer to start the first time it has to request a certificate. |
| `https_certificate_email` | contact@<https_domain> | The email address to use when requesting a certificate. |
| `https_certificate_cache_dir` | ./sqlpage/https | A writeable directory where to cache the certificates, so that SQLPage can serve https traffic immediately when it restarts. |
| `https_acme_directory_url` | https://acme-v02.api.letsencrypt.org/directory | The URL of the ACME directory to use when requesting a certificate. |
| `environment` | development | The environment in which SQLPage is running. Can be either `development` or `production`. In `production` mode, SQLPage will hide error messages and stack traces from the user, and will cache sql files in memory to avoid reloading them from disk. |
| variable | default | description |
| --------------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `listen_on` | 0.0.0.0:8080 | Interface and port on which the web server should listen |
| `database_url` | sqlite://sqlpage.db?mode=rwc | Database connection URL |
| `port` | 8080 | Like listen_on, but specifies only the port. |
| `max_database_pool_connections` | PostgreSQL: 50<BR> MySql: 75<BR> SQLite: 16<BR> MSSQL: 100 | How many simultaneous database connections to open at most |
| `database_connection_idle_timeout_seconds` | SQLite: None<BR> All other: 30 minutes | Automatically close database connections after this period of inactivity |
| `database_connection_max_lifetime_seconds` | SQLite: None<BR> All other: 60 minutes | Always close database connections after this amount of time |
| `database_connection_retries` | 6 | Database connection attempts before giving up. Retries will happen every 5 seconds. |
| `database_connection_acquire_timeout_seconds` | 10 | How long to wait when acquiring a database connection from the pool before giving up and returning an error. |
| `sqlite_extensions` | | An array of SQLite extensions to load, such as `mod_spatialite` |
| `web_root` | `.` | The root directory of the web server, where the `index.sql` file is located. |
| `allow_exec` | false | Allow usage of the `sqlpage.exec` function. Do this only if all users with write access to sqlpage query files and to the optional `sqlpage_files` table on the database are trusted. |
| `max_uploaded_file_size` | 5242880 | Maximum size of uploaded files in bytes. Defaults to 5 MiB. |
| `https_domain` | | Domain name to request a certificate for. Setting this parameter will automatically make SQLPage listen on port 443 and request an SSL certificate. The server will take a little bit longer to start the first time it has to request a certificate. |
| `https_certificate_email` | contact@<https_domain> | The email address to use when requesting a certificate. |
| `https_certificate_cache_dir` | ./sqlpage/https | A writeable directory where to cache the certificates, so that SQLPage can serve https traffic immediately when it restarts. |
| `https_acme_directory_url` | https://acme-v02.api.letsencrypt.org/directory | The URL of the ACME directory to use when requesting a certificate. |
| `environment` | development | The environment in which SQLPage is running. Can be either `development` or `production`. In `production` mode, SQLPage will hide error messages and stack traces from the user, and will cache sql files in memory to avoid reloading them from disk. |

Multiple configuration file formats are supported:
you can use a [`.json5`](https://json5.org/) file, a [`.toml`](https://toml.io/) file, or a [`.yaml`](https://en.wikipedia.org/wiki/YAML#Syntax) file.
Expand Down Expand Up @@ -95,4 +95,4 @@ You can also use this to create *temporary tables* to store intermediate results
CREATE TEMPORARY TABLE my_temporary_table(
my_temp_column TEXT
);
```
```

0 comments on commit b47f703

Please sign in to comment.