Documentation
¶
Overview ¶
Package database describes the databases Jokku runs for apps: Postgres, MySQL and Redis. Each is a Jokku app of its own (kind postgres, mysql or redis) named <engine>-<name>, deployed from a compose file with one service, the official image and a data volume, reachable from other apps at <engine>-<name>.internal, and from outside only once exposed (through the proxies, see types.ProxyStream). Its config vars hold its passwords and fill in the compose file; linking it to an app sets a connection URL on the app.
Index ¶
- Constants
- func CheckName(name string) error
- func Names() []string
- func NewPassword() string
- func Refusal(stderr string) string
- type Bucket
- type Client
- type Command
- type Engine
- func (e Engine) AddUserCommand(name string, vars map[string]string, user, password string, readOnly bool) Command
- func (e Engine) AppName(name string) string
- func (e Engine) CheckUser(user string) error
- func (e Engine) Compose(memoryMB int, image string) string
- func (e Engine) ConnectCommand(name string, vars map[string]string) ([]string, []string)
- func (e Engine) ExportCommand(name string, vars map[string]string) ([]string, []string)
- func (e Engine) HasUsers() bool
- func (e Engine) Host(name string) string
- func (e Engine) ImageRef(image, version string) string
- func (e Engine) ImportCommand(name string, vars map[string]string) ([]string, []string, bool)
- func (e Engine) ParseStats(out []byte) (*Sample, error)
- func (e Engine) ParseUsers(out []byte) ([]User, error)
- func (e Engine) PasswordCommand(name string, vars map[string]string, user, password string) Command
- func (e Engine) Process() string
- func (e Engine) PublicURL(name, host string, port int, vars map[string]string) string
- func (e Engine) RemoveUserCommand(name string, vars map[string]string, user string) Command
- func (e Engine) SetupCommand(name string, vars map[string]string, s *Sample) Command
- func (e Engine) StatsCommand(name string, vars map[string]string) Command
- func (e Engine) URL(name string, vars map[string]string) string
- func (e Engine) UserURL(name, user, password, addr string) string
- func (e Engine) UserURLs(name, user, password, host string, port int) (internal, public string)
- func (e Engine) UsersCommand(name string, vars map[string]string) Command
- func (e Engine) Vars(name, image string) map[string]string
- type Query
- type Sample
- type User
Constants ¶
const ( VarImage = "DB_IMAGE" VarName = "DB_NAME" )
Config vars a database's compose file reads.
const ( AccessAll = "all" // everything, schema changes included AccessReadWrite = "read-write" // read and change data AccessReadOnly = "read-only" AccessOther = "other" // privileges Jokku didn't set )
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Bucket ¶
type Bucket struct{ Lo, Hi float64 }
Bucket is a histogram bucket: queries that took from Lo up to Hi microseconds.
type Client ¶
type Client struct {
Addr string // "" for a local socket
User string
Count int
Active int // running a query now
}
Client is a database's connections from one address as one user.
type Engine ¶
type Engine struct {
Name string // postgres, mysql or redis
Image string // the default image, without a tag
Version string // its default tag
Port int
MemoryMB int
// EnvVar is the config var a link sets on the app.
EnvVar string
// Mount is where the data volume is in the VM.
Mount string
// Stream is how the proxies carry its connections from outside
// (types.StreamPostgres, StreamTLS or StreamPlain).
Stream string
// Dump is what an export is, for messages and file names.
Dump string
// contains filtered or unexported fields
}
Engine is one kind of database.
func (Engine) AddUserCommand ¶
func (e Engine) AddUserCommand(name string, vars map[string]string, user, password string, readOnly bool) Command
AddUserCommand creates a login that reads (and unless readOnly, writes) the database's data, but can't change its schema: Postgres's pg_read_all_data and pg_write_all_data roles, MySQL's SELECT, INSERT, UPDATE and DELETE on its tables. The password goes in on stdin, never in arguments.
func (Engine) CheckUser ¶
CheckUser refuses a name that isn't a new login's: one the engine keeps for itself, or the database's own (which its apps use).
func (Engine) Compose ¶
Compose is the compose file a database running image is deployed from, with memoryMB for its VM.
func (Engine) ConnectCommand ¶
ConnectCommand is the shell to run in the database's VM, and its environment (passwords go there, not in the arguments).
func (Engine) ExportCommand ¶
ExportCommand writes the database's contents to stdout.
func (Engine) HasUsers ¶
HasUsers says whether Jokku manages the engine's logins (db:<engine>:users). Redis keeps users only in a file its server is started with, which an existing database's isn't.
func (Engine) ImageRef ¶
ImageRef is the image to run: image (default the engine's) at version (default the engine's).
func (Engine) ImportCommand ¶
ImportCommand reads an export from stdin; ok is false when the engine can't import that way.
func (Engine) ParseStats ¶
ParseStats reads StatsCommand's output.
func (Engine) ParseUsers ¶
ParseUsers reads UsersCommand's output.
func (Engine) PasswordCommand ¶
PasswordCommand gives a login a new password.
func (Engine) PublicURL ¶
PublicURL is how a client outside connects once the database is exposed at host:port: over TLS, which the proxies insist on for a Postgres or Redis stream.
func (Engine) RemoveUserCommand ¶
RemoveUserCommand drops a login and ends its sessions; the objects it owned (Postgres) go to the database's own user.
func (Engine) SetupCommand ¶
SetupCommand is s.Setup, run as the database's administrator.
func (Engine) StatsCommand ¶
StatsCommand looks inside the database, for ParseStats.
func (Engine) UserURLs ¶
UserURLs are user's URLs: the one its apps use, and, when the database is exposed at host:port, the one from outside.
func (Engine) UsersCommand ¶
UsersCommand lists the database's logins, for ParseUsers.
type Query ¶
Query is a statement and how long it has taken, since the server's statistics last started.
type Sample ¶
type Sample struct {
// Started is when the server started (Unix seconds): its counters
// start over with it.
Started float64
MaxConns int
// MaxUsed is the most connections at once since it started; 0 when the
// engine doesn't keep it.
MaxUsed int
Clients []Client
// ActiveKnown says whether Client.Active means anything: Redis runs
// one command at a time, so its clients are never seen busy.
ActiveKnown bool
// Queries counts the queries run so far, leaving out the stats
// command's own; Per says what one is ("query" or, for Postgres
// without pg_stat_statements, "transaction"). An engine that keeps how
// long they took as a histogram fills Hist, one that keeps only the
// total fills QueryMS.
Queries uint64
Per string
QueryMS float64
Hist map[Bucket]uint64
// Own is how many of Queries the stats command itself ran, when the
// engine can't leave them out (Postgres's transactions): the collector
// subtracts it from each interval.
Own uint64
// Hits and Misses are reads served from memory and from disk (Redis:
// keys found and not found); HitsAre says which.
Hits, Misses uint64
HitsAre string
MemoryUsed, MemoryMax uint64 // Redis, in bytes; MemoryMax 0 when unlimited
Slowest []Query // Postgres with pg_stat_statements, and MySQL: by total time
Users []User
// Setup is what to run once to turn on what the stats need, and Note
// what is still missing, in a sentence.
Setup *Command
Note string
}
Sample is one look inside a running database: its connections now, and counters that only grow while it runs, which two samples turn into rates and latency ("jokku top"). The control node takes one every few seconds by running StatsCommand in the database's VM.