Page Comparison

Each Carbon-based product uses a database to store information such as user management details and registry data. All nodes in the cluster must use one central database for config and governance registry mounts. These instructions assume assume you are installing MySQL as your relational database management system (RDBMS), but you can install another supported RDBMS as needed. You can create the following databases and associated data sources:

...

WSO2_USER_DB

...

datasources.

Warning

title	H2 is not recommended in production

The embedded H2 database is NOT recommended in enterprise testing and production environments. It has lower performance, clustering limitations, and can cause file corruption failures. Please use an industry-standard RDBMS such as Oracle, PostgreSQL, MySQL, or MS SQL instead.

You can use the embedded H2 database in development environments and as the local registry in a registry mount.

Database Name	Description
WSO2_USER_DB	JDBC user store and authorization manager
`REGISTRY_DB`	Shared database for config and governance registry mounts in the product's nodes
`REGISTRY_LOCAL1`	Local registry space in Manager the manager node
`REGISTRY_LOCAL2`	Local registry space in Worker the worker node

The following diagram illustrates how they these databases are connected to the manager and worker nodes.

Image Added

The following topics will guide you through all the configurations necessary to set up databases for clustering.

...

Table of Contents

maxLevel	3
minLevel	3

Creating the databases

Do the following steps to create the databases necessary. Note that we use MySQL here as an example, but you can use any suitable database instead.

Download and install MySQL Server.
Download the MySQL JDBC driver.
Unzip the downloaded MySQL driver zipped archive, and copy the MySQL JDBC driver JAR (mysql-connector-java-x.x.xx-bin.jar) into the <PRODUCT_HOME>/repository/components/lib directory of both the manager and worker nodes.
Define the host name for configuring permissions for the new database by opening the /etc/hosts file and adding the following line:
```
<MYSQL-DB-SERVER-IP> carbondb.mysql-wso2.com
```
Info
You would do this step only if your database is not on your local machine and on a separate server.
Enter the following command in a terminal/command window, where username is the username you want to use to access the databases:
mysql -u username -p
When prompted, specify the password that will be used to access the databases with the username you specified.

Create the databases using the following commands, where <PRODUCT_HOME> is the path to any of the product instances you installed, and username and password are the same as those you specified in the previous steps:

mysql> create database WSO2_USER_DB; mysql> use WSO2_USER_DB; mysql> source <PRODUCT_HOME>/dbscripts/mysql.sql; mysql> grant all on WSO2_USER_DB.* TO regadmin@carbondb.mysql-wso2.com identified by "regadmin"; mysql> create database REGISTRY_DB; mysql> use REGISTRY_DB; mysql> source <PRODUCT_HOME>/dbscripts/mysql.sql; mysql> grant all on REGISTRY_DB.* TO regadmin@carbondb.mysql-wso2.com identified by "regadmin"; mysql> create database REGISTRY_LOCAL1; mysql> use REGISTRY_LOCAL1; mysql> source <PRODUCT_HOME>/dbscripts/mysql.sql; mysql> grant all on REGISTRY_LOCAL1.* TO regadmin@carbondb.mysql-wso2.com

Code Blockinfo

language	none

title	About using MySQL in different operating systems

For users of Microsoft Windows, when creating the database in MySQL, it is important to specify the character set as latin1. Failure to do this may result in an error (error code: 1709) when starting your cluster. This error occurs in certain versions of MySQL (5.6.x) and is related to the UTF-8 encoding. MySQL originally used the latin1 character set by default, which stored characters in a 2-byte sequence. However, in recent versions, MySQL defaults to UTF-8 to be friendlier to international users. Hence, you must use latin1 as the character set as indicated below in the database creation commands to avoid this problem. Note that this may result in issues with non-latin characters (like Hebrew, Japanese, etc.). The following is how your database creation command should look.

mysql> create database <DATABASE_NAME> character set latin1;

