1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
|
Backup & Restore
================
A well-maintained Fietsboek instance should have regular backups configured in
case data is lost due unforseen reasons.
.. note::
As a rule of thumb: A backup that you haven't restored is not a backup!
Part of the backup process is to ensure that the backups actually contain
the necessary data and that the restoration process works. Make sure to
test your backups on a separate installation of Fietsboek.
Backup
------
The Fietsboek data lives in two places: Most of it is saved in the database,
while track images and other "big files" are saved in the data directory.
You should refer to the manual of your DBMS to see what the procedure for a
backup is. Using the preferred way for your DBMS ensures that your backup
represents a consistent state of the database.
After backing up the database, you should back up the data directory with a
tool of your choice, for example by using ``tar``, ``rsync`` or a proper backup
tool like ``borg``:
.. code:: bash
tar -czf backup.tar.gz path/to/data/dir
In addition to the actual data, you should also note down the Fietsboek version
and the database schema version, as backups can only be restored to the same
version!
To view the Fietsboek version in case you are using ``git``, you can use the
following command:
.. code:: bash
git rev-parse HEAD
If you installed Fietsboek via ``pip`` or other means, you can use one of the
following to see the version:
.. code:: bash
.venv/bin/pip show fietsboek
.venv/bin/fietsctl version
To view the data version, use ``fietsupdate``:
.. code:: bash
.venv/bin/fietsupdate status -c development.ini
To view the database schema version, use ``alembic``:
.. code:: bash
.venv/bin/alembic -c development.ini current
Note those values (Fietsboek version, data version, database schema version) in
addition to your backup, as you will need them when restoring data later or
when troubleshooting the restoration process.
Restore
-------
The restoration process works in four steps:
First, we ensure that we are on the correct Fietsboek version. If you are using
``git``, this can be done with ``git checkout`` before installing it:
.. code:: bash
git checkout NOTED_GIT_VERSION_HERE
If you have installed Fietsboek via ``pip``, you can use it to request a
specific version:
.. code:: bash
.venv/bin/pip install "fietsboek==vX.Y.Z"
Next, we run the data migrations:
.. code:: bash
.venv/bin/fietsupdate update -c development.ini VERSION_FROM_EARLIER
We can verify that the database has the correct schema version by using the
same command from earlier and comparing its output to the noted value:
.. code:: bash
.venv/bin/alembic -c development.ini current
Now, we can restore the data in the database. This step is dependent on the
DBMS that you, therefore you should consult its documentation.
Finally, we can restore the data directory. This step depends on how you chose
to back up the data directory earlier. In the case of ``tar``, you can simply
extract the archive to the right location.
|
