How to Set Up PostgreSQL with Docker Step by Step

You can set up PostgreSQL Docker quickly, even if you have never used Docker before. Many users find that this method saves time and avoids the confusion of traditional installation.

You only need a few commands to get started.
You avoid complex configuration steps.
You follow a clear guide that walks you through each part.

Tip: You do not need any prior experience. The process is simple and designed for beginners.

PostgreSQL Docker Quick Start

Image Source: unsplash

It is simple to set up PostgreSQL Docker if you follow steps. You will see how to get the official image and start your first container. This guide helps you not make mistakes and keeps your database safe.

Pull the Image

You must download the PostgreSQL Docker image before using it. The official image is on Docker Hub. You can pick the newest version or choose a certain version for more safety.

Open your terminal.
To get the newest image, type:

1
docker pull postgres

To pick a certain version, use:

1
docker pull postgres:14.5

Picking a version helps you avoid problems when updates come. Your setup stays the same and works as expected.

Note: It is best to use a certain version, not “latest”. This keeps your PostgreSQL Docker safe from surprise updates.

Run the Container

After you get the image, you can start your PostgreSQL Docker container. You need to set a password and username for safety. You do this by adding environment variables when starting the container.

Here is a table with the main variables you need:

Variable	Value
POSTGRES_PASSWORD	initexample
POSTGRES_USER	initexample
POSTGRES_HOST	postgres
POSTGRES_DB	initexample

You can start the container with this command:

1
docker run --name postgres-docker -e POSTGRES_USER=initexample -e POSTGRES_PASSWORD=initexample -e POSTGRES_DB=initexample -p 5432:5432 -d postgres:14.5

--name postgres-docker gives your container a name.
-e POSTGRES_USER=initexample sets the username.
-e POSTGRES_PASSWORD=initexample sets the password.
-e POSTGRES_DB=initexample makes a database with that name.
-p 5432:5432 connects the PostgreSQL port to your computer.
-d runs the container in the background.
postgres:14.5 uses the version you picked before.

Tip: Always set a password. PostgreSQL does not have a password by default. If you skip this, your database is not safe. Always use your own password for your PostgreSQL Docker container.

Now your PostgreSQL Docker container is running. You can connect and start using your database.

Set Up Data Persistence

When you use PostgreSQL Docker, you want your data to stay safe. Your data should not disappear if you stop or delete the container. Data persistence means your database information stays even after you restart or remove the container. You can use Docker volumes to keep your data safe and always ready.

Create a Docker Volume

You need to make a Docker volume before you start your PostgreSQL Docker container. Volumes help protect your data and make it easy to handle. Here are the main reasons to use data persistence:

Safety: Your data stays even if you delete the container.
Portability: You can move your data between containers or computers.
Backup: You can back up your data more easily.

If you do not use volumes, your data stays inside the container. This can fill up your disk and cause errors like “No space left on device.” Every new container without a volume makes a new data layer. These layers do not clean up by themselves.

To make a volume, use this command:

1
docker volume create pgdata

This command makes a new volume called pgdata for your database files.

Attach Volume to Container

After you make the volume, you need to connect it to your PostgreSQL Docker container. You do this by linking the volume to the folder where PostgreSQL keeps its data. This folder is /var/lib/postgresql/data.

Here is a table with the commands and what they do:

Command	Description
docker volume create pgdata	Makes a named volume called ‘pgdata’.
docker run –name my-postgres -e POSTGRES_PASSWORD=mypassword -v pgdata:/var/lib/postgresql/data -d postgres	Starts a PostgreSQL container and links it to the ‘pgdata’ volume for data persistence.

When you use the -v pgdata:/var/lib/postgresql/data option, Docker saves your database files in the volume. Your data stays safe even if you restart or remove the container.

Docker volumes work better than bind mounts for most databases. Volumes give you faster speed, better safety, and easier handling. Bind mounts are good for testing, but volumes are best for real use.

Tip: Always use Docker volumes for your PostgreSQL Docker setup. This keeps your data safe and makes your database easier to handle.

Verify and Access PostgreSQL Docker

