C-JDBC User's Guide

Emmanuel Cecchet

Julie Marguerite

Mathieu Peltier

Nicolas Modrzyk

Version 2.0.2

Java, and all Java-based trademarks are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries.

Table of Contents

1. Getting Started
1.1. What is C-JDBC?
1.2. What do I need to use C-JDBC?
1.3. Why should I use C-JDBC?
1.4. How does it work?
1.5. What does it cost?
1.6. What kind of modifications are needed?
2. Getting the Sofware
3. Installation
3.1. C-JDBC Controller
3.1.1. Using the Java graphical installer
3.1.2. Using the binary distribution
3.2. C-JDBC Driver
3.3. C-JDBC out of the box
4. C-JDBC Driver
4.1. Overview
4.2. Loading the Driver
4.3.1. URL options
4.4. Proxying mode
4.5. Getting a connection using a data source
4.6. Stored procedures
4.7. Blobs: Binary Large Objects
4.8. Clobs: Character Large Objects
4.9. ResultSet streaming
4.10. Current Limitations
5. Configuring C-JDBC with 3rd party software
5.1. Forenotes on configuring C-JDBC with your application
5.2. Configuring C-JDBC with Jakarta Tomcat
5.3. Configuring C-JDBC with JOnAS
5.4. Configuring C-JDBC with JBoss
5.5. Configuring C-JDBC with BEA Weblogic Server 7.x/8.x
5.6. Configuring C-JDBC with Hibernate
5.7. Using sequences with Hibernate, C-JDBC and PostgreSQL
6. C-JDBC controller
6.1. Design Overview
6.2. Starting the Controller
6.3. Writing the controller configuration file
6.3.1. Controller Parameters
6.3.2. Internationalization
6.3.3. Report
6.3.4. JMX
6.3.5. Virtual Database
6.3.6. Security
6.4. Configuring the Log
6.5. Recovery Log
6.5.1. A practical example
6.5.2. Understanding checkpoints
6.5.3. A fault tolerant Recovery Log
6.6. Controller replication
6.7. Current Limitations
7. Administration console
7.1. Jmx Notifications List
7.2. Starting the Administration Console
7.3. Console Quickstart
7.4. Console Main Menu
7.5. Administrator Menu
7.5.1. Administrator Standard Commands
7.5.2. Administrator Expert Commands
7.6. Automated Backup With Jmx
7.7. Recoverying from a failed controller in distributed mode
8. Virtual Database Console Menu
9. Monitoring Console Menu
10. RAIDb Basics
10.1. RAIDb Definition
10.2. RAIDb-0
10.3. RAIDb-1
10.4. RAIDb-2
10.5. Nested RAIDb Levels
11. Virtual database configuration
11.1. Writing a Virtual Database Configuration File
11.2. Virtual Database
11.2.1. Distribution
11.2.2. Monitoring
11.3. Backup Manager
11.4. Authentication Manager
11.5. Database Backend
11.5.1. Rewriting requests on backends
11.5.2. Database Schema Definition
11.5.3. Connection Manager
11.6. Request Manager
11.6.1. Macros Handler
11.6.2. Request Scheduler
11.6.3. Request Cache
11.6.4. Load Balancer
11.6.5. Recovery Log
11.7. SSL Configuration
11.7.1. Controller
11.7.2. Console / Jmx Clients
11.7.3. Driver
11.7.4. Certificates (public and private keys)
11.8. Configuration Examples
12. Request Player
12.1. Recording a request trace
12.2. Replaying a trace file
12.3. requestplayer.properties
13. Glossary
14. About C-JDBC
14.1. License
14.2. Web Site
14.3. Wiki
14.4. Mailing Lists
14.5. Reporting a Bug
14.6. Getting Involved
14.7. About INRIA
14.8. About ObjectWeb

1. Getting Started

1.1. What is C-JDBC?

C-JDBC is a database cluster middleware that allows any Java™ application (standalone application, servlet or EJB™ container, ...) to transparently access a cluster of databases through JDBC™. You do not have to modify client applications, application servers or database server software. You just have to ensure that all database accesses are performed through C-JDBC.

C-JDBC is a free, open source project of the ObjectWeb Consortium. It is licensed under the GNU Lesser General Public License (LGPL).

1.2. What do I need to use C-JDBC?

In order to use C-JDBC, you will need:

  • a client application that accesses a database through JDBC,

  • a JDK™ 1.3 (or greater) compliant Java Virtual Machine™ (JVM)[1],

  • a database with a JDBC driver (type 1, 2, 3 or 4) or an ODBC driver used with the JDBC-ODBC bridge.

  • a network supporting TCP/IP communications between your cluster nodes.


If your client application uses ODBC, it is possible to use an ODBC-JDBC bridge such as the unixODBC provided by Easysoft.

1.3. Why should I use C-JDBC?

You have a Java application or a Java-based application server that accesses one or several databases. The database tier becomes the bottleneck of your application or it is a single point of failure or both. C-JDBC can help you resolve these problems by providing:

  • performance scalability by adding database nodes and balacing the load among these nodes.

  • high availability of the database tier, i.e. C-JDBC tolerates database crashes and offers transparent failover using database replication techniques.

  • improved performance with fine grain query caching and transparent connection pooling.

  • SQL traffic logging for performance monitoring and analysis.

  • support for clusters of heterogenous database engines.

1.4. How does it work?

C-JDBC provides a flexible architecture that allows you to achieve scalability, high availability and failover with your database tier. C-JDBC implements the concept of RAIDb: Redundant Array of Inexpensive Databases (see Section 10, “RAIDb Basics”). The database is distributed and replicated among several nodes and C-JDBC load balances the queries between these nodes.

C-JDBC provides a generic JDBC driver to be used by the clients (see Section 4, “C-JDBC Driver”). This driver forwards the SQL requests to the C-JDBC controller (see Section 6, “C-JDBC controller”) that balances them on a cluster of databases (reads are load balanced and writes are broadcasted). C-JDBC can be used with any RDBMS (Relational DataBase Management System) providing a JDBC driver, that is to say almost all existing open source and commercial databases. Figure 1, “C-JDBC principle” gives an overview of the C-JDBC principle.

Figure 1. C-JDBC principle

C-JDBC principle

C-JDBC allows to build any cluster configuration including mixing database engines from different vendors. The main features provided by C-JDBC are performance scalability, fault tolerance and high availability. Additional features such as monitoring, logging, SQL requests caching are provided as well.

The architecture is widely open to allow anyone to plug custom requests schedulers, load balancers, connection managers, caching policies, ...

1.5. What does it cost?

From a software point of view, C-JDBC is an open-source software licensed under LGPL which means that it is free of charge for any usage (personal or commercial). If you are using commercial RDBMS (such as Oracle, DB2, ...), you will have to buy extra licenses for the nodes where you install replicas of the database. But you can possibly use open-source databases to host replicas of your main database.

You need to buy extra machines if you want more performance and more fault tolerance. C-JDBC has been designed to work with standard off-the-shelf workstations because it primarily targets low cost open-source solutions but it can work as well with large SMP machines. A standard Ethernet network is sufficient to achieve good performance.

1.6. What kind of modifications are needed?

You do not have to change anything to your application or your database.

You only have to update the JDBC driver configuration used by your application (usually it is just a configuration file update) and to setup a C-JDBC configuration file (see Section 11, “Virtual database configuration”).

[1] C-JDBC may work with older JVM version, but hasn't been tested.