source: server/databases/upgradedb.xml@ bcdfc53

11.1 lazarus trunk upgradedb xry111/intltool xry111/test-20220226
Last change on this file since bcdfc53 was bcdfc53, checked in by Thomas Trepl (Moody) <thomas@…>, 6 months ago

Add some notes about upgrading DBMS

  • Property mode set to 100644
File size: 9.5 KB
1<?xml version="1.0" encoding="ISO-8859-1"?>
2<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3 "" [
4 <!ENTITY % general-entities SYSTEM "../../general.ent">
5 %general-entities;
8<sect1 id="upgradedb" xreflabel="Upgrade Database">
9 <?dbhtml filename="upgradedb.html"?>
11 <sect1info>
12 <date>$Date$</date>
13 </sect1info>
15 <title>Notes on Database Server Software</title>
17<screen>$ sudo systemctl status postgresql
18-- postgresql.service - PostgreSQL database server
19 Loaded: loaded (/usr/lib/systemd/system/postgresql.service; enabled; vendor preset: enabled)
20 Active: failed (Result: exit-code) since Tue 2021-10-26 17:11:53 CDT; 2min 49s ago
21 Process: 17336 ExecStart=/usr/bin/pg_ctl -s -D ${PGROOT}/data start -w -t 120 (code=exited, status=1/FAILURE)
22 CPU: 7ms
24Oct 26 17:11:53 SVRNAME systemd[1]: Starting PostgreSQL database server...
25Oct 26 17:11:53 SRVNAME postgres[17338]: 2021-10-26 17:11:53.420 CDT [17338] FATAL: database files are incompatible with server
26Oct 26 17:11:53 SRVNAME postgres[17338]: 2021-10-26 17:11:53.420 CDT [17338] DETAIL: The data directory was initialized by PostgreSQL version 13, which is not compatible with this version 14.0.
27Oct 26 17:11:53 SRVNAME postgres[17336]: pg_ctl: could not start server
28Oct 26 17:11:53 SRVNAME postgres[17336]: Examine the log output.
29Oct 26 17:11:53 SRVNAME systemd[1]: postgresql.service: Control process exited, code=exited, status=1/FAILURE
30Oct 26 17:11:53 SRVNAME systemd[1]: postgresql.service: Failed with result 'exit-code'.
31Oct 26 17:11:53 SRVNAME systemd[1]: Failed to start PostgreSQL database server.</screen>
33 <para>
34 If you like to avoid those situations like the one above finding
35 your database server software refusing to start, it is highly
36 recommended to read the following thoughts about how to upgrade
37 a DBMS (Database Management System) prior to actually doing the
38 upgrade.
39 </para>
40 <para>
41 Even if you are installing a DBMS the initial time, read it
42 anyway, it might give you a guideline on how to set up backup
43 and restore procedures (at least the strategy for building
44 them) which are sufficient for your needs and for the safety
45 of your data.
46 </para>
48 <sect2>
49 <title>Upgrade database server packages</title>
51 <para>
52 Usually, DB systems work on a bunch of files which holds
53 the database metadata and the data itself. Those files
54 are highly optimized in their internal structures for use
55 by the server software. When upgrading such a server software,
56 it can happen that the server software expects a slightly
57 different file format than it has been created by previous
58 versions. In the best case, the new software can act on the
59 old format as well - while not benefitting from newer formats
60 which might result in better performance or of other improvements.
61 It can also happen that the new server software will reformat
62 the data files automatically at the first start.
63 </para>
65 <para>
66 Unfortunatly, the most likly case is that the new server
67 software complains about invalid data file formats and exits.
68 When this happens and you have overwritten the installed server
69 software with the new one, you are kind of lost as you lsot the
70 software which can read the data files and the new software is
71 unwilling to do so.
72 </para>
74 <para>
75 Changes in data file formats come usually beside major
76 version changes. But there is no guaranty. Before upgrading
77 the server software, check the documentation if there are
78 changes which will require a data file reformat.
79 </para>
81 <para>
82 Of course, if you have databases with content which is not
83 easily to rebuild, it is always a good idea of creating backups
84 of the database from time to time. When going to upgrade the
85 server software, the time is quite good to run another backup.
86 </para>
88 <sect3>
89 <title>Upgrade by backup and restore</title>
91 <note>
92 <para>
93 A backup is meaningless if there is no verified process
94 to restore the data from this backup. When running a
95 database server, you should not only create backups but you
96 should also verify that the process you designed to fullfill
97 the restore task is working properly. When you encounter a
98 problem with the restore at the time you urgently have to
99 rely on the backup data, it is too late - your database are
100 in high danger at this moment.
101 </para>
102 </note>
104 <para>
105 In general, most (all?) database server software provides
106 some basic tools to create backups of your data. Usually,
107 the backups created with those tools can be read by newer
108 versions of the software (here the restore tool). The other
109 way round (older resote tools can work with newer backup data)
110 is not defined and you should <emphasis>never</emphasis>
111 blindly assume that it would work. It might do, but usually
112 it doesn't.
113 </para>
115 <para>
116 The most easiest way to upgrade your database files is to
117 </para>
119 <itemizedlist>
120 <listitem>
121 <para>Create a full database backup using the old tools.</para>
122 <para>This step creates an offline copy of the database
123 files ready to be used for long term archiving, for desaster
124 recovery or just as a preparation for upgrade. This offline
125 backups consists of the full one-to-one copy of the current
126 database files or a backup of the files from a certain time
127 in history plus all journal data (that is Oracle(R)
128 terminology, its called "Continuous Archiving" or "write
129 ahead log (WAL)" in Postgresql) containing information about
130 changes made to the data content. The later are more quickly
131 to create if the DB software provides such kind of journal as
132 you only have to save the changes which are recorded in those
133 journals from the last backup upto now. The amount of data to
134 backup is much less than doing a full backup all the time.</para>
135 <para>In terms of upgrading a DB server software, it is
136 recommended to perform a full backup (which can be used for
137 subsequent incremental backups) but if the amount of data is
138 too big an incremental backup will be sufficient, too. Which
139 strategy is sufficient for you depends on the amount of data
140 stored in your DB (is it a few hundret of table rows or is it
141 hundrets of Terabyte. A full backup of the later one isn't done
142 quickly (and we assume that the underlaying system of such a DB
143 might not be a home brewed LFS anyhow).</para>
144 </listitem>
145 <listitem>
146 <para>Upgrade the server software</para>
147 <para>In this step, instructions to build the database
148 server software are executed just as they are shown in
149 subsequent sections talking about the DBMs like MariaDB or
150 Postgresql. This is building the software as
151 it is been done as usual in the BLFS book.</para>
152 </listitem>
153 <listitem>
154 <para>Restore the database by using the new tools.</para>
155 <para>To restore the data, the tools of the newly installed
156 server software is used. During the restore process, the new
157 tools will create and/or upgrade the data files in the
158 format the software expects them to be.</para>
159 </listitem>
160 </itemizedlist>
162 <para>
163 Since you have already a backup procedure in place (and you
164 have tested your restore procedure, don't you?), this way might
165 be the easiest way to upgrade as you are going to use well-known
166 processes to upgrade just as you allways do - at least in terms
167 of the backup and restore.
168 </para>
170 </sect3>
172 <sect3>
173 <title>Upgrade by system tools</title>
175 <para>
176 Some database systems (for instance Postgresql) provides
177 a tool which can reformat (=upgrade) the existing database
178 files to the new format. Since the upgrading tool has to
179 be used from the new server software (the old one cannot
180 know anything about a new file format), the old software
181 might be overwritten due to installation of the new software.
182 </para>
184 <para>
185 In case you have to restore a backup (may be because running
186 the upgrade tool failed) you have to reinstall the old version
187 to get back the access to your data.
188 </para>
190 <para>
191 Even though those tools might work one the actual database
192 files, it is still highly recommended to create a full backup
193 before running them. Any case of failure might result in a
194 serious damage of the database files.
195 </para>
197 </sect3>
199 </sect2>
201 <sect2>
202 <title>Notes for specific DBMS</title>
204 <sect3>
205 <title>PostgreSQL</title>
207 <!-- might add some advanced notes for the DBMS here -->
209 <para>Upstream documentation for Backup &amp; Restore:
210 <ulink url=""/>
211 </para>
213 </sect3>
215 <sect3>
216 <title>MariaDB</title>
218 <!-- might add some advanced notes for the DBMS here -->
220 <para>Upstream documentation for Backup &amp; Restore:
221 <ulink url=""/>
222 </para>
224 </sect3>
226 </sect2>
Note: See TracBrowser for help on using the repository browser.