Changeset 5856

Nov 9, 2011, 9:20:26 AM (10 years ago)
Nicklas Nordborg

References #1630: Migrate from MySQL to PostgreSQL

Documented the migration process. This should more or less complete this feature. I'll keep the ticket open until we have made some more tests.

1 edited


  • trunk/doc/src/docbook/admin/installation.xml

    r5842 r5856  
    15031503  </sect1>
     1505  <sect1 id="installation.migrate">
     1506    <title>Migrating from MySQL to PostgreSQL</title>
     1508    <para>
     1509      It is possible to migrate a BASE installation on a MySQL database to a
     1510      PostgreSQL database. In a real-world scenario a migration is probably coupled
     1511      with a hardware upgrade, ie. the MySQL installation is on one (the old) server
     1512      and the PostgreSQL installation is on another (the new) server. While
     1513      this is not any problem per se, it requires a few extra steps to ensure that
     1514      everything has been moved to the new server. There are three main steps involved:
     1515    </para>
     1517    <variablelist>
     1518      <varlistentry>
     1519        <term>Export</term>
     1520        <listitem>
     1521          <para>
     1522          The first step is to export all data in the existing database. Use
     1523          the following procedure:
     1524          </para>
     1526          <orderedlist>
     1527            <listitem>
     1528              <para>
     1529              Upgrade to the latest BASE release. This is recommended since
     1530              it probably has fewer bugs.
     1531              </para>
     1532            </listitem>
     1534            <listitem>
     1535              <para>
     1536              Make sure that no other processes are writing to the database
     1537              when the export is running. Shut down Tomcat and all job agents.
     1538              It may also be a good idea to ensure that no backup scripts or
     1539              other external programs are reading from the database at the same
     1540              time. If the database is large, this may affect performance due to
     1541              increased disk I/O.
     1542              </para>
     1543            </listitem>
     1545            <listitem>
     1546              <para>
     1547              Create a temporary working directory in a suitable
     1548              location. This directory will be used for storing the
     1549              exported data. Disk I/O performance may be better if
     1550              this directory is on a different disk than what the
     1551              database is using. Ensure that the location has enough
     1552              free space to hold all data from the BASE database. The dump
     1553              typically uses less than half of the disk space used by the
     1554              MySQL tables.
     1555              </para>
     1556            </listitem>
     1558            <listitem>           
     1559              <para>
     1560                Start the export by changing to the <filename
     1561                class="directory">&lt;base-dir&gt;/bin/</filename>
     1562                directory and execute:
     1563              </para>
     1565./ export <replaceable>/path/to/migration/dir</replaceable>
     1567              <para>
     1568                where <replaceable>/path/to/migration/dir</replaceable>
     1569                is replaced with the path to the working directory created above.
     1570                Existing files will be overwritten without warning. Depending on
     1571                the size of the BASE installation this may take a long time.
     1572              </para>
     1573            </listitem>
     1574          </orderedlist>
     1576          <warning>
     1577            <para>
     1578            When exporting, make sure that no other process is updating the
     1579            database since that may create an inconsistent snapshot. The
     1580            export process does not lock the database or take any other means
     1581            to protect it against concurrent modifications.
     1582            </para>
     1583          </warning>
     1585        </listitem>
     1586      </varlistentry>
     1588      <varlistentry>
     1589        <term>Moving data</term>
     1590        <listitem>
     1591          <para>
     1592          This step is about moving the data from the old BASE server to the
     1593          new BASE server. If the migration is taking place on a single server,
     1594          this step can probably be skipped.
     1595          </para>
     1597          <orderedlist>
     1598            <listitem>
     1599              <para>
     1600              Download and unpack the BASE software on the new server. Make sure that you are
     1601              using the same version as on the old server. It is also important that
     1602              the database is identically configured. Pay special attention
     1603              to the <filename>extended-properties.xml</filename> and
     1604              <filename>raw-data-types.xml</filename> files and any files
     1605              in the <filename
     1606              class="directory">&lt;base-dir&gt;/WEB-INF/classes/extended-properties</filename>
     1607              and <filename
     1608              class="directory">&lt;base-dir&gt;/WEB-INF/classes/raw-data-types</filename>
     1609              directories.
     1610              The import program protects against some mistakes by comparing
     1611              the colum names from the export with the column names in the new
     1612              database, but it will, for example, not check that data types match.
     1613              </para>
     1615              <tip>
     1616                The easiest way to do this is to simply copy the BASE installation
     1617                from the old server to the new server. Then, go through the
     1618                configuration files and make sure that paths are correct.
     1619              </tip>
     1621            </listitem>
     1623            <listitem>
     1624              <para>
     1625              Move user files from the old server to the new server. Make sure that
     1626              the <property>userfiles</property> setting in <filename>base.config</filename>
     1627              is correct.
     1628              </para>
     1629            </listitem>
     1631            <listitem>
     1632              <para>
     1633              Move plug-ins from the old server to the new server. Make sure that
     1634              the <property>plugins.dir</property> setting in <filename>base.config</filename>
     1635              is correct.
     1636              </para>
     1637            </listitem>
     1639            <listitem>
     1640              <para>
     1641              Check other settings in <filename>base.config</filename> and
     1642              other configuration files for settings that may be affected by
     1643              the move.
     1644              </para>
     1645            </listitem>
     1647          </orderedlist>
     1649        </listitem>
     1650      </varlistentry>
     1652      <varlistentry>
     1653        <term>Import</term>
     1654        <listitem>
     1655          <para>
     1656            When everything has been moved and is properly configured it is
     1657            time to start with the import.
     1658          </para>
     1660          <orderedlist>
     1661            <listitem>
     1662              <para>
     1663              Create a new empty database following the
     1664              instructions in <xref linkend="installation.main.database" />.
     1665              Make the corresponding changes in <filename>base.config</filename>
     1666              so that the BASE installation points to the new database.
     1667              </para>
     1668            </listitem>
     1670            <listitem>
     1671              <para>
     1672              Read the
     1673              <ulink url=""></ulink>
     1674              document from the PostgreSQL documentation and consider implementing some
     1675              of the tips. The migration script makes sure that no indexes or foreign
     1676              key constraints are active during the data import, but the tips about memory,
     1677              checkpoint intervals, WAL archiving, etc. (section 14.4.5 and on) can be useful.
     1678              </para>
     1679            </listitem>
     1681            <listitem>
     1682              <para>
     1683                Start the import by changing to the <filename
     1684                class="directory">&lt;base-dir&gt;/bin/</filename>
     1685                directory and execute:
     1686              </para>
     1688./ import <replaceable>/path/to/migration/dir</replaceable>
     1690              <para>
     1691                where <replaceable>/path/to/migration/dir</replaceable>
     1692                is replaced with the path to the directory where
     1693                the exported data is stored. Depending on
     1694                the size of the BASE installation this may take a long time.
     1695              </para>
     1697              <important>
     1698                <title>Installations with separate web and database servers</title>
     1699                <para>
     1700                The export part may be executed against a remote MySQL server without
     1701                limitation, but the import need to access the migration working directory
     1702                on the given path both from the client-side and from the server-side.
     1703                If the PostgreSQL server is a remote server, ensure that the data
     1704                directory is mounted with the same path on both the client and
     1705                server.
     1706                </para>
     1707              </important>
     1709            </listitem>
     1711            <listitem>
     1712              <para>
     1713              Restart Tomcat and verify that the migration was successful. Eg.
     1714              check that you can log in to BASE, that you can access files,
     1715              that plug-ins are working, etc. Then, shut everything down again.
     1716              </para>
     1717            </listitem>
     1719            <listitem>
     1720              <para>
     1721              Setup backup procedures for the new server. Verify that the
     1722              backup is working before starting up Tomcat again.         
     1723              Restart any job agents (make sure that the are configured to use
     1724              the new server). When everything is up and running again, the
     1725              <replaceable>/path/to/migration/dir</replaceable> directory
     1726              and all files can be deleted.
     1727              </para>
     1728            </listitem>
     1729          </orderedlist>
     1731        </listitem>
     1732      </varlistentry>
     1733    </variablelist>
     1735  </sect1>
Note: See TracChangeset for help on using the changeset viewer.