1.2. 配置数据源

PDF

以下章节描述了单个或多个数据源的配置。为了简单起见，我们将引用单个数据源作为默认数据源（未命名）数据源。

1.2.1. 配置单个数据源

数据源可以是 JDBC 数据源、被动或两者。这取决于配置和选择项目扩展。

使用以下配置属性定义数据源，其中 db-kind 定义要连接到哪个数据库平台，例如 h2 ：
```
quarkus.datasource.db-kind=h2
```
Quarkus 会从 db-kind 数据库平台属性的指定的值减少需要使用的 JDBC 驱动程序类。
注意
只有在应用程序依赖于多个数据库驱动程序时，才需要执行此步骤。如果应用程序使用单个驱动程序运行，则会自动检测到此驱动程序。
Quarkus 当前包括以下内置数据库类型：
- DB2: db2
- Derby: derby
- H2: h2
- mariadb: mariadb
- Microsoft SQL Server: mssql
- MySQL: mysql
- Oracle: oracle
- postgresql: postgresql,pgsql 或 pg
- 要使用不是内置的数据库类型，请使用 other 并明确定义 JDBC 驱动程序
  注意
  您可以在 JVM 模式中使用 Quarkus 应用程序中的任何 JDBC 驱动程序，如使用其他数据库中所述。但是，当将应用程序编译到原生可执行文件时，使用非内置数据库类型不太可能可以正常工作。
  对于原生可执行构建，建议使用可用的 JDBC Quarkus 扩展，或为您的特定驱动程序提供自定义扩展。
配置以下属性以定义凭证：
```
quarkus.datasource.username=<your username>
quarkus.datasource.password=<your password>
```
您还可以使用数据源的凭证供应商从 Vault 检索密码。

到目前为止，无论您使用的是 JDBC 还是被动驱动程序，配置都相同。当您定义了数据库类型和凭证时，其余则取决于您所使用的驱动程序类型。可以同时使用 JDBC 和被动驱动程序。

1.2.1.1. JDBC 数据源

JDBC 是最常见的数据库连接模式，通常与非主动 Hibernate ORM 一起使用时需要。

要使用 JDBC 数据源，请从添加所需的依赖项开始：
1. 对于内置 JDBC 驱动程序，请从下面的列表中选择并添加相关数据库驱动程序的 Quarkus 扩展：
  - Derby - jdbc-derby
  - H2 - jdbc-h2
    注意
    H2 和 Derby 数据库可以配置为以"embedded 模式"运行，但 Derby 扩展不支持将嵌入式数据库引擎编译到原生可执行文件中。
    使用内存数据库读取测试，以了解与集成测试相关的建议。
  - DB2 - jdbc-db2
  - MariaDB - jdbc-mariadb
  - Microsoft SQL Server - jdbc-mssql
  - MySQL - jdbc-mysql
  - Oracle - jdbc-oracle
  - PostgreSQL - jdbc-postgresql
  - 其他 JDBC 扩展（如 SQLite 及其文档）可在 Quarkiverse 中找到。
    例如，添加 PostgreSQL 驱动程序依赖项：
    ./mvnw quarkus:add-extension -Dextensions="jdbc-postgresql"
    注意
    使用内置 JDBC 驱动程序扩展会自动包含 Agroal 扩展，该扩展是适用于自定义和内置 JDBC 驱动程序的 JDBC 连接池实施。但是，对于自定义驱动程序，需要明确添加 Agroal。
2. 对于自定义 JDBC 驱动程序，请将 quarkus-agroal 依赖项添加到项目中，以及您的相关数据库驱动程序的扩展：
```
./mvnw quarkus:add-extension -Dextensions="agroal"
```
  要将 JDBC 驱动程序用于其他数据库，请使用没有内置扩展或具有不同驱动程序的数据库。
通过定义 JDBC URL 属性来配置 JDBC 连接：
```
quarkus.datasource.jdbc.url=jdbc:postgresql://localhost:5432/hibernate_orm_test
```
注意
注意属性名称中的 jdbc 前缀。特定于 JDBC 的所有配置属性都具有 jdbc 前缀。对于被动数据源，前缀是 被动。

有关配置 JDBC 的更多信息，请参阅 JDBC URL 格式参考和 Quarkus 扩展和数据库驱动程序参考。

1.2.1.1.1. 自定义数据库和驱动程序

如果您需要连接到 Quarkus 没有提供 JDBC 驱动程序的扩展数据库，您可以使用自定义驱动程序。例如，如果您在项目中使用 OpenTracing JDBC 驱动程序。

如果没有扩展，驱动程序将在 JVM 模式下运行的任何 Quarkus 应用程序中正常工作。但是，当将应用程序编译到原生可执行文件时，驱动程序不太可能工作。如果您计划生成原生可执行文件，请使用现有的 JDBC Quarkus 扩展，或为您的驱动程序贡献一个。

