dbengine

package
v0.0.0-...-1614f50 Latest Latest
Warning

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

Go to latest
Published: Nov 10, 2026 License: AGPL-3.0 Imports: 20 Imported by: 0

Documentation

Overview

Package dbengine runs the data plane of a managed relational database: a real PostgreSQL, MySQL or MariaDB engine in a container whose data directory is a named volume, behind an endpoint listener the simulator owns. The endpoint terminates TLS and authenticates each client through the cloud's own hook, then relays the session to the engine. Which credentials are valid, how they are sealed at rest, and what state the control plane reconciles into the engine stay in each cloud's module.

Index

Constants

This section is empty.

Variables

View Source
var (
	Postgres16 = Engine{
		Family: Postgres,
		Port:   5432, DataPath: "/var/lib/postgresql/data", Client: "psql",
	}
	MySQL80 = Engine{
		Family: MySQL,
		Port:   3306, DataPath: "/var/lib/mysql", Client: "mysql",
		Args: []string{"--default-authentication-plugin=mysql_native_password"},
	}
	MariaDB114 = Engine{
		Family: MySQL,
		Port:   3306, DataPath: "/var/lib/mysql", Client: "mariadb",
	}
)

The presets name no image: which image a managed service runs is that cloud's choice, and each simulator's image scan must see it in its own tree.

Functions

func FixedPlatform

func FixedPlatform(platform string) func(context.Context, string) (string, error)

FixedPlatform runs the engine image for one platform whatever the host is.

func ListenLoopback

func ListenLoopback(identifier string, port int) (net.Listener, error)

ListenLoopback binds port on a loopback address derived from identifier, so every instance serves the engine's port on an address of its own, and keeps that address for identifier until ReleaseLoopback. The port is the one the control plane advertises, so no other port stands in for it: when no loopback address offers it, the error says so.

func ListenLoopbackAt

func ListenLoopbackAt(identifier, address string, port int) (net.Listener, error)

ListenLoopbackAt binds port on the loopback address identifier advertised before, as a process that starts again serves the endpoints its state records, and keeps the address for identifier as ListenLoopback does.

func ListenLoopbackPorts

func ListenLoopbackPorts(identifier string, ports []int) ([]net.Listener, error)

ListenLoopbackPorts binds every one of ports on one loopback address of identifier's own, as ListenLoopback binds one. A new identifier takes the first address on which each port is free, since another process may hold one of them on an address that offers the rest.

func PostgresEnvironment

func PostgresEnvironment(user, password, database string) map[string]string

PostgresEnvironment initialises a PostgreSQL engine whose superuser is user. The engine trusts every connection because the endpoint authenticated the client already: relaying the client's own startup then runs the session as the user the client named without the endpoint replaying a password.

func QuoteIdentifier

func QuoteIdentifier(value string) string

QuoteIdentifier quotes a PostgreSQL identifier.

func QuoteLiteral

func QuoteLiteral(value string) string

QuoteLiteral quotes a PostgreSQL string literal; standard_conforming_strings leaves backslashes literal.

func QuoteMySQLIdentifier

func QuoteMySQLIdentifier(value string) string

func QuoteMySQLLiteral

func QuoteMySQLLiteral(value string) string

QuoteMySQLLiteral quotes a MySQL string literal. MySQL treats a backslash in a literal as an escape unless NO_BACKSLASH_ESCAPES is set, so a backslash is doubled as well as a quote.

func ReleaseLoopback

func ReleaseLoopback(identifier string)

ReleaseLoopback gives up the loopback address identifier held, once the instance behind it is deleted rather than stopped.

func SelfSignedCertificate

func SelfSignedCertificate(commonName string) func() (tls.Certificate, error)

SelfSignedCertificate returns the TLS certificate an endpoint presents, generated once on first use.

func ShellQuote

func ShellQuote(value string) string

ShellQuote quotes a word for /bin/sh.

Types

type Engine

type Engine struct {
	Family   Family
	Image    string
	Port     int
	DataPath string
	Args     []string
	// Client is the engine's command-line client inside the image.
	Client string
}

Engine is a database engine image and the facts about it the data plane depends on.

