postgres

package

v0.4.2 Latest Latest Go to latest Published: Oct 30, 2026 License: Apache-2.0 Imports: 46 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/KarakoramDev/Karakoram

Links

Open Source Insights

Documentation ¶

Overview ¶

Package postgres implements the shared PostgreSQL control-plane core. Declarative profiles own extension and configuration policy; wrapper hooks compose application readiness and relay targets without duplicating lifecycle.

Index ¶

func BindingContext(ctx context.Context) context.Context
func BindingSourceRevision(c *domain.Cluster) (string, error)
func PrepareCommands(version string) []string
type Access
type CitusOptions
- func (o *CitusOptions) UnmarshalJSON(raw []byte) error
type Core
- func New(o Options) *Core
type Database
type EngineOptions
- func ParseOptions(raw json.RawMessage) (EngineOptions, error)
type Flavour
type Grant
type Options
type ProxyOptions
type Role
type RoleWrite

Constants ¶

This section is empty.

Variables ¶

This section is empty.

Functions ¶

func BindingContext ¶ added in v0.4.0

func BindingContext(ctx context.Context) context.Context

BindingContext grants the trusted in-process binding controller access to the reserved kb_ role namespace. Public API handlers never use this scope.

func BindingSourceRevision ¶ added in v0.4.0

func BindingSourceRevision(c *domain.Cluster) (string, error)

BindingSourceRevision fences cached database repairs across every managed restore, including restores requested outside the binding service. Do not publish a successful repair while recovery can still replace native ACLs.

func PrepareCommands ¶

func PrepareCommands(version string) []string

PrepareCommands installs only pinned native packages and suppresses distro daemons.

Types ¶

type Access ¶

type Access interface {
	ListRoles(context.Context, *engine.Context) ([]Role, error)
	GetRole(context.Context, *engine.Context, string) (*Role, error)
	CreateRole(context.Context, *engine.Context, RoleWrite) (string, error)
	UpdateRole(context.Context, *engine.Context, RoleWrite) error
	DeleteRole(context.Context, *engine.Context, string) error
	RotateRolePassword(context.Context, *engine.Context, string) (string, error)
	ListDatabases(context.Context, *engine.Context) ([]Database, error)
	GetDatabase(context.Context, *engine.Context, string) (*Database, error)
	CreateDatabase(context.Context, *engine.Context, Database) error
	DeleteDatabase(context.Context, *engine.Context, string, bool) error
	ListGrants(context.Context, *engine.Context, string) ([]Grant, error)
	Grant(context.Context, *engine.Context, Grant) error
	Revoke(context.Context, *engine.Context, Grant) error
}

Access is shared by PostgreSQL and providers embedding its core.

type CitusOptions ¶ added in v0.4.0

type CitusOptions struct {
	WorkerGroups int    `json:"workerGroups"`
	Database     string `json:"database"`
}

CitusOptions controls formation membership, not members per replication group.

func (*CitusOptions) UnmarshalJSON ¶ added in v0.4.0

func (o *CitusOptions) UnmarshalJSON(raw []byte) error

type Core ¶

type Core struct {
	// contains filtered or unexported fields
}

Core reconciles the PostgreSQL data plane and its stateless proxy.

func New ¶

func New(o Options) *Core

New constructs the shared PostgreSQL core.

func (*Core) ApplyDefaults ¶

func (*Core) ApplyDefaults(s *domain.ClusterSpec)

func (*Core) Balancer ¶

func (*Core) Balancer(context.Context, *engine.Context) (domain.BalancerStatus, error)

func (*Core) BindingEndpoint ¶ added in v0.4.0

func (p *Core) BindingEndpoint(ctx context.Context, rc *engine.Context) (string, []byte, error)

BindingEndpoint resolves private writer discovery without revealing system credentials.

func (*Core) CanCancelOperation ¶

func (*Core) CanCancelOperation(_ context.Context, op *domain.Operation) error

func (*Core) CanClaimOperation ¶

func (*Core) CanClaimOperation(c *domain.Cluster) (bool, error)

CanClaimOperation leaves Sync-owned maintenance ahead of queued imperative work: upgrades, directional restarts and terminal replacement recovery.

func (*Core) CancelOperation ¶

func (p *Core) CancelOperation(ctx context.Context, rc *engine.Context, op *domain.Operation) (engine.OpResult, error)

func (*Core) Cleanup ¶

func (p *Core) Cleanup(ctx context.Context, rc *engine.Context, opts domain.DeleteOptions) (done bool, err error)

Cleanup removes owned infrastructure, retaining data and credentials on suspension.

