Installing PostgreSQL in a Docker container on your local machine

Suggest edits

Using Docker for your local PostgreSQL development environment streamlines setup, ensures consistency, and simplifies management. It provides a flexible, isolated, and portable solution that can adapt to various development needs and workflows.

Prerequisites

Docker-compatible OS (macOS, Windows, Linux)

Preparing Docker

Install Docker:

macOS: Download and install Docker Desktop from Docker’s official website.
Windows: Download and install Docker Desktop from Docker’s official website. Ensure WSL 2 is enabled if using Windows 10 or later.
Linux: Download and install Docker Desktop from Docker's official website.
This sequence of commands updates the package lists, installs Docker, starts and enables Docker to run at boot, adds your user to the Docker group, and then immediately applies the group changes.

Pull the PostgreSQL Docker image:

Open a terminal or command prompt and run the following command to pull the latest PostgreSQL image from Docker Hub:

docker pull postgres

Running and accessing the container’s PostgreSQL database

Run the PostgreSQL Container:

Run a new container with the PostgreSQL image using the following command:

docker run --name my_postgres -d \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -v my_pgdata:/var/lib/postgresql/data \
  -p 5432:5432 postgres

`--name my_postgres -d postgres`

The --name flag tells docker to creates a new container named my_postgres, while the -d flag tells it to use the postgres image which we pulled previously. Note that if we had not pulled it, this command would automatically pull the PostgreSQL image.

`-e POSTGRES_PASSWORD=mysecretpassword`

The -e flag sets an environment variable POSTGRES_PASSWORD to mysecretpassword. This is used the password for the default postgres user. You should use a different password.

`-v my_pgdata:/var/lib/postgresql/data`

Docker uses volumes to persist data in Docker containers. This flag mounts a volume named my_pgdata to persist data. The data in this case is whatever what Postgres writes to the /var/lib/postgresql/data directory within the container. These writes are persisted outside the container in a docker volume; the command docker volume inspect my_pgdata will show you information about that volume.

`-p 5432:5432`

The -p flag maps the container’s port 5432 to the host machine’s port 5432. Port 5432 is Postgres's default port for communications. By using this flag, it allows you to access the PostgreSQL database from your host machine.

Verify the container is running:

To verify that the container is running, use the following command:

docker ps

This command lists all running containers. You should see the my_postgres container listed.

You now have a persistent, locally accessible Postgres database running in a Docker container. Let's start using it.

Access PostgreSQL

To access the PostgreSQL database without any additional tools, you can use the following command to open a PostgreSQL prompt:

docker exec \-it my\_postgres psql \-U postgres

This logs into the Docker container and runs the psql command as the postgres user from there.

Using a PostgreSQL client

The psql command is a powerful tool for interacting with PostgreSQL databases. You should install it on your local machine to interact with the PostgreSQL database running in the Docker container.

macOS:

You can install the PostgreSQL client using Homebrew:

brew install libpq

Windows:

Download the PostgreSQL client from the official website.

Linux:

Use your distribution’s package manager to install the PostgreSQL client. For example, on Ubuntu:

sudo apt-get install postgresql-client

Connecting other apps

You can also connect other applications to the PostgreSQL database running in the Docker container. You need to provide the following connection details:

Host: localhost
Port: 5432
Username: postgres
Password: (whatever you set it to)
Database: postgres

Or use the connection string:

   postgresql://postgres:mysecretpassword@localhost:5432/postgres

Verify data persistence

Create a table and insert data. Access the PostgreSQL instance and run the following SQL commands to create a table with columns and insert some data:

CREATE TABLE employees (  
   id SERIAL PRIMARY KEY,  
   first_name VARCHAR(50),  
   last_name VARCHAR(50),  
   email VARCHAR(100),  
   hire_date DATE  
);  
   INSERT INTO employees (first_name, last_name, email, hire_date) VALUES  
   ('John', 'Doe','john.doe@example.com', '2020-01-15'),  
   ('Jane', 'Smith', 'jane.smith@example.com', '2019-03-22');

Stop and completely remove the container.

   docker stop my_postgres
   docker rm my_postgres

Recreate the container with the same volume.

   docker run --name my_postgres -d \
      -e POSTGRES_PASSWORD=mysecretpassword \
      -v my_pgdata:/var/lib/postgresql/data \
      -p 5432:5432 postgres

Verify data persistence.
Access the PostgreSQL instance and check if the data still exists:
```
   SELECT * FROM employees
```
If everything worked as expected, you should see the employee table with the data previously loaded still present.

Conclusion

By following these steps, you have set up a robust local development environment for PostgreSQL using Docker. This setup ensures data persistence and provides a flexible, isolated, and consistent environment for all of your development needs.

← Prev

Managing a cluster

↑ Up

Getting started

Using your cluster