PostgreSQL: GitHub Actions & GitLab CI

Start een echte PostgreSQL-service vanuit uw GitHub Actions- of GitLab CI-pipeline, voer uw tests erop uit en ruim deze automatisch weer op

👋 Welkom bij de Stackhero-documentatie!

Stackhero biedt een gebruiksklare PostgreSQL cloud oplossing die tal van voordelen biedt, waaronder:

  • Onbeperkte verbindingen en datatransfers.
  • PgAdmin webinterface inbegrepen.
  • Veel modules inbegrepen zoals PostGIS, TimescaleDB en PgVector.
  • Moeiteloze updates met slechts één klik.
  • Optimale prestaties en robuuste beveiliging aangedreven door een privé en toegewijde VM.

Bespaar tijd en vereenvoudig uw leven: het kost slechts 5 minuten om de PostgreSQL cloud hosting oplossing van Stackhero te proberen!

In deze handleiding leert u hoe u een echte, dedicated PostgreSQL-service binnen uw CI-pipeline draait met GitHub Actions of GitLab CI. Door deze stappen te volgen, kunt u uw code testen tegen een live PostgreSQL-instantie onder productie-achtige omstandigheden, zodat u niet langer afhankelijk bent van mocks of simulaties. PostgreSQL is a powerful, open source object-relational SQL database that your app can rely on in production.

Elke keer dat uw pipeline draait, krijgt u een gloednieuwe PostgreSQL-instantie. Dit betekent dat uw tests communiceren met hetzelfde type service als uw gebruikers in productie. De workflow maakt automatisch een tijdelijke stack aan, voegt PostgreSQL toe, wacht tot deze gereed is, haalt de gegenereerde inloggegevens op, voert een smoke test uit met psql, en ruimt vervolgens altijd alles op zodra de run is afgerond.

U gebruikt de Stackhero CLI, een zelfstandige command-line tool waarmee u snel en eenvoudig Stackhero-services kunt starten en beheren.

1. Maak een access token aan en sla deze op als CI-secret

Om de CLI non-interactief te laten werken, heeft u een access token nodig (formaat: usr-xxxxxx:tokenId). U hoeft dit token slechts één keer aan te maken en voegt het daarna toe aan uw CI-pipeline als een beveiligde, versleutelde secret.

  1. Token aanmaken: Ga in uw Stackhero-dashboard naar uw profielfoto rechtsboven, kies Your account, vervolgens Access tokens, en klik op Create token.
  2. Voor GitHub Actions: Ga in uw repository naar Settings > Secrets and variables > Actions > New repository secret en voer het token in als STACKHERO_TOKEN.
  3. Voor GitLab CI: Ga in uw project naar Settings > CI/CD > Variables > Add variable, stel de key in op STACKHERO_TOKEN en vink Masked aan (en Protected als uw CI alleen draait op beschermde branches).

Voeg uw access token nooit direct toe aan uw pipeline YAML-bestand. Als het token in YAML staat, kan het zichtbaar zijn voor iedereen met toegang tot de repository en mogelijk in build logs verschijnen. Door het als CI-secret op te slaan, blijft het versleuteld en gemaskeerd, zodat uw token veilig blijft.

2. Het lifecycle-script

Hieronder vindt u een volledig voorbeeldscript dat de volledige levenscyclus van de service beheert. Het laat zien hoe weinig setup er nodig is: slechts een paar commando's. U kunt de kant-en-klare YAML voor uw platform kopiëren uit de secties hieronder.

#!/bin/bash
set -euo pipefail

# STACKHERO_TOKEN wordt geleverd via de CI-secret, de CLI pikt deze automatisch op.

stackName="ci-postgresql-$$"          # Unieke stacknaam voor elke run
serviceStore="postgresql"             # De PostgreSQL service store
instance="10G"        # Pas aan indien nodig (zie stap 3)
region="europe"                         # Regio-naam (zie stackhero regions-list)

# 1. Installeer de CLI op de runner
curl -fsSL https://www.stackhero.io/install.sh | sh

# 2. Installeer de benodigde client voor smoke testing (jq + curl zijn de basis)
apt-get update && apt-get install -y --no-install-recommends jq curl postgresql-client

