database

package
v0.8.22 Latest Latest
Warning

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

Go to latest
Published: Oct 17, 2026 License: MIT Imports: 17 Imported by: 0

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

View Source
const (
	VarImage = "DB_IMAGE"
	VarName  = "DB_NAME"
)

Config vars a database's compose file reads.

View Source
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

func CheckName

func CheckName(name string) error

CheckName refuses a database name that wouldn't make an app name and a database name both engines accept.

func Names

func Names() []string

Names lists the engines, sorted.

func NewPassword

func NewPassword() string

NewPassword is a fresh password for a login.

func Refusal

func Refusal(stderr string) string

Refusal is what a database said when it refused a command, without its client's prefixes.

Types

type Bucket

type Bucket struct{ Lo, Hi float64 }

Bucket is a histogram bucket: queries that took from Lo up to Hi microseconds.

func (Bucket) Mid

func (b Bucket) Mid() float64

Mid is a duration that stands for b.

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 Command

type Command struct {
	Argv  []string
	Env   []string
	Stdin string
}

Command is something to run in a database's VM: Argv with Env, fed Stdin.

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 Lookup

func Lookup(name string) (Engine, bool)

Lookup finds an engine by name.

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) AppName

func (e Engine) AppName(name string) string

AppName is the app a database runs as.

func (Engine) CheckUser

func (e Engine) CheckUser(user string) error

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

func (e Engine) Compose(memoryMB int, image string) string

Compose is the compose file a database running image is deployed from, with memoryMB for its VM.

func (Engine) ConnectCommand

func (e Engine) ConnectCommand(name string, vars map[string]string) ([]string, []string)

ConnectCommand is the shell to run in the database's VM, and its environment (passwords go there, not in the arguments).

func (Engine) ExportCommand

func (e Engine) ExportCommand(name string, vars map[string]string) ([]string, []string)

ExportCommand writes the database's contents to stdout.

func (Engine) HasUsers

func (e Engine) HasUsers() bool

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) Host

func (e Engine) Host(name string) string

Host is where apps reach a database.

func (Engine) ImageRef

func (e Engine) ImageRef(image, version string) string

ImageRef is the image to run: image (default the engine's) at version (default the engine's).

func (Engine) ImportCommand

func (e Engine) ImportCommand(name string, vars map[string]string) ([]string, []string, bool)

ImportCommand reads an export from stdin; ok is false when the engine can't import that way.

func (Engine) ParseStats

func (e Engine) ParseStats(out []byte) (*Sample, error)

ParseStats reads StatsCommand's output.

func (Engine) ParseUsers

func (e Engine) ParseUsers(out []byte) ([]User, error)

ParseUsers reads UsersCommand's output.

func (Engine) PasswordCommand

func (e Engine) PasswordCommand(name string, vars map[string]string, user, password string) Command

PasswordCommand gives a login a new password.

func (Engine) Process

func (e Engine) Process() string

Process is the database's process type in its app.

func (Engine) PublicURL

func (e Engine) PublicURL(name, host string, port int, vars map[string]string) string

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

func (e Engine) RemoveUserCommand(name string, vars map[string]string, user string) Command

RemoveUserCommand drops a login and ends its sessions; the objects it owned (Postgres) go to the database's own user.

func (Engine) SetupCommand

func (e Engine) SetupCommand(name string, vars map[string]string, s *Sample) Command

SetupCommand is s.Setup, run as the database's administrator.

func (Engine) StatsCommand

func (e Engine) StatsCommand(name string, vars map[string]string) Command

StatsCommand looks inside the database, for ParseStats.

func (Engine) URL

func (e Engine) URL(name string, vars map[string]string) string

URL is how a linked app connects.

func (Engine) UserURL

func (e Engine) UserURL(name, user, password, addr string) string

UserURL is how user connects to the database at addr (host:port).

func (Engine) UserURLs

func (e Engine) UserURLs(name, user, password, host string, port int) (internal, public string)

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

func (e Engine) UsersCommand(name string, vars map[string]string) Command

UsersCommand lists the database's logins, for ParseUsers.

func (Engine) Vars

func (e Engine) Vars(name, image string) map[string]string

Vars are a new database's config vars: its image, name and fresh passwords.

type Query

type Query struct {
	Text    string
	Calls   uint64
	TotalMS float64
	MeanMS  float64
}

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.

type User

type User struct {
	Name   string
	Access string // AccessAll, AccessReadWrite, AccessReadOnly or AccessOther
}

User is a login of a database's, and what it may do.

Jump to

Keyboard shortcuts

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