quinzee.cloud

Development edition · 16 November 2026. Commands using repository paths, Make targets or sample projects require access to the Quinzee source checkout. No public installer is available. Examples use disposable local environments.

Administrator’s guide

10. Run PostgreSQL, MySQL and Valkey safely

The managed database modules implement ARM lifecycle and durable resource metadata. A separate operator-run supervisor creates the actual containers and volumes. Clients connect to those native engines directly. This division keeps the cloud process away from the Docker socket and allows the same cloud binary to run natively or in a container.

Step 1: prepare the approved engines

Start the cloud/network, then run on the Docker administrator's host:

make engine-images
make engines-run

The first command prepares the digest-pinned engine images. The second runs a foreground reconciliation loop using .local/quinzee and triglav-http_quinzee by default. Leave it running. When using another instance, set ENGINE_DATA_DIR and ENGINE_NETWORK together, or invoke the helper directly:

python3 infrastructure/engines/runtime.py \
  --data-dir /absolute/path/to/cloud-data \
  --state-dir /absolute/path/to/private-engine-state \
  --network your-existing-docker-network

Complete engine-helper options

Argument / environment Meaning
--data-dir Required cloud data root; reads/writes engine-runtime mailboxes
--network Docker network name; omitted uses quinzee-engines-<owner>; a missing network is created
--state-dir Private helper state outside the cloud data mount; omitted uses <data-parent>/engine-state/<owner>
--once Perform one reconciliation pass and exit; not a persistent supervisor
QUINZEE_OTLP_ENDPOINT Optional HTTPS telemetry collector origin
QUINZEE_OTLP_CA Optional additional collector CA

<owner> is the first 16 hexadecimal characters of SHA-256 over the resolved <data-dir>/engine-runtime path. Moving the data directory therefore changes the default ownership identity and paths.

Record the resolved private state path when commissioning. It holds signing material, ownership and credential state needed for continuity. Do not put it inside the broadly shared cloud data mount. Each helper uses an ownership label and lock; unrelated containers must never be removed to repair this instance.

Step 2: create a server and database

In Databases and cache → PostgreSQL or MySQL, select subscription/group, enter the server name, location, administrator and password, and create it. Use PostgreSQL version 18 or MySQL 8.4. Passwords are 8–128 characters without newline or NUL; reserved administrator/system database names are rejected. Wait for Succeeded/Ready. Then create an application database under that server.

PostgreSQL lifecycle and database controls

SQL clients use verified TLS on PostgreSQL 5432 or MySQL 3306 and the returned hostname. They need the engine CA, not merely the cloud's HTTPS CA. The helper publishes its public CA at <cloud-data>/engine-runtime/ca.crt; private signing material remains in helper state. It also runs a private bridge-bound CRL responder. Keep it reachable for clients that check certificate revocation.

The engine supervisor accepts only a fixed mailbox schema. A management request cannot choose arbitrary commands, images, mounts or Docker privileges. Engine containers use fixed limits: 1 GiB memory, two CPUs and 256 processes. SKU metadata does not resize those limits. The application role model does not implement managed-identity database login or engine-local user administration.

Step 3: create the cache

Open Managed Redis and create a resource using Balanced_B0, minimum TLS 1.2, then its default database with Encrypted/NoCluster/NoEviction. The real engine is Valkey. Read the access key through the authorized database listKeys operation and store it privately. The two returned key fields currently refer to one password; rotation is not implemented. Connect on TLS port 10000. The cache has an internal 512 MiB maxmemory/noeviction configuration in addition to the container limit. Plan for rejected writes when capacity is reached.

Step 4: pause, resume or remove

Use SQL Stop and wait for completion while the helper is running. Start and Restart are explicit lifecycle operations. Stopping the helper alone leaves engine containers running; it also stops its heartbeat and CRL responder. Module unload preserves volumes. SQL/cache Delete queues deliberate removal of the instance's labelled data volume and helper credentials. There is no built-in backup/restore service to reverse that deletion.

For an orderly host shutdown, quiesce applications, stop engines through their supported lifecycle, wait for reconciled status, then stop the helper and cloud. For recovery after a crash, restart the same helper with the same paths/network, check ownership and runtime status, then reconnect clients. Never launch a second helper against the same mailbox tree.

What can and cannot be changed

Surface Supported values / boundary
SQL server Name/location/tags, administratorLogin and private password at creation, supported version, lifecycle
SQL database Child name, create/get/list/delete; reserved system names rejected
Cache Supported SKU metadata, minimum TLS, default database protocol/clustering/eviction values
Capacity Fixed local limits; at most 128 retained server records/provider and 64 databases/SQL server
Not implemented HA, replicas, engine upgrades, backups API, private endpoints/firewall emulation, administrator rotation, Entra engine login

Use engine-native administration only within the application database's intended ownership. Changing helper-managed bootstrap credentials behind its back can break readiness and future reconciliation. Backup and restore drills belong to the next operations chapters, not to ad hoc edits of runtime JSON.