postgres

package module
v0.1.0-preview.1 Latest Latest
Warning

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

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

README

Spice PostgreSQL starter

github.com/spice-framework/starter-postgres is the independently versioned, opt-in PostgreSQL integration for Spice. It provides a secure pgx-backed database/sql pool plus deterministic adapters for Spice transactions, migrations, durable outbox delivery, restartable batch execution, and SQL test slices. Importing core alone never selects pgx.

database, err := postgres.Open(postgres.Options{
    URL:             configuration.DatabaseURL,
    ApplicationName: "orders-service",
})
if err != nil {
    return nil, err
}

Open validates configuration and creates a caller-owned pool without network I/O. Ping performs the explicit readiness check using the caller's context. TLS hostname verification is the default; sslmode=disable requires the explicit AllowInsecure test-only opt-in.

The same pool can be passed to data.NewManager, NewMigrationBackend, NewBatchStore, NewOutboxStore, and spicetest.NewSQL. Schema constructors return deterministic DDL for application-owned migrations and never mutate a database implicitly.

Install

go get github.com/spice-framework/starter-postgres@latest

During preview development, applications should pin the exact compatible commit recorded in support metadata.

Verify

Go 1.26.5 is mandatory:

make check
make release-parity
make verify
make verify-release

The normal verifier checks formatting, module/vendor reproducibility, vet, allowlisted lint and nil safety, gosec, govulncheck, shuffled race tests, at least 85% repository coverage, and offline vendor builds.

Core compatibility is a separate, network-capable release check. It exercises the minimum and current exact versions in spice-compatibility.json. The minimum must equal the direct Spice requirement in go.mod. Both checks use temporary alternate module files; they never follow a moving branch during the build or rewrite go.mod, go.sum, or vendor:

make compatibility

Release parity runs the exact spice-dev tool authorized by go.mod and the retained repository builder twice each, entirely from vendor with network and workspace resolution disabled. It compares archive entries after normalizing only the builders' documented root-directory spelling, requires equivalent SBOM package and dependency facts, verifies both checksum files, and forbids rehearsal signatures on Windows and Linux.

make verify includes both compatibility lines and one execution of the local quality gate. Hosted CI runs the two compatibility lines independently so they can complete in parallel.

Real-system acceptance runs all integration-tagged tests against the pinned PostgreSQL 18.4 image digest. It proves transactions, repositories, advisory locked migrations, rollback, cancellation, batch leases/restart, outbox leasing/retry, and SQL test-slice rollback:

docker run --detach --name spice-postgres --publish 55432:5432 \
  --env POSTGRES_PASSWORD=spice-test --env POSTGRES_DB=spice \
  postgres@sha256:9a8afca54e7861fd90fab5fdf4c42477a6b1cb7d293595148e674e0a3181de15
SPICE_POSTGRES_TEST_URL='postgres://postgres:spice-test@127.0.0.1:55432/spice?sslmode=disable' \
  make integration
docker rm --force spice-postgres

See the dependency review and support contract before production adoption.

Releases

The repository builds deterministic source-only releases with an SPDX 2.3 SBOM, SHA-256 checksums, and Ed25519 signatures. See the exact artifact and clean-tag ceremony in the release guide. The reviewed public trust anchor is committed with fingerprint cc42428a74b539af7f6975d84b63c830267ac227062fc412970fc5ad586b7e65; no signed release is implied until the protected release ceremony completes. The retained repository builder and signed production workflow remain the release authority while the centrally rendered unsigned candidate is held to the dual-builder parity contract.

Documentation

Overview

Package postgres provides a reviewed pgx-backed database/sql starter for Spice applications.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func BatchSchemaSQL 

func BatchSchemaSQL(options BatchOptions) (string, error)

BatchSchemaSQL returns the deterministic initial table DDL for an application-owned migration. It performs no database operation.

func Manifest 

func Manifest() spicestarter.Manifest

Manifest returns PostgreSQL starter compatibility and review metadata.

func NewBatchStore 

func NewBatchStore(
	executor data.Executor,
	options BatchOptions,
) (*spicebatch.SQLStore, error)

NewBatchStore constructs a lease-aware PostgreSQL batch store without connecting or applying schema changes.

func NewOutboxStore 

func NewOutboxStore(
	executor data.Executor,
	options OutboxOptions,
) (*outbox.SQLStore, error)

NewOutboxStore constructs a PostgreSQL outbox store without connecting or applying schema changes.

func Open 

func Open(options Options) (*sql.DB, error)

Open validates a complete connection URL and constructs a caller-owned database/sql pool. It performs no network I/O.

func OutboxSchemaSQL 

func OutboxSchemaSQL(options OutboxOptions) (string, error)

OutboxSchemaSQL returns deterministic initial DDL for an application-owned migration. It performs no database operation.

func Ping 

func Ping(ctx context.Context, database *sql.DB) error

Ping verifies one caller-owned database with the supplied context.

Types

type BatchOptions 

type BatchOptions struct {
	Schema       string
	Table        string
	AttemptLease time.Duration
	Clock        func() time.Time
}

BatchOptions configures PostgreSQL-backed batch attempt persistence. Schema and Table must already be covered by an application-owned migration. Empty values select public.spice_batch_execution.

type MigrationBackend 

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

MigrationBackend applies module-owned migration plans through one caller-owned PostgreSQL pool.

func NewMigrationBackend 

func NewMigrationBackend(
	database *sql.DB,
	options MigrationOptions,
) (*MigrationBackend, error)

NewMigrationBackend constructs a PostgreSQL migration backend without connecting. The backend creates its fixed registry table on first use.

func (*MigrationBackend) RunLocked 

func (backend *MigrationBackend) RunLocked(
	ctx context.Context,
	work func(context.Context, spicemigration.Session) error,
) error

RunLocked pins one pgx connection, obtains a session-level advisory lock, and invokes work exactly once. Unlock failure closes the physical connection so a leaked session lock can never return to the pool.

type MigrationOptions 

type MigrationOptions struct {
	Schema string
	LockID int64
}

MigrationOptions configures the PostgreSQL implementation of the core migration backend. Schema must already exist. LockID zero selects Spice's stable process-independent default advisory lock.

type Options 

type Options struct {
	URL                   string
	ApplicationName       string
	MaxOpenConnections    int
	MaxIdleConnections    int
	ConnectionMaxLifetime time.Duration
	ConnectionMaxIdleTime time.Duration
	AllowInsecure         bool
}

Options defines a PostgreSQL pool. URL must be a complete postgres or postgresql URL so connection behavior never falls back to process environment variables.

type OutboxOptions 

type OutboxOptions struct {
	Schema string
	Table  string
}

OutboxOptions configures PostgreSQL-backed durable event publication. Schema and Table must already be covered by an application-owned migration. Empty values select public.spice_event_outbox.

Source Files

View all Source files

Directories

Path Synopsis
cmd
starter-postgres-release command
Command starter-postgres-release builds deterministic signed source releases.
 Command starter-postgres-release builds deterministic signed source releases.
internal
corecompat command
Command corecompat verifies the PostgreSQL starter against an explicit Spice core compatibility line without changing the repository module graph.
 Command corecompat verifies the PostgreSQL starter against an explicit Spice core compatibility line without changing the repository module graph.
qualitygate command
Command qualitygate runs starter-postgres's repository-owned checks.
 Command qualitygate runs starter-postgres's repository-owned checks.
release
Package release builds deterministic, signed starter-postgres source releases.
 Package release builds deterministic, signed starter-postgres source releases.

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.