pgspec

type AccessCapabilities struct {
	CredentialReceipts bool `json:"credentialReceipts"`
}

type AccessRequest struct {
	// Journal uses a distinct operation so older agents reject it before SQL.
	RequestID           string     `json:"requestId,omitempty"`
	RoleOperation       string     `json:"roleOperation,omitempty"`
	Operation           string     `json:"operation"`
	Name                string     `json:"name,omitempty"`
	Role                *RoleWrite `json:"role,omitempty"`
	Database            *Database  `json:"database,omitempty"`
	Grant               *Grant     `json:"grant,omitempty"`
	Force               bool       `json:"force,omitempty"`
	AvailableExtensions []string   `json:"availableExtensions,omitempty"`
	Extensions          []string   `json:"extensions,omitempty"`
	Binding             bool       `json:"binding,omitempty"`
	// ExpectedRoleOID fences binding updates/deletes against native replacement.
	ExpectedRoleOID uint32 `json:"expectedRoleOid,omitempty"`
}

type AccessResult struct {
	Outcome string `json:"outcome"` // applied, rejected, unknown
	Code    string `json:"code,omitempty"`
	Message string `json:"message,omitempty"`
	Status  int    `json:"status,omitempty"`
	RoleOID uint32 `json:"roleOid,omitempty"`
}

type ActionResponse struct {
	OK      bool   `json:"ok"`
	Message string `json:"message,omitempty"`
}

type ArchiveCoversRequest struct {
	LSN string `json:"lsn"`
}

type ArchiveCoversResponse struct {
	Covers bool `json:"covers"`
}

type Backup struct {
	Repository Repository `json:"repository"`
	// AdditionalRepositories receive WAL alongside the default repository so
	// schedule/manual storage overrides retain a consistent recovery chain.
	AdditionalRepositories []Repository `json:"additionalRepositories,omitempty"`
	// ArchiveTimeoutSeconds bounds the age of the newest archived WAL (RPO).
	ArchiveTimeoutSeconds int `json:"archiveTimeoutSeconds"`
}

type BackupInfo struct {
	Label      string            `json:"label"`
	Type       string            `json:"type"`
	Prior      string            `json:"prior,omitempty"`
	StartedAt  string            `json:"startedAt"`
	StoppedAt  string            `json:"stoppedAt"`
	WALStart   string            `json:"walStart,omitempty"`
	WALStop    string            `json:"walStop,omitempty"`
	SizeBytes  int64             `json:"sizeBytes"`
	RepoBytes  int64             `json:"repoBytes"`
	References []string          `json:"references,omitempty"`
	SystemID   string            `json:"systemId,omitempty"`
	Version    string            `json:"version,omitempty"`
	Annotation map[string]string `json:"annotation,omitempty"`
}

type BackupInfoResponse struct {
	Backups    []BackupInfo `json:"backups"`
	ArchiveMin string       `json:"archiveMin,omitempty"`
	ArchiveMax string       `json:"archiveMax,omitempty"`
	SystemID   string       `json:"systemId,omitempty"`
	Version    string       `json:"version,omitempty"`
}

type BackupRequest struct {
	// Receipt is a durable idempotency key (operation ID).
	Receipt    string      `json:"receipt"`
	Type       string      `json:"type"` // full, diff, incr
	Repository *Repository `json:"repository,omitempty"`
	// ObserveOnly polls an existing receipt without starting an absent backup.
	ObserveOnly bool `json:"observeOnly,omitempty"`
}

type BackupResponse struct {
	State   string `json:"state"` // running, done, failed
	Label   string `json:"label,omitempty"`
	Message string `json:"message,omitempty"`
}

type Bootstrap struct {
	// Method is "initdb" (default) or "restore".
	Method string `json:"method"`
	// AllowInitDB authorizes only the first cluster initialization. Formed
	// clusters may clone surviving data or restore, never bootstrap empty.
	AllowInitDB bool `json:"allowInitDB,omitempty"`
	// SeedMember restricts DCS initialization during single-to-HA adoption.
	// Other members may stream but must not initialize an empty cluster.
	SeedMember string `json:"seedMember,omitempty"`
	// Restore is set for Method "restore" (in-place restore or clone).
	Restore *Restore `json:"restore,omitempty"`
	// RecoverySuperuser authenticates only the fenced restored database until
	// its passwords are replaced with this cluster's own credentials.
	RecoverySuperuser *Credentials `json:"recoverySuperuser,omitempty"`
	// Generation changes whenever a new bootstrap must be performed, so agents
	// never repeat a completed restore after a restart.
	Generation int `json:"generation,omitempty"`
}

