postgres

package
v2.10.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 9, 2026 License: Apache-2.0 Imports: 16 Imported by: 0

Documentation

Overview

Package postgres is the Postgres adapter for the ports a stateless deployment needs (docs/adr/0008): store.ManifestStore, store.OperationalStore, store.BundleStore and store.DocStore, over one database through pgx, a pure-Go driver, so the binary stays CGO_ENABLED=0. There is no store.StateStore: every row is live.

Schema migrations are embedded and applied on Open, under an advisory lock, so replicas starting together apply each one once.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Open 

func Open(ctx context.Context, url string) (*pgxpool.Pool, error)

Open connects to the database a URL names, applies any migration not yet recorded, and returns the pool every adapter here is built over. Any parameter pgx does not know is sent to the server, so "?search_path=cartograph" puts the tables in a schema of their own.

Types

type AccessStore added in v2.2.0 

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

AccessStore is the Postgres adapter for store.AccessStore: one row per person. Each method is one statement; an upsert on the address is what makes two replicas enrolling one person, or a sign-in racing a grant, leave every field either writer set.

func NewAccessStore added in v2.2.0 

func NewAccessStore(pool *pgxpool.Pool) *AccessStore

NewAccessStore returns an AccessStore over a pool Open returned.

func (*AccessStore) DeletePerson added in v2.2.0 

func (s *AccessStore) DeletePerson(ctx context.Context, email string) error

func (*AccessStore) GetAgentGrant added in v2.5.0 

func (s *AccessStore) GetAgentGrant(ctx context.Context, id string) (store.AgentGrant, error)

func (*AccessStore) GetPerson added in v2.2.0 

func (s *AccessStore) GetPerson(ctx context.Context, email string) (store.Person, error)

func (*AccessStore) GrantPerson added in v2.2.0 

func (s *AccessStore) GrantPerson(ctx context.Context, p store.Person) (store.Person, error)

func (*AccessStore) ListAgentGrants added in v2.5.0 

func (s *AccessStore) ListAgentGrants(ctx context.Context, email string) ([]store.AgentGrant, error)

func (*AccessStore) ListPeople added in v2.2.0 

func (s *AccessStore) ListPeople(ctx context.Context) ([]store.Person, error)

func (*AccessStore) PutAgentGrant added in v2.5.0 

func (s *AccessStore) PutAgentGrant(ctx context.Context, t store.AgentGrant) error

func (*AccessStore) RecordSignIn added in v2.2.0 

func (s *AccessStore) RecordSignIn(ctx context.Context, in store.SignIn) (store.Person, error)

func (*AccessStore) RevokeAgentGrant added in v2.5.0 

func (s *AccessStore) RevokeAgentGrant(ctx context.Context, id string, at time.Time) error

func (*AccessStore) RotateAgentGrant added in v2.5.0 

func (s *AccessStore) RotateAgentGrant(ctx context.Context, id string, from int) (bool, error)

func (*AccessStore) TouchAgentGrant added in v2.5.0 

func (s *AccessStore) TouchAgentGrant(ctx context.Context, id string, at time.Time) error

type BundleStore 

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

BundleStore keeps handoff bundles as rows of bytes. A bundle is a few rendered documents, small enough that a database is a fine home; an object store is the adapter to write when that stops being true.

func NewBundleStore 

func NewBundleStore(pool *pgxpool.Pool) *BundleStore

NewBundleStore returns a BundleStore over a pool Open returned.

func (*BundleStore) File 

func (b *BundleStore) File(ctx context.Context, location, name string) ([]byte, bool, error)

File returns one file of a stored bundle, by the location PutBundle returned and the file's name.

func (*BundleStore) PutBundle 

func (b *BundleStore) PutBundle(ctx context.Context, projectID string, version int, files map[string][]byte) (store.Bundle, error)

PutBundle stores files under "handoff/<project>/v<n>", the location the other adapters use, replacing whatever was there, in one transaction.

type DocStore 

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

DocStore is the Postgres adapter for store.DocStore: one row per document holding its snapshot, and one row per chunk appended since.

func NewDocStore 

func NewDocStore(pool *pgxpool.Pool) *DocStore

NewDocStore returns a DocStore over a pool Open returned.

func (*DocStore) Append 

func (d *DocStore) Append(ctx context.Context, docID string, data []byte) (int64, error)

Append takes the next sequence number under the document row's lock and stores the chunk in the same transaction, so concurrent appenders on any replica get distinct, rising numbers, and a number is never handed out for a chunk that was not stored.

