> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# cimg/postgres

A PostgreSQL Docker image built to run on CircleCI. There's also a variant available with PostGIS.


***This image is designed to supercede the legacy CircleCI PostgreSQL image, `circleci/postgres`.***

`cimg/postgres` is a Docker image created by CircleCI with continuous integration builds in mind.


## Getting Started

This image can be used with the CircleCI `docker` executor as a secondary image.
For example:

```yaml
jobs:
  build:
    docker:
      - image: cimg/go:1.17
      - image: cimg/postgres:18.4.0
    steps:
      - checkout
```

In the above example, the CircleCI Go Docker image is used for the primary container while the PostgreSQL image is used as a secondary.
More specifically, the tag `13.2` is used meaning the version of PostgreSQL will be v13.2.
You can now connect to a PostgreSQL instance from the primary image within the steps for this job.


## How This Image Works

This image contains the PostgreSQL database and its complete toolchain.

### Tagging Scheme

This image has the following tagging scheme:

```
cimg/postgres:<pg-version>[-variant]
```

`<pg-version>` - The version of PostgreSQL to use.
`[-variant]` - a variant tag can optionally be added.
The available variants can be found [below](#variants).


## Image Tags


### Variants

Variant images typically contain the same base software, but with a few additional modifications.

#### PostGIS

The PostGIS variant is the same PostgreSQL image but with PostGIS (and its several dependencies) pre-installed.
The PostGIS variant can be used by appending `-postgis` to the end of an existing `cimg/postgres` tag.

```yaml
jobs:
  build:
    docker:
      - image: cimg/go:1.17
      - image: cimg/postgres:18.4.0-postgis
    steps:
      - checkout
      - run: echo "Do things"
```

#### RAM

The legacy version of this image, `circleci/postgres` had a RAM variant.
This is no longer the case.
We're determining how much of a performance increase does this variant actually give before we decide to bring it back.
If you used the legacy PostgreSQL image and you have data on the ram vs non-ram variant build times, please open a GitHub Issue and let us know.