Context Navigation

-              r736a977
+              rfe9a4337
   </sect1info>
   <title>Important notes about upgrading Database Server Software</title>
+  <title>Important Notes About Upgrading Database Server Software</title>
     <note><para>This section is about reinstalling database software
 …
     to become aware of issues that can arise in the future.</para></note>
     <para>Lets start this chapter with a dramatic screenshot of an issue that
     really happened.  This issue will not occur if you are going to install the
     software the first time:</para>
+    <para>Let's start this chapter with a dramatic screenshot of an error that
+    really happened.  This error will not occur if you are installing database
+    software for the first time:</para>
 <screen>$ sudo systemctl status postgresql
 …
   <para>
+    To avoid situations like the one above finding your database server
+    software refusing to start, read the following thoughts about how to
+    upgrade a DBMS (Database Management System) prior to actually doing the
+    upgrade.
+    To avoid situations like this (i.e., your database server
+    software refuses to start), read the following discussion of the best way to
+    upgrade a DBMS (Database Management System).
   </para>
   <para>
     The root cause of the issue shown above was an upgrade
     of the server software to a newer major version but leaving the
     data files untouched. The administrator was able to recover without any
     loss of data.
+    The root cause of the error shown above was an upgrade
+    of the server software to a newer major version which left the
+    data files untouched. In this case, the administrator was able to recover
+    the DBMS without any loss of data.
   </para>
   <para>
     Even if you are doing an install DBMS install, read through this
     section. Tt will provide you information about how to set up backup
     and restore procedures (at least the strategy for building
     them) which are sufficient for your needs and for the safety
+    Even if you are doing an initiall DBMS install, read through this
+    section. It provides information about implementing backup
+    and restore procedures (or at least a strategy for creating
+    them) which will satisfy your needs and guarantee the safety
     of your data.
   </para>
   <sect2>
     <title>Upgrade database server packages</title>
+    <title>Upgrade Database Server Packages</title>
     <para>
       Database systems work on files which hold the database metadata and the
       data itself. Those files are highly optimized in their internal
       structures for use by the server software. When upgrading such server
       software, newer server software may expect a different file format than
       was created by previous versions. In the best case, the new software can
       act on the old format as well&mdash;but not benefitting from newer
       formats which might result in better performance or of other
       improvements.  It can also happen that the new server software will
       reformat the data files automatically when starting.
+      data itself. The internal structure of these files is optimized for use
+      by the server software. When such server software is upgraded,
+      the new software may utilize a different file format than
+      had previously been used. Sometimes the new software can
+      work with the old format as well as the new one&mdash;but wiithout the
+      performance improvements the new format provides.
+      Other times, the new server software will
+      reformat the data files automatically after the upgrade.
     </para>
     <para>
       Unfortunately, the most likely case is that the new server software
       complains about out of date file formats and exits.  When this happens
       and you have overwritten the installed server software, you may not be
       able to read the data files and the new software is unwilling to do so.
     </para>
     <para>
        Changes in data file formats usually happen at major version changes but
        potentially can come at other times.  Before upgrading the server
        software, check the documentation if there are changes which will
+      complains about out of date file formats and exits.  When this happens,
+      and you have overwritten the old server software, you may end up
+      with a broken system and lost data.
+    </para>
+    <para>
+       Changes in data file formats usually happen at major version changes, but
+       they can also occur at other times.  Before upgrading any DBMS
+       software, check the documentation to see if this upgrade makes changes which
        require reformatting the database.
     </para>
     <para>
       Of course, if you have databases with content which is not easy to
       rebuild, it is always a good idea to create backups of the database from
       time to time. When upgrading the server software, it is time to run
+      Of course, if you have databases with content that is not easily
+      rebuilt, it is always a good idea to create backups of the database from
+      time to time. Before upgrading the server software, you should run
       another backup.
     </para>
     <sect3>
       <title>Upgrade by backup and restore</title>
+      <title>Upgrade by Backup and Restore</title>
       <note>
         <para>
           A backup is meaningless if there is no verified process
+          A backup is useless if there is no verified process
           to restore the data from this backup. When running a
+          database server, you should not only create backups but you
+          should also verify that the process you designed to fulfill
+          the restore task is working properly. When you encounter a
+          problem with the restore when you urgently have to
+          rely on the backup data, it is too late&mdash;your database is
+          in danger.
+          database server, you should not only create backups; you
+          should also verify that the restore process
+          really works. The time to test the restore procedure
+          is <emphasis>before</emphasis> you urgently need
+          to recover lost data.
         </para>
       </note>
       <para>
         In general, most (all?) database server software provides some basic
+        Most database server software provides some basic
         tools to create backups of your data. Usually the backups created with
         those tools can be read by newer versions of the software (via a
         restore tool). Using older restore tools with newer backup data is not
         defined and you should <emphasis>never</emphasis> blindly assume that