# 3. Maak een dedicated stack voor deze run
stackId=$(stackhero --format=script stack-create --name="$stackName")
echo "Stack aangemaakt: $stackId"

# 4. Voeg PostgreSQL toe en sla het service-id op
serviceId=$(stackhero --format=script service-add \
  --stack="$stackId" \
  --service-store="$serviceStore" \
  --instance="$instance" \
  --region="$region")
echo "Service toegevoegd: $serviceId"

# 5. Wacht tot de service actief is (dit kan enkele minuten duren)
stackhero service-wait-for --service="$serviceId"

# 6. Lees de configuratie uit (bevat de gegenereerde inloggegevens)
config=$(stackhero service-configuration-get --service="$serviceId" --format=json)

# 7. Haal de benodigde inloggegevens op
host=$(echo "$config" | jq -r '.configuration.domain')
password=$(echo "$config" | jq -r '.configuration.password')

# 8. Smoke test: Run a trivial query against the database.
PGPASSWORD="$password" psql "host=$host port=5432 user=admin dbname=admin sslmode=require" -c "SELECT 1;"

echo "✅ PostgreSQL is bereikbaar vanuit CI."

De teardown-stap, die de service verwijdert, wacht op de verwijdering en verwijdert daarna de stack, wordt behandeld in de platform-specifieke secties hieronder. Deze aanpak zorgt ervoor dat er altijd wordt opgeruimd, zelfs als een smoke test faalt.

Een stack kan alleen verwijderd worden als deze leeg is. Verwijder daarom altijd eerst de service en wacht tot deze verwijderd is, en verwijder daarna de stack. Het service-wait-for-commando zorgt ervoor dat de service daadwerkelijk draait of verwijderd is voordat u verdergaat, en is dus ook geschikt om te wachten op verwijdering.

3. Kies het instance-type

De onderstaande voorbeelden gebruiken standaard de instapinstantie 10G voor PostgreSQL. Dit is een solide keuze voor de meeste workloads, maar u kunt deze aanpassen indien gewenst. Om alle beschikbare instance-types voor PostgreSQL te bekijken, voert u het volgende uit:

# De kolom NAME toont de waarde die u aan --instance moet meegeven
stackhero instances-store-list --service-store=postgresql

4. GitHub Actions

Om te beginnen slaat u het volgende op als .github/workflows/ci.yml. Vanaf nu zal elke push en pull request tests uitvoeren tegen een echte PostgreSQL-instantie.

name: CI met PostgreSQL

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    env:
      STACKHERO_TOKEN: ${{ secrets.STACKHERO_TOKEN }}
      STACK_NAME: ci-postgresql-${{ github.run_id }}-${{ github.run_attempt }}
      INSTANCE: "10G"   # Pas aan indien nodig (zie stap 3)
      REGION: europe
    steps:
      - uses: actions/checkout@v4

      - name: Installeer de Stackhero CLI en de client
        run: |
          curl -fsSL https://www.stackhero.io/install.sh | sh
          apt-get update && apt-get install -y --no-install-recommends jq curl postgresql-client

      - name: Maak de PostgreSQL-service aan
        run: |
          set -euo pipefail
          STACK_ID=$(stackhero --format=script stack-create --name="$STACK_NAME")
          echo "STACK_ID=$STACK_ID" >> "$GITHUB_ENV"
          SERVICE_ID=$(stackhero --format=script service-add \
            --stack="$STACK_ID" \
            --service-store="postgresql" \
            --instance="$INSTANCE" \
            --region="$REGION")
          echo "SERVICE_ID=$SERVICE_ID" >> "$GITHUB_ENV"
          stackhero service-wait-for --service="$SERVICE_ID"

      - name: Voer tests uit tegen PostgreSQL
        run: |
          set -euo pipefail
          config=$(stackhero service-configuration-get --service="$SERVICE_ID" --format=json)
          host=$(echo "$config" | jq -r '.configuration.domain')
password=$(echo "$config" | jq -r '.configuration.password')
          # Run a trivial query against the database.
          PGPASSWORD="$password" psql "host=$host port=5432 user=admin dbname=admin sslmode=require" -c "SELECT 1;"
          echo "✅ PostgreSQL is bereikbaar vanuit CI."
          # U kunt hier uw eigen test suite uitvoeren met bovenstaande inloggegevens ...

      - name: Opruimen (altijd, ook bij fouten)
        if: always()
        run: |
          if [ -n "${SERVICE_ID:-}" ]; then
            stackhero service-delete --service="$SERVICE_ID" --confirm
            stackhero service-wait-for --service="$SERVICE_ID"
          fi
          if [ -n "${STACK_ID:-}" ]; then
            stackhero stack-delete --stack="$STACK_ID" --confirm
          fi

