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
.
- Unpack the tarball
Unpack the tarball to/opt
:
$ tar xzf tokumx-2.0.0-linux-x86_64-main.tar.gz --directory /opt
- 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
- 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.
Shutdown the server
Perform a clean shutdown of the old server. This can be done in two ways:
Command line
Add the
--shutdown
command line option to your normal mongod options.$ mongod --config /etc/tokumx.conf --shutdown
mongo shell
Use the db.shutdownServer() shell function.
> use admin > db.shutdownServer()
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¶
- Disable the balancer
Disable the balancer usingsh.setBalancerState(false)
.
- Upgrade routers
Upgrade all mongos instances by shutting them down and restarting them with the new binaries.
- Upgrade config servers
Upgrade all mongod config servers (upgrading the first server listed in the mongos --configdb option last).
- Upgrade shard servers
Upgrade each shard according to the instructions for Replica Set.
- Re-enable the balancer
Re-enable the balancer usingsh.setBalancerState(true)
.
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.