type Certificate struct {
	CertPEM string `json:"certPEM"`
	KeyPEM  string `json:"keyPEM"`
}

type Citus struct {
	Group    int    `json:"group"`
	Database string `json:"database"`
}

type CitusNode struct {
	NodeID  int    `json:"nodeId"`
	GroupID int    `json:"groupId"`
	Host    string `json:"host"`
	Port    int    `json:"port"`
	Role    string `json:"role"`
	Active  bool   `json:"active"`
}

type CitusNodeRequest struct {
	Host string `json:"host"`
	Port int    `json:"port"`
}

type CitusRebalanceRequest struct {
	JobID int64 `json:"jobId"`
}

type CitusRebalanceResponse struct {
	JobID int64  `json:"jobId"`
	State string `json:"state"`
}

type CitusRebalanceStartRequest struct {
	Strategy string `json:"strategy"`
	Receipt  string `json:"receipt"`
}

type CitusRestoreMetadataRequest struct {
	Nodes []CitusNode `json:"nodes"`
}

type CitusRestorePoint struct {
	NodeID int    `json:"nodeId"`
	Host   string `json:"host"`
	Port   int    `json:"port"`
	// LSN is the exact coordinator marker position, or a conservative
	// post-marker WAL insertion upper bound on a worker primary.
	LSN string `json:"lsn"`
}

type CitusRestorePointRequest struct {
	Name string `json:"name"`
}

type CitusRestorePointResponse struct {
	Nodes []CitusRestorePoint `json:"nodes"`
}

type CitusStatusResponse struct {
	Group         int                     `json:"group"`
	IsCoordinator bool                    `json:"isCoordinator"`
	Nodes         []CitusNode             `json:"nodes"`
	Rebalance     *CitusRebalanceResponse `json:"rebalance,omitempty"`
}

type Credentials struct {
	Username string `json:"username"`
	Password string `json:"password"`
}

type DCSResetRequest struct {
	Formation bool `json:"formation,omitempty"`
}

type DataAccessRole struct {
	Credentials
	Enabled bool `json:"enabled"`
	Write   bool `json:"write,omitempty"`
	// Settings are role-level GUC defaults, not a substitute for SQL privileges.
	Settings map[string]string `json:"settings,omitempty"`
}

type DataAccessRoles struct {
	// Revision changes when the managed application role catalog changes.
	Revision  string           `json:"revision,omitempty"`
	Roles     []DataAccessRole `json:"roles"`
	Databases []string         `json:"databases"`
	Schemas   []string         `json:"schemas,omitempty"`
	// GlobalRead is permitted only when neither databases nor schemas is scoped.
	GlobalRead bool `json:"globalRead,omitempty"`
}

type Database struct {
	Name             string   `json:"name"`
	Owner            string   `json:"owner"`
	OwnerOID         uint32   `json:"ownerOid,omitempty"`
	Encoding         string   `json:"encoding"`
	Locale           string   `json:"locale"`
	AllowConnections bool     `json:"allowConnections"`
	Extensions       []string `json:"extensions,omitempty"`
}

type Etcd struct {
	// InitialCluster is the name=https://host:2380 list for first start.
	InitialCluster string `json:"initialCluster"`
	// State is "new" for bootstrap members or "existing" for members added at runtime.
	State string `json:"state"`
	Token string `json:"token"`
	// Endpoints are host:2379 addresses; a nonempty list selects client-only
	// mode, so this member runs no local etcd and ignores bootstrap fields.
	Endpoints []string `json:"endpoints,omitempty"`
}

type EtcdMember struct {
	ID      string   `json:"id"`
	Name    string   `json:"name"`
	PeerURL []string `json:"peerUrls"`
	Learner bool     `json:"learner"`
}

type EtcdMemberRequest struct {
	Op       string `json:"op"` // list, add-learner, promote, remove
	Name     string `json:"name,omitempty"`
	PeerURL  string `json:"peerUrl,omitempty"`
	MemberID string `json:"memberId,omitempty"`
}

type EtcdMemberResponse struct {
	Members []EtcdMember `json:"members"`
	// InitialCluster is returned by add-learner for the new member's first start.
	InitialCluster string `json:"initialCluster,omitempty"`
}

type ExpireRequest struct {
	Set        string      `json:"set"`
	Repository *Repository `json:"repository,omitempty"`
}

type ExtensionUpdateResult struct {
	Database string   `json:"database"`
	Updated  []string `json:"updated"`
}

