postgres

README

PostgreSQL Datastore

PostgreSQL is a traditional relational database management system that is very popular. This datastore implementation allows you to use a PostgreSQL database as the backing durable storage for SpiceDB. Recommended usage: when you are comfortable with having all permissions data stored in a single region.

Implementation Caveats

While PostgreSQL uses MVCC to implement its ACID properties, it doesn't offer users the ability to read dirty data without adding an extension. For that reason, the PostgreSQL datastore driver implements a second layer of MVCC where we can manually control all writes to the database. This allows us to track all revisions of the database explicitly and perform point-in-time snapshot queries.

Documentation

Index

• Constants
• func NewPgxpoolStatsCollector(dbpool *pgxpool.Pool, dbName string) prometheus.Collector
• func NewPostgresDatastore(url string, options ...Option) (datastore.Datastore, error)
• type Option
  • func ConnMaxIdleTime(idle time.Duration) Option
  • func ConnMaxLifetime(lifetime time.Duration) Option
  • func DebugAnalyzeBeforeStatistics() Option
  • func EnableTracing() Option
  • func GCInterval(interval time.Duration) Option
  • func GCMaxOperationTime(time time.Duration) Option
  • func GCWindow(window time.Duration) Option
  • func HealthCheckPeriod(period time.Duration) Option
  • func MaxOpenConns(conns int) Option
  • func MaxRetries(maxRetries uint8) Option
  • func MaxRevisionStalenessPercent(stalenessPercent float64) Option
  • func MinOpenConns(conns int) Option
  • func RevisionQuantization(quantization time.Duration) Option
  • func SplitAtUsersetCount(splitAtUsersetCount uint16) Option
  • func WatchBufferLength(watchBufferLength uint16) Option
  • func WithEnablePrometheusStats(enablePrometheusStats bool) Option

Constants

const (
	Engine = "postgres"
)

Functions

func NewPgxpoolStatsCollector

func NewPgxpoolStatsCollector(dbpool *pgxpool.Pool, dbName string) prometheus.Collector

NewPgxpoolStatsCollector returns a collector that exports stats available in a pgxpool.

For more info see: https://pkg.go.dev/github.com/jackc/pgx/v4/pgxpool#Stat

func NewPostgresDatastore

func NewPostgresDatastore(
	url string,
	options ...Option,
) (datastore.Datastore, error)

NewPostgresDatastore initializes a SpiceDB datastore that uses a PostgreSQL database by leveraging manual book-keeping to implement revisioning.

This datastore is also tested to be compatible with CockroachDB.

Types

type Option

type Option func(*postgresOptions)

Option provides the facility to configure how clients within the Postgres datastore interact with the running Postgres database.

func ConnMaxIdleTime

func ConnMaxIdleTime(idle time.Duration) Option

ConnMaxIdleTime is the duration after which an idle connection will be automatically closed by the health check.

This value defaults to having no maximum.

func ConnMaxLifetime

func ConnMaxLifetime(lifetime time.Duration) Option

ConnMaxLifetime is the duration since creation after which a connection will be automatically closed.

This value defaults to having no maximum.

func DebugAnalyzeBeforeStatistics

func DebugAnalyzeBeforeStatistics() Option

DebugAnalyzeBeforeStatistics signals to the Statistics method that it should run Analyze on the database before returning statistics. This should only be used for debug and testing.

Disabled by default.

func EnableTracing

func EnableTracing() Option

EnableTracing enables trace-level logging for the Postgres clients being used by the datastore.

Tracing is disabled by default.

func GCInterval

func GCInterval(interval time.Duration) Option

GCInterval is the the interval at which garbage collection will occur.

This value defaults to 3 minutes.

func GCMaxOperationTime

func GCMaxOperationTime(time time.Duration) Option

GCMaxOperationTime is the maximum operation time of a garbage collection pass before it times out.

This value defaults to 1 minute.

func GCWindow

func GCWindow(window time.Duration) Option

GCWindow is the maximum age of a passed revision that will be considered valid.

This value defaults to 24 hours.

func HealthCheckPeriod

func HealthCheckPeriod(period time.Duration) Option

HealthCheckPeriod is the interval by which idle Postgres client connections are health checked in order to keep them alive in a connection pool.

func MaxOpenConns

func MaxOpenConns(conns int) Option

MaxOpenConns is the maximum size of the connection pool.

This value defaults to having no maximum.

func MaxRetries

func MaxRetries(maxRetries uint8) Option

MaxRetries is the maximum number of times a retriable transaction will be client-side retried. Default: 10

func MaxRevisionStalenessPercent

func MaxRevisionStalenessPercent(stalenessPercent float64) Option

MaxRevisionStalenessPercent is the amount of time, expressed as a percentage of the revision quantization window, that a previously computed rounded revision can still be advertised after the next rounded revision would otherwise be ready.

This value defaults to 0.1 (10%).

func MinOpenConns

func MinOpenConns(conns int) Option

MinOpenConns is the minimum size of the connection pool. The health check will increase the number of connections to this amount if it had dropped below.

This value defaults to zero.

func RevisionQuantization

func RevisionQuantization(quantization time.Duration) Option

RevisionQuantization is the time bucket size to which advertised revisions will be rounded.

This value defaults to 5 seconds.

func SplitAtUsersetCount

func SplitAtUsersetCount(splitAtUsersetCount uint16) Option

SplitAtUsersetCount is the batch size for which userset queries will be split into smaller queries.

This defaults to 1024.

func WatchBufferLength

func WatchBufferLength(watchBufferLength uint16) Option

WatchBufferLength is the number of entries that can be stored in the watch buffer while awaiting read by the client.

This value defaults to 128.

func WithEnablePrometheusStats

func WithEnablePrometheusStats(enablePrometheusStats bool) Option

WithEnablePrometheusStats marks whether Prometheus metrics provided by the Postgres clients being used by the datastore are enabled.

Prometheus metrics are disabled by default.