Skip to content

docs: recommendations to ensure backup consistency and reliability #19845

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
May 31, 2022
Merged

docs: recommendations to ensure backup consistency and reliability #19845

Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
26b83a0
docs: recommendations to ensure backup consistency and reliability
singuliere May 31, 2022
7e0798b
s/stooping/stopping/
singuliere May 31, 2022
887de84
Update docs/content/doc/usage/backup-and-restore.en-us.md
singuliere May 31, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions docs/content/doc/usage/backup-and-restore.en-us.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,12 @@ file can be unpacked and used to restore an instance.

{{< toc >}}

## Backup Consistency

To ensure the consistency of the Gitea instance, it must be shutdown during backup.

Gitea consists of a database, files and git repositories, all of which change when it is used. For instance, when a migration is in progress a transaction is created in the database while the git repository is being copied over. If the backup happens in the middle of the migration, the git repository may be incomplete although the database claims otherwise because it was dumped afterwards. The only way to avoid such race conditions is by stopping the Gitea instance during the backups.

## Backup Command (`dump`)

Switch to the user running Gitea: `su git`. Run `./gitea dump -c /path/to/app.ini` in the Gitea installation
Expand All @@ -48,6 +54,17 @@ Inside the `gitea-dump-1482906742.zip` file, will be the following:
Intermediate backup files are created in a temporary directory specified either with the
`--tempdir` command-line parameter or the `TMPDIR` environment variable.

## Backup the database

The SQL dump created by `gitea dump` uses XORM and Gitea admins may prefer to use the native the MySQL and PostgreSQL dump tools instead. There are still open issues when using XORM for dumping the database that may cause problems when attempting to restore it.

```sh
# mysql
mysqldump -u$USER -p$PASS --database $DATABASE > gitea-db.sql
# postgres
pgdump -U $USER $DATABASE > gitea-db.sql
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this should be pg_dump?

Copy link
Contributor

@wxiaoguang wxiaoguang Sep 23, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fix typo in backup documentation (pgdump->pg_dump) #20913

```

### Using Docker (`dump`)

There are a few caveats for using the `dump` command with Docker.
Expand Down