type Grant struct {
	Role       string   `json:"role"`
	Database   string   `json:"database"`
	Schema     string   `json:"schema,omitempty"`
	Privileges []string `json:"privileges"`
}

type HealthCapabilities struct {
	LocalEtcd           bool `json:"localEtcd,omitempty"`
	ReplicationSlots    bool `json:"replicationSlots,omitempty"`
	WALArchive          bool `json:"walArchive,omitempty"`
	ReplicationDistance bool `json:"replicationDistance,omitempty"`
	PatroniPause        bool `json:"patroniPause,omitempty"`
}

type Peer struct {
	Name string `json:"name"`
	// Host is the private DNS name used for PostgreSQL, Patroni and etcd.
	Host string `json:"host"`
	// Etcd reports this peer's desired etcd membership: "voter", "learner" or
	// "" when the peer does not (yet) run etcd.
	Etcd string `json:"etcd,omitempty"`
}

type Postgres struct {
	// Parameters are validated GUCs (engine-managed keys win over user keys).
	Parameters map[string]string `json:"parameters,omitempty"`
	// SharedPreloadLibraries is rendered as a proper list (never one quoted value).
	SharedPreloadLibraries []string `json:"sharedPreloadLibraries,omitempty"`
	// RequireTLS selects hostssl-only client HBA rules.
	RequireTLS bool `json:"requireTls,omitempty"`
	// ClientCIDRs are the private address ranges allowed by HBA.
	ClientCIDRs []string `json:"clientCidrs,omitempty"`
	// RecoveryClientsHeld keeps remote clients fenced until source credentials
	// have been removed from every member's durable configuration.
	RecoveryClientsHeld bool `json:"recoveryClientsHeld,omitempty"`
	// Synchronous is off, on or strict (ha only).
	Synchronous string `json:"synchronous,omitempty"`
	// PgBackRestReplicas enables pgBackRest as the first replica creation method.
	PgBackRestReplicas bool `json:"pgBackRestReplicas,omitempty"`
}

type PrepareRestoreRequest struct {
	Receipt string `json:"receipt"`
	Wipe    bool   `json:"wipe"`
}

type ProfileBootstrapRequest struct {
	Profiles []string `json:"profiles"`
}

type Proxy struct {
	// Servers are data member hosts (port 5432).
	Servers        []string    `json:"servers"`
	Users          []ProxyUser `json:"users"`
	Monitor        Credentials `json:"monitor"`
	Admin          Credentials `json:"admin"`
	ReadWriteSplit bool        `json:"readWriteSplit,omitempty"`
	ReaderPort     bool        `json:"readerPort,omitempty"`
	Threads        int         `json:"threads,omitempty"`
	MaxConnections int         `json:"maxConnections,omitempty"`
	// ServerCert is the frontend certificate (clients) when TLS is enabled.
	ServerCert *Certificate `json:"serverCert,omitempty"`
	// BackendTLS enables TLS from ProxySQL to PostgreSQL.
	BackendTLS bool `json:"backendTls,omitempty"`
}

type ProxyBackend struct {
	Host      string `json:"host"`
	Hostgroup int    `json:"hostgroup"`
	Status    string `json:"status"`
	// Diagnostics is optional for mixed-version agents. It contains only
	// allowlisted error classes, never native messages or connection strings.
	Diagnostics *ProxyDiagnostics `json:"diagnostics,omitempty"`
}

type ProxyDiagnostics struct {
	Connect          *ProxyMonitorError `json:"connect,omitempty"`
	Ping             *ProxyMonitorError `json:"ping,omitempty"`
	ReadOnly         *ProxyMonitorError `json:"readOnly,omitempty"`
	ConnectionErrors uint64             `json:"connectionErrors"`
	PoolObserved     bool               `json:"poolObserved"`
}

type ProxyMonitorError struct {
	Class         string `json:"class"`
	TimeUnixMicro int64  `json:"timeUnixMicro"`
}

type ProxyUser struct {
	Username string `json:"username"`
	Password string `json:"password"`
	// RequireTLS forces TLS on the client leg for this user.
	RequireTLS bool `json:"requireTls,omitempty"`
}

type ReplicationSlot struct {
	Name          string `json:"name"`
	Type          string `json:"type"`
	Active        bool   `json:"active"`
	RetainedBytes int64  `json:"retainedBytes"`
	WALStatus     string `json:"walStatus"`
	SafeWALBytes  *int64 `json:"safeWalBytes,omitempty"`
}

type Repository struct {
	S3     S3     `json:"s3"`
	Path   string `json:"path"`
	Stanza string `json:"stanza"`
}

