Service upgrade

Every service in vallic.yaml names a version:

services:
  - mariadb: '11.4'
  - valkey: '8.1'

That is the version your environment runs, from the next deploy. Change it, push, and the deploy brings the service up on the version you named. A version the platform does not offer is not honoured — the service stays on the current default. Software stacks lists what each service offers.

For most services that is all there is to it. For the ones that keep data, it is not always, and this page is about the difference.

#Services that keep nothing

Caches — Valkey, Redis, Memcached — and Varnish hold nothing that cannot be rebuilt. Move them up or down freely. Their contents may be empty afterwards; your application refills them as it is used, and a Drupal site can be helped along with a cache rebuild.

#Services that keep data

Databases — MariaDB, MySQL, PostgreSQL — search — Solr, Meilisearch — and the queue, RabbitMQ, keep data on disk in a format that belongs to the version that wrote it. The new version starts on the files the old one left. Whether it can read them depends on the engine and the direction:

Your application's own data is never touched by any of this — only the service's files on the machine. A database that will not start is a site that is down until one of the paths below is taken, so pick the path before you push.

#Before you change anything

1. Take a backup — Backups → Back up now on the environment. Database backups are SQL dumps, and an SQL dump can be restored into any version. That is what makes every path below work.

2. Keep a dump of your own as well, over shell access:

   ssh -p 2417 vc-t-acme@production.acme.vallic.cloud db-export > before-upgrade.sql
   

3. Try it on staging first. Backups → Copy from another environment puts production's data on staging; change the version on the branch staging tracks, deploy, and see what happens there rather than on your live site.

#Moving a database to a version that can read the old data

MariaDB or MySQL, to a newer version.

1. Take the backup above.
2. Change the version in vallic.yaml and deploy.
3. Check the site. If anything is wrong, the backup is your way back — see Going back below; changing the version back on its own is not, because the data has already been upgraded.

#Moving a database to a version that cannot read the old data

PostgreSQL to another major version, or any database to an older version. There are three ways, from the least to the most disruptive.

#A new environment, then move to it

The safest, because the old environment is not touched until the new one is proven.

1. Create a new environment — or a new project, for production — whose vallic.yaml names the new version from its first deploy. A database that starts on the version you want never has old files to read.

2. Deploy it, then load your data into it: Backups → Copy from another environment for a staging environment, or db-import with the dump you kept:

   ssh -p 2417 vc-t-acme@production.acme-new.vallic.cloud db-import < before-upgrade.sql
   

3. Move your files if they need to go too — see Shell access for rsync.

4. Check the new environment, then move your domains across and remove the old one.

#The same environment, with its database reset

When a new environment is not practical. Backups → Reset database on the environment does it in one action: a backup of the database while it still answers, then its files emptied on the machine that runs it, then the newest backup restored into the empty database. Each step waits for the one before.

1. Keep a dump of your own, as above — a second copy costs nothing.
2. Change the version in vallic.yaml and deploy. On a version that cannot read the old files the database will not start; that is expected.
3. Backups → Reset database. Leave Take a database backup first ticked if the database still answers — before step 2, or on a version change that did start — and untick it if it no longer starts; the backups already taken are what is restored then. Leave Restore the newest database backup ticked. Type the environment's name to confirm.
4. The database starts empty on the version vallic.yaml declares, and the backup loads into it. A backup is SQL, so any version reads it. If you would rather load your own dump, untick the restore and db-import it.

Only an Admin or the Owner can reset a database, and only by typing the environment's name — it deletes every table. Your site is unavailable from the reset until the restore finishes: do it at a quiet time, and consider switching the site offline first so visitors see a page saying so.

#Reimporting without clearing

Only for a database that did start on the new version but whose data you want rebuilt anyway — to shed an old format, or after an upgrade that left things half-converted. db-import loads over what is there. A MariaDB or MySQL dump from db-export carries DROP TABLE statements and replaces each table as it goes; a PostgreSQL one does not, so drop the tables it will recreate first.

#Search indexes and queues

• Solr and Meilisearch: after changing the version, rebuild the index from your application — for Drupal, drush search-api:reindex and then drush search-api:index. An index is built from your database, so nothing is lost that the rebuild cannot put back.
• RabbitMQ: let the queues drain, or stop what feeds them, before a change that is not a minor version. Messages still waiting when the service is replaced may not be there afterwards.

#Going back

• A cache or Varnish: change the version back and deploy.
• A database that has not written anything on the new version — it did not start: change the version back and deploy. The old version finds its own files untouched.
• A database that ran on the new version: the old version may no longer read its files. Take the same environment, database reset path above in reverse — put the old version back in vallic.yaml, deploy, then Reset database with the backup unticked, so the one you took before you started is what is restored.

#Who can do this

Changing a version is a commit, so it is whoever can push to the branch an environment tracks. Backing up, restoring and copying are on the environment's Backups tab, for the roles Teams lists. Resetting a database is an Admin or the Owner only.

#Next

• Configuration — the rest of vallic.yaml
• Backups — taking, restoring and copying
• Software stacks — which versions each service offers