De teardown-stap is ingesteld met if: always() zodat deze altijd wordt uitgevoerd, ongeacht het resultaat. Zo wordt uw PostgreSQL-instantie altijd verwijderd en betaalt u niet voor ongebruikte resources.

5. GitLab CI

U kunt deze configuratie opslaan als .gitlab-ci.yml. Met deze setup start elke pipeline-run een nieuwe, echte PostgreSQL voor uw tests.

test:
  image: ubuntu:24.04
  variables:
    STACK_NAME: "ci-postgresql-$CI_PIPELINE_ID-$CI_JOB_ID"
    INSTANCE: "10G"   # Pas aan indien nodig (zie stap 3)
    REGION: "europe"
    SERVICE_STORE: "postgresql"
  # STACKHERO_TOKEN komt uit de CI/CD-variabele die u in stap 1 heeft aangemaakt.
  script:
    - set -euo pipefail
    - curl -fsSL https://www.stackhero.io/install.sh | sh
    - apt-get update && apt-get install -y --no-install-recommends jq curl postgresql-client
    - STACK_ID=$(stackhero --format=script stack-create --name="$STACK_NAME")
    - echo "STACK_ID=$STACK_ID" >> deploy.env
    - SERVICE_ID=$(stackhero --format=script service-add --stack="$STACK_ID" --service-store="$SERVICE_STORE" --instance="$INSTANCE" --region="$REGION")
    - echo "SERVICE_ID=$SERVICE_ID" >> deploy.env
    - stackhero service-wait-for --service="$SERVICE_ID"
    - config=$(stackhero service-configuration-get --service="$SERVICE_ID" --format=json)
    - host=$(echo "$config" | jq -r '.configuration.domain')
password=$(echo "$config" | jq -r '.configuration.password')
    # Run a trivial query against the database.
    - PGPASSWORD="$password" psql "host=$host port=5432 user=admin dbname=admin sslmode=require" -c "SELECT 1;"
    - echo "✅ PostgreSQL is bereikbaar vanuit CI."
    # U kunt hier uw eigen test suite uitvoeren met bovenstaande inloggegevens ...
  after_script:
    - test -f deploy.env && . ./deploy.env || true
    - >
      if [ -n "${SERVICE_ID:-}" ]; then
        stackhero service-delete --service="$SERVICE_ID" --confirm
        stackhero service-wait-for --service="$SERVICE_ID"
      fi
    - >
      if [ -n "${STACK_ID:-}" ]; then
        stackhero stack-delete --stack="$STACK_ID" --confirm
      fi

In GitLab vindt het opruimen plaats in after_script. Deze sectie wordt altijd uitgevoerd, zelfs als de job faalt, zodat uw PostgreSQL-resources worden verwijderd en u niet betaalt voor ongebruikte resources.

In GitLab draait after_script in een schone shell. Om hiermee om te gaan, schrijft het script de service- en stack-ID's naar deploy.env tijdens de job en laadt deze opnieuw in vóór het opruimen. Zo worden uw resources altijd opgeruimd, zelfs als er halverwege iets misgaat.

Dit is de volledige CI-levenscyclus voor PostgreSQL: maak een stack aan, voeg de service toe, wacht, haal inloggegevens op, smoke-test en altijd opruimen. Elke pipeline-run krijgt een echte, geïsoleerde service, en er blijft niets draaien als u klaar bent. Voor meer informatie over beschikbare commando's en non-interactieve authenticatie met STACKHERO_TOKEN, kunt u de volledige CLI-documentatie raadplegen.

Andere artikelen voor PostgreSQL

  1. Aan de slag
    Hoe te beginnen met PostgreSQL
  2. Alternatief voor het stopzetten van ElephantSQL
  3. Automatiseren met de CLI
    Start PostgreSQL, haal de inloggegevens op en wijzig de configuratie programmatisch met de Stackhero CLI