type RepositoryRequest struct {
	Repository *Repository `json:"repository,omitempty"`
}

type RestartRequest struct {
	PrimaryFirst bool `json:"primaryFirst,omitempty"`
}

type Restore struct {
	Source Repository `json:"source"`
	// Set restores a specific backup label; empty means latest.
	Set string `json:"set,omitempty"`
	// TargetTime is an RFC 3339 PITR target; empty restores to the end of the set/WAL.
	TargetTime string `json:"targetTime,omitempty"`
	// TargetName is a coordinated restore point, mutually exclusive with TargetTime.
	TargetName string `json:"targetName,omitempty"`
}

type RestoreRequest struct {
	Receipt    string  `json:"receipt"`
	Restore    Restore `json:"restore"`
	Generation int     `json:"generation"`
}

type Role struct {
	Name            string   `json:"name"`
	Login           bool     `json:"login"`
	Superuser       bool     `json:"superuser"`
	Createdb        bool     `json:"createdb"`
	Createrole      bool     `json:"createrole"`
	Replication     bool     `json:"replication"`
	BypassRLS       bool     `json:"bypassrls"`
	ConnectionLimit int      `json:"connectionLimit"`
	MemberOf        []string `json:"memberOf"`
	// MemberOfAdmin is an internal-only subset of MemberOf whose memberships
	// can be delegated by this role. It is not exposed by the public OpenAPI.
	MemberOfAdmin []string `json:"memberOfAdmin,omitempty"`
	ValidUntil    *string  `json:"validUntil,omitempty"`
}

type RoleWrite struct {
	Role
	Password *string `json:"password,omitempty"`
	Binding  bool    `json:"binding,omitempty"`
}

type S3 struct {
	Endpoint  string `json:"endpoint"`
	Port      int    `json:"port,omitempty"`
	Bucket    string `json:"bucket"`
	Region    string `json:"region"`
	PathStyle bool   `json:"pathStyle"`
	VerifyTLS bool   `json:"verifyTls"`
	CAPEM     string `json:"caPEM,omitempty"`
	AccessKey string `json:"accessKey"`
	SecretKey string `json:"secretKey"`
}

type SQLBootstrapRequest struct {
	Components []string          `json:"components"`
	Extensions []string          `json:"extensions"`
	Passwords  map[string]string `json:"passwords"`
}

type Spec struct {
	DataAccess *DataAccessRoles `json:"dataAccess,omitempty"`
	Role       string           `json:"role"`
	Topology   string           `json:"topology"`
	Flavour    string           `json:"flavour,omitempty"`
	Profiles   []string         `json:"profiles,omitempty"`
	// Scope is the Patroni scope / etcd key namespace (cluster identity).
	Scope string `json:"scope"`
	// Major is the PostgreSQL major version; BinDir its binaries.
	Major  int    `json:"major"`
	BinDir string `json:"binDir"`
	// Version is the full catalog version reported to the control plane.
	Version string `json:"version"`
	Member  string `json:"member"`
	Peers   []Peer `json:"peers,omitempty"`
	// ListenHost selects the backend's private address family for listeners.
	// Empty retains the IPv4 default; supported values are 0.0.0.0 and ::.
	ListenHost string `json:"listenHost,omitempty"`
	// Retiring permanently excludes this identity from Patroni elections.
	Retiring bool `json:"retiring,omitempty"`

	Etcd      *Etcd      `json:"etcd,omitempty"`
	Citus     *Citus     `json:"citus,omitempty"`
	Postgres  *Postgres  `json:"postgres,omitempty"`
	Backup    *Backup    `json:"backup,omitempty"`
	Bootstrap *Bootstrap `json:"bootstrap,omitempty"`
	Proxy     *Proxy     `json:"proxy,omitempty"`

	// System credentials (data members).
	Superuser   Credentials `json:"superuser"`
	Replication Credentials `json:"replication"`
	Rewind      Credentials `json:"rewind"`
	Monitor     Credentials `json:"monitor"`
	PatroniREST Credentials `json:"patroniRest"`

	// TLS material issued by the cluster CA. ServerCert serves PostgreSQL,
	// Patroni REST and etcd (server+client usages); CAPEM is the trust anchor.
	CAPEM      string       `json:"caPEM"`
	ServerCert *Certificate `json:"serverCert,omitempty"`
}