After you set up your PostgreSQL Docker container, you should check if it works. You also need to know how to connect to your database. This part shows you how to check and connect in easy steps.

Check Running Containers

You can see if your container is working by using Docker commands. Here is what you do:

Open your terminal.
To see running containers, type:

1
docker container ls

If you do not see your container, you can restart it. Use these commands:

1
2
docker container stop postgres-docker
    docker container start postgres-docker

Run the list command again to check:

1
docker container ls

If your container is missing, look at the logs for problems. Use docker logs postgres-docker to see what went wrong. Make sure your data folder has the right permissions. Fix any port or name problems. Check your environment variables like POSTGRES_USER and POSTGRES_PASSWORD.

Connect with psql or Client

When your container is running, you can connect to your database. You have two main ways:

Connect from inside the container:

1
docker exec -it postgres-docker psql -U initexample -d initexample

Connect from your computer using psql:

1
psql -h localhost -p 5432 -U initexample -d initexample

You can also use a database tool like DBeaver or pgAdmin. Use these settings:

Setting	Value
Host	localhost
Port	5432
Username	initexample
Password	initexample
Database	initexample

Tip: If you cannot connect, check your firewall and make sure port 5432 is open. Always use the username and password you picked when you started your PostgreSQL Docker container.

Now you know how to check your container and connect to your database. You can start using your PostgreSQL Docker for your projects.

Configure and Manage Container

You can make your PostgreSQL Docker container safer and easier to use. You do this by setting environment variables, using your own config files, and managing how the container runs. These steps help you control your database and keep it working well.

Set Environment Variables

Environment variables help you set up your PostgreSQL container. You use them for the right user, password, and database name. Always set these before you start your container. Here is a table with the most common variables and what they do:

Environment Variable	Description
POSTGRES_USER	The username for the PostgreSQL role
POSTGRES_DB	The name of the database to create
POSTGRES_PASSWORD	The password for the PostgreSQL role

Add these variables to your docker run command. This keeps your database safe and simple to handle.

Tip: Always pick strong passwords and special usernames. This helps stop people from getting into your database who should not.

Use Custom Config Files

You can make PostgreSQL work faster by using your own config file. Follow these steps:

Make a custom postgresql.conf file with settings for your needs.
Attach the file to your container with the -v option.
Change things like shared_buffers, effective_cache_size, and work_mem to make it faster.

Be careful with the names of settings. For example, use listen_addresses and not listen_adress. Make sure you attach the file, not a whole folder, so you do not get errors.

Note: Try your custom config first before using it for real work. Bad settings can stop your database from starting.

Stop and Restart Container

You should know how to stop and restart your container without losing data. Here is an easy way:

Make a Docker volume for your data with docker volume create pgdata.
Start your container with the volume added:

1
docker run -d --name postgresql -v pgdata:/var/lib/postgresql/data postgres:14.5

To stop your container, use docker stop postgresql.
To start it again, use docker start postgresql.

Tip: Always use volumes for your data. This keeps your database safe when you stop or start the container.

Best Practices for Security and Maintenance

Use the --read-only flag to stop unwanted changes.
Do not attach important host folders.
Turn on Docker Content Trust for signed images.
Check your containers and computer often.
Use tools like Watchtower for updates.
Make backups often and watch your database with pgAdmin or Prometheus.

You can keep your PostgreSQL Docker container safe and working well by following these steps.

You now know how to set up PostgreSQL with Docker. You can do this by following these easy steps:

First, install Docker and Docker Compose.
Next, pull the PostgreSQL image.
Then, run your container using environment variables.
Check your setup and connect with a client.
Use volumes so your data stays safe.
Control your container with simple commands.

You can try more things like custom settings, health checks, and backup scripts.

You can run more than one PostgreSQL version.
You can set up SSL or replication if you need more features.

Tip: Make backups often and update your Docker and PostgreSQL images. This helps keep your setup safe and working well.

What is SQLFlash?

SQLFlash is your AI-powered SQL Optimization Partner.

Based on AI models, we accurately identify SQL performance bottlenecks and optimize query performance, freeing you from the cumbersome SQL tuning process so you can fully focus on developing and implementing business logic.