Storage Configuration

Author: Pierre van Rooden
Date: 2004-02-05

This software is OSI Certified Open Source Software. OSI Certified is a certification mark of the Open Source Initiative.

The license (Mozilla version 1.0) can be read at the MMBase site. See http://www.mmbase.org/license

Abstract

Configuration document for Storage

Table of Contents

1. Introduction
2. Overview
3. MMBaseRoot module
4. JDBC module

1. Introduction

This document describes how to configure the MMBase Storage Managers. Included are how to select the proper resource for your database, and how to adapt those resources to your own personal needs.

2. Overview

Configuration in this document is divided in five sections. The first two sections detail how to set up MMbase to use the storage laeyer, and to allow access to the database server. The last three sections detail how you can change behavior of the storage layer, and how to configure it to work with your specific database server or system setup.

Sections:

MMBaseRoot module (modules/mmbaseroot.xml). Basic configuration, selecting storagemanager or datasource.
JDBC module (modules/jdbc.xml). Configuration of the MMBase-provided JDBC interface.
Database resource (Attributes). Attributes affect the behavior of the database by specifying additional information such as the path to store blobs on file
Database resource (Options). Options affect the behavior of the database by turning features on or off, such as whether to create compound indexes.
Database resource (Schemes). Schemes define templates for SQL statements (or parts of SQL statements), such as the CREATE TABLE statement.

3. MMBaseRoot module

The MMBaseroot module can be used to configure what part of the database storage layer is used by MMBase. You can select a database storagemanager factory (the main engine), a JNDI datasource for accessing the server, and a storage resource file for configuring the storage layer to fit your server.

By default, MMBase uses the database storage layer, and selects a databse resource based on the database Driver available through the JDBC module (see next section). You can change or set the following properties to change this behavior.

Properties:

