Changeset d86ea4b


Ignore:
Timestamp:
12/05/2021 07:58:00 PM (7 weeks ago)
Author:
Bruce Dubbs <bdubbs@…>
Branches:
lazarus, trunk, upgradedb
Children:
a38fe9f, b3ba4f9
Parents:
8986fa9
Message:

Editorial changes to section about ubrading DBMS

Files:
2 edited

Legend:

Unmodified
Added
Removed
  • server/databases/upgradedb.xml

    r8986fa9 rd86ea4b  
    1515  <title>Important notes about upgrading Database Server Software</title>
    1616
    17     <para>Lets start this chapter a bit dramatic with a screenshot
    18     of an issue that really happened. Don't be scared if you read
    19     this the first time, this issue will not occur if you are going
    20     to install the software the first time:</para>
     17    <note><para>This section is about reinstalling database software
     18    when an existing database is in use.  It is not applicable for
     19    initial installations or if there is no existing database for
     20    the package being updated.</para></note>
     21
     22    <para>Lets start this chapter with a dramatic screenshot of an issue that
     23    really happened.  This issue will not occur if you are going to install the
     24    software the first time:</para>
    2125
    2226<screen>$ sudo systemctl status postgresql
     
    2832
    2933Oct 26 17:11:53 SVRNAME systemd[1]: Starting PostgreSQL database server...
    30 Oct 26 17:11:53 SRVNAME postgres[17338]: 2021-10-26 17:11:53.420 CDT [17338] FATAL:  database files are incompatible with server
    31 Oct 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.
     34Oct 26 17:11:53 SRVNAME postgres[17338]: 2021-10-26 17:11:53.420 CDT [17338] FATAL: 
     35                database files are incompatible with server
     36Oct 26 17:11:53 SRVNAME postgres[17338]: 2021-10-26 17:11:53.420 CDT [17338] DETAIL: 
     37                The data directory was initialized by PostgreSQL version 13,
     38                which is not compatible with this version 14.0.
    3239Oct 26 17:11:53 SRVNAME postgres[17336]: pg_ctl: could not start server
    3340Oct 26 17:11:53 SRVNAME postgres[17336]: Examine the log output.
     
    3744
    3845  <para>
    39     If you like to avoid those situations like the one above finding
    40     your database server software refusing to start, it is highly
    41     recommended to read the following thoughts about how to upgrade
    42     a DBMS (Database Management System) prior to actually doing the
     46    To avoid situations like the one above finding your database server
     47    software refusing to start, read the following thoughts about how to
     48    upgrade a DBMS (Database Management System) prior to actually doing the
    4349    upgrade.
    4450  </para>
     51
    4552  <para>
    4653    The root cause of the issue shown above was an upgrade
    47     of the server software to a newer major version but letting the
    48     data files untouched. The admin was able to recover without any
     54    of the server software to a newer major version but leaving the
     55    data files untouched. The administrator was able to recover without any
    4956    loss of data.
    5057  </para>
     58
    5159  <para>
    52     Even if you are installing a DBMS the initial time, read this
    53     section too, it might give you a guideline on how to set up backup
     60    Even if you are doing an install DBMS install, read through this
     61    section. Tt will provide you information about how to set up backup
    5462    and restore procedures (at least the strategy for building
    5563    them) which are sufficient for your needs and for the safety
     
    6169
    6270    <para>
    63       Usually, DB systems work on a bunch of files which holds
    64       the database metadata and the data itself. Those files
    65       are highly optimized in their internal structures for use
    66       by the server software. When upgrading such a server software,
    67       it can happen that the server software expects a slightly
    68       different file format than it has been created by previous
    69       versions. In the best case, the new software can act on the
    70       old format as well - while not benefitting from newer formats
    71       which might result in better performance or of other improvements.
    72       It can also happen that the new server software will reformat
    73       the data files automatically at the first start.
    74     </para>
    75 
    76     <para>
    77       Unfortunatly, the most likly case is that the new server
    78       software complains about invalid data file formats and exits.
    79       When this happens and you have overwritten the installed server
    80       software with the new one, you are kind of lost as you lsot the
    81       software which can read the data files and the new software is
    82       unwilling to do so.
    83     </para>
    84 
    85     <para>
    86        Changes in data file formats come usually beside major
    87        version changes. But there is no guaranty. Before upgrading
    88        the server software, check the documentation if there are
    89        changes which will require a data file reformat.
    90     </para>
    91 
    92     <para>
    93       Of course, if you have databases with content which is not
    94       easily to rebuild, it is always a good idea of creating backups
    95       of the database from time to time. When going to upgrade the
    96       server software, the time is quite good to run another backup.
     71      Database systems work on files which hold the database metadata and the
     72      data itself. Those files are highly optimized in their internal
     73      structures for use by the server software. When upgrading such server
     74      software, newer server software may expect a different file format than
     75      was created by previous versions. In the best case, the new software can
     76      act on the old format as well&mdash;but not benefitting from newer
     77      formats which might result in better performance or of other
     78      improvements.  It can also happen that the new server software will
     79      reformat the data files automatically when starting.
     80    </para>
     81
     82    <para>
     83      Unfortunatly, the most likly case is that the new server software
     84      complains about out of date file formats and exits.  When this happens
     85      and you have overwritten the installed server software, you may not be
     86      able to read the data files and the new software is unwilling to do so.
     87    </para>
     88
     89    <para>
     90       Changes in data file formats usually happen at major version changes but
     91       potentially can come at other times.  Before upgrading the server
     92       software, check the documentation if there are changes which will
     93       require reformatting the database.
     94    </para>
     95
     96    <para>
     97      Of course, if you have databases with content which is not easy to
     98      rebuild, it is always a good idea to create backups of the database from
     99      time to time. When upgrading the server software, it is time to run
     100      another backup.
    97101    </para>
    98102
     
    107111          should also verify that the process you designed to fullfill
    108112          the restore task is working properly. When you encounter a
    109           problem with the restore at the time you urgently have to
    110           rely on the backup data, it is too late - your database are
    111           in high danger at this moment.
     113          problem with the restore when you urgently have to
     114          rely on the backup data, it is too late&mdash;your database is
     115          in danger.
    112116        </para>
    113117      </note>
    114118
    115119      <para>
    116         In general, most (all?) database server software provides
    117         some basic tools to create backups of your data. Usually,
    118         the backups created with those tools can be read by newer
    119         versions of the software (here the restore tool). The other
    120         way round (older resote tools can work with newer backup data)
    121         is not defined and you should <emphasis>never</emphasis>
    122         blindly assume that it would work. It might do, but usually
    123         it doesn't.
    124       </para>
    125 
    126       <para>
    127         The most easiest way to upgrade your database files is to
     120        In general, most (all?) database server software provides some basic
     121        tools to create backups of your data. Usually the backups created with
     122        those tools can be read by newer versions of the software (via a
     123        restore tool). Using older restore tools with newer backup data is not
     124        defined and you should <emphasis>never</emphasis> blindly assume that
     125        it will work. It might, but usually it doesn't.
     126      </para>
     127
     128      <para>
     129        The easiest way to upgrade your database files is to
    128130      </para>
    129131
     
    131133        <listitem>
    132134          <para>Create a full database backup using the old tools.</para>
    133           <para>This step creates an offline copy of the database
    134           files ready to be used for long term archiving, for desaster
    135           recovery or just as a preparation for upgrade. This offline
    136           backups consists of the full one-to-one copy of the current
    137           database files or a backup of the files from a certain time
    138           in history plus all journal data (that is Oracle(R)
    139           terminology, its called "Continuous Archiving" or "write
    140           ahead log (WAL)" in Postgresql) containing information about
    141           changes made to the data content. The later are more quickly
    142           to create if the DB software provides such kind of journal as
    143           you only have to save the changes which are recorded in those
    144           journals from the last backup upto now. The amount of data to
    145           backup is much less than doing a full backup all the time.</para>
    146           <para>In terms of upgrading a DB server software, it is
    147           recommended to perform a full backup (which can be used for
    148           subsequent incremental backups) but if the amount of data is
    149           too big an incremental backup will be sufficient, too. Which
    150           strategy is sufficient for you depends on the amount of data
    151           stored in your DB (is it a few hundret of table rows or is it
    152           hundrets of Terabyte. A full backup of the later one isn't done
    153           quickly (and we assume that the underlaying system of such a DB
    154           might not be a home brewed LFS anyhow).
    155           To close the last gap to fully protect your data, create a backup
    156           of the corresponding old binaries (and/or their sources) and
    157           store it along with the data files to
    158           make sure that there is a fallback solution if it comes to
    159           the situation that newer software might not be able to read
    160           ancient data.</para>
    161         </listitem>
    162         <listitem>
    163           <para>Upgrade the server software</para>
    164           <para>In this step, instructions to build the database
    165           server software are executed just as they are shown in
    166           subsequent sections talking about the DBMs like MariaDB or
    167           Postgresql. This is building the software as
    168           it is been done as usual in the BLFS book.</para>
    169         </listitem>
    170         <listitem>
    171           <para>Restore the database by using the new tools.</para>
    172           <para>To restore the data, the tools of the newly installed
    173           server software is used. During the restore process, the new
    174           tools will create and/or upgrade the data files in the
    175           format the software expects them to be. At this moment it is
    176           assumed that newer software is capable to read old data.</para>
    177         </listitem>
    178       </itemizedlist>
    179 
    180       <para>
    181         Since you have already a backup procedure in place (and you
    182         have tested your restore procedure, don't you?), this way might
    183         be the easiest way to upgrade as you are going to use your wellknown
    184         processes to upgrade just as you allways do - at least in terms
     135         
     136          <para>This step creates an offline copy of the database files ready
     137          to be used for long term archiving, for disaster recovery, or just
     138          preparation for upgrade. This offline backup consists of the full
     139          one-to-one copy of the current database files or a backup of the
     140          files from a certain time in history plus all journal data (that is
     141          Oracle&reg; terminology, it is called "Continuous Archiving" or
     142          "write ahead log (WAL)" in Postgresql) containing information about
     143          changes made to the data content. The later take less time to create
     144          if the DB software provides this type of journaling as you only have
     145          to save the changes after creating the last backup. The amount of
     146          data to backup is much less than doing a full backup every
     147          time.</para>
     148
     149          <para>In terms of upgrading database server software, a full backup
     150          (which can be used for subsequent incremental backups) should be
     151          made, but if the amount of data is too big, an incremental backup will
     152          be sufficient. Which strategy is appropriate for you depends on
     153          the amount of data stored in your database (is it a few hundred table
     154          rows or is it hundreds of terabytes?). A full backup of the later one
     155          isn't done quickly (and we assume that the underlying system of such
     156          a database is probably not on an LFS system).  To close the last gap
     157          to fully protect your data, create a backup of the corresponding old
     158          binaries (and/or their sources) and store it along with the data
     159          files to make sure that there is a fallback solution if
     160          the newer software is not able to read the older data.</para>
     161          </listitem>
     162
     163          <listitem>
     164            <para>Upgrade the server software</para>
     165
     166            <para>In this step, instructions to build the database server
     167            software are executed just as they are shown in subsequent sections
     168            talking about the DBMs like MariaDB or Postgresql. That is, build
     169            the software as usual using BLFS instructions.</para>
     170          </listitem>
     171
     172          <listitem>
     173            <para>Restore the database by using the new tools.</para>
     174
     175            <para>To restore the data, the tools of the newly installed server
     176            software should be used. During the restoration process, the new
     177            tools will create and/or upgrade the data files in the format the
     178            software requires. It is assumed that newer software is capable of
     179            reading old data.</para>
     180          </listitem>
     181          </itemizedlist>
     182
     183      <para>
     184        Since you have already have a backup procedure in place (and you
     185        have tested your restore procedure, right?), this might
     186        be the easiest way to upgrade as you are going to use your well known
     187        processes to upgrade just as you allways do&mdash;at least in terms
    185188        of the backup and restore.
    186189      </para>
     
    189192
    190193    <sect3>
    191       <title>Upgrade data file by using system tools</title>
    192 
    193       <para>
    194         Some database systems (for instance Postgresql) provides
    195         a tool which can reformat (=upgrade) the existing database
     194      <title>Upgrade the database files by using system tools</title>
     195
     196      <para>
     197        Some database systems (for instance Postgresql) provide
     198        a tool which can reformat (upgrade) the existing database
    196199        files to the new format. Since the upgrading tool has to
    197200        be used from the new server software (the old one cannot
     
    201204
    202205      <para>
    203         In case you have to restore a backup (may be because running
     206        In case you have to restore a backup (for example, running
    204207        the upgrade tool failed) you have to reinstall the old version
    205208        to get back the access to your data.
     
    207210
    208211      <para>
    209         Even though those tools might work one the actual database
    210         files, it is still highly recommended to create a full backup
    211         before running them. Any case of failure might result in a
    212         serious damage of the database files.
     212        Even though those tools might work with one of the actual database
     213        files, you should create a full backup before running them. A failure
     214        might result in a serious damage of the database files.
    213215      </para>
    214216
     
    225227      <!-- might add some advanced notes for the DBMS here -->
    226228
    227       <para>Upstream documentation for Backup &amp; Restore:
     229      <para>Upstream documentation for Backup/Restore:
    228230        <ulink url="https://www.postgresql.org/docs/current/backup.html"/>
    229231      </para>
     
    236238      <!-- might add some advanced notes for the DBMS here -->
    237239
    238       <para>Upstream documentation for Backup &amp; Restore:
     240      <para>Upstream documentation for Backup/Restore:
    239241        <ulink url="https://mariadb.com/kb/en/backup-and-restore-overview/"/>
    240242      </para>
     
    247249      <!-- might add some advanced notes for the DBMS here -->
    248250
    249       <para>Don't underestimate <application>Sqlite</application>, it
    250       is a feature rich DBMS. The main difference to the two big
    251       players above is that Sqlite does not provide access via a
    252       network API. Sqlite databases are files always stored on the
    253       same machine as the running program which reads/writes the
    254       database. The manipulation of data content is done via API calls
     251      <para>Do not underestimate <application>Sqlite</application>. It is a
     252      feature rich DBMS. The main difference from the two big players above is
     253      that Sqlite does not provide access via a network API. Sqlite databases
     254      are files always stored on the same machine as the running program which
     255      uses the database. The manipulation of data content is done via API calls
    255256      to library functions directly within the program.</para>
    256257
    257       <para>In the upstream documentation you may find the
    258       following useful:</para>
     258      <para>In the upstream documentation you may find the following
     259      useful:</para>
    259260
    260261      <para>Documentation of the sqlite3 command line tool:
    261262        <ulink url="https://www.sqlite.org/cli.html"/>
    262263      </para>
     264
    263265      <para>Documentation of backup API calls:
    264266        <ulink url="https://www.sqlite.org/backup.html"/>
     
    266268
    267269      <para>Unfortunatly, there is no dedicated chapter in the
    268       upstream documentation talking about backup &amp; restore but
    269       there are several articles about it somewhere else in the
     270      upstream documentation talking about backup/restore but
     271      there are several articles about it on the
    270272      Internet. One example is shown below.</para>
    271273
    272       <para>Documentation for Backup &amp; Restore:
     274      <para>Documentation for Backup/Restore:
    273275        <ulink url="https://database.guide/backup-sqlite-database/"/>
    274276      </para>
     
    283285      <para>Just like <application>Sqlite</application> this
    284286      software acts on local database files meaning there is no
    285       network interface, too.</para>
    286 
    287       <para>The relevant resources for Backup &amp; Restore a Berkeley DB
     287      network interface.</para>
     288
     289      <para>The relevant resources for Backup/Restore a Berkeley database
    288290      are the man pages for <filename>db_dump</filename> and its
    289291      counterpart <filename>db_load</filename>.</para>
  • x/installing/libvdpau.xml

    r8986fa9 rd86ea4b  
    3636        VDPAU (Video Decode and Presentation API for Unix) is an open source
    3737        library (libvdpau) and API originally designed by Nvidia for its GeForce
    38         8 series and later GPU hardware targeted at the X Window System
     38        8 series and later GPU hardware targeted at the X Window System.
    3939        This VDPAU API allows video programs to offload portions of the video
    4040        decoding process and video post-processing to the GPU video-hardware.
Note: See TracChangeset for help on using the changeset viewer.