type StatusResponse struct {
	Citus              *Citus `json:"citus,omitempty"`
	CitusIsCoordinator bool   `json:"citusIsCoordinator,omitempty"`
	// HealthCapabilities distinguishes unsupported observations in older
	// member protocols from failed probes in a capable implementation.
	HealthCapabilities *HealthCapabilities `json:"healthCapabilities,omitempty"`
	// CredentialReceipts advertises durable credential mutation replay.
	CredentialReceipts bool   `json:"credentialReceipts,omitempty"`
	Role               string `json:"role"` // primary, replica, standalone, proxy, starting, stopped
	// Running reports whether PostgreSQL (or ProxySQL) accepts connections.
	Running bool `json:"running"`
	// DataRecoveryRequired refuses empty initialization after data loss.
	DataRecoveryRequired bool `json:"dataRecoveryRequired,omitempty"`
	// DataMissing is a successful filesystem observation, not a failed SQL
	// probe. Individual HA replicas may still safely clone from a live leader.
	DataMissing bool   `json:"dataMissing,omitempty"`
	Leader      string `json:"leader,omitempty"`
	Timeline    int    `json:"timeline,omitempty"`
	// LagBytes is local receive-minus-replay backlog on replicas, or the
	// maximum downstream replay distance on a primary. Cluster readiness
	// compares WALPosition across matching system identifiers and timelines.
	LagBytes  int64  `json:"lagBytes,omitempty"`
	Streaming bool   `json:"streaming,omitempty"`
	SyncState string `json:"syncState,omitempty"`
	Version   string `json:"version,omitempty"`
	// SystemID is the PostgreSQL system identifier.
	SystemID string `json:"systemId,omitempty"`
	// Locale is template1's locale, preserved when initializing pg_upgrade's target.
	Locale string `json:"locale,omitempty"`
	// Bootstrap generation applied by this member.
	BootstrapGeneration int `json:"bootstrapGeneration,omitempty"`
	// EtcdMemberID is the local etcd member ID (hex) when etcd runs.
	EtcdMemberID string `json:"etcdMemberId,omitempty"`
	// EtcdHealthy means a linearizable local request reached a DCS quorum.
	EtcdHealthy bool `json:"etcdHealthy,omitempty"`
	// PendingRestart is Patroni's observed PostgreSQL restart requirement.
	PendingRestart bool `json:"pendingRestart,omitempty"`
	// SharedMemoryParameters are the running, not merely configured, GUC values.
	SharedMemoryParameters map[string]int64 `json:"sharedMemoryParameters,omitempty"`
	// WALPosition is the primary's current LSN or a replica's replay LSN.
	WALPosition string `json:"walPosition,omitempty"`
	// Paused reports Patroni maintenance mode.
	Paused bool `json:"paused,omitempty"`
	// FailoverFenced confirms the local member's retirement tags in /cluster.
	FailoverFenced bool `json:"failoverFenced,omitempty"`
	// RetirementTagsCleared confirms /cluster observed no local election exclusion.
	RetirementTagsCleared bool `json:"retirementTagsCleared,omitempty"`
	// RetirementStopped confirms a durable stop hold and no running database.
	RetirementStopped bool `json:"retirementStopped,omitempty"`
	// LastArchivedAt is pg_stat_archiver.last_archived_time (primary).
	LastArchivedAt     string `json:"lastArchivedAt,omitempty"`
	ArchiveFailing     bool   `json:"archiveFailing,omitempty"`
	ArchiveStatusKnown bool   `json:"archiveStatusKnown,omitempty"`
	// WALStatusKnown distinguishes a failed sample from an empty WAL directory.
	WALStatusKnown   bool              `json:"walStatusKnown,omitempty"`
	WALBytes         int64             `json:"walBytes,omitempty"`
	ArchivePending   int64             `json:"archivePending,omitempty"`
	SlotStatusKnown  bool              `json:"slotStatusKnown,omitempty"`
	ReplicationSlots []ReplicationSlot `json:"replicationSlots,omitempty"`
	// RecoverableUntil bounds WAL content, not archive upload wall time.
	RecoverableUntil string `json:"recoverableUntil,omitempty"`
	// ProxyBackends reports ProxySQL runtime server states (proxy members).
	ProxyBackends []ProxyBackend `json:"proxyBackends,omitempty"`
}

type SwitchoverRequest struct {
	Candidate string `json:"candidate,omitempty"`
}

type UpgradeRequest struct {
	Receipt  string `json:"receipt"`
	OldMajor int    `json:"oldMajor"`
	NewMajor int    `json:"newMajor"`
	Locale   string `json:"locale"`
	Replica  bool   `json:"replica,omitempty"`
}

type UpgradeResponse struct {
	Checked bool `json:"checked"`
	Done    bool `json:"done"`
}

type WALSwitchResponse struct {
	LSN string `json:"lsn"`
}