1.2. 配置数据源

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

1.2.1. 配置单个数据源

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

使用以下配置属性定义数据源，其中 db-kind 定义要连接的数据库平台，如 h2 ：
```
quarkus.datasource.db-kind=h2
```
Quarkus 丢弃了从 db-kind 数据库平台属性的指定的值中需要使用的 JDBC 驱动程序类。
注意
只有在应用程序依赖于多个数据库驱动程序时，才需要这一步。如果应用程序使用单一驱动程序操作，则会自动检测到这个驱动程序。
Quarkus 目前包括以下内置数据库类型：
- DB2: db2
- Derby: derby
  注意
  Apache Derby 数据库在红帽构建的 Quarkus 3.15 中弃用，计划在以后的发行版本中删除。在当前发行生命周期中，红帽将继续对 Apache 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 - quarkus-jdbc-derby
    注意
    Apache Derby 数据库在红帽构建的 Quarkus 3.15 中弃用，计划在以后的发行版本中删除。在当前发行生命周期中，红帽将继续对 Apache Derby 提供开发支持。
  - H2 - quarkus-jdbc-h2
    注意
    H2 和 Derby 数据库可以配置为以"嵌入模式"运行，但 Derby 扩展不支持将嵌入式数据库引擎编译到原生可执行文件中。
    使用内存中数据库读取测试，以了解有关集成测试的建议。
  - DB2 - quarkus-jdbc-db2
  - MariaDB - quarkus-jdbc-mariadb
  - Microsoft SQL Server - quarkus-jdbc-mssql
  - MySQL - quarkus-jdbc-mysql
  - Oracle - quarkus-jdbc-oracle
  - PostgreSQL - quarkus-jdbc-postgresql
    例如，要添加 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 已被弃用，而是使用 OpenTelemetry。如需追踪信息，请检查有关 Datasource tracing, bellow 的相关部分。

使用传统 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 层会自动获取数据源并使用它。

对于数据源的代码访问，将其作为任何其他 Bean 获取，如下所示：

@Inject
AgroalDataSource defaultDataSource;

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

1.2.1.2. 被动数据源

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

在应用程序中添加对应的扩展：
- 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 扩展和被动数据源扩展时，将默认创建 JDBC 和被动数据源。

同时使用 JDBC 和被动数据源：

%prod.quarkus.datasource.reactive.url=postgresql:///your_database
%prod.quarkus.datasource.jdbc.url=jdbc:postgresql://localhost:5432/hibernate_orm_test

如果您不想同时创建 JDBC 数据源和被动数据源，请使用以下配置：

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

1.2.2. 配置多个数据源

注意

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

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

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

默认
名为 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

注意 configuration 属性中有一个额外的部分。语法如下： quarkus.datasource.[optional name.][datasource property]。

注意

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

1.2.2.1. 命名数据源注入

使用多个数据源时，每个 DataSource 也具有 io.quarkus.agroal.DataSource qualifier，并将数据源的名称用作值。

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

@Inject
AgroalDataSource defaultDataSource;

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

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

1.2.3. 激活或停用数据源

当数据源在构建时配置时，它在运行时默认处于活动状态。这意味着 Quarkus 将在应用程序启动时启动对应的 JDBC 连接池或被动客户端。

要在运行时取消激活数据源，请将 quarkus.datasource[.optional name].active 设置为 false。然后，quarkus 将在应用程序启动期间跳过启动 JDBC 连接池或被动客户端。在运行时尝试使用已停用的数据源都会导致异常。

当您需要应用程序在运行时从预定义的集合中选择一个数据源时，此功能特别有用。

警告

如果另一个 Quarkus 扩展依赖于不活跃的数据源，则该扩展可能无法启动。

在这种情况下，您还需要停用其他扩展。有关这种情况的示例，请参阅 Hibernate ORM 部分。

例如，使用以下配置：

quarkus.datasource."pg".db-kind=postgres
quarkus.datasource."pg".active=false
quarkus.datasource."pg".jdbc.url=jdbc:postgresql:///your_database

quarkus.datasource."oracle".db-kind=oracle
quarkus.datasource."oracle".active=false
quarkus.datasource."oracle".jdbc.url=jdbc:oracle:///your_database

