Configuring Data Sources in Your Quarkus Applications
Total Page:16
File Type:pdf, Size:1020Kb
Red Hat build of Quarkus 1.7 Configuring data sources in your Quarkus applications Last Updated: 2021-04-19 Red Hat build of Quarkus 1.7 Configuring data sources in your Quarkus applications Legal Notice Copyright © 2021 Red Hat, Inc. The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/ . In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version. Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law. Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries. Linux ® is the registered trademark of Linus Torvalds in the United States and other countries. Java ® is a registered trademark of Oracle and/or its affiliates. XFS ® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries. MySQL ® is a registered trademark of MySQL AB in the United States, the European Union and other countries. Node.js ® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project. The OpenStack ® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community. All other trademarks are the property of their respective owners. Abstract Configure a data source for your Quarkus application using extensions for built-in database drivers and connect your application to a relational database. Table of Contents Table of Contents .M . A. .K . I.N . .G . .O . P. .E . N. S. .O . U. .R . C. .E . .M . .O . R. .E . .I N. .C . L. .U . S. .I V. .E . 3. .C . H. .A . P. .T .E . R. 1.. .I .N . T. .R .O . .D . U. .C . T. .I O. N. T. O. .U . S. .I N. .G . D . .A . T. A. S. .O . U. R. C. .E . S. W. I.T . H. Q. .U . .A .R . K. .U . S. .4 . 1.1. SETTING THE DB-KIND PROPERTY FOR A DATA SOURCE 4 1.2. SETTING DATABASE CREDENTIALS 5 1.3. QUARKUS DRIVER EXTENSIONS FOR BUILT-IN DATABASES 5 .C . H. .A . P. .T .E . R. 2. J. .D . B. .C . .D . A. .T . A. S. .O . U. .R . C. .E . .C . O. .N . .F .I .G . U. .R . A. .T . I.O . N. 8. 2.1. INSTALLING QUARKUS EXTENSIONS FOR JDBC DATA SOURCES 8 2.2. SETTING THE JDBC URL OF YOUR DATA SOURCE 9 2.3. OBTAINING A JDBC DATA SOURCE WITH HIBERNATE ORM 9 2.4. DISABLING A JDBC DATA SOURCE IN A SIMULTANEOUS CONFIGURATION 10 2.5. CONFIGURING JDBC DRIVERS WITH NO BUILT-IN DRIVER EXTENSION 10 2.6. CONFIGURING MULTIPLE JDBC DATA SOURCES 11 .C . H. .A . P. .T .E . R. 3. R. .E . A. .C . T. .I V. .E . .D . A. .T . A. S . O. U. .R . C. .E . C. .O . .N . F. .I G. .U . .R .A . T. .I O. N. 1.4 . 3.1. SETTING THE REACTIVE DATA SOURCE CONNECTION URL 14 3.2. DISABLING A REACTIVE DATA SOURCE IN A SIMULTANEOUS CONFIGURATION 15 .C . H. .A . P. .T .E . R. 4. .D . A. .T .A . S . O. U. .R . C. .E . M. A. .N . A. .G . .E .M . .E . N. .T . 1.6 . 4.1. DATA SOURCE HEALTH CHECK 16 4.2. DATA SOURCE METRICS 16 4.3. NARAYANA TRANSACTION MANAGER INTEGRATION 16 4.4. TEST WITH IN-MEMORY DATABASES 16 APPENDIX A. JDBC DATABASE CONNECTION URLS FOR DATABASES WITH PRODUCTION AND .D . E. V. .E . L. .O . P. .M . .E . N. .T . .S .U . P. .P . O. R. .T . 1.8 . A.1. POSTGRESQL DATABASE URL EXAMPLE 18 A.2. MARIADB DATABASE URL EXAMPLE 18 A.3. MYSQL DATABASE URL EXAMPLE 18 A.4. MICROSOFT SQL SERVER DATABASE URL EXAMPLE 19 .A .P . P. .E . N. .D . I. X. B . J. .D . B. .C . .D . .A .T . A. .B . A. .S . E. C . .O . N. .N . .E .C . T. .I O. N. U. .R . L. .S . F. .O . R. D. .A . T. .A . B. .A . S. .E .S . .W . .I T. .H . .D . E. .V . E. .L .O . .P . M. E. N. T. .S . U. .P . P. .O . R. .T . 20 B.1. DERBY DATABASE URL EXAMPLE 20 B.2. H2 DATABASE URL EXAMPLE 20 1 Red Hat build of Quarkus 1.7 Configuring data sources in your Quarkus applications 2 MAKING OPEN SOURCE MORE INCLUSIVE MAKING OPEN SOURCE MORE INCLUSIVE Red Hat is committed to replacing problematic language in our code, documentation, and web properties. We are beginning with these four terms: master, slave, blacklist, and whitelist. Because of the enormity of this endeavor, these changes will be implemented gradually over several upcoming releases. For more details, see our CTO Chris Wright’s message . 3 Red Hat build of Quarkus 1.7 Configuring data sources in your Quarkus applications CHAPTER 1. INTRODUCTION TO USING DATA SOURCES WITH QUARKUS When you want to add persistent data storage to your application, you must connect your application to a relational database. To achieve this, you use a data source that you connect to your application using a database driver. You can connect your Quarkus application to one or multiple data sources. You can use the data source management functionalities integrated into Quarkus to: configure your application to use one or multiple data sources obtain references to data sources in your code view and set pool tuning configuration properties In Quarkus applications, you can use two types of database drivers to connect your application to a relational database. You can use multiple data sources of both types in one application simultaneously: JDBC drivers that use the standard JDBC API that provides database connectivity for Java-based application. Quarkus JDBC drivers manage database connections using Agroal, a fast, light-weight, and highly scalable database connection pool implementation that is integrated with other features of Quarkus, including security, transaction management and health checks. Reactive drivers that are based on the data source driver implementation in Eclipse Vert.x. Eclipse Vert.x reactive data source drivers provide the non-blocking and reactive network-related features of Quarkus and are suitable for applications that are designed to be highly scalable and event-driven. You can configure both types of data source drivers using a set of unified and flexible configuration options that Quarkus provides. 1.1. SETTING THE DB-KIND PROPERTY FOR A DATA SOURCE When you set the db-kind property in the configuration file of your application to match the type of your data source that you want to use, Quarkus automatically resolves the appropriate type of database driver. The following procedure demonstrates how you can set the db-kind property for a data source. Prerequisites You have a Quarkus Maven project. Procedure 1. Navigate to your Quarkus project directory. 2. In the src/main/resources/application.properties file, set the value of the db-kind property to match the type of the data source that you want to use. The following example uses postgresql as the data source type: quarkus.datasource.db-kind=postgresql Additional resources Driver extensions for Quarkus built-in databases 4 CHAPTER 1. INTRODUCTION TO USING DATA SOURCES WITH QUARKUS 1.2. SETTING DATABASE CREDENTIALS You can define credentials that your application uses to access your database. Defining access credentials for your database is optional. You can skip this procedure when configuring a data source for your application. Prerequisites You have a Quarkus Maven project. You have set the db-kind property for your data source. Your Quarkus application is in JVM mode. This prerequisite applies when you use a JDBC driver that Quarkus does not support in native mode. Procedure 1. Navigate to your Quarkus project directory. 2. In the src/main/resources/application.properties file, set the value of the quarkus.datasource.username property to match the username that your application uses to access the database: quarkus.datasource.username=<username> 3. In the src/main/resources/application.properties file, set the value of the quarkus.datasource.password property to match the password that your application uses to access the database: quarkus.datasource.password=<password> Additional resources Setting the db-kind property for a data source 1.3. QUARKUS DRIVER EXTENSIONS FOR BUILT-IN DATABASES The following table provides an overview of Quarkus built-in databases and the extensions that you can use to connect your application to a relational database: Table 1.1. Driver extensions for Quarkus built-in databases Database db-kind Agroal extension Reactive extension built-in DB2 db2 quarkus-jdbc-db2 quarkus-reactive-db2-client Derby derby quarkus-jdbc-derby N/A H2 h2 quarkus-jdbc-h2 N/A MariaDB mariadb quarkus-jdbc-mariadb quarkus-reactive-mysql-client 5 Red Hat build of Quarkus 1.7 Configuring data sources in your Quarkus applications Database db-kind Agroal extension Reactive extension built-in Microsoft mssql quarkus-jdbc-mssql N/A SQL Server MySQL mysql quarkus-jdbc-mysql quarkus-reactive-mysql-client PostgreSQL postgresql, quarkus-jdbc-postgresql quarkus-reactive-pg-client pgsql, or pg You can configure H2 and Derby databases to run in embedded mode.