Flyway-migrering

Opprett en ny Flyway-migreringsfil etter teamets konvensjoner.

Steg

1. Finn migreringsmappen ved å søke etter eksisterende V__.sql-filer under src/main/resources/db/, eller sjekk flyway.locations i applikasjonskonfigurasjonen. List deretter eksisterende migreringer for å finne neste versjonsnummer.
2. Les den nyeste migreringen for å forstå navngivings- og stilkonvensjonene
3. Opprett den nye migreringsfilen med riktig navn: V{next}__{description}.sql

Konvensjoner

• Foretrekk fail-fast i versjonerte migreringer — bruk IF NOT EXISTS / IF EXISTS bare når du bevisst vil gjøre migreringen idempotent
• Bruk TIMESTAMPTZ for tidsstempler (med DEFAULT NOW())
• Bruk UUID med genrandomuuid() for primærnøkler der det passer
• Bruk TEXT i stedet for VARCHAR
• Legg til indekser for kolonner det søkes ofte på
• Bruk CREATE INDEX CONCURRENTLY IF NOT EXISTS for nye indekser på eksisterende PostgreSQL-tabeller, men behandle avbrudd eksplisitt: en ugyldig indeks med samme navn kan bli liggende igjen
• Bruk vanlig CREATE INDEX bare når indeksen opprettes sammen med en ny tom tabell i samme migrering
• Én fokusert endring per migrering

Mal

-- V{number}__{description}.sql
CREATE TABLE table_name (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    created_at TIMESTAMPTZ DEFAULT NOW() NOT NULL,
    updated_at TIMESTAMPTZ DEFAULT NOW() NOT NULL
);

CREATE INDEX idx_table_name_field ON table_name(field);

Bruk eksempelet over bare når tabellen opprettes i samme migrering og fortsatt er tom.

Indekser på eksisterende tabeller

Bruk CREATE INDEX CONCURRENTLY IF NOT EXISTS for nye indekser på eksisterende tabeller, også når brukeren ikke sier at tabellen er stor. Dette er standardvalget i PostgreSQL-migreringer som treffer tabeller med data.

-- V5__add_index_concurrently.sql
-- NB: CREATE INDEX CONCURRENTLY kan ikke kjøre i transaksjon
-- Legg denne i egen migrering og verifiser Flyway-oppsettet først
-- flyway:executeInTransaction=false
CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_vedtak_bruker ON vedtak (bruker_id);

CREATE INDEX CONCURRENTLY IF NOT EXISTS må ligge i egen migrering og ikke kjøre i transaksjon. Hvis en slik migrering ble avbrutt, må du sjekke om en ugyldig indeks med samme navn ligger igjen og rydde den opp før ny kjøring; IF NOT EXISTS kan ellers skjule problemet i stedet for å gjøre re-kjøring trygg. Hvis prosjektet bruker rammeverk-konfig for Flyway, verifiser tilsvarende innstilling der i stedet for å gjette på globale properties.

Langvarige migreringer og NAIS

Hvis migreringen kan ta tid, sjekk også nais/ eller .nais/ for appens manifest. Verifiser at appen har spec.startup hvis Flyway må få tid til å fullføre før liveness overtar.

Hvis spec.startup mangler, foreslå eller legg den til med samme health-path som appen allerede bruker, for eksempel:

spec:
  startup:
    path: /isAlive
    initialDelay: 10
    periodSeconds: 5
    failureThreshold: 60

Informer bruker om hvor lang tid startup-proben er konfigurert med om den finnes fra før, eller hvor lang tid ditt forslag setter den til.

Ikke endre liveness/readiness unødvendig. Målet er å unngå at poden blir restartet før migreringen er ferdig.

Repeterbare migreringer

R__*.sql-filer kjøres på nytt hver gang innholdet endres.

Bruk dem for:

• views
• funksjoner
• triggers
• seed data

Hold versjonerte V__-migreringer uendrede, og bruk repeterbare migreringer for objekter som naturlig regenereres.

Eksempel på updated_at-trigger i en repeterbar migrering:

-- R__update_updated_at.sql
CREATE OR REPLACE FUNCTION update_updated_at_column()
RETURNS TRIGGER AS $$
BEGIN
    NEW.updated_at = NOW();
    RETURN NEW;
END;
$$ language 'plpgsql';

Testcontainers-eksempel

Bruk Testcontainers for å verifisere at migrasjoner faktisk kan kjøres mot en ekte PostgreSQL-instans i tester.

@Testcontainers
class DatabaseTest {
    companion object {
        @Container
        val postgres = PostgreSQLContainer("postgres:15-alpine")
            .withDatabaseName("testdb")
    }

    @Test
    fun `migrasjoner kjører uten feil`() {
        Flyway.configure()
            .dataSource(postgres.jdbcUrl, postgres.username, postgres.password)
            .load()
            .migrate()
    }
}

Dette gir rask tilbakemelding på at migrasjonsrekkefølge, SQL-syntaks og Flyway-konfig faktisk fungerer sammen.