Ignore:
Timestamp:
Nov 9, 2011, 9:20:26 AM (11 years ago)
Author:
Nicklas Nordborg
Message:

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.

File:
1 edited

Legend:

Unmodified
Added
Removed

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

    r5842 r5856  
    15031503  </sect1>
    15041504
     1505  <sect1 id="installation.migrate">
     1506    <title>Migrating from MySQL to PostgreSQL</title>
     1507   
     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>
     1516   
     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>
     1525         
     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>
     1533
     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>
     1544           
     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>
     1557
     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>
     1564<programlisting>
     1565./migrate.sh export <replaceable>/path/to/migration/dir</replaceable>
     1566</programlisting>
     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>
     1575         
     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>
     1584
     1585        </listitem>
     1586      </varlistentry>
     1587     
     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>
     1596         
     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>
     1614             
     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>
     1620             
     1621            </listitem>
     1622         
     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>
     1630           
     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>
     1638
     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>
     1646         
     1647          </orderedlist>
     1648         
     1649        </listitem>
     1650      </varlistentry>
     1651     
     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>
     1659         
     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>
     1669         
     1670            <listitem>
     1671              <para>
     1672              Read the
     1673              <ulink url="http://www.postgresql.org/docs/9.1/interactive/populate.html">http://www.postgresql.org/docs/9.1/interactive/populate.html</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>
     1680           
     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>
     1687<programlisting>
     1688./migrate.sh import <replaceable>/path/to/migration/dir</replaceable>
     1689</programlisting>
     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>
     1696             
     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>
     1708             
     1709            </listitem>
     1710           
     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>
     1718
     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>
     1730       
     1731        </listitem>
     1732      </varlistentry>
     1733    </variablelist>
     1734   
     1735  </sect1>
     1736
    15051737</chapter>
Note: See TracChangeset for help on using the changeset viewer.