Sequoia User's Guide

Emmanuel Cecchet

Julie Marguerite

Mathieu Peltier

Nicolas Modrzyk

Dylan Hansen

Nuno Carvalho

Version 2.10

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 Sequoia?
1.2. What do I need to use Sequoia?
1.3. Why should I use Sequoia?
1.4. How does it work?
1.5. What does it cost?
1.6. What kind of modifications are needed?
2. Getting the Software
3. Installation
3.1. Sequoia Controller
3.1.1. Using the Java graphical installer
3.1.2. Using the binary distribution
3.2. Sequoia Driver
3.3. Sequoia out of the box
4. Migrating from C-JDBC to Sequoia
4.1. What is new with Sequoia?
4.1.1. Licensing
4.1.2. Continuent.org
4.2. Migrating your C-JDBC configuration to Sequoia
5. Sequoia Driver
5.1. Overview
5.2. Loading the Driver
5.3. Sequoia JDBC URL
5.3.1. URL options
5.4. Getting a connection using a data source
5.5. Stored procedures
5.6. Blobs: Binary Large Objects
5.7. Clobs: Character Large Objects
5.8. ResultSet streaming
5.9. Current Limitations
6. Configuring Sequoia with 3rd party software
6.1. Forenotes on configuring Sequoia with your application
6.2. Configuring Sequoia with Jakarta Tomcat
6.3. Configuring Sequoia with JOnAS
6.4. Configuring Sequoia with JBoss
6.5. Configuring Sequoia with BEA Weblogic Server 7.x/8.x
6.6. Configuring Sequoia with Hibernate
6.7. Using sequences with Hibernate, Sequoia and PostgreSQL
7. Sequoia controller
7.1. Design Overview
7.2. Starting the Controller
7.3. Writing the controller configuration file
7.3.1. Controller Parameters
7.3.2. Internationalization
7.3.3. Report
7.3.4. JMX
7.3.5. Virtual Database
7.3.6. Security
7.4. Configuring the Log
7.5. Recovery Log
7.5.1. A practical example
7.5.2. Understanding checkpoints
7.5.3. A fault tolerant Recovery Log
7.6. Controller replication
7.7. Current Limitations
8. Administration console
8.1. Jmx Notifications List
8.2. Starting the Administration Console
8.3. Console Quickstart
8.4. Console Main Menu
8.5. Administrator Menu
8.5.1. Administrator Standard Commands
8.5.2. Administrator Expert Commands
8.6. Automated Backup With Jmx
8.7. Recoverying from a failed controller in distributed mode
8.8. Virtual Database Console Menu
9. RAIDb Basics
9.1. RAIDb Definition
9.2. RAIDb-0
9.3. RAIDb-1
9.4. RAIDb-2
9.5. Nested RAIDb Levels
10. Virtual database configuration
10.1. Writing a Virtual Database Configuration File
10.2. Virtual Database
10.2.1. Distribution
10.2.2. Monitoring
10.3. Backup Manager
10.4. Authentication Manager
10.5. Database Backend
10.5.1. Rewriting requests on backends
10.5.2. Database Schema Definition
10.5.3. Connection Manager
10.6. Request Manager
10.6.1. Macros Handler
10.6.2. Request Scheduler
10.6.3. Request Cache
10.6.4. Load Balancer
10.6.5. Recovery Log
10.7. SSL Configuration
10.7.1. Controller
10.7.2. Console / Jmx Clients
10.7.3. Driver
10.7.4. Certificates (public and private keys)
10.8. Configuration Examples
11. Glossary
12. About Sequoia
12.1. License
12.2. Web Site
12.3. Mailing Lists
12.4. Reporting a Bug
12.5. Getting Involved
12.6. About Continuent.org
12.7. About INRIA
12.8. About ObjectWeb

1. Getting Started

1.1. What is Sequoia?

Sequoia 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 Sequoia.

Sequoia is a free, open source project that is the continuation of the C-JDBC project hosted by the ObjectWeb Consortium. Sequoia is licensed under an Apache v2 license is licensed whereas C-JDBC is available under the GNU Lesser General Public License (LGPL).

Sequoia also provides driver for non-Java applications. These developments are hosted in the Carob project. An Eclipse plug-in for Sequoia is also available in the Oak project.

1.2. What do I need to use Sequoia?

In order to use Sequoia, you will need:

  • a client application that accesses a database through JDBC,

  • a JDK™ 1.4 (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.

[Note]Note

If your client application does not use JDBC, you can use the C++ API or the ODBC driver provided by the Carob project .

1.3. Why should I use Sequoia?

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. Sequoia can help you resolve these problems by providing:

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

  • high availability of the database tier, i.e. Sequoia 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 heterogeneous database engines.

1.4. How does it work?

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

Sequoia provides a generic JDBC driver to be used by the clients (see Section 5, “Sequoia Driver”). This driver forwards the SQL requests to the Sequoia controller (see Section 7, “Sequoia controller”) that balances them on a cluster of databases (reads are load balanced and writes are broadcasted). Sequoia 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, “Sequoia principle” gives an overview of the Sequoia principle.

Figure 1. Sequoia principle

Sequoia principle

Sequoia allows to build any cluster configuration including mixing database engines from different vendors. The main features provided by Sequoia 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, Sequoia is an open-source software licensed under Apache v2 License 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. Sequoia 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 Sequoia configuration file (see Section 10, “Virtual database configuration”).



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