func (*Core) Connection ¶

func (p *Core) Connection(ctx context.Context, rc *engine.Context) (domain.ConnectionDetails, error)

func (*Core) CreateDatabase ¶

func (p *Core) CreateDatabase(ctx context.Context, rc *engine.Context, v Database) error

func (*Core) CreateDatabaseRole ¶

func (*Core) CreateDatabaseRole(context.Context, *engine.Context, domain.DatabaseRole) error

func (*Core) CreateDatabaseUser ¶

func (*Core) CreateDatabaseUser(context.Context, *engine.Context, domain.DatabaseUser, string) (string, error)

func (*Core) CreateRole ¶

func (p *Core) CreateRole(ctx context.Context, rc *engine.Context, v RoleWrite) (string, error)

func (*Core) DataAccessCredentials ¶ added in v0.3.0

func (p *Core) DataAccessCredentials(ctx context.Context, rc *engine.Context, level engine.DataAccessLevel) (engine.DataAccessCredentials, error)

DataAccessCredentials uses direct project-network member DNS, never proxies or public endpoints: the companion requires PostgreSQL's full extended protocol. Multi-host URIs prefer a standby for reads and require a writer for RW. PUBLIC CONNECT/object grants remain inherited PostgreSQL privileges: database scoping is not an isolation boundary for objects already readable by PUBLIC.

func (*Core) DataMcp ¶ added in v0.3.0

func (*Core) DataMcp(c *domain.Cluster) (engine.DataMcpBackend, error)

func (*Core) DataMembers ¶

func (*Core) DataMembers(c *domain.Cluster) []string

DataMembers returns active data identities in allocation order. Credentials remain available only through the authenticated MemberConfig path.

func (*Core) DeleteDatabase ¶

func (p *Core) DeleteDatabase(ctx context.Context, rc *engine.Context, name string, force bool) error

func (*Core) DeleteDatabaseRole ¶

func (*Core) DeleteDatabaseRole(context.Context, *engine.Context, string, string) error

func (*Core) DeleteDatabaseUser ¶

func (*Core) DeleteDatabaseUser(context.Context, *engine.Context, string, string) error

func (*Core) DeleteRetainedBackup ¶

func (p *Core) DeleteRetainedBackup(ctx context.Context, storage domain.BackupStorage, b domain.Backup) error

DeleteRetainedBackup expires a repository set with no remaining live writer. Supabase promotes this method unchanged through the PostgreSQL core.

func (*Core) DeleteRole ¶

func (p *Core) DeleteRole(ctx context.Context, rc *engine.Context, name string) error

func (*Core) Describe ¶

func (p *Core) Describe() domain.ProviderInfo

func (*Core) EnqueueFullBackup ¶

func (p *Core) EnqueueFullBackup(ctx context.Context, rc *engine.Context, key string) error

EnqueueFullBackup atomically queues a deterministic fresh base. Repeating the same key after a crash does not create a second backup or operation.

func (*Core) EnsureBindingRole ¶ added in v0.4.0

func (p *Core) EnsureBindingRole(ctx context.Context, rc *engine.Context, name string, limit int) error

EnsureBindingRole recovers only roles whose creation was published by our credential journal. A matching native name alone is never ownership evidence.

func (*Core) EnsureDatabaseExtensions ¶ added in v0.4.0

func (p *Core) EnsureDatabaseExtensions(ctx context.Context, rc *engine.Context, v Database) error

EnsureDatabaseExtensions resumes extension creation on an existing database, refusing to adopt a database owned by a different role.

func (*Core) EnsureStanza ¶

func (p *Core) EnsureStanza(ctx context.Context, rc *engine.Context, upgrade bool) error

EnsureStanza creates the configured repository's stanza, or upgrades its database history after a major upgrade. Both actions are idempotent.

func (*Core) FilterRetention ¶

func (p *Core) FilterRetention(backups, candidates []domain.Backup) []domain.Backup

FilterRetention preserves pgBackRest's newest full and any chain needed by backups retained by another schedule (or created manually). Skipped sets stay eligible on later passes, once a newer full and independent retained sets exist.

func (*Core) GetDatabase ¶

func (p *Core) GetDatabase(ctx context.Context, rc *engine.Context, name string) (*Database, error)

func (*Core) GetDatabaseRole ¶

func (*Core) GetDatabaseRole(context.Context, *engine.Context, string, string) (*domain.DatabaseRole, error)

func (*Core) GetDatabaseUser ¶

func (*Core) GetDatabaseUser(context.Context, *engine.Context, string, string) (*domain.DatabaseUser, error)

