Changeset 2bda7ac4

Timestamp:

12/12/2021 07:06:40 AM (2 years ago)

Author:

Thomas Trepl (Moody) <thomas@…>

Branches:

11.1, 11.2, 11.3, 12.0, 12.1, kea, ken/TL2024, ken/inkscape-core-mods, ken/tuningfonts, lazarus, lxqt, plabs/newcss, plabs/python-mods, python3.11, qt5new, rahul/power-profiles-daemon, renodr/vulkan-addition, trunk, xry111/intltool, xry111/llvm18, xry111/soup3, xry111/test-20220226, xry111/xf86-video-removal

Children:

11d9a3f

Parents:

36a0ff4 (diff), e99a437 (diff)
Note: this is a merge changeset, the changes displayed below correspond to the merge itself.
Use the (diff) links above to see all the changes relative to each parent.

Message:

Add some notes about how to upgrade existing DBMS to avoid failures with incompatible file formats.

Location:

server/databases

Files:

• databases.xml (modified) (1 diff)
• postgresql.xml (modified) (3 diffs)
• upgradedb.xml (added)

server/databases/databases.xml

@@ -19 +19 @@
   </para>
 
+  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="upgradedb.xml"/>
+
   <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="db.xml"/>
   <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="lmdb.xml"/>

server/databases/postgresql.xml

@@ -105 +105 @@
     <title>Installation of PostgreSQL</title>
 
+    <para>
+      For enhanced security, it is better to have a dedicated group and user
+      for running the PostgreSQL server. First, issue as the
+      <systemitem class="username">root</systemitem> user:
+    </para>
+
+<screen role="root"><userinput>groupadd -g 41 postgres &amp;&amp;
+useradd -c "PostgreSQL Server" -g postgres -d /srv/pgsql/data \
+        -u 41 postgres</userinput></screen>
+
     <note>
+      <para>
+        There are several configuration items that add additional
+        functionality with optional packages to
+        <application>PostgreSQL</application>.  Use <command>./configure
+        --help</command> to see a list.
+      </para>
+    </note>
+
+    <para>
+      Install <application>PostgreSQL</application> with the
+      following commands:
+    </para>
+
+<screen><userinput>sed -i '/DEFAULT_PGSOCKET_DIR/s@/tmp@/run/postgresql@' src/include/pg_config_manual.h &amp;&amp;
+
+./configure --prefix=/usr          \
+            --enable-thread-safety \
+            --docdir=/usr/share/doc/postgresql-&postgresql-version; &amp;&amp;
+make</userinput></screen>
+
+    <para>
+      There are a number of programs in the
+      <filename class="directory">contrib/</filename> directory. If you are
+      going to run this installation as a server and wish to build some of
+      them, enter <command>make -C contrib</command> or <command>make -C
+      contrib/<replaceable>&lt;SUBDIR-NAME&gt;</replaceable></command> for
+      each subdirectory.
+    </para>
+
+    <para>
+      Tests must be run as an unprivileged user because they need to start a
+      temporary server and this is prevented as the root user. For the same
+      reason, you need to stop all PostgreSQL servers if any are running. If a
+      previous version of PostgreSQL is installed, it may be necessary to use
+      <command>--disable-rpath</command> with <command>configure</command> to
+      avoid failures, but <emphasis>installing the binaries created using this
+      switch is not recommended</emphasis>. To test the results, issue:
+      <command>make check</command>.
+    </para>
+
+    <note>
+      <para>Hold off from continuing in case you are building 
+      <application>PostgreSQL</application> to upgrade an existing
+      installation. In case the major version of the new build is 
+      different to the existing one, its quite likely that the
+      new software cannot act on the existing data files. In this case,
+      the server will not start and the old binaries has been overwritten
+      so you got stuck with an unusable database.</para>
+
       <para>
         Before upgrading an existing installation of PostgreSQL check
@@ -114 +173 @@
         <ulink url="https://www.postgresql.org/docs/current/upgrading.html"/>.
       </para>
