Last Updated: October 04, 2020
· itseranga

PostgreSQL with docker on OS-X


  • Docker using light weigh virtualization system provide by linux kernal which introduced as container
  • More info - Linux containers
  • Since docker using linux kernal features the docker host machine should runs on linux
  • In order to run docker in OS-X, we have to use linux virtual machine
  • We are using boot2docker light weight linux VM in here
  • Following diagram briefly explains how docker works in OS-X


  • Docker server runs on boot2docker VM(docker host)
  • Docker client runs on OS-X host machine
  • We can interact with docker through boot2docker VM

Install boot2docker

  • First install VirtualBox
  • Then install boot2docker and other packages, I'm using Homebrew to install all the packages
brew update

## install boot2docker
brew install boot2docker

## install docker client
brew install docker

## up boot2docker 
boot2docker init
boot2docker up
  • Execute following commands to view docker information
## docker info
docker info

## boot2docker info
boot2docker info
boot2docker status
boot2docker ip

## docker host

Docker and postgres

Search for postgres

  • You can get the latest version of postgres image from docker-registry
  • If you have your own private docker registry you can get postgres from it as well
  • More info - using private docker registry
  • For an example use following command to search postgres from docker-registry
docker search "postgres"
  • Following is the output of search


Install postgres

  • You can install postgres via docker run command
docker run -p 5432:5432 \
--name postgres-db \
-d postgres:latest
  • Few things to notice

    1. -p 5432:5432 defines port forwarding, it means forward docker container port 5432 to the docker host post 5432
    2. --name postgres-db defines name of the container
    3. -d allows to run container as a demon
    4. postgres:latest defines the container name and tag in docker-registry
  • If you download postgres from your own registry(private registry), you have to specifies the registry details with docker run command

docker run -p 5432:5432 \
--name postgres-db \
  • Few things to notice

    1. defines private registry host
    2. postgres:2.48 defines postgres container name and tag in the registry
  • Now we have successfully installed postgres with docker(on docker container)

Run postgres

  • We have to start newly created postgres container
## docker start <container-name>
docker start postgres-db
  • Issue docker ps command to verify the status of the containers
docker ps -a
  • Output would be like below(it will list container details)


Connect to postgres

  • Now you can connect to postgres service from pgAdmin(or any other postgres client)
  • Following are my connection parameters on pgAdmin3


  • Few things to notice,

    1. I'm trying to connect postgres service via localhost
    2. This will gives an error Failed connect to localhost:5432; Connection refused
  • Reason to this error is, we trying to connect localhost:5432 of our host OS-X machine

  • But our port forwarding rules defines to forward docker container port 5432 to docker host post 5432(in boot2docker VM)

  • Its NOT for host OS-X port 5432

  • To simply solve this issue we can connect to boot2docker VM(docker host)

  • Use following command to get boot2docker IP

boot2docker ip

## output
  • My latest working connection parameters are below


More on boot2docker and port forwarding

docker and docker-host

  • As I mentions earlier docker forward posts to docker host
  • In our scenario boot2docker is the docker host(not our OS-X machine)

Port forward to OS-X localhost

  • If you want to access postgres via localhost, you have to forward the 5432 port from boot2docker to OS-X 5432 port
  • Following diagram shows the overview of the port forwarding layers


Define port forwarding rules

  • VirtaulBox provides a package VBoxManage to which can use to define/modify virtual box configuration
  • We can use VBoxManage to specify the port forwarding rules (form boot2docker to OS-X host)
  • Execute following commands from OS-X
## first need to down boot2docker
boot2docker down

## define port forwarding rules
VBoxManage modifyvm "boot2docker-vm" --natpf1 "postgres-port,tcp,,5432,,5432"

## up boot2docker 
boot2docker up

## start postgres 
docker start postgres-db
  • Few things to notice,

    1. postgres-port - name of the modification
    2. - localhost
    3. 5432,,5432 - VM machine(boot2docker) post and host machine(OS-X machine) port
  • Now you can connect to postgres via localhost(without boot2docker ip -

  • If you want to delete the previously defined port forwarding rule, use following command

## first need to down boot2docker
boot2docker down

## delete port forwarding rule
VBoxManage modifyvm "boot2docker-vm" --natpf1 delete "postgres-port"

## up boot2docker 
boot2docker up