Help:External database

Canasta can be pointed at an existing external MySQL/MariaDB-compatible database server instead of running its bundled db container. This is the recommended path for production HA: it removes the database tier as a single point of failure, since a managed service (RDS Multi-AZ, Aurora, Cloud SQL, Azure Database for MySQL) or a self-hosted cluster (Galera, Percona XtraDB, MaxScale) handles replication and failover.

When to use this

Use an external database when:

You already operate a managed database service for other applications and want Canasta to use it.
You need the wiki to survive failure of the node hosting Canasta — the bundled db container uses node-local storage, so a node failure on a single-node deployment, or on the DB-pinned node in a multi-node Kubernetes deployment, takes the wiki down regardless of how many web replicas are running.
You want maintenance/update.php runs to be database-side — i.e. they don't block on a single Canasta-managed DB pod restarting.

The default deployment runs one MariaDB container on local storage. That's fine for development, evaluation, and small single-node production deployments where the host's uptime is the wiki's uptime. For anything more demanding, an external database is the simplest HA win.

Prerequisites

On the database server:

MySQL 5.7+ or MariaDB 10.3+ (matches what the bundled db uses; older versions may work but are not tested).
Network reachability from the Canasta host (or, for Kubernetes, from the web and jobrunner pods).
A user account on the database server named root, with CREATE DATABASE and full GRANT privileges. Canasta connects to the database server as root at create time to run the install.php step that provisions the wiki's database and schema. For self-hosted MariaDB / MySQL this is usually already in place. For managed services (RDS, Aurora, Cloud SQL, Azure Database for MySQL) where the master user has a different name, create a dedicated root@'%' user with appropriate grants, e.g.:

CREATE USER 'root'@'%' IDENTIFIED BY 'STRONG_PASSWORD_HERE';
GRANT ALL PRIVILEGES ON *.* TO 'root'@'%' WITH GRANT OPTION;
FLUSH PRIVILEGES;

If your security policy doesn't allow WITH GRANT OPTION, narrow the grants to the database name(s) you'll create — the user must still hold CREATE on at least the wiki databases-to-be.

For TLS-required databases, make sure the client trusts the server's CA — Canasta uses the system CA bundle inside the container.

Setup

External-database configuration is supplied via an env file passed to canasta create with -e/--envfile. Pass the password through this file, not on the command line, so it doesn't leak through ps or shell history.

Create the env file

cat > /path/to/external-db.env <<'EOF'
USE_EXTERNAL_DB=true
MYSQL_HOST=db.example.internal
MYSQL_PORT=3306
MYSQL_USER=canasta
MYSQL_PASSWORD=STRONG_PASSWORD_HERE
MYSQL_SSL=false
EOF
chmod 600 /path/to/external-db.env

Keys, in detail:

USE_EXTERNAL_DB=true required — the flag that switches Canasta out of bundled-DB mode. If set to false or omitted, the other MYSQL_* keys are ignored and the bundled db container is used.
MYSQL_HOST required when USE_EXTERNAL_DB=true — hostname or IP of the database server. canasta create fails with a clear error if this isn't set.
MYSQL_PORT (default 3306) — port the database server listens on.
MYSQL_USER (default root) — username MediaWiki uses at runtime to connect to the database. The install-time connection always uses root (see Prerequisites), so for the common case where the same account handles both, leave this at the default.
MYSQL_PASSWORD required — password for the root account on the database server. Stored in the instance's .env file (Compose) or <id>-db-credentials Secret (Kubernetes).
MYSQL_SSL (default false) — set to true to require TLS for connections to the database server.

Create the instance

Pass the env file with -e:

canasta create \
  --id mywiki \
  --wiki main \
  --domain-name wiki.example.com \
  -e /path/to/external-db.env

For a Kubernetes deployment, also pass --orchestrator kubernetes and any storage / TLS flags needed for that environment (see Help:Multi-node Kubernetes).

What happens during create:

Canasta reads USE_EXTERNAL_DB from the env file. If true, it validates that MYSQL_HOST is also set and refuses to continue otherwise.
The bundled db service is not started. On Compose, this is achieved by setting COMPOSE_PROFILES to an empty value (the db service is gated behind an internal-db profile that's only enabled in bundled-DB mode). On Kubernetes, the generated values.yaml sets db.enabled: false and populates an externalDatabase block.
install.php runs against MYSQL_HOST:MYSQL_PORT with --installdbuser = MYSQL_USER and --installdbpass = MYSQL_PASSWORD, creating the wiki database on the external server.
The web and jobrunner containers see USE_EXTERNAL_DB=true at runtime and skip the wait-for-local-db loop they use in bundled-DB mode.

Verify

After canasta create finishes:

# The bundled db container/pod should NOT exist:
docker ps --filter "name=mywiki_db_1"            # Compose: empty output
kubectl get pod -n canasta-mywiki | grep -E '\bdb\b'   # K8s: empty output

# The wiki responds:
curl -I https://wiki.example.com/wiki/Main_Page  # 200 (after TLS provisioning)

You can also check that the wiki database was created on the external server:

SHOW DATABASES LIKE 'mywiki';
SELECT COUNT(*) FROM mywiki.user;   -- should return at least 1 (the wiki admin)

Wiki farms

The external-DB flow is per-instance, not per-wiki. All wikis in the same Canasta instance share the configured external database server (the same way they all share the bundled db container by default). Each wiki gets its own database on that shared server, named after the wiki ID — e.g. canasta add --id mywiki -w docs ... creates a docs database alongside the existing main database.

The MYSQL_USER needs CREATE DATABASE at the time canasta add runs, since the wiki-add flow also calls install.php.

Read replicas

Canasta's external-DB envfile keys configure a single primary connection. Pointing MediaWiki at a read replica is a MediaWiki-level concern: configure $wgDBservers in your wiki's Settings.php. See Manual:$wgDBservers on mediawiki.org for the format.

Switching an existing instance

The five external-DB keys are immutable after instance creation:

USE_EXTERNAL_DB
MYSQL_HOST
MYSQL_PORT
MYSQL_USER
MYSQL_SSL

canasta config set blocks attempts to change these with the message:

'<key>' cannot be changed after instance creation. Delete the instance
and recreate with the new database configuration.

The reason: all wikis in the instance share the same database connection. Pointing a running instance at a different database would orphan the existing data; doing it via a config-set command would silently break the wiki at the next restart. To migrate from bundled-DB to external-DB (or vice versa), the supported path is:

canasta export the wiki(s) on the existing instance.
canasta delete the instance.
Set up the external database (or the bundled DB) according to the new shape.
canasta create a fresh instance with the desired database configuration.
canasta import the exported data.

A future feature (not yet implemented) may automate this; for now the export/delete/create/import flow is the canonical way.