For users of other operating systems, the standard database creation commands will suffice. For these operating systems, the following is how your database creation command should look.

mysql> create database <DATABASE_NAME>;

Code Block

language	none

mysql> create database WSO2_USER_DB;
mysql> use WSO2_USER_DB;
mysql> source <PRODUCT_HOME>/dbscripts/mysql.sql;
mysql> grant all on WSO2_USER_DB.* TO regadmin@"carbondb.mysql-wso2.com" identified by "regadmin";


mysql> create database REGISTRY_LOCAL2DB;
mysql> use REGISTRY_LOCAL2DB;
mysql> source <PRODUCT_HOME>/dbscripts/mysql.sql;
mysql> grant all on REGISTRY_LOCAL2DB.* TO regadmin@carbondbregadmin@"carbondb.mysql-wso2.com" identified by "regadmin";

On the manager node, open



mysql> create database REGISTRY_LOCAL1;
mysql> use REGISTRY_LOCAL1;
mysql> source <PRODUCT_HOME>/

repository/conf/datasources/master-datasource.xml and configure the data sources to point to the REGISTRY_LOCAL1, WSO2_REGISTRY_DB, and WSO2_USER_DB databases as follows (change the username, password, and database URL as needed for your environment):

Code Block

language	html/xml

<datasources-configuration xmlns:svns="http://org.wso2.securevault/configuration"> 
     <providers> 
        <provider>org.wso2.carbon.ndatasource.rdbms.RDBMSDataSourceReader</provider> 
    </providers> 
    <datasources> 
        <datasource> 
            <name>REGISTRY_LOCAL1</name> 
            <description>The datasource used for registry- local</description>dbscripts/mysql.sql;
mysql> grant all on REGISTRY_LOCAL1.* TO regadmin@"carbondb.mysql-wso2.com" identified by "regadmin";
 
mysql> create database REGISTRY_LOCAL2;
mysql> use REGISTRY_LOCAL2;
mysql> source <PRODUCT_HOME>/dbscripts/mysql.sql;
mysql> grant all on REGISTRY_LOCAL2.* TO regadmin@"carbondb.mysql-wso2.com" identified by "regadmin";

Configuring the manager node

Do the following configurations in the manager node of your cluster.

On the manager node, open the <PRODUCT_HOME>/repository/conf/datasources/master-datasource.xml file, and configure the datasources to point to the REGISTRY_LOCAL1, WSO2_REGISTRY_DB, and WSO2_USER_DB databases as follows (change the username, password, and database URL as needed for your environment).

Code Block

language	html/xml

