# Operating pilcrow

## Upgrades

The `pilcrow` server will automatically upgrade its database on startup. Before doing so, it will create a backup of your database (at `pilcrow.db.backup`, or controlled by `--backup-database-url`). If the migration process succeeds, this backup will be deleted automatically. If the migration process _fails_, however, `pilcrow` will attempt to restore your existing database from the backup before exiting. If the restore process also fails, then both the backup database and the suspected-broken database will be left in place.

To avoid destroying backups that may still be needed, `pilcrow` will not start if the backup database already exists. **There is no catch-all advice on how to proceed**, but you can try the following:

- Start the server with **a copy** of the backup database, and determine if any data has been lost. If not, shut it down, replace your main database by copying the backup, and carry on.

The `pilcrow` database is an ordinary file. While the server is not running, it can be freely copied or renamed without invalidating the data in it.

## Permissions

The Pilcrow database (`pilcrow.db` by default) should have restricted permissions, as it contains data that is either confidential (such as users' conversations), sensitive (such as the service's configuration), or both. At minimum, it should not be world-readable on the server where Pilcrow is installed.

By default, the `pilcrow` command will set the process' umask to a value that prevents the creation of world-readable or world-writeable files, so that the Pilcrow database will be created with appropriate filesystem permissions. This behaviour can be controlled using the `--umask` startup option, which takes the following values:

- `masked`, the default, which takes the inherited umask and additionally sets the world-readable, world-writeable, and world-executable bits;
- `inherit`, which takes the inherited umask as-is, requiring the operator to set a sensible value here; or
- any octal value corresponding to a valid umask, such as `0027`.

Pilcrow does not check or change the permissions of the database after creation. Changing the umask of the server after the database has been created has no effect on the database's filesystem permissions.