home > Dependencies > Database

Database Use

Overview

We are currently using Hibernate 3.3 to persist data objects. Hibernate hides a multitude of details at the JDBC level, including conversion of data types in queries and result sets, and transaction handling. In addition, from the Hibernate Web page:

"Hibernate is a powerful, high performance object/relational persistence and query service. Hibernate lets you develop persistent classes following object-oriented idiom - including association, inheritance, polymorphism, composition, and collections."

The underlying database server is MySQL. Currently we are using version 5.0. The MySQL server is set up to only accept connections from the machine it is running on, for security reasons. It depends on the presence of a Web server on the same machine to forward requests to it. All requests are authenticated and authorized via the AAA before being passed on to Hibernate and the database.

Installing MySQL
If you already have a version of MySQL 4.1 or later, you should not need to install another version. However, we are currently using the latest 5.0 version if you wish to update.

Go to MySQL 5.0 downloads and chose the distribution for your platform. Download and install it per the instructions that are included with the distribution.  The installation will be intially set up with grants for all privileges on *.* root@localhost, with grant option where root has no password set, and two anoymous user@localhost accounts with more restricted access. You will want to add a passwords for these accounts. Instructions on how to set the passwords or delete accounts can be found at MySQL Securing the Initial MySQL Accounts.
For a Unix system the following will work.

shell> mysql -u root
mysql> SET PASSWORD FOR ''@'localhost' = PASSWORD('newpwd');
mysql> SET PASSWORD FOR ''@'host_name' = PASSWORD('newpwd');
mysql> SET PASSWORD FOR 'root'@'localhost' = PASSWORD('newpwd');
mysql> SET PASSWORD FOR 'root'@'host_name' = PASSWORD('newpwd');
where host_name is replaced by your local host name, i.e the results of the hostname command, which should also be the result of the following mysql query.

<mysql> SELECT host,user FROM mysql.user;

During the installation of OSCARS the intall.sh script will ask for the name of the mysql privileged user and its password when it is going to create the databases and tables needed by OSCARS. You should give it the user root and the password you have just set.

Database schema set up and population

Note: the do_build.sh script now creates the aaa, bss, testaaa and testbss databases; creates the bss and ass tables; and populates the aaa tables with default values for institutions, resources, permissions and attributes.  There are command line scripts in tools/utils to add and delete users, institutions (org) and domains (in the bss database).

OSCARS makes use of two databases, one for the AAA named "aaa", and one for the BSS, pathfinder, PSS and TSS, named "bss". The Hibernate configuration information for these databases is in conf/server, in the files aaa.cfg.xml and bss.cfg.xml, respectively. These are copied to the appropriate place in the classpath as part of the build process.

The scripts to create the necessary tables in the aaa and bss databases are contained in sql/aaa/createTables.sql and sql/bss/createTables.sql, respectively. sql/aaa/populateDefaults.sql is a sample script setting up default attributes, resources, and permissions.

The program to populate the bss database with the network topology for ESNet is located in tools/updatedb/TopologyUpdater.java. It depends on the presence of a directory with previously gathered information about each router in the topology, which was gained using SNMP queries. Currently the format of the files in that directory is ESnet-specific.

There is a similar program in tools/updatedbterce/TERCETopologyUpdate.java that will populate the bss database from the TERCE web service.

Test databases

Separate test databases, testaaa and testbss, are set up for unit tests. Make sure that they are created as well as the aaa and bss databases. They are repopulated as necessary each time a test suite executes. Their Hibernate configuration files are in the conf/server directory, testaaa.cfg.xml and testbss.cfg.xml. These are identical to the production configuration files except for the names of the databases.

Object/relational mapping

Each table in the database has a corresponding Java bean. The mapping is defined in the Hibernate configuration files mentioned above. There is also a Hibernate configuration file that maps each field in the table to a bean property, with a suffix of ".hbm.xml", located in the same directory as the bean.

OSCARS makes extensive use of the DAO (data-access object) design pattern. Each bean, for example Router.java, has an associated DAO object, in this case RouterDAO.java, that performs low-level CRUD (create, retrieve, update, delete) operations. Each DAO object sub-classes src/net/es/oscars/database/GenericHibernateDAO.java.

Useful MySQL commands

shell> mysql -u <username> -p  prompts for a password and starts mysql
mysql> show status; shows the status of a number of variables.
mysql> show databases;  shows what databases are available
mysql> connect <database>;  connects you to the specified database
mysql> show tables;  shows all the tables in the database
mysql> describe <table>;  shows the fields of the specified table
mysql> select * from <table>;  shows all the rows of the specified table.

For the rest of the iceberg see MySQL documentation.