1. Installation

1. Installation

Percona TokuMX Community edition is available in packages for RHEL/CentOS and Debian and Ubuntu.

For users of other distributions, Tokutek provides a binary version of Percona TokuMX. The Tokutek distribution includes the Percona TokuMX server (mongod), router (mongos), and client (mongo) for your system, as well as miscellaneous tools like those provided with MongoDB.

The installation of Percona TokuMX from a tarball release file is similar to the installation of MongoDB. This process is described nicely in the MongoDB Documentation.

1.1. System and Hardware Requirements

  • Operating Systems: Percona TokuMX is currently supported on 64-bit Linux only. Percona TokuMX is tested on CentOS 5, 6 and 7, but is expected to work on other Linux distributions.
  • A virtual machine image is available for evaluations on Windows and Mac. There are also binaries available for recent versions of Mac OS X for development use only. Please contact us at support@tokutek.com for more information.
  • Memory: Percona TokuMX requires at least 1GB of RAM but for best results, we recommend to run with at least 2GB of RAM.
  • Disk space and configuration: Please make sure to allocate enough disk space for data, indexes and logs. In our users’ experience, Percona TokuMX achieves up to 20x space savings on data and indexes over MongoDB due to high compression.

1.2. Downloading

To download the binary tarball, visit Percona’s Download Page.

After downloading, optionally verify the MD5 checksum by comparing the output of md5sum to the MD5 checksum from the download page:

$ md5sum tokumx-2.0.0-linux-x86_64-main.tar.gz
d2f979f2c6bb0d47bf9d3fd615a4ad53  tokumx-2.0.0-linux-x86_64-main.tar.gz

1.3. Installing the Tarball

For maximum flexibility, we recommend unpacking the tarball to a unique location, and then creating symlinks to the binaries there. In this example, we’ll unpack the tarball in /opt.

  1. Unpack the tarball
Unpack the tarball to /opt:
$ tar xzf tokumx-2.0.0-linux-x86_64-main.tar.gz --directory /opt
  1. Create symlinks
Create symlinks to all the binaries in /usr/local/bin:
$ ln -snf /opt/tokumx-2.0.0-linux-x86_64/bin/* /usr/local/bin
  1. Check your PATH
Ensure that your PATH includes /usr/local/bin to make sure you can run Percona TokuMX. Make sure your shell finds the right binaries.
$ which mongod
/usr/local/bin/mongod
$ readlink /usr/local/bin/mongod
/opt/tokumx-2.0.0-linux-x86_64/bin/mongod

If not, add /usr/local/bin to your PATH and make it persistent in your .bash_profile:

$ export PATH=/usr/local/bin:"$PATH"
$ echo 'export PATH=/usr/local/bin:"$PATH"' >> $HOME/.bash_profile

Note

If you unpack and use symlinks this way, the binaries will be accessible to all users in the system (including initscripts you may want to install later), and upgrades will be simpler, and can use the exact same steps above.

1.4. Running the Server

Percona TokuMX supports almost all of the command line options for basic MongoDB, along with many new options. The differences are described in Server Parameters.

To start the server in its default configuration, just run mongod from its installation location. You can stop it with C-c.

If you have an existing /etc/mongodb.conf, you can copy it to /etc/tokumx.conf and run mongod --config /etc/tokumx.conf to use its options.

Warning

Be sure to change the dbpath and logpath options to avoid conflicting with any existing basic MongoDB data. Also, to avoid conflicting with a running server, either shut down basic MongoDB or change the port option.

To connect to the Percona TokuMX server, use the mongo program:

$ mongo
TokuMX mongo shell v2.0.0-mongodb-2.4.10
connecting to: test
Welcome to the TokuMX shell.
For interactive help, type "help".
For more comprehensive documentation, see
  http://docs.mongodb.org/
and the TokuMX Users' Guide available at
  https://www.percona.com/doc/percona-tokumx/
Questions? Try the support group
http://groups.google.com/group/tokumx-user
> db.serverBuildInfo().tokumxVersion
2.0.0

1.5. Replacing MongoDB

Note

If migrating from an existing MongoDB installation, copy any relevant configuration from /etc/mongodb.conf to /etc/tokumx.conf.

Percona TokuMX is not file-format compatible with MongoDB, so you must export your data from your existing MongoDB installation and import the data into Percona TokuMX. This can be accomplished by using mongodump and mongorestore.

This procedure is described in Migrating to TokuMX along with advanced techniques for online (no-downtime) migrations of replica sets, and migrations of sharded clusters.

1.6. Upgrading TokuMX

Unless otherwise noted, Percona TokuMX is file-format compatible with prior versions.

Important

Percona TokuMX 1.3.0 introduced MongoDB 2.4 compatibility, and as such you must follow the Upgrade to MongoDB 2.4 procedure if upgrading a pre-1.3.0 Percona TokuMX environment to 1.3.0 or newer, or if upgrading from MongoDB 2.2 to Percona TokuMX 1.3.0 or newer.

1.6.1. Single Server

To upgrade a single Percona TokuMX server, you must cleanly shut down the old server before installing and starting the new binaries.

  1. Shutdown the server

    Perform a clean shutdown of the old server. This can be done in two ways:

    1. Command line

      Add the --shutdown command line option to your normal mongod options.

      $ mongod --config /etc/tokumx.conf --shutdown

    2. mongo shell

      Use the db.shutdownServer() shell function.

      > use admin
> db.shutdownServer()

  2. Install and restart

Install the new Percona TokuMX binaries, and restart mongod.

Warning

Some OS initscripts will time out if shutdown takes too long, and will then send a KILL signal, which will abort the clean shutdown. If this happens, the upgrade may fail. It is recommended to shut down the server manually, and avoid using init scripts.

1.6.2. Replica Set

To upgrade a Percona TokuMX replica set, you should upgrade each machine in the set one at a time, starting with arbiters, then secondaries, then finally upgrade the primary.

Important

TokuMX 1.4.0 introduced new oplog types that cannot be processed by secondaries running TokuMX 1.3.x and lower. Therefore, if a member running 1.4.0 or greater becomes primary, it may write oplog entries that will not be processed by members with earlier versions. For this reason, you should always upgrade all secondary machines first. TokuMX 2.0.0 also introduced new oplog types that cannot be processed by secondaries running TokuMX 1.5.x and lower. Therefore, like when upgrading to 1.4.0, when upgrading to 2.0.0, be sure to upgrade all secondary machines first.

Tip

You may wish to use Replica Set priority to have one machine try to stay primary during the upgrade process.

1. Upgrade all secondaries Upgrade each secondary in the set, one at a time, according to the instructions for Single Server. Make sure to wait for each member to return to SECONDARY status (in rs.status()) before upgrading the next member.

2. Step down the primary Use rs.stepDown() to have the primary fail over to one of the newly upgraded secondaries.

3. Upgrade the primary Upgrade the stepped down primary according to the instructions for Single Server.

1.6.3. Sharded Cluster

  1. Disable the balancer
Disable the balancer using sh.setBalancerState(false).
  1. Upgrade routers
Upgrade all mongos instances by shutting them down and restarting them with the new binaries.
  1. Upgrade config servers
Upgrade all mongod config servers (upgrading the first server listed in the mongos --configdb option last).
  1. Upgrade shard servers
Upgrade each shard according to the instructions for Replica Set.
  1. Re-enable the balancer
Re-enable the balancer using sh.setBalancerState(true).
Download PDF Manual

Table Of Contents

This Page

Contact Us

For free technical help, visit the Percona Community Forum.
To report bugs or submit feature requests, open a JIRA ticket.
For paid support and managed or professional services, contact Percona Sales.