Data Stores

When a Jmix application is created, the main data store already exists and can be accessed from the Jmix Tool Window.

data tree

By double-clicking, you can open the properties dialog of the data store. By default, HSQLDB is set as a database type.

data properties

The following properties are available both for the main and additional data stores:

  • Database type - type of the database server. You can select one of the available databases from the list.

  • Database URL - a host, port, and database name.

    • Connection params - other connection parameters. The format of the connection parameters depends on the selected DBMS. The string should include a separator between the database name and parameters. You can use the pencil button in the right part of the Connection params field to enter connection parameters conveniently. In this case, Studio automatically forms the connection string by adding DBMS-specific separator characters.

      data params

    • Show raw URL - shows connection parameters as URL.

    • Integrated Security - enables the corresponding authentication option when connecting to the Microsoft SQL Server 2012+ database.

  • Database user and Password - database connection credentials.

If you use profile-specific configuration files, the Data Store Properties editor will read and write properties to and from the profile instead of application.properties.

You can use placeholders of the following type ${VAR:default_value} where VAR is an environment variable to set database properties.

data vars

Studio resolves the placeholders and uses the resulting values for all operations with the database: test connection, recreate, update, Liquibase diff, and so on.

Supported DB Types section contains the Enable support for several DB types checkbox. If this checkbox is activated, you can select more than one supported databases. Studio will generate one set of Liquibase migration scripts supporting all selected database types.

Database Identifiers Length Mode section allows you to select one of the three available modes:

  • Oracle - maximum 30 symbols length of tables, columns, indexes, other names.

  • Postgres - maximum 64 symbols length of tables, columns, indexes, other names.

  • Unlimited - unlimited length of tables, columns, indexes, other names.

Additional Data Store

To create additional data store, use an action from the context menu. Another way is to select the one from Advanced:

data advanced

See the description of the database properties common for both the main and additional data stores above.

data schema

For the additional data store, specify Data store name and select an option in the DB Schema Management section:

  • Disabled - Studio doesn’t track database schema changes for this data store. This is the default mode.

  • Update Only - provides the Update action and creates Liquibase changelogs.

  • Create and Update - provides the Update and Recreate actions and creates Liquibase scripts.

Connecting to Unsupported Databases

You can define an additional data store connected to a database not supported by Jmix natively.

This feature is currently in the preview state and disabled by default. To enable it, press Shift twice, select the Jmix Features item in the opened list and check the Generic Database Support for Additional Data Store checkbox.

After enabling it, when you create an additional data store, you will see the Generic DB option in the Database type dropdown. If you select this option, Studio will allow you to enter the following parameters:

  • DBMS type - an arbitrary identifier of the database type, used also as a prefix for the database-specific classes (explained below). Enter a short string containing only lowercase alphanumeric characters, for example, foo.

  • Database URL - the full JDBC connection URL, for example, jdbc:foosql://localhost/database.

  • Driver class name - the class name of the JDBC driver, for example org.foosql.Driver.

  • Driver artifact - JDBC driver artifact coordinates, for example, org.foosql:foosql:1.0.0.

  • Connection test query - an SQL query for testing the connection, for example, select 1.

  • Database platform - a class extending org.eclipse.persistence.platform.database.DatabasePlatform which describes the database for the EclipseLink ORM framework. You can select an existing class if it suits your database or choose the Create DatabasePlatform class option to create a new class.

data store unsupported

Click OK.

Studio will create the usual Myds1StoreConfiguration class with the required beans in the base package. It will also create the following stubs in the <base-package>/dbms package:

  • FooPlatform - a class extending DatabasePlatform. It describes the database for the EclipseLink ORM framework.

  • FooDbmsFeatures - a class implementing the DbmsFeatures interface. It describes the database for the Jmix framework.

  • FooSequenceSupport - a class implementing the SequenceSupport interface. It describes how sequences should be handled in this database.

  • FooDbTypeConverter - a class implementing the DbTypeConverter interface. It defines methods for converting data between Java objects and JDBC parameters and results.

Studio will also add the org.foosql:foosql:1.0.0 dependency to your build.gradle file.

Now you should implement the methods in the generated stubs appropriately. Use framework classes like JmixPostgreSQLPlatform, PostgresqlDbmsFeatures, and so on as examples.

Data Store Actions

By right-clicking the data store item in the Jmix project tree, you can open its context menu:

data actions

The number of actions shown in the menu depends on the data store type and DB schema management mode.

  • New → Additional Data Store - opens the dialog for creating a new data store.

  • New → Liquibase Changelog - generates a new changelog file with a correct name.

  • Manage Data Store - opens the dialog to edit data store settings.

  • Delete Data Store - removes the data store along with all associated configuration files and Liquibase changelogs.

  • Recreate - recreates database belonging to the selected data store. Applicable for the main data store and additional data stores with Create and Update schema management type.

  • Update - updates database schema for the selected data store. Applicable for the main data store and additional data stores with Update Only and Create and Update schema management types.

  • Generate Liquibase Changelog - generates changelog files for the selected data store by comparing data model with the database schema. Applicable for the main data store and additional data stores with Update Only and Create and Update schema management types.

    This feature is free to use in small projects with up to 10 entities and roles. In a larger project, it requires a RAD or Enterprise subscription.

  • Check Liquibase Changelog Includes - checks that includes in the root changelog correspond to the add-ons used in the project. If there is a mismatch, Studio shows a notification dialog and suggests adding or removing includes.

  • Aggregate Liquibase Changelogs - allows you to combine multiple recent changelogs into a single file, eliminating duplicate actions within changesets.

    This feature can be used by developers before each commit to a shared code repository. It helps to maintain a tidy collection of changelogs and reduces the application startup time due to fewer changesets.

    The Aggregate Liquibase Changelogs action launches a wizard that enables the developer to customize the aggregated changelog.

  • Generate Model from Database - generates a data model from a database.

  • Jump to Source - opens a Spring configuration class.