Connection pooling to upstream in Nginx - Commands & Configuration

Introduction

When a web server talks to another server to get data, opening a new connection every time can slow things down. Connection pooling keeps connections open and ready to use, making the process faster and smoother.

When your Nginx server needs to talk to a backend server many times quickly, like a web app calling an API.

When you want to reduce the delay caused by opening new connections repeatedly.

When your backend servers can handle multiple requests on the same connection.

When you want to improve the speed and efficiency of your server without changing your backend code.

When you notice high CPU or network usage due to many short connections opening and closing.

Config File - nginx.conf

nginx.conf

http {
    upstream backend {
        server 192.168.1.100:8080;
        server 192.168.1.101:8080;

        keepalive 16;
    }

    server {
        listen 80;

        location / {
            proxy_pass http://backend;
            proxy_http_version 1.1;
            proxy_set_header Connection "";
        }
    }
}

upstream backend: Defines the backend servers Nginx will connect to.

keepalive 16;: Keeps 16 connections open to the backend servers for reuse.

proxy_http_version 1.1;: Uses HTTP/1.1 to support persistent connections.

proxy_set_header Connection "";: Clears the Connection header to allow connection reuse.

Commands

Check the Nginx configuration file for syntax errors before reloading.

Terminal

nginx -t

Expected Output

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok

nginx: configuration file /etc/nginx/nginx.conf test is successful

Reload Nginx to apply the new configuration without stopping the server.

Terminal

systemctl reload nginx

Expected Output

No output (command runs silently)

Send a simple request to Nginx to verify it forwards requests to the backend using connection pooling.

Terminal

curl -I http://localhost/

Expected Output

HTTP/1.1 200 OK

Server: nginx

Date: Wed, 01 Jan 2025 12:00:00 GMT

Content-Type: text/html

Connection: keep-alive

Key Concept

If you remember nothing else from this pattern, remember: enabling keepalive connections in Nginx upstream lets it reuse backend connections, making requests faster and reducing load.

Common Mistakes

Not setting proxy_http_version to 1.1 when enabling keepalive.

HTTP/1.0 does not support persistent connections, so connection pooling won't work.

Always set proxy_http_version 1.1 in the location block when using keepalive upstream.

Forgetting to clear the Connection header with proxy_set_header Connection "".

The Connection header may force closing the connection, preventing reuse.

Add proxy_set_header Connection "" to allow connection reuse.

Setting keepalive to a very high number without backend capacity.

Too many open connections can overwhelm backend servers.

Choose a reasonable keepalive value based on backend server capacity, like 16.

Summary

Define backend servers in an upstream block with keepalive to enable connection pooling.

Set proxy_http_version to 1.1 and clear the Connection header in the proxy location to support reuse.

Test the configuration syntax and reload Nginx to apply changes.

Verify connection pooling by sending requests and checking for keep-alive connections.