<datasources-configuration xmlns:svns="http://org.wso2.securevault/configuration"> 
     <providers> 
     <jndiConfig>   <provider>org.wso2.carbon.ndatasource.rdbms.RDBMSDataSourceReader</provider> 
    </providers> 
    <datasources> 
 <name>jdbc/WSO2CarbonDB</name>       <datasource> 
     </jndiConfig>       <name>REGISTRY_LOCAL1</name> 
     <definition type="RDBMS">      <description>The datasource used for registry- local</description> 
     <configuration>       <jndiConfig> 
             <url>jdbc:mysql://carbondb.mysql-wso2.com:3306/REGISTRY_LOCAL1?autoReconnect=true</url>   <name>jdbc/WSO2CarbonDB</name> 
                 <username>regadmin</username></jndiConfig> 
               <definition type="RDBMS"> 
   <password>regadmin</password>             <configuration> 
       <driverClassName>com.mysql.jdbc.Driver</driverClassName>              <url>jdbc:mysql://carbondb.mysql-wso2.com:3306/REGISTRY_LOCAL1?autoReconnect=true</url> 
      <maxActive>50</maxActive>              <username>regadmin</username> 
       <maxWait>60000</maxWait>             <password>regadmin</password> 
       <testOnBorrow>true</testOnBorrow>             <driverClassName>com.mysql.jdbc.Driver</driverClassName> 
         <validationQuery>SELECT 1</validationQuery>          <maxActive>50</maxActive> 
          <validationInterval>30000</validationInterval>          <maxWait>60000</maxWait> 
      </configuration>              <<testOnBorrow>true</definition>testOnBorrow> 
        </datasource>          <datasource>  <validationQuery>SELECT  1</validationQuery> 
        <name>REGISTRY_DB</name>              <description>The datasource used for registry- config/governance</description><validationInterval>30000</validationInterval> 
            <jndiConfig>    </configuration> 
            <name>jdbc</WSO2RegistryDB</name>definition> 
            </jndiConfig>datasource> 
        <datasource> 
  <definition type="RDBMS">         <name>REGISTRY_DB</name> 
       <configuration>     <description>The datasource used for registry- config/governance</description> 
          <url>jdbc:mysql://carbondb.mysql-wso2.com:3306/REGISTRY_DB?autoReconnect=true</url>  <jndiConfig> 
                  <username>regadmin</username><name>jdbc/WSO2RegistryDB</name> 
            </jndiConfig> 
      <password>regadmin</password>      <definition type="RDBMS"> 
             <driverClassName>com.mysql.jdbc.Driver</driverClassName>     <configuration> 
               <maxActive>50</maxActive>     <url>jdbc:mysql://carbondb.mysql-wso2.com:3306/REGISTRY_DB?autoReconnect=true</url> 
               <maxWait>60000</maxWait>     <username>regadmin</username> 
                    <testOnBorrow>true<<password>regadmin</testOnBorrow>password> 
                    <validationQuery>SELECT 1</validationQuery><driverClassName>com.mysql.jdbc.Driver</driverClassName> 
                    <validationInterval>30000<<maxActive>50</validationInterval>maxActive> 
                </configuration>    <maxWait>60000</maxWait> 
        </definition>          </datasource>  <testOnBorrow>true</testOnBorrow> 
       <datasource>             <validationQuery>SELECT <name>WSO2_USER_DB</name>1</validationQuery> 
             <description>The datasource used for registry and user manager<<validationInterval>30000</description>validationInterval> 
            <jndiConfig>    </configuration> 
            <name>jdbc/WSO2UMDB</name></definition> 
        </datasource> 
    </jndiConfig>     <datasource> 
        <definition type="RDBMS">   <name>WSO2_USER_DB</name> 
            <description>The <configuration>datasource used for registry and user manager</description> 
            <jndiConfig> 
<url>jdbc:mysql://carbondb.mysql-wso2.com:3306/USER_DB</url>                      <username>regadmin</username><name>jdbc/WSO2UMDB</name> 
                    <password>regadmin</password></jndiConfig> 
                <definition type="RDBMS"> 
  <driverClassName>com.mysql.jdbc.Driver</driverClassName>              <configuration> 
      <maxActive>50</maxActive>              <url>jdbc:mysql://carbondb.mysql-wso2.com:3306/WSO2_USER_DB</url> 
      <maxWait>60000</maxWait>              <username>regadmin</username> 
        <testOnBorrow>true</testOnBorrow>            <password>regadmin</password> 
         <validationQuery>SELECT 1</validationQuery>          <driverClassName>com.mysql.jdbc.Driver</driverClassName> 
          <validationInterval>30000</validationInterval>          <maxActive>50</maxActive> 
      </configuration>              <<maxWait>60000</definition>maxWait> 
          </datasource>     </datasources>  </datasources-configuration>

Info
Make sure to replace `username` and `password` with your MySQL database username and password.

Repeat this configuration on the worker node, this time configuring the local registry to point to REGISTRY_LOCAL2:

Code Block

language	html/xml

