Database Preparation

Tigase uses generally the same database schema and the same set of stored procedures and functions on every database. However, the schema creation scripts and code for stored procedures is different for each database. Therefore the manual process to prepare database is different for each database system.

Of course the simplest and easiest way to prepare database is to use Tigase installer or webinstaller which automates the whole process. Sometimes this is not possible. A second option is to use the DBSchemaLoader utility in Tigase. If either of those won’t work, or won’t suit your needs, provided are set of guides describing initialization and preparation process for each supported database.

-The DBSchemaLoader Utility - Prepare the MySQL Database for the Tigase Server - Hashed User Passwords in Database - Prepare the Derby Database for the Tigase Server - Prepare the MS SQL Server Database for the Tigase Server - Prepare the PostgreSQL Database for the Tigase Server

dbSchemaLoader Utility

Included with Tigase is the dbSchemaLoader Utility, which can be used to apply schema files to databases. It is able to operate with Derby, MySQL, SQLServer, and PostgreSQL databases. In order to use this utility with any of the databases, you will need to first have the database environment up and running, and have established user credentials. You may use root or an account with administrator write privileges.

Important

All commands in this guide are required to be running from the Tigase installation directory.

Operation & Variables

First, lets cover the DBSchemaLoader operation and variables:

Operation The utility is run using the java -cp command from the Tigase installation directory. Be sure that you have JDK v1.8 or later installed. Linux

java -cp "jars/*" tigase.util.DBSchemaLoader

or from a Windows environment

