Instead of using a file-based data store, you can set up a broker to access any data store accessible through a JDBC-compliant driver. This involves setting the appropriate JDBC-related broker configuration properties and using the Database Manager utility (imqdbmgr) to create the proper database schema. See Configuring a JDBC-Based Data Store for specifics.
The full set of properties for configuring a broker to use a JDBC database are listed in Table 16–6. You can specify these properties either in the instance configuration file (config.properties) of each broker instance or by using the -D command line option to the Broker utility (imqbrokerd) or the Database Manager utility (imqdbmgr).
In practice, however, JDBC properties are preconfigured by default, depending on the database vendor being used for the data store. The property values are set in the default.properties file, and only need to be explicitly set if you are overriding the default values. In general, you only need to set the following properties:
This property specifies that a JDBC-based data store (as opposed to the default file-based data store) is used to store persistent data.
imq.persist.jdbc.dbVendor
This property identifies the database vendor being used for the data store; all of the remaining properties are qualified by this vendor name.
imq.persist.jdbc.connection.limit
This property specifies the maximum number of connections that can be opened to the database.
imq.persist.jdbcvendorName.user
This property specifies the user name to be used by the broker in accessing the database.
imq.persist.jdbcvendorName.password
This property specifies the password for accessing the database, if required; imq.persist.jdbc.vendorName.needpassword is a boolean flag specifying whether a password is needed. For security reasons, the database access password should be specified only in a password file referenced with the -passfile command line option; if no such password file is specified, the imqbrokerd and imqdbmgr commands will prompt for the password interactively.
imq.persist.jdbc.vendorName.property.propName
This set of properties represents any additional, vendor-specific properties that are required.
imq.persist.jdbc.vendorName.tableoption
Specifies the vendor-specific options passed to the database when creating the table schema.
imq.persist.store=jdbc imq.persist.jdbc.dbVendor=mysql imq.persist.jdbc.mysql.user=userName imq.persist.jdbc.mysql.password=password imq.persist.jdbc.mysql.property.url=jdbc:mysql://hostName:port/dataBase |
If you expect to have messages that are larger than 1 MB, configure MySQL's max_allowed_packet variable accordingly when starting the database. For more information see Appendix B of the MySQL 5.0 Reference Manual.
imq.persist.store=jdbc imq.persist.jdbc.dbVendor=hadb imq.persist.jdbc.hadb.user=userName imq.persist.jdbc.hadb.password=password imq.persist.jdbc.hadb.property.serverlist=hostName:port,hostName:port,... |
You can obtain the server list using the hadbm get jdbcURL command.
In addition, in an enhanced broker cluster, in which a JDBC database is shared by multiple broker instances, each broker must be uniquely identified in the database (unnecessary for an embedded database, which stores data for only one broker instance). The configuration property imq.brokerid specifies a unique instance identifier to be appended to the names of database tables for each broker. See Enhanced Broker Cluster Properties.
After setting all of the broker’s needed JDBC configuration properties, you must also install your JDBC driver’s .jar file in the appropriate directory location, depending on your operating-system platform (as listed in Appendix A, Platform-Specific Locations of Message Queue Data) and then create the database schema for the JDBC-based data store (see To Set Up a JDBC-Based Data Store).
To configure a broker to use a JDBC database, you set JDBC-related properties in the broker’s instance configuration file and create the appropriate database schema. The Message Queue Database Manager utility (imqdbmgr) uses your JDBC driver and the broker configuration properties to create the schema and manage the database. You can also use the Database Manager to delete corrupted tables from the database or if you want to use a different database as a data store. See Database Manager Utility for more information.
If you use an embedded database, it is best to create it under the following directory:
.../instances/instanceName/dbstore/databaseName
If an embedded database is not protected by a user name and password, it is probably protected by file system permissions. To ensure that the database is readable and writable by the broker, the user who runs the broker should be the same user who created the embedded database using the imqdbmgr command.
Set JDBC-related properties in the broker’s instance configuration file.
The relevant properties are discussed, with examples, in JDBC-Based Persistence Properties and listed in full in Table 16–6. In particular, you must specify a JDBC-based data store by setting the broker’s imq.persist.store property to jdbc.
Place a copy of, or a symbolic link to, your JDBC driver’s .jar file in the Message Queue external resource files directory, depending on your platform (see Appendix A, Platform-Specific Locations of Message Queue Data):
Solaris: /usr/share/lib/imq/ext
Linux: /opt/sun/mq/share/lib/ext
AIX: IMQ_VARHOME/lib/ext
Windows: IMQ_VARHOME\lib\ext
For example, if you are using HADB on a Solaris system, the following command copies the driver’s .jar file to the appropriate location:
cp /opt/SUNWhadb/4/lib/hadbjdbc4.jar /usr/share/lib/imq/ext
The following command creates a symbolic link instead:
ln -s /opt/SUNWhadb/4/lib/hadbjdbc4.jar /usr/share/lib/imq/ext
Create the database schema needed for Message Queue persistence.
Use the imqdbmgr create all command (for an embedded database) or the imqdbmgr create tbl command (for an external database); see Database Manager Utility.
You can display information about a JDBC-based data store using the Database Manager utility (imqdbmgr) as follows:
Change to the directory where the Database Manager utility resides, depending on your platform:
Solaris: cd /usr/bin
Linux: cd /opt/sun/mq/bin
AIX: cd IMQ_HOME/bin
Windows: cd IMQ_HOME\bin
Enter the imqdbmgr command:
imqdbmgr query
The output should resemble the following
dbmgr query [04/Oct/2005:15:30:20 PDT] Using plugged-in persistent store: version=400 brokerid=Mozart1756 database connection url=jdbc:oracle:thin:@Xhome:1521:mqdb database user=scott Running in standalone mode. Database tables have already been created.
The persistent data store can contain, among other information, message files that are being temporarily stored. Since these messages may contain proprietary information, it is important to secure the data store against unauthorized access. This section describes how to secure data in a JDBC-based data store.
A broker using JDBC-based persistence writes persistent data to a JDBC-compliant database. For a database managed by a database server (such as Oracle), it is recommended that you create a user name and password to access the Message Queue database tables (tables whose names start with MQ). If the database does not allow individual tables to be protected, create a dedicated database to be used only by Message Queue brokers. See the documentation provided by your database vendor for information on how to create user name/password access.
The user name and password required to open a database connection by a broker can be provided as broker configuration properties. However it is more secure to provide them as command line options when starting up the broker, using the imqbrokerd command’s -dbuserand -dbpassword options (see Broker Utility).
For an embedded database that is accessed directly by the broker by means of the database’s JDBC driver, security is usually provided by setting file permissions on the directory where the persistent data will be stored, as described above under Securing a File-Based Data Store To ensure that the database is readable and writable by both the broker and the Database Manager utility, however, both should be run by the same user.