连接至数据库 - CUBA 框架开发者手册

3.3.1. 连接至数据库

CUBA 应用程序通过 JDBC DataSource-数据源 获取数据库的连接。一个数据源可以在应用程序中配置，也可以通过 JNDI 获取。获取数据源的方法通过应用程序属性 cuba.dataSourceProvider 来指定：可以设置为 application 或 jndi。

使用 CUBA Studio 可以很方便的配置主数据库连接和附加数据存储，参阅文档。下面的信息对于排查问题很有帮助，也可以用来定义那些 Studio 中没有的参数，比如连接池配置。

在应用程序中配置数据源

Since7.2

当在应用程序中配置数据源时，框架会使用 HikariCP 创建一个连接池。连接参数和连接池配置都通过 core 模块 app.properties 中的应用程序属性来配置。如果不需要特别指定由应用程序服务提供的连接池，推荐直接使用这种配置。

下列应用程序属性定义数据库类型和连接参数：

cuba.dbmsType - 定义 DBMS 类型。
cuba.dataSourceProvider - application 值表示数据源必须使用应用程序属性来配置。
cuba.dataSource.username - 数据库的用户名称。
cuba.dataSource.password - 数据库的用户密码。
cuba.dataSource.dbName - 数据库的名称。
cuba.dataSource.host - 数据库的地址。
cuba.dataSource.port - 可选参数，设定数据库端口，如果使用了非标准端口的话。
cuba.dataSource.jdbcUrl - 可选参数，设置 JDBC URL 的全路径，如果需要一些额外的连接参数。注意，对于数据迁移任务，所有以上的单独属性还是需要配置的。

如需配置连接池参数，使用 cuba.dataSource. 前缀指定 HikariCP 的属性，比如 cuba.dataSource.maximumPoolSize 或 cuba.dataSource.connectionTimeout。参考 HikariCP 文档了解所有支持的参数及其默认值。

如果应用程序使用了附加数据存储，需要同样为每个数据存储定义一组参数。数据存储的名称添加到每个属性名称的第二部分：

示例：

# main data store connection parameters
cuba.dbmsType = hsql
cuba.dataSourceProvider = application
cuba.dataSource.username = sa
cuba.dataSource.password =
cuba.dataSource.dbName = demo
cuba.dataSource.host = localhost
cuba.dataSource.port = 9111
cuba.dataSource.maximumPoolSize = 20

# names of additional data stores
cuba.additionalStores = clients,orders

# 'clients' data store connection parameters
cuba.dbmsType_clients = postgres
cuba.dataSourceProvider_clients = application
cuba.dataSource_clients.username = postgres
cuba.dataSource_clients.password = postgres
cuba.dataSource_clients.dbName = clients_db
cuba.dataSource_clients.host = localhost

# 'orders' data store connection parameters
cuba.dbmsType_orders = mssql
cuba.dataSourceProvider_orders = application
cuba.dataSource_orders.jdbcUrl = jdbc:sqlserver://localhost;databaseName=orders_db;currentSchema=my_schema
cuba.dataSource_orders.username = sa
cuba.dataSource_orders.password = myPass123
cuba.dataSource_orders.dbName = orders_db
cuba.dataSource_orders.host = localhost

另外，对于每个附加数据存储，core 模块的 spring.xml 文件必须包含一个 CubaDataSourceFactoryBean bean 的定义，该定义需要使用合适的 storeName 参数，示例：

<bean id="cubaDataSource_clients" class="com.haulmont.cuba.core.sys.CubaDataSourceFactoryBean">
    <property name="storeName" value="clients"/>
</bean>

<bean id="cubaDataSource_orders" class="com.haulmont.cuba.core.sys.CubaDataSourceFactoryBean">
    <property name="storeName" value="orders"/>
</bean>

如果在应用程序中配置数据源，数据库迁移的 Gradle 任务可能没有参数，因为这些参数会通过应用程序属性获取。这是在应用程序中配置数据源的另外一个好处。示例：

task createDb(dependsOn: assembleDbScripts, description: 'Creates local database', type: CubaDbCreation) {
}

task updateDb(dependsOn: assembleDbScripts, description: 'Updates local database', type: CubaDbUpdate) {
}

从 JNDI 获取数据源

如果需要通过 JNDI 使用由应用程序服务提供的数据源，需要在 core 模块的 app.properties 文件定义以下应用程序属性：

cuba.dbmsType - 定义 DBMS 类型。
cuba.dataSourceProvider - jndi 值表示数据源必须通过 JNDI 获取。

数据源的 JNDI 名称通过 cuba.dataSourceJndiName 应用程序属性指定，默认为 java:comp/env/jdbc/CubaDS。对于附加数据存储，定义同样的属性，但是需要添加数据存储名称。

示例：

# main data store connection parameters
cuba.dbmsType = hsql
cuba.dataSourceProvider = jndi

# names of additional data stores
cuba.additionalStores = clients,orders

# 'clients' data store connection parameters
cuba.dbmsType_clients = postgres
cuba.dataSourceProvider_clients = jndi
cuba.dataSourceJndiName_clients = jdbc/ClientsDS

# 'orders' data store connection parameters
cuba.dbmsType_orders = mssql
cuba.dataSourceProvider_orders = jndi
cuba.dataSourceJndiName_orders = jdbc/OrdersDS

另外，对于每个附加数据存储，core 模块的 spring.xml 文件必须包含一个 CubaDataSourceFactoryBean bean 的定义，该定义需要使用合适的 storeName 参数和 jndiNameAppProperty 参数，示例：

<bean id="cubaDataSource_clients" class="com.haulmont.cuba.core.sys.CubaDataSourceFactoryBean">
    <property name="storeName" value="clients"/>
    <property name="jndiNameAppProperty" value="cuba.dataSourceJndiName_clients"/>
</bean>

<bean id="cubaDataSource_orders" class="com.haulmont.cuba.core.sys.CubaDataSourceFactoryBean">
    <property name="storeName" value="orders"/>
    <property name="jndiNameAppProperty" value="cuba.dataSourceJndiName_orders"/>
</bean>

通过 JNDI 提供的数据源需要根据应用程序服务做特殊的配置。在 Tomcat 中，配置在 context.xml 文件。CUBA Studio 会将连接参数写入 modules/core/web/META-INF/context.xml 并在开发应用程序时通过标准部署过程使用该文件。

如果数据源配置在 context.xml，数据库迁移的 Gradle 任务必须有定义数据库连接的参数，示例：

task createDb(dependsOn: assembleDbScripts, description: 'Creates local database', type: CubaDbCreation) {
    dbms = 'hsql'
    host = 'localhost:9111'
    dbName = 'demo'
    dbUser = 'sa'
    dbPassword = ''
}

task updateDb(dependsOn: assembleDbScripts, description: 'Updates local database', type: CubaDbUpdate) {
    dbms = 'hsql'
    host = 'localhost:9111'
    dbName = 'demo'
    dbUser = 'sa'
    dbPassword = ''
}