带有 OpenTracing 驱动程序的示例：

quarkus.datasource.jdbc.driver=io.opentracing.contrib.jdbc.TracingDriver

定义在 JVM 模式中不支持内置支持的数据库的访问示例：

quarkus.datasource.db-kind=other
quarkus.datasource.jdbc.driver=oracle.jdbc.driver.OracleDriver
quarkus.datasource.jdbc.url=jdbc:oracle:thin:@192.168.1.12:1521/ORCL_SVC
quarkus.datasource.username=scott
quarkus.datasource.password=tiger

有关 JDBC 配置选项和配置其他方面的所有详细信息，如连接池大小，请参阅 JDBC 配置参考部分。

1.2.1.1.2. 消耗数据源

使用 Hibernate ORM 时，Hibernate 层会自动获取数据源并使用它。

对于对数据源的 in-code 访问，请作为任何其他 bean 获取，如下所示：

@Inject
AgroalDataSource defaultDataSource;

在上例中，type 是 AgroalDataSource，一个 javax.sql.DataSource 子类型。因此，您也可以使用 javax.sql.DataSource 作为注入的类型。

1.2.1.2. 主动数据源

Quarkus 提供多个被动客户端，用于被动数据源。

在应用程序中添加对应的扩展：
- DB2: quarkus-reactive-db2-client
- mariadb/MySQL: quarkus-reactive-mysql-client
- Microsoft SQL Server: quarkus-reactive-mssql-client
- Oracle: quarkus-reactive-oracle-client
- postgresql: quarkus-reactive-pg-client
  安装的扩展必须与您在数据源配置中定义的 quarkus.datasource.db-kind 一致。

添加驱动程序后，配置连接 URL，并为您的连接池定义正确的大小。

quarkus.datasource.reactive.url=postgresql:///your_database
quarkus.datasource.reactive.max-size=20

1.2.1.2.1. 重新调整连接池大小

为了保护您的数据库在负载高峰期间被过载，请适当调整池的大小，以节流数据库负载。正确的大小总是取决于许多因素，如并行应用程序用户的数量或工作负载的性质。

请注意，设置池大小太大可能会导致一些请求在等待连接时超时。

有关池大小调整属性的更多信息，请参阅主动数据源配置参考部分。

1.2.1.3. JDBC 和被动数据源同时

当 JDBC 扩展 - 以及 Agroal - 以及处理给定数据库类型的被动数据源扩展时，将默认创建这两个数据库。

明确禁用 JDBC 数据源：
```
quarkus.datasource.jdbc=false
```
明确禁用被动数据源：
```
quarkus.datasource.reactive=false
```
提示
在大多数情况下，上述配置将作为 JDBC 驱动程序或被动数据源扩展是可选的，而不是同时存在。

1.2.2. 配置多个数据源

注意

Hibernate ORM 扩展支持使用配置属性定义持久性单元。对于每个持久性单元，指向您选择的数据源。

定义多个数据源的工作方式类似于定义一个数据源，具有一个重要更改 - 您必须为每个数据源指定一个名称（配置键）。

以下示例提供三个不同的数据源：

默认 1
名为 users的数据源
名为 inventory的数据源

每个配置都有其配置：

quarkus.datasource.db-kind=h2
quarkus.datasource.username=username-default
quarkus.datasource.jdbc.url=jdbc:h2:mem:default
quarkus.datasource.jdbc.max-size=13

quarkus.datasource.users.db-kind=h2
quarkus.datasource.users.username=username1
quarkus.datasource.users.jdbc.url=jdbc:h2:mem:users
quarkus.datasource.users.jdbc.max-size=11

quarkus.datasource.inventory.db-kind=h2
quarkus.datasource.inventory.username=username2
quarkus.datasource.inventory.jdbc.url=jdbc:h2:mem:inventory
quarkus.datasource.inventory.jdbc.max-size=12

请注意，配置键中有一个额外部分。语法如下： quarkus.datasource.[optional name.][datasource property].

注意

即使只安装了一个数据库扩展，命名的数据库还需要指定一个 build-time 属性，以便 Quarkus 能够检测它们。通常，这是 db-kind 属性，但您也可以指定 Dev Services 属性，以根据 Dev Services for Databases 指南创建名为 datasources。

1.2.2.1. 命名数据源注入

使用多个数据源时，每个 DataSource 也具有 io.quarkus.agroal.DataSource 限定符，其名称为数据源的名称。

通过使用上一节中提到的属性来配置三个不同的数据源，请按如下所示注入每个数据源：

@Inject
AgroalDataSource defaultDataSource;

@Inject
@DataSource("users")
AgroalDataSource usersDataSource;

@Inject
@DataSource("inventory")
AgroalDataSource inventoryDataSource;