java -cp jars/* tigase.util.DBSchemaLoader

These commands will be followed by a combination of the following variables

Variables

Use the following options to customize. Options in bold are required, {potential options are in brackets}.
  • -dbType database_type {derby, mysql, postgresql, sqlserver}
  • -schemaVersion schema version {4, 5, 5-1}
  • -dbName database name
  • -dbHostname database hostname (default is localhost)
  • -dbUser tigase username
  • -dbPass tigase user password
  • -rootUser database root username
  • -rootPass database root password
  • -file path to sql schema file {database/derby-schema-7-1.sql}
  • -query sql query to execute
  • -logLevel java logger Level
  • -adminJID comma separated list of admin JIDs
  • -adminJIDpass password (one for all entered JIDs)

With that out of the way, lets look at some examples. Lets say you have a new mysql database server with root user root and password rood (to keep things simple, we do not recommend this). The MySQL database is hosted locally, your command would be as follows:

java -cp "jars/*" tigase.util.DBSchemaLoader -dbType mysql -dbName tigasedb -rootUser root -rootPass root -schemaVersion -adminJID admin@example.com -adminJIDpass password 7.1 -file database/mysql-schema-7-1.sql

This will create the tigasedb database, add an Admin user as admin@example.com with password 'password', and apply the v7.1 schema files. Output will look like this:

LogLevel: CONFIG

tigase.util.DBSchemaLoader     	 <init>          	 CONFIG     Properties: [{dbHostname=localhost, logLevel=CONFIG, adminJID=admin@example.com, dbType=mysql, file=database/mysql-schema-7-1.sql, rootUser=root, adminJIDpass=password, dbPass=tigase_pass, dbName=tigasedb, schemaVersion=7.1, rootPass=root, dbUser=tigase_user}]

tigase.util.DBSchemaLoader     	 validateDBConnection 	 INFO       Validating DBConnection, URI: jdbc:mysql://localhost/?user=root&password=root

tigase.util.DBSchemaLoader     	 validateDBConnection 	 CONFIG     DriverManager (available drivers): [[org.apache.derby.jdbc.AutoloadedDriver@10f87f48, org.postgresql.Driver@1b2c6ec2, com.mysql.jdbc.Driver@50040f0c, jTDS 1.3.1]]

tigase.util.DBSchemaLoader     	 validateDBConnection 	 INFO       Connection OK
tigase.util.DBSchemaLoader     	 validateDBExists 	 INFO       Validating whether DB Exists, URI: jdbc:mysql://localhost/tigasedb?user=tigase_user&password=tigase_pass

tigase.util.DBSchemaLoader     	 validateDBExists 	 INFO       Doesn't exist, creating...

tigase.util.DBSchemaLoader     	 validateDBExists 	 INFO        OK

tigase.util.DBSchemaLoader     	 loadSchemaFile  	 INFO       Loading schema from file: database/mysql-schema-7-1.sql, URI: jdbc:mysql://localhost/tigasedb?user=root&password=root
tigase.util.DBSchemaLoader     	 loadSchemaFile  	 INFO        completed OK

tigase.util.DBSchemaLoader     	 printInfo       	 INFO

Database init.properties configuration:

--user-db=mysql
--user-db-uri=jdbc:mysql://localhost/tigasedb user=tigase_user&password=tigase_pass&useUnicode=true&characterEncoding=UTF-8

Tip

The utility will automatically generate the lines you need to add to your init.properties file to use this database!

At this time, it is suggested to load the PubSub schema since you will have to change very little of the command:

java -cp "jars/*" tigase.util.DBSchemaLoader -dbType mysql -dbName tigasedb -rootUser root -rootPass root -file database/mysql-pubsub-schema-3.2.0.sql

Should you wish to use the Socks5 Proxy component, you will need to load that schema as well

java -cp "jars/*" tigase.util.DBSchemaLoader -dbType mysql -dbName tigasedb -rootUser root -rootPass root -file database/mysql-socks5-schema.sql

At this time you’re finished setting up a database for use with Tigase! For other databases that are supported, the operations will be very similar with only the -dbType and perhaps the -dbHostname being different.

-Query function

Should you decide to customize your own functions, or have specific information you want to put into the database, you can use the -query function to perform a single query step.

java -cp "jars/*" tigase.util.DBSchemaLoader -dpType mysql -dbName tigasedb -rootUser root -rootPass root -query "CREATE TABLE tigasedb.EXTRA_TABLE (id INT(6) UNSIGNED AUTO_INCREMENT PRIMARY KEY, name VARCHAR(10) NOT NULL)"

Of course this would break the schema for tigasedb by adding an unexpected table, you will receive the following message:

tigase.util.DBSchemaLoader       printInfo          WARNING       Database schema is invalid
A note about MySQL

If you are using these commands, you may result in the following error:

tigase.util.DBSchemaLoader       validateDBConnection    WARNING    Table 'performance_schema.session_variables' does not exist

If this occurs, you will need to upgrade your version of MySQL using the following command:

mysql_upgrade -u root -p --force

After entering the password and upgrading MySQL the schema error should no longer show when working with Tigase databases.

But this is a demonstration how you may run a query through the database without the need to use another tool. Note that you will need to select the specific database for each query.

Prepare the MySQL Database for the Tigase Server

This guide describes how to prepare MySQL database for connecting Tigase server.

Basic Setup

The MySQL database can be prepared in many ways. Most Linux distributions contain tools which allow you to go through all steps from the shell command line. To make sure it works on all platforms in the same way, we will first show how to do it under MySQL command line client.

Configuring from MySQL command line tool

Run the MySQL command line client in either Linux or MS Windows environment and enter following instructions:

  1. Create the database for the Tigase server:

    mysql> create database tigasedb;
  2. Add the tigase_user user and grant him access to the tigasedb database. Depending on how you plan to connect to the database (locally or over the network) use one of following commands or all if you are not sure:

    Grant access to tigase_user connecting from any network address.

    mysql> GRANT ALL ON tigasedb.* TO tigase_user@'%'
                IDENTIFIED BY 'tigase_passwd';

    Grant access to tigase_user connecting from localhost.

    mysql> GRANT ALL ON tigasedb.* TO tigase_user@'localhost'
                IDENTIFIED BY 'tigase_passwd';

    Grant access to tigase_user connecting from local machine only.

    mysql> GRANT ALL ON tigasedb.* TO tigase_user
                IDENTIFIED BY 'tigase_passwd';

    For the Tigase server version 4.x additional permissions must be granted for the database user:

    mysql> GRANT SELECT, INSERT, UPDATE ON mysql.proc TO 'tigase_user'@'localhost';
    mysql> GRANT SELECT, INSERT, UPDATE ON mysql.proc TO 'tigase_user'@'%';
    mysql> GRANT SELECT, INSERT, UPDATE ON mysql.proc TO 'tigase_user';

    And now you can update user permission changes in the database:

    mysql> FLUSH PRIVILEGES;
  3. Load the proper mysql schema into the database. Full installations of Tigase will have all the SQL file you need to create and update the database. First, switch to the database you have just created:

    mysql> use tigasedb;

    We are assuming you run the mysql client in Linux from the Tigase installation directory.

    mysql> source database/mysql-7-1-schema.sql;

    For the Tigase server version v7.1.0 you have to use proper schema version which is 5.1. You will also need to manually load the PubSub schema as well, current version is v3.2.0. All modern versions will load previous schemas first so no need to do a manual upgrade.

    mysql> source database/mysql-pubsub-schema-3.2.0.sql;

    If you plan to use the Socks5 component, you will also need to add that schema as well.

    mysql> source database/mysql-socks5-schema.sql;

    On Windows you have probably to enter the full path, assuming Tigase is installed in C:\Program Files\Tigase:

    mysql> source c:/Program Files/Tigase/database/mysql-7-1-schema.sql;
    mysql> source c:/Program Files/Tigase/database/mysql-pubsub-schema-3.2.0.sql;
    mysql> source c:/Program Files/Tigase/database/mysql-socks5-schema.sql;

Configuring From the Linux Shell Command Line

Follow steps below to prepare the MySQL database:

  1. Create the database space for the Tigase server:
mysqladmin -p create tigasedb
  1. Add the tigase_user user and grant access to the tigasedb database. Depending on how you plan to connect to the database (locally or over the network) use one of following commands or all if you are not sure: Grant access to tigase_user connecting from any network address.
echo "GRANT ALL ON tigasedb.* TO tigase_user@'%' \
            IDENTIFIED BY 'tigase_passwd'; \
            FLUSH PRIVILEGES;" | mysql -u root -pdbpass mysql

Grant access to tigase_user connecting from localhost.

echo "GRANT ALL ON tigasedb.* TO tigase_user@'localhost' \
            IDENTIFIED BY 'tigase_passwd'; \
            FLUSH PRIVILEGES;" | mysql -u root -pdbpass mysql

Grant access to tigase_user connecting from local machine only.

echo "GRANT ALL ON tigasedb.* TO tigase_user \
            IDENTIFIED BY 'tigase_passwd'; \
            FLUSH PRIVILEGES;" | mysql -u root -pdbpass mysql
  1. Load the proper mysql schema into the database. Full installations of Tigase will have all the SQL file you need to create and update the database.
mysql -u dbuser -p tigasedb < mysql-schema-7-1.sql
mysql -u dbuser -p tigasedb < mysql-pubsub-schema-3.2.0.sql

If you want to use the socks5 component, then oyu will need to include the following line as well:

mysql -u dbuser -p tigasedb < mysql-socks5-schema.sql

Configuring MySQL for UTF-8 Support

In my.conf put following lines:

[mysql]
default-character-SET=utf8

[client]
default-character-SET=utf8

[mysqld]
init_connect='SET collation_connection = utf8_general_ci; SET NAMES utf8;'
character-set-server=utf8
default-character-SET=utf8
collation-server=utf8_general_ci
skip-character-set-client-handshake

Then connect to the database from the command line shell check settings:

SHOW VARIABLES LIKE 'character_set_database';
SHOW VARIABLES LIKE 'character_set_client';

If any of these shows something else then 'utf8' then you need to fix it using the command:

ALTER DATABASE tigasedb DEFAULT CHARACTER SET utf8;

You can now also test your database installation if it accepts UTF-8 data. The easiest way to ensure this is to just to create an account with UTF-8 characters:

call TigAddUserPlainPw('żółw@some.domain.com', 'żółw');

And then check that the account has been created:

SELECT * FROM tig_users WHERE user_id = 'żółw@some.domain.com';

If the last command gives you no results it means there is still something wrong with your settings. You might also want to check your shell settings to make sure your command line shell supports UTF-8 characters and passes them correctly to MySQL:

export LANG=en_US.UTF-8
export LOCALE=UTF-8
export LESSCHARSET='utf-8'

It seems that MySQL 5.0.x also needs extra parameters in the connection string: '&useUnicode=true&characterEncoding=UTF-8' while MySQL 5.1.x seems to not need it but it doesn’t hurt to have it for both versions. You have to edit 'etc/init.properties' file and append this to the database connection string.

For MySQL 5.1.x, however, you need to also update code for all database stored procedures and functions used by the Tigase. They are updated for Tigase version 4.4.x and up, however if you use an older version of the Tigase server, you can reload stored procedures using the file from SVN.

Other MySQL Settings Worth Considering

There are a number of other useful options, especially for performance improvements. Please note, you will have to review them as some of them may impact data reliability and are useful for performance or load tests installations only.

# InnoDB seems to be a better choice
# so lets make it a default DB engine
default-storage-engine = innodb

Some the general MySQL settings which mainly affect performance:

key_buffer = 64M
max_allowed_packet = 32M
sort_buffer_size = 64M
net_buffer_length = 64K
read_buffer_size = 16M
read_rnd_buffer_size = 16M
thread_stack = 192K
thread_cache_size = 8
query_cache_limit = 10M
query_cache_size = 64M

InnoDB specific settings:

# Keep data in a separate file for each table
innodb_file_per_table = 1
# Allocate memory for data buffers
innodb_buffer_pool_size = 1000M
innodb_additional_mem_pool_size = 100M
# A location of the MySQL database
innodb_data_home_dir = /home/databases/mysql/
innodb_log_group_home_dir = /home/databases/mysql/
# The main thing here is the 'autoextend' property
# without it your data file may reach maximum size and
# no more records can be added to the table.
innodb_data_file_path = ibdata1:10M:autoextend
innodb_log_file_size = 10M
innodb_log_buffer_size = 32M
# Some other performance affecting settings
innodb_flush_log_at_trx_commit = 2
innodb_lock_wait_timeout = 50
innodb_thread_concurrency = 16

These settings may not be fully optimized for your system, and have been only tested on our systems. If you have found better settings for your systems, feel free to let us know.

Prepare the Derby Database for the Tigase Server

This guide describes how to prepare Derby database for connecting the Tigase server.

Basic Setup

Preparation of Derby database is quite simple, but the following assumptions are made

  • DerbyDB - Derby database name
  • database/ directory contains all necessary schema files
  • jars/ and libs/ directories contains Tigase and Derby binaries
General Approach

From the main Tigase directory execute following commands (Linux and Windows accordingly)

Linux

java -Dij.protocol=jdbc:derby: -Dij.database="DerbyDB;create=true" -cp libs/derby.jar:libs/derbytools.jar:jars/tigase-server.jar org.apache.derby.tools.ij database/derby-schema-7.1.sql

Windows

java -Dij.protocol=jdbc:derby: -Dij.database="DerbyDB;create=true" -cp libs\derby.jar;libs\derbytools.jar;jars\tigase-server.jar org.apache.derby.tools.ij "database\derby-schema-7-1.sql"

This will create Derby database named DerbyDB in the main Tigase directory and load Tigase schema for version 7.1.

You will need to repeat this process again to add the PubSub schema into the database.

Linux

java -Dij.protocol=jdbc:derby: -Dij.database="DerbyDB;create=true" -cp libs/derby.jar:libs/derbytools.jar:jars/tigase-server.jar org.apache.derby.tools.ij database/derby-pubsub-schema-3.2.0.sql

Windows

java -Dij.protocol=jdbc:derby: -Dij.database="DerbyDB;create=true" -cp libs\derby.jar;libs\derbytools.jar;jars\tigase-server.jar org.apache.derby.tools.ij "database\derby-pubsub-schema-3.2.0.sql"

If you wish to use the Sock5 Proxy Component, you will need to add that schema as well:

Linux

java -Dij.protocol=jdbc:derby: -Dij.database="DerbyDB;create=true" -cp libs/derby.jar:libs/derbytools.jar:jars/tigase-server.jar org.apache.derby.tools.ij database/derby-socks5-schema.sql

Windows

java -Dij.protocol=jdbc:derby: -Dij.database="DerbyDB;create=true" -cp libs\derby.jar;libs\derbytools.jar;jars\tigase-server.jar org.apache.derby.tools.ij "database\derby-socks5-schema.sql"

Connecting Tigase to database

Once the database is setup, configure the init.properties file in Tigase and add the following configuration:

jdbc:derby:{location of derby database};

Prepare the MS SQL Server Database for the Tigase Server

This guide describes how to prepare the MS SQL Server database for connecting the Tigase server to it.

Basic Setup

It’s expected that a working installation of Microsoft SQL Server is present. The following guide will describe the necessary configurations required for using MS SQL Server with Tigase XMPP Server.

Preparing MS SQL Server Instance

After installation of MS SQL Server an instance needs to be configure to handle incoming JDBC connections. For that purpose it’s required to open SQL Server Configuration Manager. In the left-hand side panel navigate to SQL Server Configuration Manager, then SQL Server Network Configuration → Protocols for ${INSTANCE_NAME}. After selecting instance in the right-hand side panel select TCP/IP and open Properties, in the Protocol tab in General section select Yes for Enabled property. In the IP Addresses tab select Yes for Active and Enabled properties of all IP Addresses that you want MS SQL Server to handle. Subsequently set the TCP Port property (if missing) to the default value - 1433. A restart of the instance may be required afterwards.

Configuration using MS SQL Server Management Studio

In order to prepare the database you can use either a wizard or execute queries directly in the Query Editor. Firstly you need to establish a connection to the MS SQL Server instance. From Object Explorer select Connect and in the Connect to Server dialog enter administrator credentials.

Using Wizards
  • Create Login

    In the left-hand side panel select Security → Logins and from context menu choose New Login, in the Wizard window enter desired Login name, select SQL Server authentication and enter desired password subsequently confirming action with OK

  • Create Database

    From the Object Explorer select Databases node and from context menu select New Database; in the Wizard window enter desired Database name and enter previously created Login name into Owner field; subsequently confirming action with OK.

Using Queries

From the Object Explorer root node’s context menu select New Query. In the Query windows execute following statements adjusting details to your liking:

USE [master]
GO

CREATE DATABASE [tigasedb];
GO

CREATE LOGIN [tigase] WITH PASSWORD=N'tigase12', DEFAULT_DATABASE=[tigasedb]
GO

ALTER AUTHORIZATION ON DATABASE::tigasedb TO tigase;
GO

Import Schema

From the File menu Select Open → File (or use Ctrl+O) and then open following files:

  • sqlserver-schema-7-1-schema.sql
  • sqlserver-schema-7-1-sp.sql
  • sqlserver-schema-7-1-props.sql
  • sqlserver-pubsub-schema-3.2.0.sql

Subsequently select created database from the list of Available Databases (Ctrl+U) available on the toolbar and execute each of the opened files in the order listed above.

Configuring from command line tool

Creation of the database and import of schema can be done from command line as well. In order to do that, execute following commands from the directory where Tigase XMPP Server is installed otherwise paths to the schema need to be adjusted accordingly:

sqlcmd -S %servername% -U %root_user% -P %root_pass% -Q "CREATE DATABASE [%database%]"
sqlcmd -S %servername% -U %root_user% -P %root_pass% -Q "CREATE LOGIN [%user%] WITH PASSWORD=N'%password%', DEFAULT_DATABASE=[%database%]"
sqlcmd -S %servername% -U %root_user% -P %root_pass% -d %database% -Q "ALTER AUTHORIZATION ON DATABASE::%database% TO %user%;"
sqlcmd -S %servername% -U %root_user% -P %root_pass% -d %database% -i database\sqlserver-schema-7-1-schema.sql
sqlcmd -S %servername% -U %root_user% -P %root_pass% -d %database% -i database\sqlserver-schema-7-1-sp.sql
sqlcmd -S %servername% -U %root_user% -P %root_pass% -d %database% -i database\sqlserver-schema-7-1-props.sql
sqlcmd -S %servername% -U %root_user% -P %root_pass% -d %database% -i database\sqlserver-pubsub-schema-3.2.0.sql

Above can be automatized with provided script %tigase-server%\scripts\db-create-sqlserver.cmd (note: it needs to be executed from main Tigase XMPP Server directory due to maintain correct paths):

$ scripts\db-create-sqlserver.cmd %database_servername% %database_name% %tigase_username% %tigase_password% %root_username% %root_password%

If no parameters are provided then the following defaults are used:

%database_servername%=localhost
%database_name%=tigasedb
%tigase_username%=tigase
%tigase_password%=tigase12
%root_username%=root
%root_password%=root

Tigase configuration - init.properties

Configuration of the MS SQL Server follows general database convention. For MS SQL Support --user-db needs to be set to sqlserver:

--user-db=sqlserver

and the --user-db-uri needs to point to the configured database:

--user-db-uri=jdbc:[jtds:]sqlserver://db_hostname:port[;property=val]

where any number of additional parameters can (and should) consist of:

  • databaseName - name of the database
  • user - username configured to access database
  • password - password for the above username
  • schema - name of the database schema
  • lastUpdateCount - 'false' value causes all update counts to be returned, including those returned by server triggers

Example:

--user-db-uri=jdbc:sqlserver://hostname:1433;databaseName=tigasedb;user=tigase;password=tigase12;schema=dbo;lastUpdateCount=false

JDBC: jTDS vs MS JDBC driver

Tigase XMPP Server supports two JDBC drivers intended to be used with Microsoft SQL Server - one created and provided by Microsoft itself and the alternative implementation - jTDS. Tigase is shipped with the latter in the distribution packages. Starting with the version 7.1.0 we recommend using jDTS driver that is shipped with Tigase as JDBC driver created by Microsoft can cause problems with some components in cluster installations. MS driver can be downloaded form the website: JDBC Drivers 4.0, 4.1 for SQL Server then unpack the archive. Copy sqljdbc_4.0/enu/sqljdbc4.jar file to ${tigase-server}/jars directory.

Depending on the driver used --user-db-uri needs to be configured accordingly.

  • Microsoft driver:

    --user-db-uri=jdbc:sqlserver://...
  • jDTS driver

    --user-db-uri=jdbc:jdts:sqlserver://...

Prepare the PostgreSQL Database for the Tigase Server

This guide describes how to prepare PostgreSQL database for connecting to Tigase server.

Basic Setup

The PostgreSQL database can be prepared in many ways. Below are presented two possible ways. The following assumptions apply to both methods:

  • admin_db_user - database user with admin rights
  • tigase_user - database user for Tigase
  • tigasedb - database for Tigase
Configuring from PostgreSQL Command Line Tool

Run the PostgreSQL command line client and enter following instructions:

  1. Add the tigase_user:

    psql=# create role tigase_user with login password 'tigase123';
  2. Create the database for the Tigase server with tigase_user as owner of database:

    psql=# create database tigasedb owner tigase_user;
  3. Load database schema to initialize the Tigase server from the file that corresponds to the version of Tigase you want to use. First you need to switch to tigasedb.

    psql=# \connect tigasedb

    Begin by applying the basic Schema

    psql=# \i database/postgresql-schema-7-1.sql

    Continue by adding the PubSub Schema

    psql=# \i database/postgresql-pubsub-schema-3.2.0.sql

    And finally if you wish to use Socks5 Proxy component, add that schema:

psql=# \i database/postgresql-socks5-schema.sql
Configuring From the Linux Shell Command Line

Follow steps below to prepare the PostgreSQL database:

  1. Add the tigase_user:

    createuser -U admin_db_user -W -D -R -S -P tigase_user

    You will be asked for credentials for admin_db_user and password for new database user.

  2. Create the database for the Tigase server with tigase_user as owner of database:

    createdb -U admin_db_user -W -O tigase_user tigasedb
  3. Load database schema to initialize the Tigase server from the file that corresponds to the Tigase version you want to use.

    psql -q -U tigase_user -W tigasedb -f database/postgresql-schema-7-1.sql
    psql -q -U tigase_user -W tigasedb -f database/postgresql-pubsub-schema-3.2.0.sql

    If you want to use the socks5 proxy component, then add the following line:

    psql -q -U tigase_user -W tigasedb -f database/postgresql-socks5-schema.sql

    The above commands should be executed from the main Tigase directory. The initialization schema file should be also available locally in database/ directory of your Tigase installation.

Preparing Tigase for MongoDB

Tigase now supports MongoDB for auth, settings, and storage repositories. If you wish to use MongoDB for Tigase, please use this guide to help you.

Dependencies

To run Tigase MongoDB support library requires drivers for MongoDB for Java which can be downloaded from here. This driver needs to be placed in /jars directory located in Tigase XMPP Server installation directory.

Configuration

Configuration of user repository for Tigase XMPP Server

To configure Tigase XMPP Server to use MongoDB you need to set --user-db-uri= in etc/init.properties file to proper MongoDB URI pointing to which MongoDB database should be used (it will be created by MongoDB if it does not exist). --user-db property should not be set to let Tigase XMPP Server autodetect proper implementation of UserRepository. Tigase XMPP Server will create proper collections in MongoDB if they do not exist so no schema files are necessary.

Example configuration of XMPP Server pointing to MongoDB database tigase_test in a local instance:

--user-db-uri=mongodb://localhost/tigase_test

If Tigase Server is not able to detect a proper storage layer implementation, it can be forced to use one provided by Tigase using the following lines in etc/init.properties file:

--user-db=tigase.mongodb.MongoRepository
--auth-db=tigase.mongodb.MongoRepository

Every component should be able to use proper implementation to support MongoDB using this URI. Also MongoDB URI can be passed as any URI in configuration of any component.

Configuration for MUC

By default, MUC component will use MongoDB to store data if Tigase is configured to use it as a default store. However, if you would like to use a different MongoDB database to store MUC message archive, you can do this by adding the following line to etc/init.properties file:

muc/history-db-uri=mongodb://localhost/tigase_test

If MUC components fails to detect and use a proper storage layer for MongoDB, you can force it to use one provided by Tigase by using the following line in the init.properties file:

muc/history-db=tigase.mongodb.muc.MongoHistoryProvider
Configuration for PubSub

By default, PubSub component will use MongoDB to store data if Tigase is configured to use it as a default store. However, if you would like to use a different MongoDB database to store PubSub component data, you can do this by adding the following line to etc/init.properties file:

pubsub/pubsub-repo-url=mongodb://localhost/tigase_test

If the PubSub components fails to detect and use a proper storage layer for MongoDB, you can force it to use one provided by Tigase by using the following line in the init.properties file:

pubsub/pubsub-repo-class=tigase.mongodb.pubsub.PubSubDAOMongo
Configuration for Message Archiving

By default, the Message Archiving component will use MongoDB to store data if Tigase is configured to use it as a default store. However, if you would like to use a different MongoDB database to store message archives, you can do this by adding the following line to etc/init.properties file:

message-archive/archive-repo-uri=mongodb://localhost/tigase_test

If Message Archiving component fails to detect and use a proper storage layer for MongoDB, you can force it to use one provided by Tigase by using the following line in the init.properties file:

message-archive/archive-repo-class=tigase.mongodb.archive.MongoMessageArchiveRepository

Schema Description

This description contains only basic description of schema and only basic part of it. More collections may be created if additional components of Tigase XMPP Server are loaded and configured to use MongoDB.

Tigase XMPP Server Schema

Basic schema for UserRespository and AuthRepository consists of two collections: . tig_users - contains list of users . tig_nodes - contains data related to users in tree-like way

tig_users collection contains the following fields:

Table 7.1. tig_users

NameDescription

_id

id of user which is SHA256 hash of users jid (raw byte array)

user_id

contains full user jid

domain

domain to which user belongs for easier lookup of users by domain

password

password of user (or hash of password)


tig_nodes collection contains the following fields

Table 7.2. tig_nodes

NameDescription

_id

id of row autogenerated by MongoDB

uid

id of user which is SHA256 hash of users jid (raw byte array)

node

full path of node in tree-like structure separated by / (may not exist)

key

key for which value for node is set

value

value which is set for node key


Tigase XMPP Server also uses additional collections for storage of Offline Messages

Table 7.3. msg_history collection

NameDescription

from

full user jid of message sender

from_hash

SHA256 hash of message sender jid as raw byte array

to

full users jid of message recipient

to_hash

SHA256 hash of message recipient full jid as raw byte array

ts

timestamp of message as date

message

serialized XML stanza containing message

expire-at

timestamp of expiration of message (if message contains AMP expire-at set)