How to backup, restore and migrate

Important Notes

  • This post is based on Gogs
  • If you’re trying to restore to PostgrsSQL, you need at least

Other than pack up gogs-repositories, custom and database separately, Gogs provides two commands for unified process of backup, restore and even migrate to another database engine.


Go to the directory where your Gogs binary is located, and execute following command:

./gogs backup

Without any flags, backup command will pack up all gogs-repositories, custom and database into a single zip archive (e.g. under current directory.

It could be a bad idea if your gogs-repositories contains GB of raw data, in that case, you can apply --exclude-repos flag:

./gogs backup --exclude-repos

If your custom/conf/app.ini is somewhere unusual, make sure you specify it via --config flag like always:

./gogs backup --config=my/custom/conf/app.ini


If you’re only interested in backup database, or want to migrate from one database engine (e.g. SQLite3) to another engine (e.g. MySQL), --database-only is your friend:

./gogs backup --database-only

The backup format of database are portable JSON files, each file corresponds to a database table, you can do whatever you want with those files.


The restore command also has flags to indicate only restore database or everything in backup archive:

./gogs restore --database-only --from=""

If a table that is not presented in backup archive, whatever in current database table will remain unchanged.

Custom config file

There are 3 steps to determine which custom/conf/app.ini command uses:

  1. Use the one you specified vis flag --config.
  2. Use the one stored in backup archive.
  3. Use the one in $(pwd)/custom/conf/app.ini.

If all 3 steps failed, sorry, impossible to perform restore process.

:speech_balloon: Please leave comments if you have any questions or concerns about this post.


Is there an Option to define the filename? Or have you an idea how i can uploud the file with replacing the old file to gdrive or another cloudstorage? Maybe with regex?

What “filename”?

The output file name, because I have problems with the timestamp :smiley:

Ah, not impossible currently. Suggest file an issue on GitHub and refer to this thread.

Is it intended to be used for version changes?

For instance:

  1. Backup
  2. Install new/different version
  3. Restore to new version

Is it up and downward compatible?

No, restore is not needed for upgrade.

Getting an error doing this inside docker container, version 0.10.18:

$ sudo docker exec -it gogs /bin/bash
bash-4.3# su - git
689b4880070d:~$ /app/gogs/gogs backup
2017/03/24 20:14:08 [  INFO] Backing up root directory: /tmp/gogs-backup-665910483
2017/03/24 20:14:08 [  INFO] Packing backup files to:
2017/03/24 20:14:08 [FATAL] Fail to dump database: fail to dump table 'User' : no such table: user

Set the USER environment variable as described here, rather than switching to the git user with su, and I get the same error.

It seems to me your database is empty.

It’s not.

$ sqlite3 gogs.db
SQLite version 3.11.0 2016-02-15 17:29:24
Enter ".help" for usage hints.
sqlite> select count(*) from user;

How do you make sure you’re connecting to same SQLite3 database file?

Found the issue, but discovered another. PATH was set as a relative path in my app.ini:

DB_TYPE = sqlite3
NAME = gogs
USER = root
SSL_MODE = disable
PATH = data/gogs.db

If I change this to PATH = /data/gogs.db the backup runs fine inside the container, but the problem then becomes gogs no longer works in production. I get a blank screen when I go to the explore URL, and none of my users can login. If I stop the container, change the PATH back to PATH = data/gogs.db and then start it again, everything is normal, and my users can login and see repositories.

1 Like

Definitely something going on here, taking this out of the thread and into an issue on github

Having a problem with the Restore option version for Gogs

The error shown is as follows:

[FATAL] Fail to import ‘custom’: rename /tmp/gogs-backup/custom /data/gogs: invalid cross-device link

Hi,I am trying to using gogs backup to backup my repo.
Why do you say “It could be a bad idea if your gogs-repositories contains GB of raw data”,if so,what’s the better solution for backing up.
Thank you.

@akav use tar or rsync, but it’s really your taste, you can of course use ./gogs backup to pack everything

Thank you very much.
I just want to make sure that ./gogs backup works fine with GB of raw data.

And,I have another question.
How can I ignore dirs like sessions tmp with ./gogs backup…
Thank you for your help.

I believe these dirs are ignored by default, at least in least realese.