From a740c0e357b8fd6ae5da433c19ce5b211a42d101 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 3 Nov 2025 20:47:01 +0000 Subject: [PATCH 1/5] Docs: Add Nginx streaming and compression configuration Co-authored-by: contact --- examples/nginx/README.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/examples/nginx/README.md b/examples/nginx/README.md index e1b838b2..1238d91c 100644 --- a/examples/nginx/README.md +++ b/examples/nginx/README.md @@ -43,6 +43,24 @@ This service sets up a MySQL database with predefined credentials and a persiste The `nginx.conf` file contains the NGINX configuration: +### Streaming and compression + +SQLPage streams HTML as it is generated, so browsers can start rendering before the database finishes returning rows. To keep that behaviour through NGINX, prefer minimal buffering and let the proxy handle compression: + +``` + proxy_buffering off; + + gzip on; + gzip_buffers 2 4k; + gzip_types text/html text/plain text/css application/javascript application/json; + + chunked_transfer_encoding on; +``` + +Disabling buffering lowers latency but increases the number of active connections; tune the gzip settings to balance CPU cost versus bandwidth, and re-enable buffering only if you need request coalescing or traffic smoothing. See the [proxy buffering](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffering), [gzip](https://nginx.org/en/docs/http/ngx_http_gzip_module.html), and [chunked transfer](https://nginx.org/en/docs/http/ngx_http_core_module.html#chunked_transfer_encoding) directives for more guidance. + +When SQLPage runs behind a reverse proxy, set `compress_responses` to `false` in its configuration (documented [here](https://github.com/sqlpage/SQLPage/blob/main/configuration.md)) so that NGINX can perform compression once at the edge. + ### Rate Limiting From b8b370c1370891d29e09912148b481152645ed88 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 3 Nov 2025 20:49:22 +0000 Subject: [PATCH 2/5] Add NGINX streaming and compression configuration Co-authored-by: contact --- .../your-first-sql-website/nginx.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/examples/official-site/your-first-sql-website/nginx.md b/examples/official-site/your-first-sql-website/nginx.md index b910114a..3cec518d 100644 --- a/examples/official-site/your-first-sql-website/nginx.md +++ b/examples/official-site/your-first-sql-website/nginx.md @@ -52,6 +52,24 @@ server { } ``` +### Streaming and compression + +SQLPage streams HTML as it is generated, so browsers start rendering before the database finishes returning rows. Preserve that behaviour in NGINX by keeping buffering minimal and letting the proxy handle compression: + +```nginx + proxy_buffering off; + + gzip on; + gzip_buffers 2 4k; + gzip_types text/html text/plain text/css application/javascript application/json; + + chunked_transfer_encoding on; +``` + +Turning off buffering lowers latency but increases how many concurrent connections reach SQLPage; only raise the buffers if you need to smooth bursty traffic. Adjust the gzip buffers for your CPU versus bandwidth trade-off, and toggle chunked transfer to keep streaming with HTTP/1.1 clients. See the official guidance for [proxy buffering](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffering), [gzip](https://nginx.org/en/docs/http/ngx_http_gzip_module.html), and [chunked transfer](https://nginx.org/en/docs/http/ngx_http_core_module.html#chunked_transfer_encoding). + +When SQLPage runs behind a reverse proxy, set `compress_responses` to `false` so NGINX can compress once at the edge (documented [here](https://github.com/sqlpage/SQLPage/blob/main/configuration.md)). + Save the file and create a symbolic link to it in the `/etc/nginx/sites-enabled/` directory: ```bash sudo ln -s /etc/nginx/sites-available/sqlpage /etc/nginx/sites-enabled/sqlpage From d562c5958ebcd8a2a2d6b9a0bcc4ef43563eb17e Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 3 Nov 2025 20:52:38 +0000 Subject: [PATCH 3/5] Refactor NGINX proxy settings documentation for clarity Co-authored-by: contact --- examples/official-site/your-first-sql-website/nginx.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/examples/official-site/your-first-sql-website/nginx.md b/examples/official-site/your-first-sql-website/nginx.md index 3cec518d..44a42d7f 100644 --- a/examples/official-site/your-first-sql-website/nginx.md +++ b/examples/official-site/your-first-sql-website/nginx.md @@ -52,9 +52,9 @@ server { } ``` -### Streaming and compression +### Streaming-friendly proxy settings -SQLPage streams HTML as it is generated, so browsers start rendering before the database finishes returning rows. Preserve that behaviour in NGINX by keeping buffering minimal and letting the proxy handle compression: +SQLPage streams HTML by default so the browser can render results while the database is still sending rows. To preserve this low-latency behaviour through NGINX, add the following directives inside the same `location` block as `proxy_pass`: ```nginx proxy_buffering off; @@ -66,9 +66,9 @@ SQLPage streams HTML as it is generated, so browsers start rendering before the chunked_transfer_encoding on; ``` -Turning off buffering lowers latency but increases how many concurrent connections reach SQLPage; only raise the buffers if you need to smooth bursty traffic. Adjust the gzip buffers for your CPU versus bandwidth trade-off, and toggle chunked transfer to keep streaming with HTTP/1.1 clients. See the official guidance for [proxy buffering](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffering), [gzip](https://nginx.org/en/docs/http/ngx_http_gzip_module.html), and [chunked transfer](https://nginx.org/en/docs/http/ngx_http_core_module.html#chunked_transfer_encoding). +Disabling buffering lets responses reach clients immediately but increases how many simultaneous connections SQLPage must serve; raise the buffers only if you prefer smoothing bursts over fastest-first rendering. Tune the gzip buffer count and size to balance CPU cost and bandwidth, and keep chunked transfer enabled so streaming works with HTTP/1.1 clients. Consult the official NGINX documentation for [proxy buffering](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffering), [gzip](https://nginx.org/en/docs/http/ngx_http_gzip_module.html), and [chunked transfer](https://nginx.org/en/docs/http/ngx_http_core_module.html#chunked_transfer_encoding) when adjusting these values. If you later implement heavy caching (see the section below), you may choose to reintroduce buffering for specific locations. -When SQLPage runs behind a reverse proxy, set `compress_responses` to `false` so NGINX can compress once at the edge (documented [here](https://github.com/sqlpage/SQLPage/blob/main/configuration.md)). +When SQLPage sits behind a reverse proxy, set `compress_responses` to `false` in `sqlpage.json` so that NGINX compresses once at the edge (documented [here](https://github.com/sqlpage/SQLPage/blob/main/configuration.md)). Save the file and create a symbolic link to it in the `/etc/nginx/sites-enabled/` directory: ```bash From 69e0fb3eab7ed9bc66d2b3882e12086b14c19a29 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 3 Nov 2025 21:03:47 +0000 Subject: [PATCH 4/5] Refine NGINX proxy buffering recommendations for streaming Co-authored-by: contact --- examples/nginx/README.md | 8 +++++--- examples/official-site/your-first-sql-website/nginx.md | 8 +++++--- 2 files changed, 10 insertions(+), 6 deletions(-) diff --git a/examples/nginx/README.md b/examples/nginx/README.md index 1238d91c..46f38ee8 100644 --- a/examples/nginx/README.md +++ b/examples/nginx/README.md @@ -45,10 +45,12 @@ The `nginx.conf` file contains the NGINX configuration: ### Streaming and compression -SQLPage streams HTML as it is generated, so browsers can start rendering before the database finishes returning rows. To keep that behaviour through NGINX, prefer minimal buffering and let the proxy handle compression: +SQLPage streams HTML as it is generated, so browsers can start rendering before the database finishes returning rows. NGINX enables `proxy_buffering` by default, which can delay those first bytes but stores responses for slow clients. Start with a modest buffer configuration and let the proxy handle compression: ``` - proxy_buffering off; + proxy_buffering on; + proxy_buffer_size 16k; + proxy_buffers 4 16k; gzip on; gzip_buffers 2 4k; @@ -57,7 +59,7 @@ SQLPage streams HTML as it is generated, so browsers can start rendering before chunked_transfer_encoding on; ``` -Disabling buffering lowers latency but increases the number of active connections; tune the gzip settings to balance CPU cost versus bandwidth, and re-enable buffering only if you need request coalescing or traffic smoothing. See the [proxy buffering](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffering), [gzip](https://nginx.org/en/docs/http/ngx_http_gzip_module.html), and [chunked transfer](https://nginx.org/en/docs/http/ngx_http_core_module.html#chunked_transfer_encoding) directives for more guidance. +Keep buffering when you expect slow clients or longer SQLPage queries, increasing the buffer sizes only if responses overflow. When most users are on fast connections reading lightweight pages, consider reducing the buffer counts or flipping to `proxy_buffering off;` to minimise latency, accepting the extra load on SQLPage. See the [proxy buffering](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffering), [gzip](https://nginx.org/en/docs/http/ngx_http_gzip_module.html), and [chunked transfer](https://nginx.org/en/docs/http/ngx_http_core_module.html#chunked_transfer_encoding) directives for more guidance. When SQLPage runs behind a reverse proxy, set `compress_responses` to `false` in its configuration (documented [here](https://github.com/sqlpage/SQLPage/blob/main/configuration.md)) so that NGINX can perform compression once at the edge. diff --git a/examples/official-site/your-first-sql-website/nginx.md b/examples/official-site/your-first-sql-website/nginx.md index 44a42d7f..c41bcebc 100644 --- a/examples/official-site/your-first-sql-website/nginx.md +++ b/examples/official-site/your-first-sql-website/nginx.md @@ -54,10 +54,12 @@ server { ### Streaming-friendly proxy settings -SQLPage streams HTML by default so the browser can render results while the database is still sending rows. To preserve this low-latency behaviour through NGINX, add the following directives inside the same `location` block as `proxy_pass`: +SQLPage streams HTML by default so the browser can render results while the database is still sending rows. NGINX keeps `proxy_buffering` enabled by default, which smooths bursts and protects upstreams from slow clients at the cost of delaying the first bytes. Start with these directives inside the same `location` block as `proxy_pass`: ```nginx - proxy_buffering off; + proxy_buffering on; + proxy_buffer_size 16k; + proxy_buffers 4 16k; gzip on; gzip_buffers 2 4k; @@ -66,7 +68,7 @@ SQLPage streams HTML by default so the browser can render results while the data chunked_transfer_encoding on; ``` -Disabling buffering lets responses reach clients immediately but increases how many simultaneous connections SQLPage must serve; raise the buffers only if you prefer smoothing bursts over fastest-first rendering. Tune the gzip buffer count and size to balance CPU cost and bandwidth, and keep chunked transfer enabled so streaming works with HTTP/1.1 clients. Consult the official NGINX documentation for [proxy buffering](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffering), [gzip](https://nginx.org/en/docs/http/ngx_http_gzip_module.html), and [chunked transfer](https://nginx.org/en/docs/http/ngx_http_core_module.html#chunked_transfer_encoding) when adjusting these values. If you later implement heavy caching (see the section below), you may choose to reintroduce buffering for specific locations. +Keep the default buffering behaviour when most visitors are on slow links (mobile, high latency) or when SQLPage queries run long (large aggregations, reports). Increase the buffer count or size if responses exceed these limits frequently, or leave them to NGINX defaults when unsure. For primarily fast clients reading light pages, you can switch to `proxy_buffering off;` or reduce the number of buffers to let the streamed HTML reach the browser sooner, accepting higher upstream connection pressure. Refer to the official documentation for [proxy buffering](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffering), [gzip](https://nginx.org/en/docs/http/ngx_http_gzip_module.html), and [chunked transfer](https://nginx.org/en/docs/http/ngx_http_core_module.html#chunked_transfer_encoding) when tuning these values. When SQLPage sits behind a reverse proxy, set `compress_responses` to `false` in `sqlpage.json` so that NGINX compresses once at the edge (documented [here](https://github.com/sqlpage/SQLPage/blob/main/configuration.md)). From b982d6c0ae6d0b2166a9c82d9dae5d3884b09eb6 Mon Sep 17 00:00:00 2001 From: lovasoa Date: Mon, 3 Nov 2025 23:51:53 +0100 Subject: [PATCH 5/5] Update NGINX proxy buffering settings for improved streaming performance Revised the documentation to clarify the impact of enabling and disabling proxy buffering in NGINX for SQLPage. Added concise recommendations for handling slow SQL queries and emphasized the importance of adjusting `compress_responses` in `sqlpage.json` when using a reverse proxy. Co-authored-by: contact --- .../your-first-sql-website/nginx.md | 37 +++++++++---------- 1 file changed, 17 insertions(+), 20 deletions(-) diff --git a/examples/official-site/your-first-sql-website/nginx.md b/examples/official-site/your-first-sql-website/nginx.md index c41bcebc..9e156135 100644 --- a/examples/official-site/your-first-sql-website/nginx.md +++ b/examples/official-site/your-first-sql-website/nginx.md @@ -52,26 +52,6 @@ server { } ``` -### Streaming-friendly proxy settings - -SQLPage streams HTML by default so the browser can render results while the database is still sending rows. NGINX keeps `proxy_buffering` enabled by default, which smooths bursts and protects upstreams from slow clients at the cost of delaying the first bytes. Start with these directives inside the same `location` block as `proxy_pass`: - -```nginx - proxy_buffering on; - proxy_buffer_size 16k; - proxy_buffers 4 16k; - - gzip on; - gzip_buffers 2 4k; - gzip_types text/html text/plain text/css application/javascript application/json; - - chunked_transfer_encoding on; -``` - -Keep the default buffering behaviour when most visitors are on slow links (mobile, high latency) or when SQLPage queries run long (large aggregations, reports). Increase the buffer count or size if responses exceed these limits frequently, or leave them to NGINX defaults when unsure. For primarily fast clients reading light pages, you can switch to `proxy_buffering off;` or reduce the number of buffers to let the streamed HTML reach the browser sooner, accepting higher upstream connection pressure. Refer to the official documentation for [proxy buffering](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffering), [gzip](https://nginx.org/en/docs/http/ngx_http_gzip_module.html), and [chunked transfer](https://nginx.org/en/docs/http/ngx_http_core_module.html#chunked_transfer_encoding) when tuning these values. - -When SQLPage sits behind a reverse proxy, set `compress_responses` to `false` in `sqlpage.json` so that NGINX compresses once at the edge (documented [here](https://github.com/sqlpage/SQLPage/blob/main/configuration.md)). - Save the file and create a symbolic link to it in the `/etc/nginx/sites-enabled/` directory: ```bash sudo ln -s /etc/nginx/sites-available/sqlpage /etc/nginx/sites-enabled/sqlpage @@ -85,6 +65,23 @@ sudo systemctl reload nginx Your SQLPage instance is now hosted behind a reverse proxy using NGINX. You can access it by visiting `http://example.com`. + +### Streaming-friendly proxy settings + +SQLPage streams HTML by default so the browser can render results while the database is still sending rows. +If you have slow SQL queries (you shouldn't), you can add the following directive to your location block: + +```nginx +proxy_buffering off; +``` + +That will allow users to start seeing the top of your pages faster, +but will increase the load on your SQLPage server, and reduce the amount of users you can serve concurrently. + +Refer to the official documentation for [proxy buffering](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffering), [gzip](https://nginx.org/en/docs/http/ngx_http_gzip_module.html), and [chunked transfer](https://nginx.org/en/docs/http/ngx_http_core_module.html#chunked_transfer_encoding) when tuning these values. + +When SQLPage sits behind a reverse proxy, set `compress_responses` to `false` [in `sqlpage.json`](https://github.com/sqlpage/SQLPage/blob/main/configuration.md) so that NGINX compresses once at the edge. + ### URL Rewriting URL rewriting is a powerful feature that allows you to manipulate URLs to make them more readable, search-engine-friendly, and easy to maintain.