> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/open-source/use-harness-open-source/pipelines-1/samples/postgres.md).

# Postgres

This guide covers configuring continuous integration pipelines for projects that have a PostgreSQL dependency.

## Basic Example <a href="#basic-example" id="basic-example"></a>

In the below example we demonstrate a pipeline that launches PostgreSQL as a background step. The database server will be available at `database:5432`, where the hostname matches the background step name.

```yaml
kind: pipeline
spec:
  stages:
  - type: ci
    spec:
      steps:
      - name: database
        type: background
        spec:
          container: postgres:14.4-alpine
          envs:
            POSTGRES_DB: test
            POSTGRES_USER: postgres
            POSTGRES_PASSWORD: password

      - name: test
        type: run
        spec:
          envs:
            PGPASSWORD: password
          container: postgres:14.4-alpine
          script: |-
            until pg_isready -U postgres -h database; do sleep 2; done
            psql -U postgres -d test -h database
```

## Database Settings <a href="#database-settings" id="database-settings"></a>

The official Postgres image provides environment variables used at startup to create the default username, password, database and more. Please see the official image [documentation](https://hub.docker.com/_/postgres/) for more details.

```yaml
      - name: database
        type: background
        spec:
          container: postgres:14.4-alpine
          envs:
            POSTGRES_DB: test
            POSTGRES_USER: postgres
            POSTGRES_PASSWORD: password
```

## Common Problems <a href="#common-problems" id="common-problems"></a>

### Initialization <a href="#initialization" id="initialization"></a>

If you are unable to connect to the Postgres container please make sure you are giving Postgres adequate time to initialize and begin accepting connections. The `pg_isready` tool provided by PostgreSQL can help ensure the database is ready to accept connections.

```yaml
      - name: test
        type: run
        spec:
          envs:
            PGPASSWORD: password
          container: postgres:14.4-alpine
          script: |-
            until pg_isready -U postgres -h database; do sleep 2; done
            psql -U postgres -d test -h database
```

### Incorrect Hostname <a href="#incorrect-hostname" id="incorrect-hostname"></a>

You cannot use `127.0.0.1` or `localhost` to connect with the PostgreSQL container. If you are unable to connect to the Postgres container please verify you are using the correct hostname, corresponding with the name of the postgres service container.

Bad:

```yaml
      - name: test
        type: run
        spec:
          envs:
            PGPASSWORD: password
          container: postgres:14.4-alpine
          script: |-
            psql -U postgres -d test -h localhost
```

Good:

```yaml
      - name: test
        type: run
        spec:
          envs:
            PGPASSWORD: password
          container: postgres:14.4-alpine
          script: |-
            psql -U postgres -d test -h database
```