For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /docs/overview.md.
Ivory

    Overview

    What is a Keeper?

    A Keeper is the HA management layer responsible for leader election, automatic failover, and cluster coordination. Ivory uses "Keeper" as its generic term for this role — the same interface works regardless of which HA system the cluster uses. A Keeper can be a standalone agent running beside the database engine or a management system embedded directly in it. Patroni is the first supported implementation, with more planned.

    The Keeper's job is to answer one question at all times: who is the leader? It does this by:

    • Continuously monitoring the local database instance and reporting its health
    • Competing with peer Keeper agents for the leadership lock in a shared coordination backend (such as a DCS — Distributed Configuration Store like etcd, Consul, or ZooKeeper)
    • Triggering automatic failover when the current leader loses the lock or becomes unreachable
    • Exposing a management API (on the keeper port, default 8008) that Ivory uses to read cluster state and issue management commands

    Because every node exposes a Keeper and every Keeper knows the full cluster topology, Ivory only needs to reach any one node's keeper port to get a complete picture of the cluster.

    Node Roles

    RoleDescription
    LeaderThe primary node. Holds the leadership lock. Accepts reads and writes. Exactly one node holds this role at a time.
    ReplicaA standby node. Continuously replicates from the leader. Read-only.
    UnknownRole could not be determined — the Keeper is unreachable or the node is initialising.

    Cluster Health Grid

    The Overview block is the cluster-level dashboard. It shows the real-time state of every node as reported by the Keeper.

    FieldDescription
    RoleLeader or Replica
    StateKeeper-reported state: running, streaming, paused, stopped, failed, …
    LagReplication lag in bytes behind the leader (N/A for the leader itself)
    Pending RestartWhether the database needs a restart to apply a pending configuration change
    ScheduledAny scheduled switchover or restart waiting to fire
    TagsKey-value pairs set on this node by the Keeper
    WarningsIssues Ivory detected: connection errors, replication problems, etc.

    Clicking any node card opens its Node view for fine-grained per-node operations.

    HA Operations

    Every node card in the grid has its own action buttons. The cluster header additionally provides Pause and Resume which affect the entire cluster at once.

    Per-node actions (available on each node card):

    OperationWhen to use
    SwitchoverPlanned leadership change. The current leader steps down cleanly, then a replica is promoted. Choose which replica becomes the new leader, or let the Keeper decide. Can be scheduled.
    FailoverForced promotion of a replica without waiting for the current leader. Use only when the leader is unreachable.
    ReinitialiseWipes and re-syncs a node's data directory from the current leader. Use when a replica is too far behind or its data directory is corrupted.
    RestartRestarts the database process on this node. Can be scheduled.
    ReloadReloads configuration without a restart — applies changes that take effect immediately.

    Cluster-level actions (cluster header):

    OperationWhen to use
    PausePuts the Keeper into maintenance mode across the entire cluster. Automatic failovers are disabled. Use for planned maintenance.
    ResumeRestores normal HA behaviour after a pause.

    The Node → Keeper tab shows all actions for a single node in a dedicated full-page view alongside the configuration editor.

    Cluster Options

    Click the settings icon in the top-right corner to open the cluster options panel:

    • Update database credentials and Keeper API credentials
    • Configure TLS for keeper and database connections
    • Assign or update a vault reference for credential management
    • Add, remove, or rename tags
    • Override the main instance — pin operations to a specific node instead of the auto-selected leader