A newer version of Platform is available.

View latest

Configuring a Map with the Generic MapStore

5.5-SNAPSHOT 5.4 5.3 5.2 5.1 5.0

With the generic MapStore, you can configure a map to cache data in an external data store. This topic includes an example of how to configure a map with a generic MapStore that connects to a MySQL database.

For a list of all supported databases, see the built-in data store factories.

Before you Begin

You need a data store connection that’s configured on all cluster members.

Quickstart Configuration

This example shows a basic map configuration for an external datastore called my-mysql-database. See Distributed Map for the details of other properties that you include in your map configuration.

  • XML

  • YAML

  • Java

<hazelcast>
    ...
    <map name="default">
        <map-store enabled="true">
            <class-name>com.hazelcast.mapstore.GenericMapStore</class-name> (1)
            <properties>
                <property name="external-data-store-ref">my-mysql-database</property> (2)
            </properties>
        </map-store>
    </map>
    ...
</hazelcast>
hazelcast:
  map:
    default:
      map-store:
        enabled: true
        class-name: com.hazelcast.mapstore.GenericMapStore (1)
        properties:
            external-data-store-ref: my-mysql-database (2)
MapConfig mapConfig = new MapConfig("default");
MapStoreConfig mapStoreConfig = new MapStoreConfig();
mapStoreConfig.setClassName("com.hazelcast.mapstore.GenericMapStore"); (1)
mapStoreConfig.setProperty("external-data-store-ref", "my-mysql-database"); (2)
mapConfig.setMapStoreConfig(mapStoreConfig);
instance().getConfig().addMapConfig(mapConfig);
1 The class name of the generic MapStore that’s built into Hazelcast. This implementation reads from the external data store configuration to create a SQL mapping.
2 The name of your external data store configuration.

SQL Mapping for the Generic MapStore

When you configure a map with the generic MapStore, Hazelcast creates a SQL mapping with the JDBC connector. The name of the mapping is the same name as your map prefixed with __map-store.. This mapping is used to read data from the data store or write data to the data store and it is removed whenever the configured map is removed. You can also configure this SQL mapping, using configuration properties.

Configuration Properties for the Generic MapStore

These configuration properties allow you to configure the generic MapStore and its SQL mapping.

As well as these properties, you can also configure general MapStore settings.
Table 1. Generic MapStore configuration options
Option Description Default Example

external-data-store-ref (required)

The name of the configured external data store to use to set up a mapping. Use this property when you have an existing connection to an external data store.

'' (empty)

  • XML

  • YAML

  • Java

<hazelcast>
  <map name="default">
    <map-store enabled="true">
      <class-name>com.hazelcast.mapstore.GenericMapStore</class-name>
      <properties>
          <property name="external-data-store-ref">my-mysql-database</property>
      </properties>
    </map-store>
</hazelcast>
hazelcast:
  map:
    default:
      map-store:
        enabled: true
        class-name: com.hazelcast.mapstore.GenericMapStore
        properties:
            external-data-store-ref: my-mysql-database
MapConfig mapConfig = new MapConfig("default");

MapStoreConfig mapStoreConfig = new MapStoreConfig();
mapStoreConfig.setClassName("com.hazelcast.mapstore.GenericMapStore");
mapStoreConfig.setProperty("external-data-store-ref", "my-mysql-database");

mapConfig.setMapStoreConfig(mapStoreConfig);

table-name

Name of the table to read from.

The name of the map.

  • XML

  • YAML

  • Java

<hazelcast>
  <map name="default">
    <map-store enabled="true">
      <class-name>com.hazelcast.mapstore.GenericMapStore</class-name>
      <properties>
          <property name="external-data-store-ref">my-mysql-database</property>
          <property name="table-name">test</property>
      </properties>
    </map-store>