<datasources-configuration xmlns:svns="http://org.wso2.securevault/configuration">   <testOnBorrow>true</testOnBorrow> 
           <providers>          <provider>org.wso2.carbon.ndatasource.rdbms.RDBMSDataSourceReader</provider><validationQuery>SELECT 1</validationQuery> 
    </providers>      <datasources>          <datasource><validationInterval>30000</validationInterval> 
            <name>REGISTRY_LOCAL2</name>    </configuration> 
        <description>The datasource used for registry- local</description></definition> 
        </datasource> 
  <jndiConfig> 
                <name>jdbc/WSO2CarbonDB</name> 
            </jndiConfig> 
            <definition type="RDBMS"> 
                <configuration> 
                    <url>jdbc:mysql://carbondb.mysql-wso2.com:3306/REGISTRY_LOCAL2?autoReconnect=true</url> 
  </datasources> 
</datasources-configuration>

Info
Make sure to replace `username` and `password` with your MySQL database username and password.

To configure the datasource, update the dataSource property found in <PRODUCT_HOME>/repository/conf/user-mgt.xml of the manager node as shown below:
Code Block
language html/xml
<Property name="dataSource">jdbc/WSO2UMDB</Property>

Configuring the worker node

Do the following configurations in the worker node of your cluster.

On the worker node, open the <PRODUCT_HOME>/repository/conf/datasources/master-datasource.xml file and configure the datasources to point to the REGISTRY_LOCAL2, WSO2_REGISTRY_DB, and WSO2_USER_DB databases as follows (change the username, password, and database URL as needed for your environment):

Code Block

language	html/xml

<datasources-configuration xmlns:svns="http://org.wso2.securevault/configuration"> 
     <providers> 
         <username>regadmin</username><provider>org.wso2.carbon.ndatasource.rdbms.RDBMSDataSourceReader</provider> 
    </providers> 
    <datasources> 
        <password>regadmin</password><datasource> 
            <name>REGISTRY_LOCAL2</name> 
      <driverClassName>com.mysql.jdbc.Driver</driverClassName>      <description>The datasource used for registry- local</description> 
         <maxActive>50</maxActive>   <jndiConfig> 
                 <maxWait>60000</maxWait><name>jdbc/WSO2CarbonDB</name> 
            </jndiConfig> 
      <testOnBorrow>true</testOnBorrow>      <definition type="RDBMS"> 
             <validationQuery>SELECT 1</validationQuery>  <configuration> 
                  <validationInterval>30000</validationInterval> 
  <url>jdbc:mysql://carbondb.mysql-wso2.com:3306/REGISTRY_LOCAL2?autoReconnect=true</url> 
              </configuration>      <username>regadmin</username> 
      </definition>          </datasource>    <password>regadmin</password> 
    <datasource>              <name>REGISTRY_DB</name>  <driverClassName>com.mysql.jdbc.Driver</driverClassName> 
           <description>The     datasource used for registry- config/governance</description><maxActive>50</maxActive> 
                 <jndiConfig>   <maxWait>60000</maxWait> 
             <name>jdbc/WSO2RegistryDB</name>       <testOnBorrow>true</testOnBorrow> 
      </jndiConfig>              <definition type="RDBMS"><validationQuery>SELECT 1</validationQuery> 
                <configuration>    <validationInterval>30000</validationInterval> 
                <url>jdbc:mysql://carbondb.mysql-wso2.com:3306/REGISTRY_DB?autoReconnect=true</url></configuration> 
            </definition> 
        <username>regadmin<</username>datasource> 
        <datasource> 
          <password>regadmin</password>  <name>REGISTRY_DB</name> 
            <description>The datasource used for   <driverClassName>com.mysql.jdbc.Driver</driverClassName>registry- config/governance</description> 
            <jndiConfig> 
      <maxActive>50</maxActive>          <name>jdbc/WSO2RegistryDB</name> 
          <maxWait>60000</maxWait>  </jndiConfig> 
            <definition type="RDBMS"> 
   <testOnBorrow>true</testOnBorrow>             <configuration> 
       <validationQuery>SELECT 1</validationQuery>            <url>jdbc:mysql://carbondb.mysql-wso2.com:3306/REGISTRY_DB?autoReconnect=true</url> 
        <validationInterval>30000</validationInterval>                  </configuration><username>regadmin</username> 
            </definition>          </datasource> <password>regadmin</password> 
        <datasource>              <name>WSO2_USER_DB</name><driverClassName>com.mysql.jdbc.Driver</driverClassName> 
             <description>The datasource used for registry and user manager</description><maxActive>50</maxActive> 
                  <jndiConfig>  <maxWait>60000</maxWait> 
              <name>jdbc/WSO2UMDB</name>      <testOnBorrow>true</testOnBorrow> 
      </jndiConfig>              <definition type="RDBMS"><validationQuery>SELECT 1</validationQuery> 
                <configuration>    <validationInterval>30000</validationInterval> 
                <url>jdbc:mysql://carbondb.mysql-wso2.com:3306/USER_DB</url></configuration> 
            </definition> 
        <username>regadmin<</username>datasource> 
         <datasource> 
         <password>regadmin</password>   <name>WSO2_USER_DB</name> 
            <description>The datasource used for  <driverClassName>com.mysql.jdbc.Driver</driverClassName> 
