How to Run a Postgres Service in Bitbucket Pipelines

Bitbucket Pipelines runs backing databases as services defined under definitions:services and attached per step.

Declare the service image and variables under definitions.services, then add the service name to a step's services: list. It is reachable on localhost.

Postgres service

Define the Postgres service once, then attach it to the test step; connect via localhost.

definitions:
  services:
    postgres:
      image: postgres:16
      variables:
        POSTGRES_DB: app_test
        POSTGRES_PASSWORD: postgres

pipelines:
  default:
    - step:
        name: Test
        image: node:20
        services:
          - postgres
        script:
          - export DATABASE_URL=postgres://postgres:postgres@localhost:5432/app_test
          - npm ci && npm test

Gotchas

• Services bind to localhost from the step container - connect to localhost:5432, not a hostname.
• All services for a step plus the step itself share a 4 GB memory limit (8 GB on larger size) - size accordingly.
• Define the service once under definitions: and reference it by name in each step that needs it.

Related guides