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.

Practice

1. What is the main purpose of using keepalive in an upstream block in nginx?

easy

A. To limit the number of client connections to nginx

B. To close all connections immediately after each request

C. To reuse open connections to backend servers and improve response speed

D. To enable caching of static files on the server

Solution

1. Step 1: Understand the role of keepalive in upstream

   The keepalive directive in the upstream block tells nginx to keep a number of connections open to backend servers for reuse.

2. Step 2: Identify the benefit of connection reuse

   Reusing connections avoids the overhead of opening new connections for each request, improving speed and reducing latency.

3. Final Answer:

   To reuse open connections to backend servers and improve response speed -> Option C

4. Quick Check:

   Connection pooling = reuse connections = To reuse open connections to backend servers and improve response speed [OK]

Hint: Remember: keepalive means keep connections open for reuse [OK]

Common Mistakes:

• Thinking keepalive limits client connections
• Confusing keepalive with caching
• Assuming keepalive closes connections immediately

2. Which of the following is the correct syntax to enable connection pooling with 32 keepalive connections in an nginx upstream block?

easy

A. upstream backend { keepalive 32; server backend1.example.com; }

B. upstream backend { keepalive_connections 32; server backend1.example.com; }

C. upstream backend { keepalive=32; server backend1.example.com; }

D. upstream backend { keepalive 32 servers; server backend1.example.com; }

Solution

1. Step 1: Recall the correct directive syntax

   The correct directive to set connection pooling count is keepalive followed by the number, ending with a semicolon.

2. Step 2: Check each option's syntax

   upstream backend { keepalive 32; server backend1.example.com; } uses keepalive 32; which is correct. Options A, B, and C use incorrect directive names or syntax.

3. Final Answer:

   upstream backend { keepalive 32; server backend1.example.com; } -> Option A

4. Quick Check:

   Correct syntax = keepalive 32; = upstream backend { keepalive 32; server backend1.example.com; } [OK]

Hint: Use 'keepalive' followed by number and semicolon inside upstream [OK]

Common Mistakes:

• Using incorrect directive names like keepalive_connections
• Adding extra words after number
• Using equal sign instead of space

3. Given this nginx configuration snippet, what will be the effect on connection reuse?

upstream backend {
    server backend1.example.com;
    keepalive 16;
}

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

medium

A. Connections will be closed immediately after each request

B. Connections will not be reused because proxy_http_version is 1.1

C. The configuration will cause a syntax error and fail to start nginx

D. Connections to backend will be reused up to 16 times, improving performance

Solution

1. Step 1: Analyze upstream keepalive setting

   The keepalive 16; directive allows nginx to keep up to 16 idle connections open to the backend for reuse.

2. Step 2: Check proxy settings for connection reuse

   Setting proxy_http_version 1.1; and proxy_set_header Connection ""; enables connection reuse by preventing the 'Connection: close' header.

3. Final Answer:

   Connections to backend will be reused up to 16 times, improving performance -> Option D

4. Quick Check:

   keepalive + proxy_http_version 1.1 + empty Connection header = reuse [OK]

Hint: Use HTTP/1.1 and clear Connection header to enable reuse [OK]

Common Mistakes:

• Assuming HTTP/1.1 disables reuse
• Not clearing Connection header disables pooling
• Confusing keepalive with client connections

4. You configured connection pooling with keepalive 10; in your upstream block, but nginx is still opening new connections for every request. What is the most likely cause?

medium

A. You forgot to set proxy_http_version 1.1; and clear the Connection header

B. The keepalive directive only works with HTTP/2

C. You need to increase keepalive to at least 100

D. The backend server does not support keepalive connections

Solution

1. Step 1: Check proxy settings required for connection reuse

   For connection pooling to work, nginx must use HTTP/1.1 and clear the Connection header to avoid closing connections.

2. Step 2: Identify common misconfiguration

   If proxy_http_version 1.1; and proxy_set_header Connection ""; are missing, nginx will close connections after each request despite keepalive.

3. Final Answer:

   You forgot to set proxy_http_version 1.1; and clear the Connection header -> Option A

4. Quick Check:

   Missing proxy_http_version 1.1 + Connection header clear = no reuse [OK]

Hint: Always set proxy_http_version 1.1 and clear Connection header [OK]

Common Mistakes:

• Believing keepalive works without proxy_http_version 1.1
• Thinking backend server must be changed first
• Assuming keepalive number is too low

5. You want to optimize nginx to reuse connections to multiple backend servers with different keepalive limits. Which configuration correctly sets 20 keepalive connections for backend1 and 10 for backend2?

hard

A. upstream backend { server backend1.example.com; keepalive 20; server backend2.example.com; keepalive 10; }

B. upstream backend1 { server backend1.example.com; keepalive 20; } upstream backend2 { server backend2.example.com; keepalive 10; }

C. upstream backend { server backend1.example.com keepalive=20; server backend2.example.com keepalive=10; }

D. upstream backend { server backend1.example.com; server backend2.example.com; keepalive 30; }

Solution

1. Step 1: Understand keepalive scope

   The keepalive directive applies per upstream block, not per server inside it.

2. Step 2: Check options for setting different keepalive values

   upstream backend1 { server backend1.example.com; keepalive 20; } upstream backend2 { server backend2.example.com; keepalive 10; } defines two separate upstream blocks, each with its own keepalive setting, which is correct. Options B, C, and D try to set different keepalive values inside one upstream block, which is invalid.

3. Final Answer:

   upstream backend1 { server backend1.example.com; keepalive 20; } upstream backend2 { server backend2.example.com; keepalive 10; } -> Option B

4. Quick Check:

   Separate upstream blocks for different keepalive values = upstream backend1 { server backend1.example.com; keepalive 20; } upstream backend2 { server backend2.example.com; keepalive 10; } [OK]

Hint: Use separate upstream blocks to set different keepalive values [OK]

Common Mistakes:

• Trying to set keepalive per server inside one upstream
• Using invalid syntax with equal signs
• Setting one keepalive for multiple servers expecting different limits