1. System Requirements
1.1 Supported Operating Systems
dbShards Enterprise Edition is currently certified on the following operation systems. Additional operating systems can be supported easily since dbShards is mostly implemented in Java.
- CentOS 5.2
- Ubuntu 9.1.0
1.2 Software Requirements
dbShards Enterprise Edition requires the following software products and versions to be installed prior to installation of dbShards:
- Java Runtime Environment (JRE) version 1.6.0_21 or later
- Ruby 1.8.x (used for scripts that launch dbShards processes)
1.3 Networking / Environment Requirements
- UDP multicast must be enabled between all servers running dbShards components (client or server).
- Firewalls must be configured to allow TCP/IP packets between dbShards processes on a small range of ports, typically between 4000 and 4050.
- The /etc/hosts file must map the host name to a remotely accessible IP address rather than mapping the host name to 127.0.0.1
- dbShards requires the number of file handles to be set to a larger limit than the typical default of 1024 (a value of 16,000 is suggested).
1.4 Database Requirements
dbShards Enterprise Edition is currently certified against MySQL 5.1.32 and support for Postgres will soon be available.
2. Installation
2.1 Software Installation
dbShards is distributed as a platform-neutral .tar.gz file that can be deployed on UNIX, Linux, Microsoft Windows and Mac OS X. However, dbShards is currently only tested and supported on Linux platforms.
When upgrading from a previous release it is important to delete old jar files since jar file names sometimes change between releases. The following commands can be used to delete jar files from a previous release.
rm -f /opt/dbshards/jars/cf*.jar rm -f /opt/dbshards/jars/dbs*.jar
Use the following command to extract the dbShards product from the installation file. This will automatically create a ‘dbshards’ directory below the current working directory. Throughout this document it is assumed that dbShards is installed under /opt.
cd /opt tar xzf dbshards_enterprise-2.2.0-b1.tar.gz
2.2 UDP Configuration
dbShards relies heavily on UDP multicast (with the exception of dbShards Cloud Edition, which uses an alternate mechanism for membership) so it is important that UDP is enabled on all hosts and that the firewall on each host allows incoming UDP packets on port 45565. The following commands should be used on CentOS to enable UDP.
route add -net 224.0.0.0 netmask 240.0.0.0 dev eth0 iptables -I RH-Firewall-1-INPUT -s 0.0.0.0/0 -p udp --dport 45565 -j ACCEPT
2.3 TCP Configuration
dbShards clients and agents communicate via TCP and the ports used are configurable in the dbShards configuration file. The examples use ports 4000 and above. The number of ports used depends on the configuration. The following commands should be used on RHEL 5 / CentOS 5 to enable incoming TCP packets on ports 4000 through 4100.
iptables -I RH-Firewall-1-INPUT -s 0.0.0.0/0 -p tcp --dport 4000:4100 -j ACCEPT
It is essential to increase the number of file handles using this command to avoid getting java.net.SocketException: Too many open files
ulimit -n 128000
2.3 IP Address Configuration
dbShards determines the IP address of each host automatically based on the host name. For this functionality to work correctly it is important that /etc/hosts is configured correctly. A common installation problem is that /etc/hosts maps the host name to 127.0.0.1 instead of the external IP address. The host name can be found by running the hostname command. Here is an example
In this example, the host name is ‘db3′. The ping command can be used to see what IP address this host name resolves to. For example:
[username@db3 ~]$ ping db3 PING db3 (127.0.0.1) 56(84) bytes of data. 64 bytes from db3 (127.0.0.1): icmp_seq=1 ttl=64 time=22.4 ms
The hostname is resolving to 127.0.0.1 which is not correct. The next step is to view the /etc/hosts file:
127.0.0.1 db3 localhost.localdomain localhost ::1 localhost6.localdomain6 localhost6
This clearly shows that the host name ‘db3′ is being mapped to 127.0.0.1 and the solution is simply to add a line to the hosts file and move the mapping of the host name. For example:
127.0.0.1 localhost.localdomain localhost ::1 localhost6.localdomain6 localhost6 192.168.1.51 db3
Once this file has been modified, running the ping command again will show the following results:
[username@db3 ~]$ ping db3 PING db3 (192.168.1.51) 56(84) bytes of data. 64 bytes from db3 (192.168.1.51): icmp_seq=1 ttl=64 time=21.6 ms
3. Starting dbShards Processes
Before the dbShards processes can be started, a valid dbShards configuration file (usually named dbshards-config.xml) must be created and copied to /etc. This is beyond the scope of this installation guide. Once the dbshards-config.xml is in place the dbShards Daemon (dbsd) service can be started. This service will start all other dbShards processes, such as the dbShards Membership Daemon (dbsmemberd) and dbShards Agents.
cd /opt/dbshards ./dbsd start
The following command can be used to confirm that the processes started correctly:
ps -ef | grep java
The output will typically look something like this:
root 19099 19098 3 13:49 ? 00:14:23 java -Xms16m -Xmx32m com.dbshards.dbsd.Dbsd /etc/dbshards-config.xml root 19140 19139 0 13:49 ? 00:02:53 java -Xms16m -Xmx64m com.dbshards.dbsmemberd.DbsMembershipDaemon /etc/dbshards-config.xml root 19147 19142 0 13:49 ? 00:00:12 java -Xms64m -Xmx128m -Djava.library.path=/usr/lib64:/usr/lib com.dbshards.agent.Agent /etc/dbshards-config.xml 102 root 19166 19161 0 13:49 ? 00:00:11 java -Xms64m -Xmx128m -Djava.library.path=/usr/lib64:/usr/lib com.dbshards.agent.Agent /etc/dbshards-config.xml 103 root 19177 19171 0 13:49 ? 00:00:11 java -Xms64m -Xmx128m -Djava.library.path=/usr/lib64:/usr/lib com.dbshards.agent.Agent /etc/dbshards-config.xml 104 root 19189 19168 0 13:49 ? 00:00:11 java -Xms64m -Xmx128m -Djava.library.path=/usr/lib64:/usr/lib com.dbshards.agent.Agent /etc/dbshards-config.xml 101 root 30938 30883 0 20:06 pts/1 00:00:00 grep java
4. dbShards Management Console
4.1 Installation
dbShards has a web based console for monitoring the health of various components. The console is packaged as a .war file and can be deployed into Apache Tomcat or any other Java application server that supports the J2EE standard. Simply copy the /opt/dbshards/webapps/dbsmanage.war into the correct location for the application server being used. The management console can then be accessed with the URL http://server:port/dbsmanage/web
DbsManage requires a valid dbshards-config.xml to be installed to /etc and also requires the dbShards Membership Daemon (dbsmemberd) to be running. This is automatically started by the dbShards Daemon (dbsd) when launched with the following commands.
cd /opt/dbshards ./dbsd start
5. dbShards JDBC Driver
The dbShards JDBC driver is contained in a single jar file named dbshards-driver-with-dependencies.jar located in the jars directory beneath the the dbshards installation directory. This jar files needs to added to the application classpath.
The driver class name is com.dbshards.jdbc.Driver. There are several supported URL formats for connecting to the database.
To connect to a sharded database, using the configuration file located at /etc/dbsards-config.xml, the format is:
jdbc:dbshards:/etc/dbshards-config.xml
To connect to a single shard directly (also used if dbShards is purely being used for database replication), the shard number can be appeneded to the URL. Here is an example of a URL for connecting to shard 1. In a replication-only setup, there is on shard #1.
jdbc:dbshards:/etc/dbshards-config.xml:1
Finally, to use the product in session-based sharding mode, the following URL format is used:
jdbc:dbshards:/etc/dbshards-config.xml?shard=4
6. dbShards Native MySQL Driver
6.1 Installation
dbShards ships with a drop-in replacement for the regular native MySQL driver (libmysqlclient.so). The driver is located in operating-system-specific directories beneath the lib directory beneath the dbShards installation directory. Each directory contains an ‘install.rb’ Ruby script for installing the driver. To install the driver, simple navigate to the directory for the host platform and run the following command.
ruby install.rb
The install script will install libraries that dbShards depends on (boost and antlr) and will install the following files to /usr/lib or /usr/lib64.
libdbsclient_mysql15.so.2.2.0 libdbsclient_mysql16.so.2.2.0
These are the dbShards drivers that are API compatible with libmysqlclient.so.15.0.0 and libmysqlclient.so.16.0.0 respectively.
In addition to installing these files, the install script also creates two directories containing symlinks to these drivers. This allows applications that require dbShards functionality to set LD_LIBRARY_PATH to one of these directories so that the application finds a libmysqlclient.so symlink that redirects to the dbShards driver. Applications that do not require dbShards functionality will find the regular libmysqlclient.so symlink on the system path.
The two directories created by the install script and:
/usr/lib64/dbshards_mysql15 /usr/lib64/dbshards_mysql16
6.2 Connecting
There dbshards C driver can be used in three distinct modes – passthrough, sharding and replication.
6.2.1 Pass-through Mode
Driver acts as a wrapper around MySQL without any sharding or replication functionality. This allows applications to connect to dbShards databases and regular MySQL databases using a single driver. With debug logging enabled it also allows the driver to act as a logging driver so that SQL statements can be recorded for analysis prior to sharding a database. To enable debug logging the line “DbsMySQLNativeConnection=DEBUG” should be added to /opt/dbshards/conf/log.properties. Connection details should be the same as when using the MySQL driver directly. Log output will be written to /var/log/libdbsclient.log
6.2.2 Sharding Mode
To enable sharding functionality the database name should be changed from a simple database name such as “bookstore” to a string such as “dbshards:/etc/dbshards-config.xml”.
6.2.3 Replication Mode / Sharded Session Mode
To connect directly to a single shard or a single replicated database, the database name should be changes to “dbshards:/etc/dbshards-config.xml:N” where N is the shard number (this should be ’1′ for a single replicated database).