func (*DocStore) Compact 

func (d *DocStore) Compact(ctx context.Context, docID string, snapshot []byte, upTo int64) error

Compact replaces the snapshot and drops the chunks it includes, under the document row's lock. Chunks after upTo are untouched, whoever appends them meanwhile. A compaction older than the one already stored changes nothing: its snapshot lacks chunks that are gone.

func (*DocStore) Create 

func (d *DocStore) Create(ctx context.Context, kind, id, docID string, snapshot []byte) (string, bool, error)

Create inserts the document unless the manifest has one. When two replicas race, the unique key on the manifest makes the second insert wait for the first and then do nothing; the second then reads the winner's id, which its own read can see once the first has committed.

func (*DocStore) DocumentFor 

func (d *DocStore) DocumentFor(ctx context.Context, kind, id string) (string, error)

DocumentFor returns the id of a manifest's document.

func (*DocStore) Load 

func (d *DocStore) Load(ctx context.Context, docID string) ([]byte, []store.Chunk, error)

Load reads the snapshot and the chunks in one repeatable-read transaction, so a compaction committing in between cannot leave it with a snapshot that lacks chunks it no longer sees.

func (*DocStore) ManifestFor 

func (d *DocStore) ManifestFor(ctx context.Context, docID string) (string, string, error)

ManifestFor returns the manifest a document belongs to.

func (*DocStore) Since 

func (d *DocStore) Since(ctx context.Context, docID string, after int64) ([]store.Chunk, error)

Since returns the chunks after a sequence number.

type ManifestStore 

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

ManifestStore is the Postgres adapter for store.ManifestStore. Construct it with NewManifestStore.

func NewManifestStore 

func NewManifestStore(pool *pgxpool.Pool) *ManifestStore

NewManifestStore returns a ManifestStore over a pool Open returned.

func (*ManifestStore) CompactHistory added in v2.3.0 

func (m *ManifestStore) CompactHistory(ctx context.Context, before time.Time, limit int) (int, error)

CompactHistory compacts the history of up to limit manifests: every version saved before before, other than a manifest's latest, keeps a keyframe or a patch and loses its text. It returns how many versions it compacted. One replica compacts at a time; another that asks meanwhile compacts nothing.

func (*ManifestStore) Counts 

func (m *ManifestStore) Counts(ctx context.Context) (map[string]int, error)

Counts returns how many manifests each kind has.

func (*ManifestStore) CurrentMany added in v2.3.0 

func (m *ManifestStore) CurrentMany(ctx context.Context, kind string, ids []string) ([]store.Version, error)

CurrentMany returns the current version of each of ids that exists, in one query.

func (*ManifestStore) CurrentOfKind added in v2.3.0 

func (m *ManifestStore) CurrentOfKind(ctx context.Context, kind string) ([]store.Version, error)

CurrentOfKind returns what GetCurrent returns for every manifest of a kind, in one query over the kind's rows.

func (*ManifestStore) DecideProposal added in v2.5.0 

func (m *ManifestStore) DecideProposal(ctx context.Context, id, status, by, reason string, at time.Time, version int) (store.Proposal, error)

DecideProposal decides an open proposal in one statement: of two decisions at once, one updates the row and the other finds it decided.

func (*ManifestStore) DecideProposalSet added in v2.6.0 

func (m *ManifestStore) DecideProposalSet(ctx context.Context, set, status, by, reason string, at time.Time, versions map[string]int) ([]store.Proposal, error)

DecideProposalSet decides every proposal of a set in one transaction, the rows locked first: of two decisions at once, one decides them all and the other finds them decided.

func (*ManifestStore) DeleteChangeItem added in v2.7.0 

func (m *ManifestStore) DeleteChangeItem(ctx context.Context, set, kind, id string) error

DeleteChangeItem drops an item.

func (*ManifestStore) Events added in v2.3.0 

func (m *ManifestStore) Events(ctx context.Context, after int64, limit int) ([]store.Event, error)

Events returns events after a cursor, only those older than every transaction still open, so none can commit behind the cursor later.

func (*ManifestStore) Exclude 

func (m *ManifestStore) Exclude(ctx context.Context, kind, id, name, reason, operator string) error

Exclude records that a manifest is excluded. There is no state manifest to remove it from; the record is what an interface reads.

func (*ManifestStore) GetChangeItem added in v2.7.0 

func (m *ManifestStore) GetChangeItem(ctx context.Context, set, kind, id string) (store.ChangeItem, bool, error)

