{
  "slug": "timeline-history-file",
  "term": "Timeline history file (PostgreSQL)",
  "aliases": [
    "WAL timeline history file"
  ],
  "definition": "A PostgreSQL timeline history file records ancestor timelines and WAL switchpoints used to select the appropriate log history during recovery.",
  "note": "The child timeline's .history file inherits its parent's history and adds the parent ID, switchpoint LSN and reason. PostgreSQL 18.0 writes parent IDs in decimal within entries; the filename encodes the child ID in hexadecimal. Timeline 1 has no preceding branch and normally has no history file. [pg-history-code]\n\nThe replication command TIMELINE_HISTORY retrieves a specified timeline's filename and contents. This metadata identifies history, not the availability or integrity of all required WAL segments. [pg-identity]\n\nKeep this ancestry metadata distinct from a backup manifest's required WAL intervals. A history file helps select the branch; it is not an inventory proving that its segments are retrievable. [pg-history-code]",
  "related": [
    "postgresql-timeline",
    "wal-archiving",
    "point-in-time-recovery",
    "log-sequence-number",
    "backup-manifest"
  ],
  "citations": [
    {
      "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": "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": "hesela-replication",
      "title": "Hesela: Replication acknowledgements: received, durable, applied",
      "url": "https://hesela.com/analyses/replication-acknowledgements-durability-lag/#timeline-identity",
      "accessed": "2026-10-20"
    }
  ],
  "status": "shipping",
  "advantages": [],
  "limitations": [],
  "supersedes": [],
  "supersededBy": [],
  "firstSeen": null,
  "lastSeen": null,
  "updated": "2026-10-21"
}