<<property name="storagemanagerfactory" >>. This property points out a class to use for instantiating the storage manager factory class. This class is the engine that provides access to the storage device (i.e. a database). In MMBase 1.7, you have to provide this property in order to use the new storage layer.
Values:
- org.mmbase.storage.implementation.database.DatabaseStorageManagerFactory. Selects the factory that provides generic database access. This is currently the only available factory.
- [empty]. In MMBase 1.7, not specifying the factory prompts the system to use the old 'support' classes. Activate this only if you are upgrading a system and the new storage configuration causes different behavior from the old system (i.e. when your old system uses PostgreSQL, you may want to do this so you can convert BLOB files in the databse to files on disk)
<<property name="datasource" >>. In older systems, connections to the database were created and maintained by the JDBC module. This method is still available with the new storage layer, and can be very useful if you like to run MMBase standalone.
You can also leave database access and maintenance of such elements as connection pools to the application server.
This is a more elegant way of accessing the database, but requires some knowledge of how to set up an application server's data-sources (a class that provides a databse connection). Information on setting up datasources can be found in the documentation of your application server. For instance, in Orion, you set up the datasource in a data-sources.xml file in the Orion config directory. Such a file typically looks as follows:
```
<?xml version="1.0"?>
<!DOCTYPE data-sources PUBLIC "Orion data-sources" "http://www.orionserver.com/dtds/data-sources.dtd">
<data-sources>
	<data-source
		class="com.evermind.sql.DriverManagerDataSource"
		name="Hsqldb"
		location="jdbc/HsqldbCoreDS"
		xa-location="jdbc/xa/HsqldbXADS"
		ejb-location="jdbc/HsqldbDS"
		connection-driver="org.hsqldb.jdbcDriver"
		username="sa"
		password=""
		url="jdbc:hsqldb:./database/defaultdb"
		inactivity-timeout="30"
	/>
</data-sources>
				
```
This configures a datasource for a hsqldb database.
After setting up the datasource, you need to specify a JNDI pointer to it. This pointer is an identifier equal to one of the 'location' identifiers specified for the datasource. We recommend using the 'ejb-location' identifier ('dbc/HsqldbDS' in the example), as that will provide connection pooling, which speeds up the storage layer. If you use this method, you need to turn off the JDBC Module (by setting it's status to inactive).
<<property name="datasource-context" >>. Specifies the context for the datasource.
The default value is "java:comp/env".
<<property name="database" >>. MMBase needs some additonal configuration data to deal with the database connection. Most databases have some peculiarities, but by specifying the right parameters you can work around this. You can set up your own resource, or use the set of resources delivered with MMBase.
MMBase provides a mechanism to automatically determine what configuraton to use, based on information obtained from the datasource. As such, you generally only need to specify what configuration to use if you have your supply own configuration file, or if MMBase, for some reason, fails to correctly determine what database you have.
To explicitly set the configuration resource to use, you specify a pathname to the resource in the 'database' property.
Example 1.
```
<property name="database">/org/mmbase/storage/implementation/database/resources/hsqldb.xml</property>
```
The path is a classpath to the resource (the resource needs to be present in the MMBase classpath). If the resource is a .xml file located in the org.mmbase.storage.implementation.database.resources package, you can use shortcut notation as follows :
Example 2.
```
<property name="database">hsqldb</property>
```
The storage will automatically expand the name to its correct resource path.
Available resources:
- [empty] (recommended). Causes MMBase to attempt to select the database resource by itself, based on information from the database JDBC Driver. A lookup table exists which contains information on the most common drivers for the supported databases.
- mysql. Selects the predefined MySQL database resource
- postgresql. Selects the predefined PostGreSQl database resource
- hsqldb. Selects the predefined HSQLDB database resource
- hypersonic. Selects the predefined Hypersonic database resource
- informix. Selects the predefined Informix database resource

4. JDBC module

The JDBC module provides a connection to a database through the JDBC interface. The module is wrapped by the Storage layer in a datasource (see above) and can thus be used to 'emulate' a datsource when an application server is not available.

The configuration file can be found under config/modules/jdbc.xml. By default this modules is active. If you have specified a datasource in the MMBaseRoot module configuration, you should set the JDBC module to inactive or remove the configurationfile alltogether.

url. Defines the jdbc url MMBase will use to connect to your database. You can use a number of patterns similar to variables in the url, which are set by other tags.
Variables available are:
Example 3. An example url for MySQL:
```
<property name="url">jdbc:mysql://$HOST:$PORT/$DBM</property>
					
```
Example 4. An example url for HSQLDB:
```
<property name="url">jdbc:hsqldb:$DBM</property>
					
```
user. The name of the user with which to log on to the database.
password. The password with which to log on to the database.
host. Specifieds the server host (the machine on which the database runs). If you run MMBase on the same machine as the database, you can set the value to 'localhost' (the default)
port. The port the database engine is running on. You can find the port in your database manual or ask the database admininstrator.
Default ports for supported databases are:
database. Most database engines allow you to store multiple databases in one engine. Specify this name to select the database within the engine.
driver. Defines the classname for the used jdbc driver. This can be obtained from the documentation from the jdbc driver you use. Note that the class specified affects the default configuration resource MMBase loads unless you specify the mmbaseroot database property.
Possible driver classes:
connections. MMBase does its own database connection pooling. Pooling means that connections to the database are kept open over several database queries, to speed up queries by not logging in and closing the connection on every query. The connections property allows you to set the number of connections MMBase keeps open to the database. The default is 10 connections, You cans et this higher, but consult your server documentation to see what the maximum for your database engine is.
queries. MMBase replaces connections after a certain nr of executed queries, because some databases drivers or jdbc drivers may have memory leaks or other possible problems. With the queries property you can set the number of queruies that will be run per connection before it gets replaced. The default is 256 queries.
probetime. Sometimes connections take a long time. Every now and then the database connection pooling has to check/kill queries that take to long. Connections that are running for more then 120 seconds will then be aborted, and the connection will be closed and freed. The probetime property is the time in seconds between the checks. The default is 30 seconds.
supportclass. Specify a class to allow for additional actions to take into account when connecting to a database. The only database that currently uses this feature is Informix, which sets lock modes when initializing a connection.
Values:
- org.mmbase.module.database.DatabaseSupportShim. Standard database support class
- org.mmbase.module.database.DatabaseSupportInformix. Support class for Informix

Example 5. An example jdbc.xml

<?xml version="1.0"?>
<!DOCTYPE module PUBLIC "-//MMBase/ DTD module config 1.0//EN" "http://www.mmbase.org/dtd/module_1_0.dtd">
<module maintainer="mmbase.org" version="0">
	<status>active</status>
	<classfile>org.mmbase.module.database.JDBC</classfile>
	<properties>
		<property name="supportclass">org.mmbase.module.database.DatabaseSupportShim</property>
		<property name="driver">com.mysql.jdbc.Driver</property>
		<property name="url">jdbc:mysql://$HOST:$PORT/$DBM</property>
		<property name="user">mmbase</property>
		<property name="password">mypassword</property>
		<property name="database">mmbase_db</property>
		<property name="host">localhost</property>
		<property name="port">3306</property>
		<property name="connections">20</property> <!-- size of connection pool -->
		<property name="queries">256</property>    <!-- connections are refreshed after 256 uses -->
		<property name="probetime">300</property>  <!-- running connections are checked once every 300 s -->
	</properties>
</module>

This is part of the MMBase documentation.

For questions and remarks about this documentation mail to: documentation@mmbase.org