func (Engine) WithImage

func (e Engine) WithImage(image string) Engine

WithImage is the engine run from image.

type Family

type Family string
const (
	Postgres Family = "postgres"
	MySQL    Family = "mysql"
)

type Instance

type Instance struct {
	// Name prefixes the data plane's log lines, e.g. "Amazon RDS db-1".
	Name     string
	Engine   Engine
	Volume   string
	Labels   map[string]string
	Sandbox  sim.SandboxProfile
	Platform func(ctx context.Context, image string) (string, error)
	// Environment is read afresh at every engine start.
	Environment func() (map[string]string, error)
	// Ready runs once the engine accepts clients and before the first client
	// is relayed, to reconcile what the control plane recorded while the
	// engine was down.
	Ready func() error

	Certificate  func() (tls.Certificate, error)
	Authenticate func(user, password string, secure bool) bool
	// RefusePlaintext applies to PostgreSQL clients that did not ask for TLS.
	RefusePlaintext func() (message string, refuse bool)
	// BackendLogin names the engine account a MySQL-family session logs in as.
	BackendLogin func(user, password string) (backendUser, backendPassword string, err error)
	// Log receives the engine container's output, each line dated by the
	// container runtime. An adopted container replays its whole output, so
	// the sink sees lines it already holds again. Nil discards the output.
	Log sim.LogSink
	// contains filtered or unexported fields
}

Instance is one database instance's data plane: its endpoint listener and the engine container behind it. The engine starts on the first client connection, or is adopted from an earlier control-plane process.

func (*Instance) Adopt

func (i *Instance) Adopt() error

Adopt picks up the engine container an earlier control-plane process left for this instance, resuming it when it had stopped.

func (*Instance) Close

func (i *Instance) Close() error

Close stops accepting clients and stops the engine; the volume stays.

func (*Instance) Discard

func (i *Instance) Discard() error

Discard stops accepting clients and stops the engine of a resource being deleted, whose volume goes with it. An engine that has not yet accepted clients is killed rather than given the stop grace: the MySQL image's entrypoint ignores SIGTERM while it initialises the data directory, and a directory about to be removed needs no clean shutdown.

func (*Instance) Ensure

func (i *Instance) Ensure() error

Ensure brings the engine up and does not return until it accepts clients and Ready has run. An endpoint that relayed a client before then would answer with the engine's own startup refusal, which a managed database reporting itself available never does. The outcome holds until Stop.

func (*Instance) Exec

func (i *Instance) Exec(command []string) error

Exec runs command inside the running engine container and fails with the command's output when it exits non-zero. A command that lands while a volume capture holds the engine frozen waits for the capture, which bounds the freeze, to thaw it.

func (*Instance) Running

func (i *Instance) Running() bool

Running reports whether the engine container is up.

func (*Instance) Serve

func (i *Instance) Serve(listener net.Listener)

Serve accepts clients on listener until Close.

func (*Instance) ServeReadOnly

func (i *Instance) ServeReadOnly(listener net.Listener)

ServeReadOnly accepts clients on listener until Close and runs each session read-only in the engine, the way a replica serves it: PostgreSQL opens the session with default_transaction_read_only on and MySQL sets the session's transactions READ ONLY, so the engine itself refuses every write.

func (*Instance) Stop

func (i *Instance) Stop() error

Stop stops the engine and forgets the outcome of the last start, so the next client starts a fresh engine on the same volume. It returns once the container is gone and its volume is free to remove or replace.

Directories

Path Synopsis
Package mysqlwire speaks the connection phase of the MySQL client/server protocol a managed-database endpoint owns.
Package mysqlwire speaks the connection phase of the MySQL client/server protocol a managed-database endpoint owns.
Package pgwire speaks the front half of the PostgreSQL frontend/backend protocol a managed-database endpoint owns: the startup packet, the SSLRequest upgrade, a cleartext-password exchange, and ErrorResponse refusals.
Package pgwire speaks the front half of the PostgreSQL frontend/backend protocol a managed-database endpoint owns: the startup packet, the SSLRequest upgrade, a cleartext-password exchange, and ErrorResponse refusals.

Jump to

Keyboard shortcuts

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