vFabric SQLFire Hibernate Dialect

The attached vFabric SQLFire Hibernate dialect file defines the SQLFire variant of the SQL language. You can use the hibernate dialect file along with the SQLFire JDBC driver to configure SQLFire as a database for developing Hibernate projects.

The topics in this section describe how to install and use the SQLFire dialect file with Hibernate projects. The examples use the hibernate tutorial files that are available from the Hibernate community site, and the dialect file attached to this article.

Prerequisites

Integrating SQLFire with a Hibernate project has the following requirements and recommendations:

Hibernate 3.1 or later.

Note: If you need to use a version of Hibernate prior to 3.1 with SQLFire, specify the Apache Derby dialect (not the SQLFire Hibernate dialect) for your project.

SQLFire 1.0.x installation with the Hibernate dialect file.
(Recommended) JBoss Maven repository for setting up and compiling Hibernate projects. In the examples it is assumed that you have installed Maven in your development environment.
(Recommended) Hibernate tutorial files for following the examples in this section. Unzip the files to a local directory (it is assumed that the files are available at /hibernate-tutorials).

Generate DDL Statements

Generate DDL scripts for your project, either by:

Writing new DDL statements in a SQL script file that you can execute using sqlf.
Using the sqlf utility to export the DDL from an existing database to a file. You can then modify the file to add SQLFire-specific DDL extensions, such as for partitioning and replicating tables. After modifying the script, use sqlf to import the generated DDL into a SQLFire database that you will use in your hibernate project.

Note: See Using SQLF Commands to Export and Import Data in the SQLFire documentation for instructions and examples of exporting DDL from an existing database, modifying the DDL, and importing the DDL to SQLFire.

Add the Dialect File and JDBC Driver to Your Project

Both the SQLFire JDBC thin client driver JAR file and the SQLFire hibernate dialect file must be available as resources to your hibernate projects.

Procedure

To add the dialect file and JDBC driver to your project, do one of the following:

Install these files to your local Maven repository (using a unique groupId and artifactId) and then reference the resources in project files.

Edit your project file to directly specify the local files as system resources. For example, open the /hibernate-tutorials/pom.xml file in a text editor, and add the following system resources:

...   <dependencies>        <!-- SQLfire dependencies -->        <dependency>          <groupId>com.vmware</groupId>          <artifactId>sqlf-client</artifactId>          <version>1.0.3</version>          <scope>system</scope>          <systemPath>/vFabric_SQLFire_103/lib/sqlfireclient.jar</systemPath>        </dependency>        <dependency>          <groupId>com.vmware</groupId>          <artifactId>sqlf-dialect</artifactId>          <version>1.0.3</version>          <scope>system</scope>          <systemPath>/vFabric_SQLFire_103/lib/sqlfHibernateDialect.jar</systemPath>        </dependency>
        ...   </dependencies>
...

Note: The above example assumes that you have installed SQLFire in the /vFabric_SQLFire_103 directory, and that you have copied the Hibernate dialect JAR file into /vFabric_SQLFire_103/lib. Substitute the correct paths to for your installation.

Configure the Dialect Version and JDBC Connection

The hibernate.cfg.xml file configures JDBC connection information as well as the version of the SQL dialect to use. SQLFire provides dialect versions to correspond with the feature set of a base snapshot version of Hibernate. Use com.vmware.sqlfire.hibernate.SQLFireDialect for all current (4.1) Hibernate versions.

Procedure

To configure the dialect version:

Specify one of the above strings as the dialect property in hibernate.cfg.xml or hibernate.properties. For example, edit the /hibernate-tutorials/basic/src/test/hibernate.cfg.xml file and change the existing property definition as follows:

<property name="dialect">com.vmware.sqlfire.hibernate.SQLFireDialect</property>
Define the SQLFire JDBC driver class and connection properties as you would for other JDBC clients, by specifying the driver class and thin-client connection string. For example, in hibernate.cfg.xml edit connection properties similar to:

<!-- Database connection settings --><property name="connection.driver_class">com.vmware.sqlfire.jdbc.ClientDriver</property><property name="connection.url">jdbc:sqlfire://localhost:1527</property><property name="connection.username">sqlf</property><property name="connection.password">sqlf</property>

Note: If you have enabled authentication in SQLFire, specify a valid username and password combination. If you have not enabled authentication, specify any value for the username and password. Keep in mind that SQLFire uses the username as the default schema name for creating new tables.

Note: If you are using an older version of Hibernate, specify one of the following SQLFire dialect versions instead of com.vmware.sqlfire.hibernate.SQLFireDialect:

SQLFire Dialect Version	Archived Hibernate Version(s)
com.vmware.sqlfire.hibernate.v4.v0.SQLFireDialect	4.0.1.Final
com.vmware.sqlfire.hibernate.v3.v6.SQLFireDialect	3.6.0.Final, 3.6.10
com.vmware.sqlfire.hibernate.v3.SQLFireDialect	3.1.3, 3.2.0GA, 3.2.7, 3.3.0.GA, 3.3.0.SP1, 3.3.1GA, 3.3.2GA, 3.5.1Final

Run the Basic Hibernate Tutorial

After you make the above changes to the Hibernate tutorial files, run the basic Hibernate tutorial with SQLFire as the database.

Procedure

Ensure that the SQLFire distributed system is running and that you can connect using the JDBC connection string.
Generate and execute the necessary DDL statements in the target SQLFire database as described in "Generate DDL Statements" above. See Using SQLF Commands to Export and Import Data for more information and examples.
Change to the basic Hibernate tutorial directory:
```
cd /hibernate-tutorials/basic
```
Build the project and run the basic tutorial:
```
mvn test
```

In the output, verify that the SQLFire dialect and JDBC driver are used:

INFO: HHH000401: using driver [com.vmware.sqlfire.jdbc.ClientDriver] at URL [jdbc:sqlfire://localhost:1527]
Jul 3, 2012 3:15:24 PM org.hibernate.service.jdbc.connections.internal.DriverManagerConnectionProviderImpl configure
INFO: HHH000046: Connection properties: {user=sqlf, password=****}
Jul 3, 2012 3:15:24 PM org.hibernate.dialect.Dialect <init>
INFO: HHH000400: Using dialect: com.vmware.sqlfire.hibernate.SQLFireDialect
Jul 3, 2012 3:15:24 PM com.vmware.sqlfire.hibernate.SQLFireDialectBase <init>

Connect to SQLFire using sqlf to validate that the table is created:

$ sqlf
sqlf> connect client 'localhost:1527';
sqlf> select * from sqlf.events;
EVENT_ID            |EVENT_DATE                |TITLE                                                                                                                          
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
1                   |2012-07-03 15:15:24.573   |Our very first event!                                                                                                          
2                   |2012-07-03 15:15:24.671   |A follow up event                                                                                                              

2 rows selected

Limitations

By default, the table DDL that is generated for identity columns uses the GENERATED ALWAYS AS IDENTITY syntax. You can override this behavior by setting the SQLF_GENERATE_IDENTITY environment variable to "BYDEFAULT". With the "BYDEFAULT" setting, table DDL uses the GENERATED BY DEFAULT IDENTITY syntax for identity columns.

SQLFire does not support using the hbm2ddl tool with the hibernate dialect.