在运行时设置 quarkus.datasource."pg".active=true 将使 PostgreSQL 数据源可用，并在运行时设置 quarkus.datasource."oracle".active=true 将使 Oracle 数据源可用。

提示

自定义配置配置文件可帮助简化这样的设置。通过将特定于配置集的配置附加到上面的配置，您可以在运行时通过设置 quarkus.profile: quarkus.profile =prod,pg 或 quarkus.profile=prod,oracle 来选择持久性单元/数据源。

%pg.quarkus.hibernate-orm."pg".active=true
%pg.quarkus.datasource."pg".active=true
# Add any pg-related runtime configuration here, prefixed with "%pg."

%oracle.quarkus.hibernate-orm."oracle".active=true
%oracle.quarkus.datasource."oracle".active=true
# Add any pg-related runtime configuration here, prefixed with "%pg."

提示

定义 CDI bean 生成者重定向到当前活动数据源，如下所示：

public class MyProducer {
    @Inject
    DataSourceSupport dataSourceSupport;

    @Inject
    @DataSource("pg")
    AgroalDataSource pgDataSourceBean;

    @Inject
    @DataSource("oracle")
    AgroalDataSource oracleDataSourceBean;

    @Produces
    @ApplicationScoped
    public AgroalDataSource dataSource() {
        if (dataSourceSupport.getInactiveNames().contains("pg")) {
            return oracleDataSourceBean;
        } else {
            return pgDataSourceBean;
        }
    }
}

1.2.4. 在单个事务中使用多个数据源

默认情况下，数据源上的 XA 支持被禁用。因此，事务中不包含多个数据源。在同一个事务中尝试访问多个非 XA datasources 会导致异常类似如下：

...
Caused by: java.sql.SQLException: Exception in association of connection to existing transaction
        at io.agroal.narayana.NarayanaTransactionIntegration.associate(NarayanaTransactionIntegration.java:130)
        ...
Caused by: java.sql.SQLException: Failed to enlist. Check if a connection from another datasource is already enlisted to the same transaction
        at io.agroal.narayana.NarayanaTransactionIntegration.associate(NarayanaTransactionIntegration.java:121)
        ...

允许在同一事务中使用多个 JDBC 数据源：

确保您的 JDBC 驱动程序支持 XA。所有支持的 JDBC 驱动程序都执行，但其他 JDBC 驱动程序可能不。
确保您的数据库服务器已配置为启用 XA。
通过将 quarkus.datasource[.optional name].jdbc.transactions 设置为 xa，为每个相关数据源启用 XA 支持。

使用 XA 时，一个数据源的回滚将在事务中注册的每个其他数据源中触发回滚。

注意

目前不支持被动数据源上的 XA 事务。

注意

如果您的事务涉及非数据源资源，请注意它们可能不支持 XA 事务，或者可能需要额外的配置。

如果无法为您的其中一个数据源启用 XA ：

请注意，仍然通过 Last Resource Commit Optimization (LRCO)支持为所有数据源启用 XA，但仍然通过 Last Resource Commit Optimization (LRCO) 支持。
如果您不需要一个数据源的回滚来为其他数据源触发回滚，请考虑将您的代码拆分为多个事务。要做到这一点，请使用 QuarkusTransaction.requiringNew （）/@Transactional (REQUIRES_NEW) 或 UserTransaction （用于更复杂的用例）。

小心

如果没有其他解决方案，并且保持与 Quarkus 3.8 及更早版本的兼容性，请设置 quarkus.transaction-manager.unsafe-multiple-last-resources，以 允许在多个 非 XA datasources 间启用不安全事务处理。

将此属性设置为 allow 时，可能会发生事务回滚将只应用于最后一个非 XA 数据源，而其他非 XA 数据源也已提交了其更改，可能会使整个系统处于不一致的状态。

另外，您可以允许相同的不安全行为，但在其生效时发出警告：

将属性设置为 warn-each 会导致 在每个 异常事务上记录警告。
将属性设置为 warn-first 会导致 在第一次 出错事务时记录警告。

我们不推荐使用这个配置属性，我们计划在以后删除它，因此您应该相应地修复应用程序。如果您认为这个功能的用例有效，且应该保留这个选项，请在 Quarkus tracker 中创建一个问题，解释原因的原因。