Create a Postgres Database from scratch in 5 minutes

Prerequisite: The article assume you know Postgres and Docker. To learn more about Docker, please feel free to check out my Docker series.

Create a Docker volume as data storage

Docker containers don’t have permanent storage, so we’ll start by creating a Docker volume. This makes it easier to destroy and launch a new Postgres container without losing your database data.

Run the following command to create a Docker volume. Note that the example uses the name pgdata, but you can change this to whatever you like. Be sure to use the same name in all subsequent commands too if you do change it though.

docker volume create pgdata

Now you can verify a docker volume has been created like this

docker volume ls
DRIVER    VOLUME NAME
local     pgdata

Create a new Postgres Docker container

Now we can create the container. I recommend using an easy to remember port such as 54320, which is Postgres' default port with a zero added at the end. This way it can be easily remembered and at the same time you avoid possible conflicts should you, for whatever reason, already have another Postgres instance running on the default port.

docker run --name postgres-dev -e POSTGRES_PASSWORD=my_postgres_password -d -p 54320:5432 -v pgdata:/var/lib/postgresql/data postgres

The above command creates a Postgres container with name postgres-dev and password my_postgres_password

Verify that with the following command

docker ps
CONTAINER ID   IMAGE      COMMAND                  CREATED         STATUS         PORTS                     NAMES
9b6baf4970cc   postgres   "docker-entrypoint.s…"   4 seconds ago   Up 4 seconds   0.0.0.0:54320->5432/tcp   postgres-dev

Note: Be sure to set the password to something secure enough. You should never expose your Docker instance or Postgres container to the world but it’s important to ensure no unwanted person (even via your local network) can access all your data.

Docker will automatically download the Postgres image if you don’t already have it on your machine. When the command finishes, a fresh Postgres container should be up and running in the background. To confirm, try connecting to it using your favorite GUI client or by using something like the psql command-line interface.

docker exec -it postgres-dev psql -U postgres
psql (13.1 (Debian 13.1–1.pgdg100+1))
Type “help” for help.
postgres=#

Create a new Database

You can now create a database to use to either import your existing data into, or for setting up your new project with.

docker exec -i postgres-dev psql -U postgres -c "CREATE DATABASE golinks WITH ENCODING='UTF8' OWNER=postgres;"
CREATE DATABASE

Tip: You do not have to specify your password with this command as it is defined in the container’s environment variable.

You should now have a new and clean database, ready for use.

docker exec -it postgres-dev psql -U postgres
psql (13.1 (Debian 13.1-1.pgdg100+1))
Type "help" for help.

postgres=# \l
                                 List of databases
   Name    |  Owner   | Encoding |  Collate   |   Ctype    |   Access privileges
-----------+----------+----------+------------+------------+-----------------------
 golinks   | postgres | UTF8     | en_US.utf8 | en_US.utf8 |
 postgres  | postgres | UTF8     | en_US.utf8 | en_US.utf8 |
 template0 | postgres | UTF8     | en_US.utf8 | en_US.utf8 | =c/postgres          +
           |          |          |            |            | postgres=CTc/postgres
 template1 | postgres | UTF8     | en_US.utf8 | en_US.utf8 | =c/postgres          +
           |          |          |            |            | postgres=CTc/postgres
(4 rows)
postgres=#