{
  "slug": "postgresql-timeline",
  "term": "PostgreSQL timeline",
  "aliases": [
    "WAL timeline"
  ],
  "definition": "A PostgreSQL timeline identifies a branch of a database cluster's write-ahead-log history.",
  "note": "Completing archive recovery creates a new branch for subsequent WAL, preserving the earlier history. Timeline IDs distinguish WAL filenames. [pg-timelines]\n\nSelection: recovery_target_timeline accepts an ID, current for the base backup's timeline, or latest, the default. This selects history, not the replay stopping point. [pg-target-timeline]\n\nInterpretation: a larger timeline ID alone does not establish ancestry or possession of another branch's commits. Compare cluster identity, timeline history and the named LSN progress stage together. IDENTIFY_SYSTEM reports systemid, timeline and the current WAL flush position separately. [pg-identity] [pg-history-code]\n\nBackup scope: a standby following an upstream promotion during a base backup can require WAL ranges on several timelines. The manifest retains the timeline for each range rather than one unqualified byte interval. [pg-manifest-ranges]",
  "related": [
    "timeline-history-file",
    "log-sequence-number",
    "replication-lag",
    "point-in-time-recovery",
    "recovery-target",
    "backup-manifest"
  ],
  "citations": [
    {
      "id": "pg-timelines",
      "title": "PostgreSQL 18: Timelines",
      "url": "https://www.postgresql.org/docs/18/continuous-archiving.html#BACKUP-TIMELINES",
      "accessed": "2026-10-20"
    },
    {
      "id": "pg-target-timeline",
      "title": "PostgreSQL 18: recovery_target_timeline",
      "url": "https://www.postgresql.org/docs/18/runtime-config-wal.html#GUC-RECOVERY-TARGET-TIMELINE",
      "accessed": "2026-10-20"
    },
    {
      "id": "pg-identity",
      "title": "PostgreSQL 18: IDENTIFY_SYSTEM and TIMELINE_HISTORY",
      "url": "https://www.postgresql.org/docs/18/protocol-replication.html",
      "accessed": "2026-10-20"
    },
    {
      "id": "pg-history-code",
      "title": "PostgreSQL 18.0: timeline history reader and writer",
      "url": "https://github.com/postgres/postgres/blob/REL_18_0/src/backend/access/transam/timeline.c",
      "accessed": "2026-10-20"
    },
    {
      "id": "hesela-replication",
      "title": "Hesela: Replication acknowledgements: received, durable, applied",
      "url": "https://hesela.com/analyses/replication-acknowledgements-durability-lag/#timeline-identity",
      "accessed": "2026-10-20"
    },
    {
      "id": "pg-manifest-ranges",
      "title": "PostgreSQL 18: Backup Manifest WAL Range Object",
      "url": "https://www.postgresql.org/docs/18/backup-manifest-wal-ranges.html",
      "accessed": "2026-10-21"
    }
  ],
  "status": "shipping",
  "advantages": [],
  "limitations": [],
  "supersedes": [],
  "supersededBy": [],
  "firstSeen": null,
  "lastSeen": null,
  "updated": "2026-10-21"
}