+        restore tool). Using older restore tools with newer backup data is
+        a bad idea; you should <emphasis>never</emphasis> blindly assume that
         it will work. It might, but usually it doesn't.
       </para>
 …
           <para>Create a full database backup using the old tools.</para>
           <para>This step creates an offline copy of the database files ready
           to be used for long term archiving, for disaster recovery, or just
           preparation for upgrade. This offline backup consists of the full
           one-to-one copy of the current database files or a backup of the
           files from a certain time in history plus all journal data (that is
+          <para>This step creates an offline copy of the database files&mdash;for
+          long term archiving, for disaster recovery, or as
+          preparation for an upgrade. This offline backup consists of either (1) a full
+          one-to-one copy of the current database files, or (2) a full backup of the
+          database files from a certain point in time, plus all the journal data (that is
           Oracle&reg; terminology, it is called "Continuous Archiving" or
+          "write ahead log (WAL)" in Postgresql) containing information about
+          changes made to the data content. The later take less time to create
+          if the DB software provides this type of journaling as you only have
+          to save the changes after creating the last backup. The amount of
+          data to backup is much less than doing a full backup every
+          time.</para>
+          <para>In terms of upgrading database server software, a full backup
+          "write ahead log (WAL)" in Postgresql) describing the
+          changes made after that point in time. This second form takes less time to create
+          (if the DB software provides this type of journaling) because you only have
+          to save the data that have changed since the last full backup was created.</para>
+          <para>When upgrading database server software, a full backup
           (which can be used for subsequent incremental backups) should be
           made, but if the amount of data is too big, an incremental backup will
           be sufficient. Which strategy is appropriate for you depends on
+          created; but if there is a lot of data, an incremental backup will
+          suffice. The best strategy for you depends on
           the amount of data stored in your database (is it a few hundred table
+          rows or is it hundreds of terabytes?). A full backup of the later one
+          isn't done quickly (and we assume that the underlying system of such
+          a database is probably not on an LFS system).  To close the last gap
+          to fully protect your data, create a backup of the corresponding old
+          binaries (and/or their sources) and store it along with the data
+          files to make sure that there is a fallback solution if
+          the newer software is not able to read the older data.</para>
+          rows, or is it hundreds of terabytes?). A full backup in the latter case
+          can't be done quickly.  To
+          fully protect your data, create a backup of the old
+          programs (and/or their sources) and save it, along with the data
+          files, to be certain there is a fallback solution if
+          the new software cannot read the old data.</para>
           </listitem>
 …
             software should be used. During the restoration process, the new
             tools will create and/or upgrade the data files in the format the
             software requires. It is assumed that newer software is capable of
+            new software requires. It is assumed that newer software is capable of
             reading old data.</para>
           </listitem>
 …
       <para>
         Since you have already have a backup procedure in place (and you
+        Since you already have a backup procedure in place (and you
         have tested your restore procedure, right?), this might
         be the easiest way to upgrade as you are going to use your well known
+        be the easiest way to upgrade as you can use your well known
         processes to upgrade just as you always do&mdash;at least in terms
         of the backup and restore.
 …
     <sect3>
       <title>Upgrade the database files by using system tools</title>
+      <title>Upgrade the Database Files by Using System Tools</title>
       <para>
         Some database systems (for instance Postgresql) provide
         a tool which can reformat (upgrade) the existing database
+        files to the new format. Since the upgrading tool has to
+        be used from the new server software (the old one cannot
+        know anything about a new file format), the old software
+        might be overwritten due to installation of the new software.
+      </para>
+      <para>
+        In case you have to restore a backup (for example, running
+        the upgrade tool failed) you have to reinstall the old version
+        to get back the access to your data.
+      </para>
+      <para>
+        Even though those tools might work with one of the actual database
+        files, you should create a full backup before running them. A failure
+        might result in a serious damage of the database files.
+        files to the new format.
+        If you need to restore from a backup (for example, running
+        the upgrade tool failed) you will have to reinstall the old software
+        to recover your data.
+      </para>
+      <para>
+        Even though the reformatting tools might work as advertised,
+        you should create a full backup before running them. A failure
+        could cause serious damage to the database.
       </para>
 …
   <sect2>
     <title>Notes for specific DBMS</title>
+    <title>Notes for Specific DBMS</title>
     <sect3>
 …
       <para>Do not underestimate <application>Sqlite</application>. It is a
       feature rich DBMS. The main difference from the two big players above is
+      feature-rich DBMS. The main difference from the two big players above is
       that Sqlite does not provide access via a network API. Sqlite databases
       are files always stored on the same machine as the running program which
+      are always stored on the machine running the program which
       uses the database. The manipulation of data content is done via API calls
       to library functions directly within the program.</para>
 …
       <para>Unfortunately, there is no dedicated chapter in the
       upstream documentation talking about backup/restore but
+      upstream documentation talking about backup/restore, but
       there are several articles about it on the
       Internet. One example is shown below.</para>
+      Internet. Here is an example.</para>
       <para>Documentation for Backup/Restore:
 …
       <!-- might add some advanced notes for the DBMS here -->
       <para>Just like <application>Sqlite</application> this
       software acts on local database files meaning there is no
+      <para>Like <application>Sqlite</application>, this
+      software acts on local database files; there is no
       network interface.</para>
       <para>The relevant resources for Backup/Restore a Berkeley database
+      <para>The relevant resources to back up/restore a Berkeley database
       are the man pages for <filename>db_dump</filename> and its
       counterpart <filename>db_load</filename>.</para>

Note: See TracChangeset for help on using the changeset viewer.

Context Navigation

Changeset fe9a4337

Legend:

server/databases/upgradedb.xml

Download in other formats: