Documentation
¶
Index ¶
- Variables
- func ContainerName(instanceName string) string
- func DetectPGVersionFromImage(imageName string) (string, bool)
- func PGDataMountTarget(version string) string
- func ParsePGMajorEnv(env []string) (int, bool)
- func ScratchContainerName(instanceName string, nonce int64) string
- func VolumeName(instanceName string) string
- type Client
- func (c *Client) CheckImageExists(imageName string) ([]string, bool)
- func (c *Client) ContainerPGData(containerID, version string) (string, error)
- func (c *Client) CreateContainer(name, version, image string, port int, password string, cpuCores, ramMB int, ...) (string, error)
- func (c *Client) CreateScratchCluster(containerName, instanceName, version, image string, cpuCores, ramMB int, ...) (string, error)
- func (c *Client) EnsureContainerOnNetwork(containerID string) (bool, error)
- func (c *Client) GetContainerImageID(containerID string) (string, error)
- func (c *Client) GetContainerLogs(containerID, tail string) (string, error)
- func (c *Client) GetContainerStatus(containerID string) (string, error)
- func (c *Client) GetDockerClient() *client.Client
- func (c *Client) GetImageID(imageName string) (string, bool)
- func (c *Client) ImagePGMajor(imageName string) (int, bool)
- func (c *Client) PullImageProgress(ctx context.Context, imageName string, progress io.Writer) error
- func (c *Client) RecreateContainer(name, version, image string, port, cpuCores, ramMB int, ...) (string, error)
- func (c *Client) RemoveContainer(containerID string) error
- func (c *Client) RemoveHelperContainers() (int, error)
- func (c *Client) RemoveOrphanedScratchVolumes() (int, error)
- func (c *Client) RemoveScratchCluster(containerID, volumeName string) error
- func (c *Client) RemoveVolume(volumeName string) error
- func (c *Client) StartContainer(containerID string) error
- func (c *Client) StopContainer(containerID string) error
- func (c *Client) StreamContainerLogs(ctx context.Context, containerID, tail string, w io.Writer) error
Constants ¶
This section is empty.
Variables ¶
var ErrPreflight = errors.New("container not modified")
ErrPreflight marks a RecreateContainer/CreateContainer failure that happened before any existing container was removed. Callers must not roll back on it — the previous container is still the one that is running.
Functions ¶
func ContainerName ¶ added in v0.1.78
ContainerName and VolumeName are the only places these two names are spelled. They are exported because the operations layer removes both by name during destroy — a container whose ID the store never learned still has to go, and a destroy that leaves the volume behind makes `oddk create --name <same>` fail forever (CreateContainer refuses to adopt an existing volume).
func DetectPGVersionFromImage ¶
DetectPGVersionFromImage tries to parse the PostgreSQL major version from an image name. Handles:
"postgres:17" → "17" "postgres:17.2" → "17" "pgvector/pgvector:pg18-trixie" → "18" "pgvector/pgvector:0.8.2-pg18" → "18" "postgis/postgis:18-3.6" → "18"
Returns major version string and whether detection succeeded.
func PGDataMountTarget ¶ added in v0.1.61
PGDataMountTarget is where an instance's data volume is mounted inside its container: the data directory itself for PG <= 17, its parent for PG 18+ (the official image moved PGDATA to /var/lib/postgresql/<major>/docker). Exported for the physical snapshot paths, which must know where inside the volume the cluster lives.
func ParsePGMajorEnv ¶ added in v0.1.61
ParsePGMajorEnv extracts PG_MAJOR from a docker env list. Exported for the package's external tests, matching its other pure helpers.
func ScratchContainerName ¶ added in v0.1.93
ScratchContainerName names the throwaway cluster a single-database restore out of a physical snapshot is read from. Deliberately NOT ContainerName's "oddk-pg-" prefix: that name means "an instance's container", and a scratch copy of a cluster must never be mistaken for the instance it was copied from.
func VolumeName ¶ added in v0.1.78
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
func (*Client) CheckImageExists ¶
CheckImageExists accepts tags, digests and image IDs, including untagged images retained for rollback, and returns the image's current tags.
func (*Client) ContainerPGData ¶ added in v0.1.61
ContainerPGData returns the container's effective PGDATA path, read from its environment (which includes image-inherited variables). The fallback mirrors the official images' conventions for containers that somehow lack the variable: the volume mount target for PG <= 17, <target>/<major>/docker for PG 18+.
func (*Client) CreateContainer ¶
func (*Client) CreateScratchCluster ¶ added in v0.1.93
func (c *Client) CreateScratchCluster(containerName, instanceName, version, image string, cpuCores, ramMB int, parameterGroupParams []parameters.Parameter) (string, error)
CreateScratchCluster creates — but does not start — an isolated container that a physical snapshot entry can be streamed into and then read from, on its own labelled volume (named like the container). The caller owns removal (RemoveScratchCluster); the startup sweep is the backstop for both.
func (*Client) EnsureContainerOnNetwork ¶ added in v0.1.50
EnsureContainerOnNetwork checks that the container is attached to the oddk-bridge network and connects it if not. Docker refuses to remove or prune a network that has containers attached (running or stopped), so keeping every instance container attached is what protects oddk-bridge from 'docker network prune'. Returns true if a connect was performed.
func (*Client) GetContainerImageID ¶
GetContainerImageID returns the ID (sha256:...) of the image a container was created from. Comparable with GetImageID's result.
func (*Client) GetContainerLogs ¶
GetContainerLogs returns the last N lines of logs from a container. Both stdout and stderr are merged into a single string.
func (*Client) GetContainerStatus ¶
func (*Client) GetDockerClient ¶
GetDockerClient returns the underlying Docker client for advanced operations
func (*Client) GetImageID ¶
GetImageID returns the local image ID (sha256:...) that an image tag/name currently resolves to, if the image is present locally. After re-pulling a moving tag (e.g. postgres:18) this reflects the newest patch, which can be compared against a container's image ID to detect a pending update.
func (*Client) ImagePGMajor ¶ added in v0.1.61
ImagePGMajor reports the PostgreSQL major version a local image serves, read from the PG_MAJOR environment variable the official images (and everything derived from them: pgvector, postgis, ...) carry. Best-effort: ok is false when the image cannot be inspected or does not declare PG_MAJOR, and callers must skip their check rather than refuse — a non-standard image is not proof of a mismatch.
func (*Client) PullImageProgress ¶
PullImageProgress pulls a Docker image from the registry, streaming the raw Docker progress JSON (newline-delimited jsonmessage frames) to progress as it arrives so a caller can render live progress. progress may be nil.
Unlike a bare io.Copy of the pull stream, this also decodes each frame to detect an embedded pull error (Docker reports failures such as "manifest unknown" inside the stream and still returns a clean EOF), so the returned error reflects the real outcome.
If writing to progress fails (e.g. the client disconnected), the pull is NOT aborted: progress writes are dropped and the stream is drained to completion so the image still lands in the local cache. Operations are uninterruptible by client disconnect by design.
func (*Client) RecreateContainer ¶
func (c *Client) RecreateContainer(name, version, image string, port, cpuCores, ramMB int, parameterGroupName string, parameterGroupParams []parameters.Parameter, oldContainerID string) (string, error)
RecreateContainer stops and removes the old container, then creates a new one with the same volume but new parameters.
Cheap checks (image, parameter resolution, shared-memory fit, volume exists) run BEFORE the old container is removed. Failures of those wrap ErrPreflight so the caller knows the previous container is still the running one.
It deliberately takes NO password: the volume it reuses is populated by construction (preflight refuses a missing one), so the entrypoint skips initdb and would discard the value. Keeping the parameter off the signature is what stops it being reintroduced. See containerEnv.
func (*Client) RemoveContainer ¶
func (*Client) RemoveHelperContainers ¶
RemoveHelperContainers force-removes any containers labeled as ODDK helpers (label oddk.helper=true). Called at daemon startup to clean up orphans left by a previous crashed daemon run. Returns the number of containers removed.
Single-host single-daemon deployment is assumed. If a second ODDK daemon is running on the same host, this will rip out its in-flight helper containers.
func (*Client) RemoveOrphanedScratchVolumes ¶ added in v0.1.93
RemoveOrphanedScratchVolumes removes every labelled scratch volume. Run at daemon startup, AFTER RemoveHelperContainers: at that point no operation is running, so any scratch volume left is an orphan — from a crash, or from a removal Docker reported as successful but did not complete. Returns how many were removed.
func (*Client) RemoveScratchCluster ¶ added in v0.1.93
RemoveScratchCluster force-removes a scratch container and then, separately, its volume — which holds a full copy of the instance's cluster. The volume removal is its own checked call on purpose: a container removed with RemoveVolumes reports success even when Docker failed to delete the volume, and the caller must be able to tell the operator a copy of their data is still on disk. An already-absent container or volume is not an error.
Source Files