registry and user manager</description> 
            <jndiConfig> 
    <maxActive>50</maxActive>            <name>jdbc/WSO2UMDB</name> 
        <maxWait>60000</maxWait>    </jndiConfig> 
            <definition    <testOnBorrow>true</testOnBorrow>type="RDBMS"> 
                <configuration> 
                    <url>jdbc:mysql://carbondb.mysql-wso2.com:3306/WSO2_USER_DB</url> 
                     <validationQuery>SELECT 1</validationQuery> 
                    <validationInterval>30000</validationInterval> 
                </configuration> 
            </definition> 
        </datasource> 
   </datasources> 
</datasources-configuration>

Info
Make sure to replace `username` and `password` with your MySQL database username and password.

To configure the datasource, update the dataSource property found in <PRODUCT_MANAGER_HOME>/repository/conf/user-mgt.xml as shown below:
Code Block
language html/xml
<Property name="dataSource">jdbc/WSO2UMDB</Property>

      <username>regadmin</username> 
                    <password>regadmin</password> 
                    <driverClassName>com.mysql.jdbc.Driver</driverClassName> 
                    <maxActive>50</maxActive> 
                    <maxWait>60000</maxWait> 
                    <testOnBorrow>true</testOnBorrow> 
                    <validationQuery>SELECT 1</validationQuery> 
                    <validationInterval>30000</validationInterval> 
                </configuration> 
            </definition> 
        </datasource> 
   </datasources> 
</datasources-configuration>

Info
Make sure to replace `username` and `password` with your MySQL database username and password.

To configure the datasource, update the dataSource property found in <PRODUCT_HOME>/repository/conf/user-mgt.xml of the worker node as shown below.
Code Block
language html/xml
<Property name="dataSource">jdbc/WSO2UMDB</Property>

Mounting the registry on manager and worker nodes

We do this step to ensure that the shared registry for governance and config is mounting to both the nodes. This database is REGISTRY_DB.

Configure the shared registry database and mounting details in the <PRODUCT_HOME>/repository/conf/registry.xml file of the manager node as shown below:

Tip
Note: The existing `dbConfig` called `wso2registry` must not be removed when adding the following configurations.

Code Block

language	html/xml

<dbConfig name="sharedregistry">
	<dataSource>jdbc/WSO2RegistryDB</dataSource>
</dbConfig>

<remoteInstance url="https://localhost:9443/registry">
	<id>instanceid</id>
	<dbConfig>sharedregistry</dbConfig>
	<readOnly>false</readOnly>
	<enableCache>true</enableCache>
	<registryRoot>/</registryRoot>
	<cacheId>regadmin@jdbc:mysql://carbondb.mysql-wso2.com:3306/REGISTRY_DB?autoReconnect=true</cacheId>
