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 ¶
- Variables
- func FixedPlatform(platform string) func(context.Context, string) (string, error)
- func ListenLoopback(identifier string, port int) (net.Listener, error)
- func ListenLoopbackAt(identifier, address string, port int) (net.Listener, error)
- func ListenLoopbackPorts(identifier string, ports []int) ([]net.Listener, error)
- func PostgresEnvironment(user, password, database string) map[string]string
- func QuoteIdentifier(value string) string
- func QuoteLiteral(value string) string
- func QuoteMySQLIdentifier(value string) string
- func QuoteMySQLLiteral(value string) string
- func ReleaseLoopback(identifier string)
- func SelfSignedCertificate(commonName string) func() (tls.Certificate, error)
- func ShellQuote(value string) string
- type Engine
- type Family
- type Instance
- func (i *Instance) Adopt() error
- func (i *Instance) Close() error
- func (i *Instance) Discard() error
- func (i *Instance) Ensure() error
- func (i *Instance) Exec(command []string) error
- func (i *Instance) Running() bool
- func (i *Instance) Serve(listener net.Listener)
- func (i *Instance) ServeReadOnly(listener net.Listener)
- func (i *Instance) Stop() error
Constants ¶
This section is empty.
Variables ¶
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 ¶
FixedPlatform runs the engine image for one platform whatever the host is.
func ListenLoopback ¶
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 ¶
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 ¶
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 ¶
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 ¶
QuoteIdentifier quotes a PostgreSQL identifier.
func QuoteLiteral ¶
QuoteLiteral quotes a PostgreSQL string literal; standard_conforming_strings leaves backslashes literal.
func QuoteMySQLIdentifier ¶
func QuoteMySQLLiteral ¶
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.
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.
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 ¶
Adopt picks up the engine container an earlier control-plane process left for this instance, resuming it when it had stopped.
func (*Instance) Discard ¶
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 ¶
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 ¶
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) ServeReadOnly ¶
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.
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. |