func (*Core) GetRole ¶

func (p *Core) GetRole(ctx context.Context, rc *engine.Context, name string) (*Role, error)

func (*Core) Grant ¶

func (p *Core) Grant(ctx context.Context, rc *engine.Context, v Grant) error

func (*Core) InitialDataSourceApplied ¶

func (p *Core) InitialDataSourceApplied(c *domain.Cluster) (bool, error)

func (*Core) InitialDataSourceRecoveryPending ¶

func (*Core) InitialDataSourceRecoveryPending(c *domain.Cluster) (bool, error)

func (*Core) ListDatabaseRoles ¶

func (*Core) ListDatabaseRoles(context.Context, *engine.Context) ([]domain.DatabaseRole, error)

func (*Core) ListDatabaseUsers ¶

func (*Core) ListDatabaseUsers(context.Context, *engine.Context) ([]domain.DatabaseUser, error)

func (*Core) ListDatabases ¶

func (p *Core) ListDatabases(ctx context.Context, rc *engine.Context) ([]Database, error)

func (*Core) ListGrants ¶

func (p *Core) ListGrants(ctx context.Context, rc *engine.Context, database string) ([]Grant, error)

func (*Core) ListRoles ¶

func (p *Core) ListRoles(ctx context.Context, rc *engine.Context) ([]Role, error)

func (*Core) MemberConfig ¶

func (p *Core) MemberConfig(ctx context.Context, rc *engine.Context, name string) (agentapi.MemberConfig, error)

MemberConfig renders secret-bearing configuration only for an allocated member.

func (*Core) MemberLogs ¶

func (*Core) MemberLogs(ctx context.Context, rc *engine.Context, name, process string, lines int) ([]domain.MemberLogLine, error)

func (*Core) Metrics ¶

func (*Core) Metrics() []domain.MetricDescriptor

Metrics maps the native runner's stable vocabulary into canonical series.

func (*Core) MigrateInitialDataSource ¶

func (p *Core) MigrateInitialDataSource(ctx context.Context, rc *engine.Context) error

MigrateInitialDataSource accepts a completed pre-marker recovery receipt, not its (possibly superseded) create tracker. No source/native I/O is replayed.

func (*Core) Name ¶

func (*Core) Name() string

func (*Core) OwnBindingDatabase ¶ added in v0.4.0

func (p *Core) OwnBindingDatabase(ctx context.Context, rc *engine.Context, db Database) error

OwnBindingDatabase repairs a binding-owned database's public schema ownership and CONNECT/TEMPORARY privileges; it cannot change database ownership.

func (*Core) PITRWindow ¶

func (p *Core) PITRWindow(ctx context.Context, rc *engine.Context) ([]domain.TimeWindow, error)

PITRWindow reports a deliberately conservative observable interval, not WAL filename timestamps or a promise that an external actor has not removed WAL.

func (*Core) Placement ¶

func (p *Core) Placement(ctx context.Context, rc *engine.Context) (domain.Placement, error)

func (*Core) ProjectCredentialsStatus ¶

func (p *Core) ProjectCredentialsStatus(ctx context.Context, rc *engine.Context, status domain.ClusterStatus) domain.ClusterStatus

ProjectCredentialsStatus fences cached publication observations against access mutations completed since the last reconciliation.

func (*Core) RelayTargets ¶

func (p *Core) RelayTargets(c *domain.Cluster) []string

func (*Core) RequiredCapabilities ¶

func (*Core) RequiredCapabilities(s domain.ClusterSpec) []string

func (*Core) Revoke ¶

func (p *Core) Revoke(ctx context.Context, rc *engine.Context, v Grant) error

func (*Core) RotateRolePassword ¶

func (p *Core) RotateRolePassword(ctx context.Context, rc *engine.Context, name string) (string, error)

func (*Core) RunOperation ¶

func (p *Core) RunOperation(ctx context.Context, rc *engine.Context, op *domain.Operation) (result engine.OpResult, err error)

RunOperation executes bounded, checkpointed rolling restarts.

func (*Core) SetBalancer ¶

func (*Core) SetBalancer(context.Context, *engine.Context, bool) error

func (*Core) Status ¶

func (p *Core) Status(ctx context.Context, rc *engine.Context) (status domain.ClusterStatus, statusErr error)

func (*Core) SupportsFailureCleanup ¶

func (*Core) SupportsFailureCleanup(op *domain.Operation) bool

Failure cleanup hands a durable recovery owner to Sync. Once retirement has started, completing that same cutover is safer than trying to undo stop holds or an etcd removal whose response may have been lost.

