# Go back to an earlier release (/run/go-back-a-release)

Return an install to an earlier release with marfa server upgrade, and put back the copy of the database an update took when the earlier release can't read it.



**Going back is an upgrade to the earlier release:** `marfa server upgrade` asks it first, and changes nothing when it refuses. An earlier release refuses a database that a later one changed, and then the way back is [the copy the update took](#once-the-database-has-changed).

## Go back by hand [#go-back-by-hand]

* **Programs you install.** Install the earlier release with the install script, which takes the release in `MARFA_VERSION` and the folder in `MARFA_INSTALL_DIR`, then run `marfa server upgrade` with its `marfa`. Homebrew installs only its newest release, so with Homebrew, use the install script, which installs in `~/.local/bin`, and run `~/.local/bin/marfa server upgrade`.
* **Docker, set up by the CLI.** Run `marfa server upgrade --release <version>`. It refuses an image before 0.0.76, which can't be asked: [move to a new install](/run/upgrade#move-to-a-new-install) instead.
* **Railway.** Set the earlier tag and deploy.

```bash
curl -fsSL https://raw.githubusercontent.com/withmarfa/marfa/main/scripts/install.sh | MARFA_VERSION=0.0.86 sh
marfa server upgrade --dir ~/marfa-server
```

**The `upgrade` of releases up to 0.0.85 refuses to go back.** To go back to one of them, install it the same way and run its `marfa server restart`. Its server refuses a database it can't read, and changes nothing. That's also the way when a message says the release that last ran can't be told.

## After the server updates itself [#after-the-server-updates-itself]

After `marfa update start`, the server swaps in the new `marfa-server` and keeps the old one beside it as `.marfa-server.previous`, and the new `marfa` waits as `.marfa.next`. The service's `marfa server run` then tries the new server, and `marfa update status` shows the outcome in `last`:

* **It settles once the new server stays up for 20 seconds.** The new `marfa` goes in place, the old one stays as `.marfa.previous`, and the update is `succeeded` once both programs report the new release.
* **Two starts that end before it settles put the old release back,** and so does one that refuses its settings or database, with exit `78`. The update is `rolled_back`, and `last` says why. Stopping the service or the machine counts no start.
* **When the old release can't open the database,** because the new one already changed it, the new release stays and the update is `failed`, saying why and, where needed, how to install the release again.

`marfa server run --check` checks an install's folder, settings, log path and server version without starting it.

## Once the database has changed [#once-the-database-has-changed]

**A release that changes the database schema first copies the database** to `marfa.db.before-upgrade` beside it. That copy is the way back, and **everything written since the update is lost.** An archive exported with the later release doesn't save it: restored into the copy, it adds only the items the copy lacks.

To put the copy back on an install in `~/marfa-server`:

### Stop the server [#stop-the-server]

Run `marfa server stop --dir ~/marfa-server`.

### Swap in the copy [#swap-in-the-copy]

Move `marfa.db` away **with its `marfa.db-wal` and `marfa.db-shm`**, then copy `marfa.db.before-upgrade` into its place. After a crash, or a stop while another program read the database, `marfa.db-wal` holds writes that would otherwise be read into the copy.

```bash
mkdir ~/marfa-server/replaced
cd ~/marfa-server/data
mv marfa.db marfa.db-wal marfa.db-shm ~/marfa-server/replaced/
cp marfa.db.before-upgrade marfa.db
```

`mv` reports a file that isn't there and moves the rest. Keep the moved files until the instance works again.

In a Docker install the files are in the volume `<name>-data`, and `docker cp` can't remove a file, so swap them in a one-off container on the volume:

```bash
docker run --rm --user 65532:65532 -v marfa-data:/data busybox:1.37 sh -c 'cd /data && mkdir replaced && for f in marfa.db marfa.db-wal marfa.db-shm; do [ ! -e "$f" ] || mv "$f" replaced/; done && cp marfa.db.before-upgrade marfa.db'
```

`docker cp marfa:/data/replaced .` copies the moved files out of the stopped container.

### Move to the earlier release [#move-to-the-earlier-release]

Install the earlier release and run `marfa server upgrade --dir ~/marfa-server` with its `marfa`, or `--release <version>` for Docker, as [Go back by hand](#go-back-by-hand) says.

The rules behind this page are in the contract's [updates](https://github.com/withmarfa/marfa/blob/main/conformance/spec/updates.md) chapter and the [instance](https://github.com/withmarfa/marfa/blob/main/conformance/spec/instance.md#a-database-this-build-did-not-write) chapter.