</remoteInstance>

<mount path="/_system/config" overwrite="true">
	<instanceId>instanceid</instanceId>
	<targetPath>/_system/asNodes</targetPath>
</mount>

<mount path="/_system/governance" overwrite="true">
	<instanceId>instanceid</instanceId>
	<targetPath>/_system/governance</targetPath>
</mount>

Configure the shared registry database and mounting details in <PRODUCT_

...

HOME>/repository/conf/registry.xml

...

of the worker node as shown below:

Code Block

language	html/xml

<dbConfig name="sharedregistry">
	<dataSource>jdbc/WSO2RegistryDB</dataSource>
</dbConfig>

<remoteInstance url="https://localhost:9443/registry">
	<id>instanceid</id>
	<dbConfig>sharedregistry</dbConfig>

...

<readOnly>true</readOnly>
	<enableCache>true</enableCache>
	<registryRoot>/</registryRoot>

...

<cacheId>regadmin@jdbc:mysql://carbondb.mysql-wso2.com:3306/REGISTRY_

...

DB?autoReconnect=true</cacheId>
</remoteInstance>

<mount path="/_system/config" overwrite="true">
	<instanceId>instanceid</instanceId>
	<targetPath>/_system/asNodes</targetPath>
</mount>

<mount path="/_system/governance" overwrite="true">
	<instanceId>instanceid</instanceId>
	<targetPath>/_system/governance</targetPath>
</mount>

The following

...

are some key points to note when adding these configurations:

The dataSource you specify under the <dbConfig name="sharedregistry"> tag must match the jndiConfig name specified in the master-datasources.xml file of the manager and worker.
The registry mount path is used to identify the type of registry. For example, ”/_system/config” refers to configuration registry, and "/_system/governance" refers to the governance registry.

This configuration

The dbconfig entry enables you to identify the

data source

datasource you configured in the master-datasources.xml file

using the

dbConfig

entry and we give a unique name to

. We use the unique name sharedregistry to refer to that datasource entry

which is “

sharedregistry

”

.
The remoteInstance section refers to an external registry mount. We can specify the read-only/read-write nature of this instance as well as caching configurations and the registry root location. In case of a worker node

the

, the readOnly

property

property should

be

be true, and in case of a manager node, this property should be set

to

to false.
Additionally, we

need to specify

cacheId

for

must specify cacheId, which enables caching to function properly in the clustered environment. Note that cacheId is the same as the JDBC connection URL

to our

of the registry database. This value is

the

the cacheId

of

of the remote instance. Here

the

the cacheId

should

should be in the format

of

of $database_username@$database_url,

where $database

where $database_username

is

is the username of the remote instance database

and $database

and $database_url

is

is the remote instance database URL.

This

This cacheID

is

is used to identify the cache it should look for when caching is enabled

. In this case, the database we should connect to is

WSO2CARBON_DB.

You need to

. In this case, the database we should connect to is REGISTRY_DB, which is the database shared across all the master/workers nodes. You can identify that by looking in the mounting configurations, where the same datasource is being used.
You must define a unique name “id” for each remote instance, which is then referred to from mount configurations. In the above example, the unique

id

ID for the remote instance is instanceId.
In each of the mounting configurations, we specify the actual mount path and target mount path. The targetPath can be any meaningful name. In this instance, it is /_system/asNodes.

Now your database is set up. The next step is to configure the manager and worker node.

Excerpt

hidden	true

All This topic encompasses all configurations related to creating and setting up databases for the products in your cluster are found in this topic. This includes configurations you would have to make in both the manager node and the worker node.

Versions Compared

Old Version 29

New Version Current

Key

Creating the databases

Configuring the manager node

Configuring the worker node

Mounting the registry on manager and worker nodes