func (*Core) Sync ¶

func (p *Core) Sync(ctx context.Context, rc *engine.Context) (result engine.Result, err error)

Sync advances durable infrastructure work and rolls one ready member at a time.

func (*Core) SyncDuringOperation ¶

func (*Core) SyncDuringOperation(op *domain.Operation) bool

SyncDuringOperation permits provisioning only while a replacement joins. Maintenance operations must retain exclusive ownership of the data plane.

func (*Core) SystemUsers ¶

func (*Core) SystemUsers(_ context.Context, rc *engine.Context) ([]domain.SystemUser, error)

func (*Core) UpdateDatabaseRole ¶

func (*Core) UpdateDatabaseRole(context.Context, *engine.Context, domain.DatabaseRole) error

func (*Core) UpdateDatabaseUser ¶

func (*Core) UpdateDatabaseUser(context.Context, *engine.Context, domain.DatabaseUser, string) error

func (*Core) UpdateRole ¶

func (p *Core) UpdateRole(ctx context.Context, rc *engine.Context, v RoleWrite) error

func (*Core) Validate ¶

func (p *Core) Validate(ctx context.Context, old, n *domain.Cluster) error

func (*Core) ValidateDatabasePassword ¶

func (*Core) ValidateDatabasePassword(v string) error

func (*Core) ValidateMemberReplacement ¶ added in v0.4.0

func (*Core) ValidateMemberReplacement(c *domain.Cluster, name string) error

ValidateMemberReplacement is also promoted by the Supabase provider.

func (*Core) ValidatePITRRestore ¶

func (p *Core) ValidatePITRRestore(ctx context.Context, rc *engine.Context, target time.Time) ([]domain.TimeWindow, error)

func (*Core) VerifyBindingRole ¶ added in v0.4.0

func (p *Core) VerifyBindingRole(ctx context.Context, rc *engine.Context, name string) (uint32, error)

VerifyBindingRole checks ownership before cleanup touches dependent objects.

func (*Core) VolumeReferences ¶ added in v0.4.1

func (*Core) VolumeReferences(c *domain.Cluster) ([]engine.VolumeReference, error)

VolumeReferences exposes persistent identities for backend sizing observation.

type Database ¶

type Database = pgspec.Database

type EngineOptions ¶

type EngineOptions struct {
	SynchronousMode string            `json:"synchronousMode,omitempty"`
	Parameters      map[string]string `json:"parameters,omitempty"`
	Proxy           ProxyOptions      `json:"proxy,omitempty"`
	Profiles        []string          `json:"profiles,omitempty"`
	Citus           *CitusOptions     `json:"citus,omitempty"`
}

EngineOptions contains the safe user-controlled PostgreSQL settings.

func ParseOptions ¶

func ParseOptions(raw json.RawMessage) (EngineOptions, error)

ParseOptions rejects unknown fields and parameters that escape engine ownership.

type Flavour ¶

type Flavour interface {
	Name() string
	PostReady(context.Context, *engine.Context) error
	RelayTargets(*domain.Cluster) []string
}

Flavour customizes data members without duplicating their lifecycle.

type Grant ¶

type Grant = pgspec.Grant

type Options ¶

type Options struct {
	ControlPlaneURL, InternalCAPEM string
	Store                          engine.ClusterStore
	Logger                         *slog.Logger
	Flavour                        Flavour
	// ReservedRole extends the immutable system-role set for a composed engine.
	ReservedRole func(string) bool
	// AvailableExtensions is the admission authority for database extension requests.
	// Nil uses the conservative Percona contrib baseline.
	AvailableExtensions func(context.Context, *engine.Context) ([]string, error)
	// ProfileExtensions lists extensions to update after a version upgrade.
	ProfileExtensions func(*engine.Context) []string
}

Options supplies namespace-independent provider dependencies.

type ProxyOptions ¶

type ProxyOptions struct {
	ReadWriteSplit bool `json:"readWriteSplit,omitempty"`
	ReaderPort     bool `json:"readerPort,omitempty"`
}

type Role ¶

type Role = pgspec.Role

type RoleWrite ¶

type RoleWrite = pgspec.RoleWrite

Source Files ¶

View all Source files

Directories ¶

Path	Synopsis
pgprofile Package pgprofile is the shared availability and curated SQL authority for PostgreSQL profiles.	Package pgprofile is the shared availability and curated SQL authority for PostgreSQL profiles.
pgspec SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors	SPDX-License-Identifier: Apache-2.0 Copyright 2026 The Karakoram Authors

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL