...
Eroare Docker · Baze de date în containere

FATAL: the database system is starting up

Pe scurt

Aplicația s-a conectat la Postgres înainte ca acesta să termine pornirea (sau inițializarea la prima rulare). În Compose, adaugă bazei un healthcheck cu pg_isready și fă aplicația să aștepte cu depends_on: condition: service_healthy; în cod, adaugă reîncercări la conectare.

Explicat de Tudor Andrei Dumitrescu, Senior Software Developer, fondatorul Academiei ProgramatorilorActualizat la

Ce înseamnă

Mesajul vine chiar de la serverul Postgres: conexiunea a ajuns la el, dar serverul e încă în faza de pornire (recuperare, citirea datelor sau, la prima rulare, inițializarea bazei și rularea scripturilor) și refuză temporar clienții. După câteva secunde, aceeași conexiune ar reuși.

În Docker apare tipic cu Compose: depends_on: - db (forma scurtă) așteaptă doar ca containerul db să fi pornit, nu ca Postgres să accepte conexiuni. Aplicația pornește imediat, încearcă să se conecteze, primește the database system is starting up și, dacă nu reîncearcă, se oprește cu eroare.

Ca să eviți asta, Compose trebuie să știe când baza e gata: healthcheck-ul cu pg_isready raportează healthy doar când serverul acceptă conexiuni, iar condition: service_healthy așteaptă exact acel moment.

De ce apare: cauzele frecvente

1depends_on în forma scurtă

Greșit
BASH
api:
  depends_on:
    - db
Corect
BASH
api:
  depends_on:
    db:
      condition: service_healthy

Forma lungă cu service_healthy așteaptă ca healthcheck-ul bazei să treacă, nu doar pornirea containerului.

2Fără healthcheck pe bază

Greșit
BASH
db:
  image: postgres:16
Corect
BASH
db:
  image: postgres:16
  healthcheck:
    test: ["CMD-SHELL", "pg_isready -U postgres"]
    interval: 5s
    retries: 5

pg_isready răspunde cu succes doar când serverul acceptă conexiuni.

3Aplicația nu reîncearcă

Greșit
BASH
pool = connect(DATABASE_URL)
# o singură încercare la pornire
Corect
BASH
for incercare in range(10):
    try:
        pool = connect(DATABASE_URL)
        break
    except OperationalError:
        time.sleep(2)

Reîncercările acoperă și repornirile bazei din timpul rulării, nu doar pornirea inițială.

Repară tu

Repară eroarea, direct în pagină

În ~/magazin, db (postgres:16) are deja un healthcheck cu pg_isready, dar serviciul api folosește depends_on: - db și pornește prea devreme, primind the database system is starting up. Fă ca api să aștepte ca db să fie sănătos și pornește proiectul.

Indiciu

Forma lungă: depends_on: → db: → condition: service_healthy.

Alte forme ale mesajului

  • psql: error: connection to server at "db" (172.18.0.2), port 5432 failed: FATAL: the database system is starting up
  • error: the database system is starting up
  • FATAL: the database system is shutting down

Cum o eviți pe viitor

În orice compose.yaml cu bază de date, pune healthcheck pe bază și condition: service_healthy la serviciile care se conectează la ea. Scrie și codul de conectare cu reîncercări, pentru că baza poate reporni și în timpul rulării. La prima pornire cu volum gol, inițializarea durează mai mult; ține cont de asta la retries și start_period.

Întrebări frecvente

De ce eroarea apare doar la prima pornire?

La prima rulare, imaginea inițializează baza și rulează scripturile din /docker-entrypoint-initdb.d, deci durează mai mult. La pornirile următoare, serverul e gata în una-două secunde și aplicația are noroc.

Ajunge un sleep 10 înainte de pornirea aplicației?

Merge uneori, dar e fragil: pe un calculator mai lent sau cu mai multe date, 10 secunde nu ajung. Healthcheck-ul așteaptă exact cât trebuie.

Erori înrudite

← Toate erorile Docker

Tudor Andrei Dumitrescu
Cine a explicat eroarea

Tudor Andrei Dumitrescu

Senior Software Developer · fondatorul Academiei Programatorilor

LinkedIn
  1. 2019 Junior JavaCognizant Softvision
  2. 2021 Mid JavaCognizant Softvision
  3. 2022 Team LeaderEndava
  4. 2023 Senior Software DeveloperUniCredit
  5. Acum Senior Software DeveloperHCLTech
Certificat de absolvire Instructor / Preparator formare, Tudor Andrei Dumitrescu
Certificat de formator autorizatMinisterul Muncii și Ministerul Educației · 2022
Certificat de absolvire Instructor / Preparator formare, Tudor Andrei Dumitrescu

Certificat de formator autorizat · Ministerul Muncii și Ministerul Educației · 2022

Din 2020 construiește Academia Programatorilor, iar din 2026 și JoburiIT.ro. Fiecare eroare de aici a fost reprodusă în editorul nostru: codul greșit chiar dă mesajul din titlu, iar reparația chiar funcționează.

Învață Docker de la zero, cu exerciții la fiecare lecție

Curs Docker: lecții scurte, fiecare cu un exercițiu verificat automat, direct în browser. Primele 15 lecții sunt gratuite.