Postgresql guide by igor-alexandrov · Pull Request #24068 · docker/docs

igor-alexandrov · 2026-02-03T22:07:21Z

Description

Add comprehensive PostgreSQL containerization guide with 4 modules covering setup, configuration, networking, and ecosystem tools
Include practical Docker and Docker Compose examples for each topic
Cover data persistence strategies (named volumes, bind mounts), initialization scripts, performance tuning, and connection pooling

This PR introduces a new PostgreSQL-specific guide to help users containerize PostgreSQL databases using Docker. The guide is structured into four progressive modules:

Immediate Setup & Data Persistence - Covers running PostgreSQL containers with proper data persistence using named volumes, bind mounts, and Docker Compose configurations.
Advanced Configuration and Initialization - Explains initialization scripts (/docker-entrypoint-initdb.d/), performance tuning parameters (memory settings, connection limits, I/O
configuration), and timezone/locale settings.
Networking and Connectivity - Details how to configure networking for containerized PostgreSQL deployments.
Companions for PostgreSQL - Introduces ecosystem tools including pgAdmin 4 for visual management, PgBouncer and Pgpool-II for connection pooling, and pgbench for performance testing.

Examples include tabs showing both Docker Hardened Images (DHI) and Docker Official Images (DOI) variants where applicable.

The guide is prepared by @igor-alexandrov, @edithturn, and @Expeto.

Reviews

Technical review
Editorial review
Product review

netlify · 2026-02-03T22:07:26Z

✅ Deploy Preview for docsdocker ready!

Name	Link
🔨 Latest commit	`f705491`
🔍 Latest deploy log	https://app.netlify.com/projects/docsdocker/deploys/699efe63635afb0008749ca0
😎 Deploy Preview	https://deploy-preview-24068--docsdocker.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

tippexs

Just a small remark. Other then that, Great Work LGTM

tippexs · 2026-02-18T08:38:23Z

content/guides/postgresql/companions-for-postgresql.md