GetChangeItem returns one item.

func (*ManifestStore) GetChangeSet added in v2.7.0 

func (m *ManifestStore) GetChangeSet(ctx context.Context, id string) (store.ChangeSet, error)

GetChangeSet returns one change set.

func (*ManifestStore) GetCurrent 

func (m *ManifestStore) GetCurrent(ctx context.Context, kind, id string) (store.Version, bool, error)

GetCurrent returns the working copy when there is one, as version 0, and the highest version otherwise.

func (*ManifestStore) GetProposal added in v2.5.0 

func (m *ManifestStore) GetProposal(ctx context.Context, id string) (store.Proposal, error)

GetProposal returns one proposal.

func (*ManifestStore) GetVersion 

func (m *ManifestStore) GetVersion(ctx context.Context, kind, id string, number int) (store.Version, bool, error)

GetVersion returns one version, rebuilt from the nearest keyframe when it is stored as a patch: at most keyframeEvery-1 patches.

func (*ManifestStore) GetWorking 

func (m *ManifestStore) GetWorking(ctx context.Context, kind, id string) ([]byte, bool, error)

GetWorking returns a manifest's working copy, if it has one.

func (*ManifestStore) IndexReferences 

func (m *ManifestStore) IndexReferences(ctx context.Context, fromKind, fromID string, refs []store.Ref) error

IndexReferences replaces a manifest's recorded outgoing references: one delete and one insert over arrays, sent together in one round trip.

func (*ManifestStore) LatestNumber added in v2.3.0 

func (m *ManifestStore) LatestNumber(ctx context.Context, kind, id string) (int, error)

LatestNumber reads the manifest's row: one index lookup, whatever the length of its history.

func (*ManifestStore) ListAllVersions 

func (m *ManifestStore) ListAllVersions(ctx context.Context, limit int, cursor string) ([]store.Version, string, error)

ListAllVersions pages through every version, newest first. The cursor is the last row's sort key, "on,kind,id,number".

func (*ManifestStore) ListChangeItems added in v2.7.0 

func (m *ManifestStore) ListChangeItems(ctx context.Context, set string) ([]store.ChangeItem, error)

ListChangeItems returns a change set's items, oldest first.

func (*ManifestStore) ListChangeSets added in v2.7.0 

func (m *ManifestStore) ListChangeSets(ctx context.Context, f store.ChangeSetFilter) ([]store.ChangeSet, error)

ListChangeSets returns change sets, newest first, through the indexes on the person and on the owner.

func (*ManifestStore) ListExcluded 

func (m *ManifestStore) ListExcluded(ctx context.Context) ([]store.Exclusion, error)

ListExcluded returns every exclusion, newest first.

func (*ManifestStore) ListIDs 

func (m *ManifestStore) ListIDs(ctx context.Context, kind string) ([]string, error)

ListIDs returns the id of every manifest of a kind, versioned or only saved as a working copy.

func (*ManifestStore) ListProposals added in v2.5.0 

func (m *ManifestStore) ListProposals(ctx context.Context, f store.ProposalFilter) ([]store.Proposal, error)

ListProposals returns proposals, newest first, through the indexes on the person and on the manifest.

func (*ManifestStore) ListReferencedBy 

func (m *ManifestStore) ListReferencedBy(ctx context.Context, fromKind, fromID string) ([]store.Ref, error)

ListReferencedBy returns a manifest's recorded outgoing references.

func (*ManifestStore) ListReferencing 

func (m *ManifestStore) ListReferencing(ctx context.Context, toKind, toID string) ([]store.Summary, error)

ListReferencing returns the current summary of every manifest that references toKind/toID.

func (*ManifestStore) ListSummaries 

func (m *ManifestStore) ListSummaries(ctx context.Context, kind, query string, refs []store.RefFilter) ([]store.Summary, error)

ListSummaries returns the current entry of every manifest of a kind that matches the query and every reference filter.

func (*ManifestStore) ListSummariesAfter added in v2.3.0 

func (m *ManifestStore) ListSummariesAfter(ctx context.Context, kind, query string, refs []store.RefFilter, afterID string, limit int) ([]store.Summary, error)

ListSummariesAfter is ListSummaries from the id after afterID, at most limit rows (0 for all): a seek in the primary key, then the page.

func (*ManifestStore) ListVersions 

func (m *ManifestStore) ListVersions(ctx context.Context, kind, id string) ([]store.Version, error)

ListVersions returns every version of a manifest, oldest first, rebuilt in one pass.