</hazelcast>
hazelcast:
  map:
    default:
      map-store:
        enabled: true
        class-name: com.hazelcast.mapstore.GenericMapStore
        properties:
            external-data-store-ref: my-mysql-database
            table-name: test
MapConfig mapConfig = new MapConfig("default");

MapStoreConfig mapStoreConfig = new MapStoreConfig();
mapStoreConfig.setClassName("com.hazelcast.mapstore.GenericMapStore");
mapStoreConfig.setProperty("external-data-store-ref", "my-mysql-database");
mapStoreConfig.setProperty("table-name", "test");

mapConfig.setMapStoreConfig(mapStoreConfig);

mapping-type

SQL connector to use for the mapping.

The SQL connector is derived from the external data store in the configuration.

  • XML

  • YAML

  • Java

<hazelcast>
  <map name="default">
    <map-store enabled="true">
      <class-name>com.hazelcast.mapstore.GenericMapStore</class-name>
      <properties>
          <property name="external-data-store-ref">my-mysql-database</property>
          <property name="mapping-type">JDBC</property>
      </properties>
    </map-store>
</hazelcast>
hazelcast:
  map:
    default:
      map-store:
        enabled: true
        class-name: com.hazelcast.mapstore.GenericMapStore
        properties:
            external-data-store-ref: my-mysql-database
            mapping-type: JDBC
MapConfig mapConfig = new MapConfig("default");

MapStoreConfig mapStoreConfig = new MapStoreConfig();
mapStoreConfig.setClassName("com.hazelcast.mapstore.GenericMapStore");
mapStoreConfig.setProperty("external-data-store-ref", "my-mysql-database");
mapStoreConfig.setProperty("mapping-type", "JDBC");

mapConfig.setMapStoreConfig(mapStoreConfig);

id-column

Name of the column that contains the primary key.

id

  • XML

  • YAML

  • Java

<hazelcast>
  <map name="default">
    <map-store enabled="true">
      <class-name>com.hazelcast.mapstore.GenericMapStore</class-name>
      <properties>
          <property name="external-data-store-ref">my-mysql-database</property>
          <property name="id-column">id</property>
      </properties>
    </map-store>
</hazelcast>
hazelcast:
  map:
    default:
      map-store:
        enabled: true
        class-name: com.hazelcast.mapstore.GenericMapStore
        properties:
            external-data-store-ref: my-mysql-database
            id-column: id
MapConfig mapConfig = new MapConfig("default");

MapStoreConfig mapStoreConfig = new MapStoreConfig();
mapStoreConfig.setClassName("com.hazelcast.mapstore.GenericMapStore");
mapStoreConfig.setProperty("external-data-store-ref", "my-mysql-database");
mapStoreConfig.setProperty("id-column", "id");

mapConfig.setMapStoreConfig(mapStoreConfig);

columns

Names of the columns to map. This value must include a subset of columns in the table. Missing columns must have a default value defined.

  • XML

  • YAML

  • Java

<hazelcast>
  <map name="default">
    <map-store enabled="true">
      <class-name>com.hazelcast.mapstore.GenericMapStore</class-name>
      <properties>
          <property name="external-data-store-ref">my-mysql-database</property>
          <property name="columns">name</property>
      </properties>
    </map-store>
</hazelcast>
hazelcast:
  map:
    default:
      map-store:
        enabled: true
        class-name: com.hazelcast.mapstore.GenericMapStore
        properties:
            external-data-store-ref: my-mysql-database
            columns: name
MapConfig mapConfig = new MapConfig("default");

MapStoreConfig mapStoreConfig = new MapStoreConfig();
mapStoreConfig.setClassName("com.hazelcast.mapstore.GenericMapStore");
mapStoreConfig.setProperty("external-data-store-ref", "my-mysql-database");
mapStoreConfig.setProperty("columns", "name");

mapConfig.setMapStoreConfig(mapStoreConfig);

Next Steps

See the MapStore configuration guide for details about configuring the MapStore and a list of configuration options.