This tutorial shows you how build a simple Java application with CockroachDB using a PostgreSQL-compatible driver or ORM.
We have tested the Java JDBC driver and the Hibernate ORM enough to claim beta-level support, so those are featured here. If you encounter problems, please open an issue with details to help us make progress toward full support.
{{site.data.alerts.callout_success}} For a more realistic use of Hibernate with CockroachDB, see our examples-orms repository. {{site.data.alerts.end}}
Choose the instructions that correspond to whether your cluster is secure or insecure:
{{site.data.alerts.callout_danger}} The examples on this page assume you are using a Java version <= 9. They do not work with Java 10. {{site.data.alerts.end}}
Step 1. Install the Gradle build tool
This tutorial uses the Gradle build tool to get all dependencies for your application, including Hibernate.
To install Gradle on Mac, run the following command:
$ brew install gradle
To install Gradle on a Debian-based Linux distribution like Ubuntu:
$ apt-get install gradle
To install Gradle on a Red Hat-based Linux distribution like Fedora:
## Step 2. Create the `maxroach` user and `bank` database {% include {{page.version.version}}/app/create-maxroach-user-and-bank-database.md %} ## Step 3. Generate a certificate for the `maxroach` user Create a certificate and key for the `maxroach` user by running the following command. The code samples will run as this user. {% include copy-clipboard.html %} ~~~ shell $ cockroach cert create-client maxroach --certs-dir=certs --ca-key=my-safe-directory/ca.key ~~~ ## Step 4. Convert the key file for use with Java The private key generated for user `maxroach` by CockroachDB is [PEM encoded](https://tools.ietf.org/html/rfc1421). To read the key in a Java application, you will need to convert it into [PKCS#8 format](https://tools.ietf.org/html/rfc5208), which is the standard key encoding format in Java. To convert the key to PKCS#8 format, run the following OpenSSL command on the `maxroach` user's key file in the directory where you stored your certificates (`/tmp/certs` in this example): {% include copy-clipboard.html %} ~~~ shell $ openssl pkcs8 -topk8 -inform PEM -outform DER -in client.maxroach.key -out client.maxroach.pk8 -nocrypt ~~~ ## Step 5. Run the Java code Download and extract [hibernate-basic-sample.tgz](https://github.com/cockroachdb/docs/raw/master/_includes/v2.1/app/hibernate-basic-sample/hibernate-basic-sample.tgz), which contains a Java project that includes the following files: File | Description -----|------------ [`Sample.java`](https://raw.githubusercontent.com/cockroachdb/docs/master/_includes/v2.1/app/hibernate-basic-sample/Sample.java) | Uses [Hibernate](http://hibernate.org/orm/) to map Java object state to SQL operations. For more information, see [Sample.java](#sample-java). [`hibernate.cfg.xml`](https://raw.githubusercontent.com/cockroachdb/docs/master/_includes/v2.1/app/hibernate-basic-sample/hibernate.cfg.xml) | Specifies how to connect to the database and that the database schema will be deleted and recreated each time the app is run. For more information, see [hibernate.cfg.xml](#hibernate-cfg-xml). [`build.gradle`](https://raw.githubusercontent.com/cockroachdb/docs/master/_includes/v2.1/app/hibernate-basic-sample/build.gradle) | Used to build and run your app. For more information, see [build.gradle](#build-gradle). In the `hibernate-basic-sample` directory, build and run the application: {% include copy-clipboard.html %} ~~~ shell $ gradle run ~~~ Toward the end of the output, you should see: ~~~ 1 1000 2 250 ~~~ To verify that the table and rows were created successfully, start the [built-in SQL client](use-the-built-in-sql-client.html): {% include copy-clipboard.html %} ~~~ shell $ cockroach sql --certs-dir=certs --database=bank ~~~ To check the account balances, issue the following statement: {% include copy-clipboard.html %} ~~~ sql > SELECT id, balance FROM accounts; ~~~ ~~~ +----+---------+ | id | balance | +----+---------+ | 1 | 1000 | | 2 | 250 | +----+---------+ (2 rows) ~~~ ### Sample.java The Java code shown below uses the [Hibernate ORM](http://hibernate.org/orm/) to map Java object state to SQL operations. Specifically, this code: - Creates an `accounts` table in the database based on the `Account` class. - Inserts rows into the table using `session.save(new Account())`. - Defines the SQL query for selecting from the table so that balances can be printed using the `CriteriaQuery
query` object. {% include copy-clipboard.html %} ~~~ java {% include {{page.version.version}}/app/hibernate-basic-sample/Sample.java %} ~~~ ### hibernate.cfg.xml The Hibernate config (in `hibernate.cfg.xml`, shown below) specifies how to connect to the database. Note the [connection URL](connection-parameters.html#connect-using-a-url) that turns on SSL and specifies the location of the security certificates. {% include copy-clipboard.html %} ~~~ xml {% include {{page.version.version}}/app/hibernate-basic-sample/hibernate.cfg.xml %} ~~~ ### build.gradle The Gradle build file specifies the dependencies (in this case the Postgres JDBC driver and Hibernate): {% include copy-clipboard.html %} ~~~ groovy {% include {{page.version.version}}/app/hibernate-basic-sample/build.gradle %} ~~~
## Step 2. Create the `maxroach` user and `bank` database {% include {{page.version.version}}/app/insecure/create-maxroach-user-and-bank-database.md %} ## Step 3. Run the Java code Download and extract [hibernate-basic-sample.tgz](https://github.com/cockroachdb/docs/raw/master/_includes/v2.1/app/insecure/hibernate-basic-sample/hibernate-basic-sample.tgz), which contains a Java project that includes the following files: File | Description -----|------------ [`Sample.java`](https://raw.githubusercontent.com/cockroachdb/docs/master/_includes/v2.1/app/insecure/hibernate-basic-sample/Sample.java) | Uses [Hibernate](http://hibernate.org/orm/) to map Java object state to SQL operations. For more information, see [Sample.java](#sample-java). [`hibernate.cfg.xml`](https://raw.githubusercontent.com/cockroachdb/docs/master/_includes/v2.1/app/insecure/hibernate-basic-sample/hibernate.cfg.xml) | Specifies how to connect to the database and that the database schema will be deleted and recreated each time the app is run. For more information, see [hibernate.cfg.xml](#hibernate-cfg-xml). [`build.gradle`](https://raw.githubusercontent.com/cockroachdb/docs/master/_includes/v2.1/app/insecure/hibernate-basic-sample/build.gradle) | Used to build and run your app. For more information, see [build.gradle](#build-gradle). In the `hibernate-basic-sample` directory, build and run the application: {% include copy-clipboard.html %} ~~~ shell $ gradle run ~~~ Toward the end of the output, you should see: ~~~ 1 1000 2 250 ~~~ To verify that the table and rows were created successfully, start the [built-in SQL client](use-the-built-in-sql-client.html): {% include copy-clipboard.html %} ~~~ shell $ cockroach sql --insecure --database=bank ~~~ To check the account balances, issue the following statement: {% include copy-clipboard.html %} ~~~ sql > SELECT id, balance FROM accounts; ~~~ ~~~ +----+---------+ | id | balance | +----+---------+ | 1 | 1000 | | 2 | 250 | +----+---------+ (2 rows) ~~~ ### Sample.java The Java code shown below uses the [Hibernate ORM](http://hibernate.org/orm/) to map Java object state to SQL operations. Specifically, this code: - Creates an `accounts` table in the database based on the `Account` class. - Inserts rows into the table using `session.save(new Account())`. - Defines the SQL query for selecting from the table so that balances can be printed using the `CriteriaQuery
query` object. {% include copy-clipboard.html %} ~~~ java {% include {{page.version.version}}/app/insecure/hibernate-basic-sample/Sample.java %} ~~~ ### hibernate.cfg.xml The Hibernate config (in `hibernate.cfg.xml`, shown below) specifies how to connect to the database. Note the [connection URL](connection-parameters.html#connect-using-a-url) that turns on SSL and specifies the location of the security certificates. {% include copy-clipboard.html %} ~~~ xml {% include {{page.version.version}}/app/insecure/hibernate-basic-sample/hibernate.cfg.xml %} ~~~ ### build.gradle The Gradle build file specifies the dependencies (in this case the Postgres JDBC driver and Hibernate): {% include copy-clipboard.html %} ~~~ groovy {% include {{page.version.version}}/app/insecure/hibernate-basic-sample/build.gradle %} ~~~
What's next?
Read more about using the Hibernate ORM, or check out a more realistic implementation of Hibernate with CockroachDB in our examples-orms repository.
You might also be interested in using a local cluster to explore the following CockroachDB benefits: