# Quickstart

> Protect your first PostgreSQL database in about 10 minutes, from sign-up to the first backup and restore drill.

Source: https://rowsafe.sh/docs/quickstart

This guide protects one PostgreSQL server. You'll install a small agent on it, review a plan, apply it, and restart PostgreSQL once, when it suits you.

**You need:**

- A Linux server running PostgreSQL 13 to 18 on Debian 12/13 or Ubuntu 22.04/24.04, with `sudo`. (PostgreSQL in Docker? See [Run the agent in Docker](https://rowsafe.sh/docs/guides/docker).)
- A storage bucket for the backups: Cloudflare R2 (10 GB free), Backblaze B2, Amazon S3, Wasabi, DigitalOcean Spaces or any S3-compatible storage.
- A few seconds of downtime for one PostgreSQL restart, at a time you choose.

> **Production database?** This is the short version. For a server that matters, follow [Adopt an existing database](https://rowsafe.sh/docs/guides/adopt): it adds the preflight checks, secret handling and rollback plan.

### Create an account

[Sign up](https://app.rowsafe.sh/sign-up). The Free plan protects one server with up to three databases, with every feature.

### Install the CLI and log in

Run this on your own computer, not on the database server. The CLI is a single binary for macOS and Linux:

**macOS (Apple silicon)**

```sh
curl -fsSLo rowsafe https://github.com/rowsafe/rowsafe/releases/latest/download/rowsafe-darwin-arm64
chmod +x rowsafe && sudo mv rowsafe /usr/local/bin/
```

**macOS (Intel)**

```sh
curl -fsSLo rowsafe https://github.com/rowsafe/rowsafe/releases/latest/download/rowsafe-darwin-amd64
chmod +x rowsafe && sudo mv rowsafe /usr/local/bin/
```

**Linux (x86-64)**

```sh
curl -fsSLo rowsafe https://github.com/rowsafe/rowsafe/releases/latest/download/rowsafe-linux-amd64
chmod +x rowsafe && sudo mv rowsafe /usr/local/bin/
```

**Linux (ARM64)**

```sh
curl -fsSLo rowsafe https://github.com/rowsafe/rowsafe/releases/latest/download/rowsafe-linux-arm64
chmod +x rowsafe && sudo mv rowsafe /usr/local/bin/
```

Then log in. This opens the dashboard in your browser, where you confirm a code:

```sh
rowsafe login
```

Over SSH, or with `--no-browser`, open the printed link on any device.

### Create a bucket

Create a **private**, empty bucket, for example `app-rowsafe`, and an access key that can read, write and delete **only in that bucket**. [Set up backup storage](https://rowsafe.sh/docs/guides/storage) has click-by-click steps for each provider.

Keep the page with the access key ID and secret open: you'll paste them into the installer in the next step.

### Install the agent

Create a one-time enrollment token. It is valid for one hour:

```sh
rowsafe hosts enroll-token
```

It prints the install command with the token. Run it **on the database server**:

```sh
curl -fsSL https://rowsafe.sh | sudo sh -s rse_...
```

The installer checks the agent's signature and installs it with the backup tool it needs. Then it asks, in your terminal:

1. **Where to keep backups**: pick your provider, then paste the bucket name and access key.
2. **It tests the bucket**: writes, reads back and deletes a small file. If something is wrong, it tells you what and lets you fix it.
3. **The encryption passphrase**: it generates a strong one and shows it once. Then it starts the agent.

> **Save the passphrase before you continue:** Put the passphrase in your password manager **before** the first backup. Without it, no backup can ever be restored, and nobody can recover it, Rowsafe included. The installer asks you to type its last 4 characters to confirm.

Your keys and passphrase stay on the server, in `/etc/rowsafe/agent.env`. Rowsafe never sees them.

Back on your computer, check that the server shows up:

```sh
rowsafe hosts list
```

You can also do this step from the dashboard: **Hosts**, then **Add host**.

### Adopt the database

Give the database a name in Rowsafe, for example `app`. The name covers the whole PostgreSQL server (all its databases). It uses lowercase letters, digits and dashes.

```sh
rowsafe adopt app
```

This **only reads**. It prints a plan: the backup configuration Rowsafe will write, and the database settings it will change.

**Example plan**

```text
Plan (nothing has been changed yet):
  + write pgBackRest config (0600, contains repository credentials) to /etc/rowsafe/pgbackrest/app.conf
  + pgbackrest stanza-create: initialise the repository for this cluster
  ~ archive_mode: off -> on   [needs restart]
  ~ archive_command: - -> /usr/bin/pgbackrest --config=/etc/rowsafe/pgbackrest/app.conf --stanza=app archive-push %p
  ~ archive_timeout: 0 -> 300
Next: rowsafe apply app
```

See [How PostgreSQL backups work](https://rowsafe.sh/docs/concepts/postgresql) for what each change does.

If you have more than one server, add `--host HOST`. If the plan warns that another tool already archives your database, stop and find out what it is first. See [Adopt an existing database](https://rowsafe.sh/docs/guides/adopt).

### Apply the plan

```sh
rowsafe apply app
```

Rowsafe writes the backup configuration, prepares the bucket, and changes the settings. There is no downtime. It **never restarts your database**.

### Restart PostgreSQL in your maintenance window

Turning on archiving needs one restart. Pick a quiet moment. Clients see a few seconds of refused connections:

```sh
sudo systemctl restart postgresql
```

On Debian and Ubuntu you can restart one cluster with its own unit, for example `postgresql@18-main`.

### Verify

```sh
rowsafe verify app
```

Rowsafe proves that your database's changes reach your bucket. Then:

```text
app is protected. The first full backup is queued; follow it with `rowsafe tasks app`.
```

### Run your first restore drill

When the first backup has finished (`rowsafe backups app`), prove that it restores:

```sh
rowsafe drill app
rowsafe status app
```

`rowsafe status app` says `app is PROTECTED.` once there is a recent backup and a passing drill.

## What happens next

Rowsafe now runs on its own. By default, in UTC:

| When                     | What                                                              |
| ------------------------ | ----------------------------------------------------------------- |
| Continuously             | Every change is archived to your bucket, at most 5 minutes behind |
| Sundays 01:00            | Full backup                                                       |
| Monday to Saturday 01:00 | Differential backup                                               |
| Sundays 21:15            | Restore drill                                                     |

It keeps two full backups, so you can restore to any point in about the last two weeks. You can change the schedules and retention with [`rowsafe db set`](https://rowsafe.sh/docs/reference/cli#database-settings).

**Set up alerts** so you hear about problems. For example, to get warnings and critical alerts in Slack:

```sh
rowsafe channels add --type slack --name team --url https://hooks.slack.com/services/...
```

See [Monitoring and alerts](https://rowsafe.sh/docs/guides/monitoring) for email, Discord and webhooks.

- [Restore a database](https://rowsafe.sh/docs/guides/restore): Read it now, before you need it.

- [Restore points](https://rowsafe.sh/docs/concepts/restore-points): Mark a moment before a migration: `rowsafe mark app before-migration`.

- [AI agents](https://rowsafe.sh/docs/guides/ai-agents): Let coding agents create restore points before risky changes.

- [Troubleshooting](https://rowsafe.sh/docs/troubleshooting): Common errors and how to fix them.