+```yaml
+services:
+  postgres:
+    image: postgres:17.7


Is there a reason why we do use 17.7 instead of 18 as in the rest of the guide?

We fixed! Thank you @tippexs

craig-osterhout

Thanks @igor-alexandrov and all.
It looks great!
I left mostly style nits, not any technical blockers.

craig-osterhout · 2026-02-26T20:00:44Z

content/guides/postgresql/_index.md

+title: PostgreSQL specific guide
+linkTitle: PostgreSQL
+description: Containerize PostgreSQL databases using Docker
+keywords: Docker, getting started, postgresql, languag


Suggested change

keywords: Docker, getting started, postgresql, languag

keywords: Docker, getting started, postgresql, language

craig-osterhout · 2026-02-26T20:01:43Z

content/guides/postgresql/_index.md

+  time: 20 minutes
+---
+
+- Immediate Setup & Data Persistence


Not needed, as the template auto populates the child pages.

Suggested change

- Immediate Setup & Data Persistence

craig-osterhout · 2026-02-26T20:01:49Z

content/guides/postgresql/_index.md

+---
+
+- Immediate Setup & Data Persistence
+- Advanced Configuration and Initialization


Suggested change

- Advanced Configuration and Initialization

craig-osterhout · 2026-02-26T20:01:55Z

content/guides/postgresql/_index.md

+
+- Immediate Setup & Data Persistence
+- Advanced Configuration and Initialization
+- Networking and Connectivity


Suggested change

- Networking and Connectivity

craig-osterhout · 2026-02-26T20:02:02Z

content/guides/postgresql/_index.md

+- Immediate Setup & Data Persistence
+- Advanced Configuration and Initialization
+- Networking and Connectivity
+- Companions for PostfgreSQL


Suggested change

- Companions for PostfgreSQL

craig-osterhout · 2026-02-26T22:52:52Z

content/guides/postgresql/companions-for-postgresql.md

+
+Does PgBouncer actually make a difference? Run the benchmarks yourself to find out. Your results will vary based on your hardware, Docker configuration, network setup, and system load.
+
+### What to Expect


Suggested change

### What to Expect

### What to expect

craig-osterhout · 2026-02-26T22:53:01Z

content/guides/postgresql/companions-for-postgresql.md

+
+When you run these benchmarks, you'll observe patterns rather than specific numbers. Think of it like comparing two different routes to work: the "faster" route depends on traffic conditions, time of day, and your vehicle.
+
+### Key Observations


Suggested change

### Key Observations

### Key observations

craig-osterhout · 2026-02-26T22:53:32Z

content/guides/postgresql/companions-for-postgresql.md

+
+When comparing direct connections versus PgBouncer, you'll typically notice:
+
+**1. Connection overhead differs significantly**


Suggested change

**1. Connection overhead differs significantly**

#### 1. Connection overhead differs significantly

craig-osterhout · 2026-02-26T22:53:46Z

content/guides/postgresql/companions-for-postgresql.md

+
+Direct connections require PostgreSQL to spawn a new process for each client. PgBouncer reuses existing connections. Watch the "initial connection time" metric in your results—PgBouncer often shows dramatically faster connection setup.
+
+**2. Behavior under pressure reveals the real difference**


Suggested change

**2. Behavior under pressure reveals the real difference**

#### 2. Behavior under pressure reveals the real difference

craig-osterhout · 2026-02-26T22:54:07Z

content/guides/postgresql/companions-for-postgresql.md

+
+Try increasing the client count (`-c` parameter) gradually: 50, 100, 150, 200. At some point, direct connections will fail with "too many clients already" while PgBouncer continues handling requests. This is PgBouncer's primary value: **it prevents connection exhaustion**.
+
+**3. Throughput varies by environment**


Suggested change

**3. Throughput varies by environment**

#### 3. Throughput varies by environment

dvdksn · 2026-02-27T13:51:18Z

content/guides/postgresql/companions-for-postgresql.md

+      POSTGRES_DB: benchmark
+      POSTGRES_HOST_AUTH_METHOD: trust
+    volumes:
+      - postgres_data:/var/lib/postgresql/data


Suggested change

- postgres_data:/var/lib/postgresql/data

- postgres_data:/var/lib/postgresql

dvdksn · 2026-02-27T13:57:17Z

content/guides/postgresql/advanced-configuration-and-initialization.md

+
+### How initialization works
+
+When the container starts, it checks whether the data directory (`/var/lib/postgresql/data`) is empty. If the directory already contains data, PostgreSQL starts immediately without running any initialization. If the directory is empty, the container runs `initdb` to create a new database cluster, then executes all scripts in `/docker-entrypoint-initdb.d/` in alphabetical order before starting PostgreSQL.


So, I noticed that there's a discrepancy in where exactly the data directory is stored between dhi.io/postgres and docker.io/library/postgres.

The official image stores it at /var/lib/postgresql//docker whereas the hardened image stores it at /var/lib/postgresql//data.

I don't think we need to get into the weeds about where exactly it is in this paragraph, so maybe we can rephrase to:

Suggested change

When the container starts, it checks whether the data directory (`/var/lib/postgresql/data`) is empty. If the directory already contains data, PostgreSQL starts immediately without running any initialization. If the directory is empty, the container runs `initdb` to create a new database cluster, then executes all scripts in `/docker-entrypoint-initdb.d/` in alphabetical order before starting PostgreSQL.

When the container starts, it checks whether the PostgreSQL data directory is empty. If the directory already contains data, PostgreSQL starts immediately without running any initialization. If the directory is empty, the container runs `initdb` to create a new database cluster, then executes all scripts in `/docker-entrypoint-initdb.d/` in alphabetical order before starting PostgreSQL.

dvdksn · 2026-02-27T13:57:42Z

content/guides/postgresql/advanced-configuration-and-initialization.md

+| `.sql.gz` | Gzip-compressed SQL files |
+| `.sh` | Shell scripts executed with bash |
+
+> **Important:** Initialization scripts only run when the PostgreSQL data directory (`/var/lib/postgresql/data`) is empty. If you mount a volume containing existing data, initialization is skipped. This behavior prevents overwriting existing databases.


Suggested change

> **Important:** Initialization scripts only run when the PostgreSQL data directory (`/var/lib/postgresql/data`) is empty. If you mount a volume containing existing data, initialization is skipped. This behavior prevents overwriting existing databases.

> **Important:** Initialization scripts only run when the PostgreSQL data directory is empty. If you mount a volume containing existing data, initialization is skipped. This behavior prevents overwriting existing databases.

dvdksn · 2026-02-27T13:58:31Z

content/guides/postgresql/immediate-setup-and-data-persistence.md

+
+The `-v postgres_data:/var/lib/postgresql` flag mounts a named volume called `postgres_data` to PostgreSQL's data directory. If the volume doesn't exist, Docker creates it automatically.
+
+> **Note:** PostgreSQL 18+ stores data in a version-specific subdirectory under `/var/lib/postgresql`. Mounting at this level (rather than `/var/lib/postgresql/data`) allows for easier upgrades using `pg_upgrade --link`.


igor-alexandrov and others added 11 commits February 3, 2026 15:00

Initial PostgreSQL guide structure

7318b3a

dhi: postgresql, part 2 and 4 , final drafts

0a9ffb0

Added two first sections to the first part of the PostgreSQL guide.

9238c68

Added the Named Volumes section

0942ec7

Added the "Bind Mounts" section

c92e89e

Added the Compose section

46d3879

Updated the first section based on comments from Edith Puclla

7df793d

Update PostgreSQL Modules 2 and 4 with feedback fixes

7ca2716

Added DHI examples

dcd11dc

Added more DHI examples

bc3e9c8

Adding Networking and Connectivity part

3468d44

github-actions bot added the area/guides label Feb 3, 2026

igor-alexandrov marked this pull request as draft February 3, 2026 22:50

edithturn added 6 commits February 4, 2026 14:50

Fix the reference links

b8a6385

Adding description and fixing level of doc tittle

85114f5

Fixing bash format for code snippeds

8fe9952

Remove content form the static resource

d680956

Fixing minor error in the doc spellings

e42a58b

Fixing validate check for grammar

2a3ae04

igor-alexandrov marked this pull request as ready for review February 13, 2026 19:59

tippexs reviewed Feb 18, 2026

View reviewed changes

Change postgresql version from 17 to 18

f705491

craig-osterhout requested a review from a team February 26, 2026 17:03

craig-osterhout added the status/review label Feb 26, 2026

craig-osterhout requested changes Feb 26, 2026

View reviewed changes

dvdksn reviewed Feb 27, 2026

View reviewed changes

	keywords: Docker, getting started, postgresql, languag
	keywords: Docker, getting started, postgresql, language


		Does PgBouncer actually make a difference? Run the benchmarks yourself to find out. Your results will vary based on your hardware, Docker configuration, network setup, and system load.

		### What to Expect


		When you run these benchmarks, you'll observe patterns rather than specific numbers. Think of it like comparing two different routes to work: the "faster" route depends on traffic conditions, time of day, and your vehicle.

		### Key Observations


		When comparing direct connections versus PgBouncer, you'll typically notice:

		1. Connection overhead differs significantly

	1. Connection overhead differs significantly
	#### 1. Connection overhead differs significantly


		Direct connections require PostgreSQL to spawn a new process for each client. PgBouncer reuses existing connections. Watch the "initial connection time" metric in your results—PgBouncer often shows dramatically faster connection setup.

		2. Behavior under pressure reveals the real difference

	2. Behavior under pressure reveals the real difference
	#### 2. Behavior under pressure reveals the real difference


		Try increasing the client count (`-c` parameter) gradually: 50, 100, 150, 200. At some point, direct connections will fail with "too many clients already" while PgBouncer continues handling requests. This is PgBouncer's primary value: it prevents connection exhaustion.

		3. Throughput varies by environment

	3. Throughput varies by environment
	#### 3. Throughput varies by environment

	- postgres_data:/var/lib/postgresql/data
	- postgres_data:/var/lib/postgresql


		### How initialization works

		When the container starts, it checks whether the data directory (`/var/lib/postgresql/data`) is empty. If the directory already contains data, PostgreSQL starts immediately without running any initialization. If the directory is empty, the container runs `initdb` to create a new database cluster, then executes all scripts in `/docker-entrypoint-initdb.d/` in alphabetical order before starting PostgreSQL.

	> Important: Initialization scripts only run when the PostgreSQL data directory (`/var/lib/postgresql/data`) is empty. If you mount a volume containing existing data, initialization is skipped. This behavior prevents overwriting existing databases.
	> Important: Initialization scripts only run when the PostgreSQL data directory is empty. If you mount a volume containing existing data, initialization is skipped. This behavior prevents overwriting existing databases.


		The `-v postgres_data:/var/lib/postgresql` flag mounts a named volume called `postgres_data` to PostgreSQL's data directory. If the volume doesn't exist, Docker creates it automatically.

		> Note: PostgreSQL 18+ stores data in a version-specific subdirectory under `/var/lib/postgresql`. Mounting at this level (rather than `/var/lib/postgresql/data`) allows for easier upgrades using `pg_upgrade --link`.

Conversation

igor-alexandrov commented Feb 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Reviews

Uh oh!

netlify bot commented Feb 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for docsdocker ready!

Uh oh!

tippexs left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

craig-osterhout left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

igor-alexandrov commented Feb 3, 2026 •

edited

Loading

netlify bot commented Feb 3, 2026 •

edited

Loading