func (*ManifestStore) MoveChangeSet added in v2.7.0 

func (m *ManifestStore) MoveChangeSet(ctx context.Context, id, from, to, by, reason string, at time.Time) (store.ChangeSet, error)

MoveChangeSet moves a change set from one status to another, in one statement, so of two moves from the same status one wins.

func (*ManifestStore) PutChangeItem added in v2.7.0 

func (m *ManifestStore) PutChangeItem(ctx context.Context, it store.ChangeItem) error

PutChangeItem keeps an item.

func (*ManifestStore) PutChangeSet added in v2.7.0 

func (m *ManifestStore) PutChangeSet(ctx context.Context, cs store.ChangeSet) error

PutChangeSet keeps a change set.

func (*ManifestStore) PutDocs added in v2.3.0 

func (m *ManifestStore) PutDocs(ctx context.Context, docs []store.Version) error

PutDocs gives each version or working copy its document, in one round trip. The triggers carry each onto the manifest's row.

func (*ManifestStore) PutProposal added in v2.5.0 

func (m *ManifestStore) PutProposal(ctx context.Context, p store.Proposal) error

PutProposal keeps a proposal.

func (*ManifestStore) PutVersion 

func (m *ManifestStore) PutVersion(ctx context.Context, v store.Version) error

PutVersion appends v with its document. The trigger on manifest_versions accepts it only as one more than the manifest's current version, with the manifest's row locked, and moves the row on.

func (*ManifestStore) PutWorking 

func (m *ManifestStore) PutWorking(ctx context.Context, kind, id string, yamlBytes []byte) error

PutWorking replaces a manifest's working copy.

func (*ManifestStore) PutWorkingDoc added in v2.3.0 

func (m *ManifestStore) PutWorkingDoc(ctx context.Context, kind, id string, text, doc []byte) error

PutWorkingDoc replaces a manifest's working copy, with its document.

func (*ManifestStore) RecordSeries added in v2.3.0 

func (m *ManifestStore) RecordSeries(ctx context.Context, items []store.SeriesItem) error

RecordSeries appends series items, in one round trip.

func (*ManifestStore) Recover 

func (m *ManifestStore) Recover(ctx context.Context, kind, id, reason, operator string) error

Recover removes an exclusion record.

func (*ManifestStore) ReferencingKind added in v2.3.0 

func (m *ManifestStore) ReferencingKind(ctx context.Context, toKind string) (map[string][]store.Summary, error)

ReferencingKind returns who references each manifest of toKind, in one query over the references to that kind.

func (*ManifestStore) SeriesAsOf added in v2.3.0 

func (m *ManifestStore) SeriesAsOf(ctx context.Context, kind, series string, ids []string, at time.Time) (map[string][]store.SeriesItem, error)

SeriesAsOf merges each key's rows into its value at at: the last row recorded by then, through series_items_as_of.

func (*ManifestStore) StaleDocs added in v2.3.0 

func (m *ManifestStore) StaleDocs(ctx context.Context, limit int) ([]store.Version, error)

StaleDocs returns versions and working copies stored without a document: by a replica of the previous release, or as text no writer could read. The partial indexes keep this cheap once there are none.

func (*ManifestStore) WithinTransaction 

func (m *ManifestStore) WithinTransaction(ctx context.Context, fn func(ctx context.Context, tx store.ManifestStore) error) error

WithinTransaction runs fn against a ManifestStore inside one transaction, committed when fn returns nil.

type OperationalStore 

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

OperationalStore is the Postgres adapter for store.OperationalStore.

func NewOperationalStore 

func NewOperationalStore(pool *pgxpool.Pool) *OperationalStore

NewOperationalStore returns an OperationalStore over a pool Open returned.

func (*OperationalStore) CurrentStates added in v2.3.0 

func (o *OperationalStore) CurrentStates(ctx context.Context, projectIDs []string) (map[string]string, error)

CurrentStates returns the latest state of each project with history, in one query that project_state_project answers.

func (*OperationalStore) ListProjectStateHistory 

func (o *OperationalStore) ListProjectStateHistory(ctx context.Context, projectID string) ([]store.ProjectStateEntry, error)

ListProjectStateHistory returns a project's history, oldest first; rows written at the same instant keep the order they were written in.

func (*OperationalStore) PutProjectStateTransition 

func (o *OperationalStore) PutProjectStateTransition(ctx context.Context, e store.ProjectStateEntry) error

PutProjectStateTransition appends one row to a project's history.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.