+
+      <para>At this moment, you have both, the old and the new binaries
+      on disk. They can be used to perform an upgrade of your existing
+      database right now. For the folloging instructions it is
+      assumed that
+      <itemizedlist>
+        <listitem><para>The actual data files are stored in
+          <filename class="directory">/srv/pgsql/data</filename></para>
+        </listitem>
+        <listitem><para>The upgraded data files will be stored in
+          <filename class="directory">/srv/pgsql/newdata</filename></para>
+        </listitem>
+        <listitem><para>There is enough disk space to hold the actual
+          data files twice. The upgrade is not an inline upgrade but
+          it will copy the data to new database files.</para>
+        </listitem>
+      </itemizedlist>
+      </para>
+
+      <para>Do a temporary install which makes access to the new
+      binaries a bit easier:</para>
+      <screen><userinput>make DESTDIR=$(pwd)/DESTDIR install</userinput></screen>
+
+      <para>Create a directory which is writable by the
+      <systemitem class="username">postgres</systemitem> as the
+      <systemitem class="username">root</systemitem> user:</para>
+      
+      <screen><userinput role="root">install -D -o postgres $(pwd)/DESTDIR/tmp</userinput></screen>
+      
+      <para>Now, stop the existing instance of <application>PostgreSQL</application>
+      and start the upgrade process as the
+      <systemitem class="username">root</systemitem> user:</para>
+      
+      <screen><userinput role="root">pushd $(pwd)/DESTDIR/tmp
+/etc/rc.d/init.d/postgresql stop
+su postgres -c "../usr/bin/initdb -D /srv/pgsql/newdata"
+su postgres -c "../usr/bin/pg_upgrade \
+                    -d /srv/pgsql/data    -b /usr/bin \
+                    -D /srv/pgsql/newdata -B ../usr/bin"
+popd</userinput></screen>
+      
+      <para>At this stage, you have your database files two times on
+      disk, one is the old data in <filename class="directory">/srv/pgsql/data</filename>
+      and the new ones in <filename class="directory">/srv/pgsql/newdata</filename>.
+      May this is the time you do a last backup of the old database files.</para>
+      
+      <para>Remove the old database files, and rename the new data 
+      directory as the <systemitem class="username">root</systemitem> user:</para>
+      
+      <screen><userinput role="root">rm -rf /srv/pgsql/data
+mv /srv/pgsql/newdata /srv/pgsql/data</userinput></screen>
+
     </note>
-
-    <para>
-      For enhanced security, it is better to have a dedicated group and user
-      for running the PostgreSQL server. First, issue as the
-      <systemitem class="username">root</systemitem> user:
-    </para>
-
-<screen role="root"><userinput>groupadd -g 41 postgres &amp;&amp;
-useradd -c "PostgreSQL Server" -g postgres -d /srv/pgsql/data \
-        -u 41 postgres</userinput></screen>
-
-    <note>
-      <para>
-        There are several configuration items that add additional
-        functionality with optional packages to
-        <application>PostgreSQL</application>.  Use <command>./configure
-        --help</command> to see a list.
-      </para>
-    </note>
-
-    <para>
-      Install <application>PostgreSQL</application> with the
-      following commands:
-    </para>
-
-<screen><userinput>sed -i '/DEFAULT_PGSOCKET_DIR/s@/tmp@/run/postgresql@' src/include/pg_config_manual.h &amp;&amp;
-
-./configure --prefix=/usr          \
-            --enable-thread-safety \
-            --docdir=/usr/share/doc/postgresql-&postgresql-version; &amp;&amp;
-make</userinput></screen>
-
-    <para>
-      There are a number of programs in the
-      <filename class="directory">contrib/</filename> directory. If you are
-      going to run this installation as a server and wish to build some of
-      them, enter <command>make -C contrib</command> or <command>make -C
-      contrib/<replaceable>&lt;SUBDIR-NAME&gt;</replaceable></command> for
-      each subdirectory.
-    </para>
-
-    <para>
-      Tests must be run as an unprivileged user because they need to start a
-      temporary server and this is prevented as the root user. For the same
-      reason, you need to stop all PostgreSQL servers if any are running. If a
-      previous version of PostgreSQL is installed, it may be necessary to use
-      <command>--disable-rpath</command> with <command>configure</command> to
-      avoid failures, but <emphasis>installing the binaries created using this
-      switch is not recommended</emphasis>. To test the results, issue:
-      <command>make check</command>.
-    </para>
-
+    
     <para>
       Now, as the <systemitem class="username">root</systemitem> user:
@@ -188 +248 @@
       </para>
     </tip>
+
+    <para>
+      If you have upgraded an existing database, skip the rest of the
+      commands because your database is ready to use. If this is the
+      first time you install <application>PostgreSQL</application>,
+      continue with the initialization.
+    </para>
 
     <para>