[MDEV-8007] Update MariaDB documenation for TokuDB installation instructions - JIRA

Details

Type: Technical task
Status: Closed
Priority: Major
Resolution: Fixed
Affects Version/s: 10.0.16, 10.0.17
Fix Version/s: N/A
Component/s: Documentation, Storage Engine - TokuDB
Labels:
- Documentation
- TokuDB

Description

To be updated :
https://mariadb.com/kb/en/mariadb/enabling-tokudb/
https://mariadb.com/kb/en/mariadb/yum/

TokuDB plugin is NOT distributed anymore as a separate package, the ha_tokudb.so comes now with the other engine plugins, but not enabled.

root@centos-6-5-minimal-base:[Fri Apr 17 09:48:54][/usr/lib64/mysql/plugin]$ ls
auth_pam.so     dialog.so     ha_mroonga.so     ha_sequence.so  ha_spider.so  locales.so             mysql_clear_password.so  query_response_time.so  semisync_slave.so  sql_errlog.so
auth_socket.so  ha_innodb.so  handlersocket.so  ha_sphinx.so    ha_tokudb.so  metadata_lock_info.so  query_cache_info.so      semisync_master.so      server_audit.so
root@centos-6-5-minimal-base:[Fri Apr 17 09:48:55][/usr/lib64/mysql/plugin]$  rpm -qa | grep MariaDB
MariaDB-compat-10.0.17-1.el6.x86_64
MariaDB-server-10.0.17-1.el6.x86_64
MariaDB-devel-10.0.17-1.el6.x86_64
MariaDB-common-10.0.17-1.el6.x86_64
MariaDB-client-10.0.17-1.el6.x86_64
MariaDB-shared-10.0.17-1.el6.x86_64

Gliffy Diagrams

Attachments

Activity

Ascending order - Click to sort in descending order

Hide

Permalink

Stoykov added a comment - 2015-04-17 11:53 - edited

Some additions

installing from command line seems to output some non documented errors when Transparent huge pages are enabled :

root@centos-6-5-minimal-base:[Fri Apr 17 10:32:57][/var/lib/mysql]$ cat /sys/kernel/mm/transparent_hugepage/enabled
[always] madvise never
mysql root@centos-6-5-minimal-base:[Fri Apr 17 10:34:27 2015][(none)]> show plugins;
+-----------------------------+----------+--------------------+---------+---------+
| Name                        | Status   | Type               | Library | License |
+-----------------------------+----------+--------------------+---------+---------+
| binlog                      | ACTIVE   | STORAGE ENGINE     | NULL    | GPL     |
| mysql_native_password       | ACTIVE   | AUTHENTICATION     | NULL    | GPL     |
| mysql_old_password          | ACTIVE   | AUTHENTICATION     | NULL    | GPL     |
| CSV                         | ACTIVE   | STORAGE ENGINE     | NULL    | GPL     |
| MEMORY                      | ACTIVE   | STORAGE ENGINE     | NULL    | GPL     |
| MyISAM                      | ACTIVE   | STORAGE ENGINE     | NULL    | GPL     |
| MRG_MyISAM                  | ACTIVE   | STORAGE ENGINE     | NULL    | GPL     |
| BLACKHOLE                   | ACTIVE   | STORAGE ENGINE     | NULL    | GPL     |
| InnoDB                      | ACTIVE   | STORAGE ENGINE     | NULL    | GPL     |
| XTRADB_READ_VIEW            | ACTIVE   | INFORMATION SCHEMA | NULL    | GPL     |
| XTRADB_INTERNAL_HASH_TABLES | ACTIVE   | INFORMATION SCHEMA | NULL    | GPL     |
| XTRADB_RSEG                 | ACTIVE   | INFORMATION SCHEMA | NULL    | GPL     |
| INNODB_TRX                  | ACTIVE   | INFORMATION SCHEMA | NULL    | GPL     |
| INNODB_LOCKS                | ACTIVE   | INFORMATION SCHEMA | NULL    | GPL     |
| INNODB_LOCK_WAITS           | ACTIVE   | INFORMATION SCHEMA | NULL    | GPL     |
| INNODB_CMP                  | ACTIVE   | INFORMATION SCHEMA | NULL    | GPL     |
| INNODB_CMP_RESET            | ACTIVE   | INFORMATION SCHEMA | NULL    | GPL     |
| INNODB_CMPMEM               | ACTIVE   | INFORMATION SCHEMA | NULL    | GPL     |
| INNODB_CMPMEM_RESET         | ACTIVE   | INFORMATION SCHEMA | NULL    | GPL     |
| INNODB_CMP_PER_INDEX        | ACTIVE   | INFORMATION SCHEMA | NULL    | GPL     |
| INNODB_CMP_PER_INDEX_RESET  | ACTIVE   | INFORMATION SCHEMA | NULL    | GPL     |
| INNODB_BUFFER_PAGE          | ACTIVE   | INFORMATION SCHEMA | NULL    | GPL     |
| INNODB_BUFFER_PAGE_LRU      | ACTIVE   | INFORMATION SCHEMA | NULL    | GPL     |
| INNODB_BUFFER_POOL_STATS    | ACTIVE   | INFORMATION SCHEMA | NULL    | GPL     |
| INNODB_METRICS              | ACTIVE   | INFORMATION SCHEMA | NULL    | GPL     |
| INNODB_FT_DEFAULT_STOPWORD  | ACTIVE   | INFORMATION SCHEMA | NULL    | GPL     |
| INNODB_FT_DELETED           | ACTIVE   | INFORMATION SCHEMA | NULL    | GPL     |
| INNODB_FT_BEING_DELETED     | ACTIVE   | INFORMATION SCHEMA | NULL    | GPL     |
| INNODB_FT_CONFIG            | ACTIVE   | INFORMATION SCHEMA | NULL    | GPL     |
| INNODB_FT_INDEX_CACHE       | ACTIVE   | INFORMATION SCHEMA | NULL    | GPL     |
| INNODB_FT_INDEX_TABLE       | ACTIVE   | INFORMATION SCHEMA | NULL    | GPL     |
| INNODB_SYS_TABLES           | ACTIVE   | INFORMATION SCHEMA | NULL    | GPL     |
| INNODB_SYS_TABLESTATS       | ACTIVE   | INFORMATION SCHEMA | NULL    | GPL     |
| INNODB_SYS_INDEXES          | ACTIVE   | INFORMATION SCHEMA | NULL    | GPL     |
| INNODB_SYS_COLUMNS          | ACTIVE   | INFORMATION SCHEMA | NULL    | GPL     |
| INNODB_SYS_FIELDS           | ACTIVE   | INFORMATION SCHEMA | NULL    | GPL     |
| INNODB_SYS_FOREIGN          | ACTIVE   | INFORMATION SCHEMA | NULL    | GPL     |
| INNODB_SYS_FOREIGN_COLS     | ACTIVE   | INFORMATION SCHEMA | NULL    | GPL     |
| INNODB_SYS_TABLESPACES      | ACTIVE   | INFORMATION SCHEMA | NULL    | GPL     |
| INNODB_SYS_DATAFILES        | ACTIVE   | INFORMATION SCHEMA | NULL    | GPL     |
| INNODB_CHANGED_PAGES        | ACTIVE   | INFORMATION SCHEMA | NULL    | GPL     |
| FEDERATED                   | ACTIVE   | STORAGE ENGINE     | NULL    | GPL     |
| ARCHIVE                     | ACTIVE   | STORAGE ENGINE     | NULL    | GPL     |
| PERFORMANCE_SCHEMA          | ACTIVE   | STORAGE ENGINE     | NULL    | GPL     |
| Aria                        | ACTIVE   | STORAGE ENGINE     | NULL    | GPL     |
| FEEDBACK                    | DISABLED | INFORMATION SCHEMA | NULL    | GPL     |
| partition                   | ACTIVE   | STORAGE ENGINE     | NULL    | GPL     |
+-----------------------------+----------+--------------------+---------+---------+
47 rows in set (0.00 sec)

mysql root@centos-6-5-minimal-base:[Fri Apr 17 10:34:35 2015][(none)]> INSTALL SONAME 'ha_tokudb';
ERROR 1123 (HY000): Can't initialize function 'TokuDB'; Plugin initialization function failed.
mysql root@centos-6-5-minimal-base:[Fri Apr 17 10:34:43 2015][(none)]> show plugins;
+-------------------------------+----------+--------------------+--------------+---------+
| Name                          | Status   | Type               | Library      | License |
+-------------------------------+----------+--------------------+--------------+---------+
| binlog                        | ACTIVE   | STORAGE ENGINE     | NULL         | GPL     |
| mysql_native_password         | ACTIVE   | AUTHENTICATION     | NULL         | GPL     |
| mysql_old_password            | ACTIVE   | AUTHENTICATION     | NULL         | GPL     |
| CSV                           | ACTIVE   | STORAGE ENGINE     | NULL         | GPL     |
| MEMORY                        | ACTIVE   | STORAGE ENGINE     | NULL         | GPL     |
| MyISAM                        | ACTIVE   | STORAGE ENGINE     | NULL         | GPL     |
| MRG_MyISAM                    | ACTIVE   | STORAGE ENGINE     | NULL         | GPL     |
| BLACKHOLE                     | ACTIVE   | STORAGE ENGINE     | NULL         | GPL     |
| InnoDB                        | ACTIVE   | STORAGE ENGINE     | NULL         | GPL     |
| XTRADB_READ_VIEW              | ACTIVE   | INFORMATION SCHEMA | NULL         | GPL     |
| XTRADB_INTERNAL_HASH_TABLES   | ACTIVE   | INFORMATION SCHEMA | NULL         | GPL     |
| XTRADB_RSEG                   | ACTIVE   | INFORMATION SCHEMA | NULL         | GPL     |
| INNODB_TRX                    | ACTIVE   | INFORMATION SCHEMA | NULL         | GPL     |
| INNODB_LOCKS                  | ACTIVE   | INFORMATION SCHEMA | NULL         | GPL     |
| INNODB_LOCK_WAITS             | ACTIVE   | INFORMATION SCHEMA | NULL         | GPL     |
| INNODB_CMP                    | ACTIVE   | INFORMATION SCHEMA | NULL         | GPL     |
| INNODB_CMP_RESET              | ACTIVE   | INFORMATION SCHEMA | NULL         | GPL     |
| INNODB_CMPMEM                 | ACTIVE   | INFORMATION SCHEMA | NULL         | GPL     |
| INNODB_CMPMEM_RESET           | ACTIVE   | INFORMATION SCHEMA | NULL         | GPL     |
| INNODB_CMP_PER_INDEX          | ACTIVE   | INFORMATION SCHEMA | NULL         | GPL     |
| INNODB_CMP_PER_INDEX_RESET    | ACTIVE   | INFORMATION SCHEMA | NULL         | GPL     |
| INNODB_BUFFER_PAGE            | ACTIVE   | INFORMATION SCHEMA | NULL         | GPL     |
| INNODB_BUFFER_PAGE_LRU        | ACTIVE   | INFORMATION SCHEMA | NULL         | GPL     |
| INNODB_BUFFER_POOL_STATS      | ACTIVE   | INFORMATION SCHEMA | NULL         | GPL     |
| INNODB_METRICS                | ACTIVE   | INFORMATION SCHEMA | NULL         | GPL     |
| INNODB_FT_DEFAULT_STOPWORD    | ACTIVE   | INFORMATION SCHEMA | NULL         | GPL     |
| INNODB_FT_DELETED             | ACTIVE   | INFORMATION SCHEMA | NULL         | GPL     |
| INNODB_FT_BEING_DELETED       | ACTIVE   | INFORMATION SCHEMA | NULL         | GPL     |
| INNODB_FT_CONFIG              | ACTIVE   | INFORMATION SCHEMA | NULL         | GPL     |
| INNODB_FT_INDEX_CACHE         | ACTIVE   | INFORMATION SCHEMA | NULL         | GPL     |
| INNODB_FT_INDEX_TABLE         | ACTIVE   | INFORMATION SCHEMA | NULL         | GPL     |
| INNODB_SYS_TABLES             | ACTIVE   | INFORMATION SCHEMA | NULL         | GPL     |
| INNODB_SYS_TABLESTATS         | ACTIVE   | INFORMATION SCHEMA | NULL         | GPL     |
| INNODB_SYS_INDEXES            | ACTIVE   | INFORMATION SCHEMA | NULL         | GPL     |
| INNODB_SYS_COLUMNS            | ACTIVE   | INFORMATION SCHEMA | NULL         | GPL     |
| INNODB_SYS_FIELDS             | ACTIVE   | INFORMATION SCHEMA | NULL         | GPL     |
| INNODB_SYS_FOREIGN            | ACTIVE   | INFORMATION SCHEMA | NULL         | GPL     |
| INNODB_SYS_FOREIGN_COLS       | ACTIVE   | INFORMATION SCHEMA | NULL         | GPL     |
| INNODB_SYS_TABLESPACES        | ACTIVE   | INFORMATION SCHEMA | NULL         | GPL     |
| INNODB_SYS_DATAFILES          | ACTIVE   | INFORMATION SCHEMA | NULL         | GPL     |
| INNODB_CHANGED_PAGES          | ACTIVE   | INFORMATION SCHEMA | NULL         | GPL     |
| FEDERATED                     | ACTIVE   | STORAGE ENGINE     | NULL         | GPL     |
| ARCHIVE                       | ACTIVE   | STORAGE ENGINE     | NULL         | GPL     |
| PERFORMANCE_SCHEMA            | ACTIVE   | STORAGE ENGINE     | NULL         | GPL     |
| Aria                          | ACTIVE   | STORAGE ENGINE     | NULL         | GPL     |
| FEEDBACK                      | DISABLED | INFORMATION SCHEMA | NULL         | GPL     |
| partition                     | ACTIVE   | STORAGE ENGINE     | NULL         | GPL     |
| TokuDB_trx                    | ACTIVE   | INFORMATION SCHEMA | ha_tokudb.so | GPL     |
| TokuDB_lock_waits             | ACTIVE   | INFORMATION SCHEMA | ha_tokudb.so | GPL     |
| TokuDB_locks                  | ACTIVE   | INFORMATION SCHEMA | ha_tokudb.so | GPL     |
| TokuDB_file_map               | ACTIVE   | INFORMATION SCHEMA | ha_tokudb.so | GPL     |
| TokuDB_fractal_tree_info      | ACTIVE   | INFORMATION SCHEMA | ha_tokudb.so | GPL     |
| TokuDB_fractal_tree_block_map | ACTIVE   | INFORMATION SCHEMA | ha_tokudb.so | GPL     |
+-------------------------------+----------+--------------------+--------------+---------+
53 rows in set (0.00 sec)

mysql root@centos-6-5-minimal-base:[Fri Apr 17 10:34:54 2015][(none)]> select version();
+-----------------+
| version()       |
+-----------------+
| 10.0.17-MariaDB |
+-----------------+
1 row in set (0.00 sec)

mysql root@centos-6-5-minimal-base:[Fri Apr 17 10:36:43 2015][(none)]> 

error log:
Version: '10.0.17-MariaDB'  socket: '/var/lib/mysql/mysql.sock'  port: 3306  MariaDB Server
Transparent huge pages are enabled, according to /sys/kernel/mm/redhat_transparent_hugepage/enabled
Transparent huge pages are enabled, according to /sys/kernel/mm/transparent_hugepage/enabled
150417 10:34:43 [ERROR] TokuDB: Huge pages are enabled, disable them before continuing

150417 10:34:43 [ERROR] ************************************************************
150417 10:34:43 [ERROR]                                                             
150417 10:34:43 [ERROR]                         @@@@@@@@@@@                         
150417 10:34:43 [ERROR]                       @@'         '@@                       
150417 10:34:43 [ERROR]                      @@    _     _  @@                      
150417 10:34:43 [ERROR]                      |    (.)   (.)  |                      
150417 10:34:43 [ERROR]                      |             ` |                      
150417 10:34:43 [ERROR]                      |        >    ' |                      
150417 10:34:43 [ERROR]                      |     .----.    |                      
150417 10:34:43 [ERROR]                      ..   |.----.|  ..                      
150417 10:34:43 [ERROR]                       ..  '      ' ..                       
150417 10:34:43 [ERROR]                         .._______,.                         
150417 10:34:43 [ERROR]                                                             
150417 10:34:43 [ERROR] TokuDB will not run with transparent huge pages enabled.        
150417 10:34:43 [ERROR] Please disable them to continue.                            
150417 10:34:43 [ERROR] (echo never > /sys/kernel/mm/transparent_hugepage/enabled)  
150417 10:34:43 [ERROR]                                                             
150417 10:34:43 [ERROR] ************************************************************
150417 10:34:43 [ERROR] Plugin 'TokuDB' init function returned error.
150417 10:34:43 [ERROR] Plugin 'TokuDB' registration as a STORAGE ENGINE failed.

And yes the plugin is listed in the SHOW PLUGINS ; listing ..
So the error should be documented and the possible reason to be linked to the enabling Transparent Huge pages part of the documentation,
When listed in the plugins list after attempt to be installed when Transparent huge pages are enabled, there is no way to UNINSTALL the plugin /remove from the PLUGINS list/ so one needs to restart the MariaDB instance.

mysql root@centos-6-5-minimal-base:[Fri Apr 17 10:44:06 2015][(none)]> UNINSTALL SONAME 'ha_tokudb';
ERROR 1305 (42000): PLUGIN TokuDB does not exist

Installing from the command line outputs a non documented warnings as " Cannot enable tc-log at run-time. XA features of TokuDB are disabled"
That warning needs to be documented along with an explanation how critical it is.
Example: installing again the TokuDB plugin from the command line:

root@centos-6-5-minimal-base:[Fri Apr 17 10:44:48][/var/lib/mysql]$ service mysql  restart 
Shutting down MySQL.. SUCCESS! 
Starting MySQL. SUCCESS! 
root@centos-6-5-minimal-base:[Fri Apr 17 10:44:54][/var/lib/mysql]$ echo never > /sys/kernel/mm/transparent_hugepage/enabled
root@centos-6-5-minimal-base:[Fri Apr 17 10:45:17][/var/lib/mysql]$ echo never > /sys/kernel/mm/transparent_hugepage/defrag

mysql root@centos-6-5-minimal-base:[Fri Apr 17 10:44:59 2015][(none)]> INSTALL SONAME 'ha_tokudb';
Query OK, 0 rows affected, 1 warning (0.41 sec)

mysql root@centos-6-5-minimal-base:[Fri Apr 17 10:45:25 2015][(none)]> SHOW WARNINGS;
+---------+------+----------------------------------------------------------------------+
| Level   | Code | Message                                                              |
+---------+------+----------------------------------------------------------------------+
| Warning | 1105 | Cannot enable tc-log at run-time. XA features of TokuDB are disabled |
+---------+------+----------------------------------------------------------------------+
1 row in set (0.00 sec)

mysql root@centos-6-5-minimal-base:[Fri Apr 17 10:45:33 2015][(none)]>

Show

Hide

Permalink

Stoykov added a comment - 2015-04-17 13:31

Next addition:

The TokuDB variable tokudb_pk_insert_mode https://mariadb.com/kb/en/mariadb/tokudb-system-variables/#tokudb_pk_insert_mode has the default value of 1, and according to the description the * RBR based replication will fail*:

1: Fast inserts if no triggers are defined, otherwise inserts may be slow. Row-based replication will not work.

That should be added to the https://mariadb.com/kb/en/mariadb/tokudb/ page in red or bold letters, as there are installations entirely built on RBR based replication and installing TokuDB with that default setting will break the replication or the plugin will not work at all - I am not entirely sure here which one will fail

Show

Stoykov added a comment - 2015-04-17 13:31 Next addition: The TokuDB variable tokudb_pk_insert_mode https://mariadb.com/kb/en/mariadb/tokudb-system-variables/#tokudb_pk_insert_mode has the default value of 1, and according to the description the * RBR based replication will fail* : 1: Fast inserts if no triggers are defined, otherwise inserts may be slow. Row-based replication will not work. That should be added to the https://mariadb.com/kb/en/mariadb/tokudb/ page in red or bold letters, as there are installations entirely built on RBR based replication and installing TokuDB with that default setting will break the replication or the plugin will not work at all - I am not entirely sure here which one will fail

Hide

Permalink

Stoykov added a comment - 2015-04-17 13:36

Next addition:

At https://mariadb.com/kb/en/mariadb/tokudb/ there are two external links :
TokuDB Users Guide pointing to http://www.tokutek.com/wp-content/uploads/2014/05/mariadb-5.5.37-tokudb-7.1.6-users-guide.pdf
TokuDB Quick Start Guide pointing to http://www.tokutek.com/wp-content/uploads/2014/05/QuickStartGuide-7.1.6.pdf
Both links are broken, I assume due to the new version released .. that should be updated too

Show

Stoykov added a comment - 2015-04-17 13:36 Next addition: At https://mariadb.com/kb/en/mariadb/tokudb/ there are two external links : TokuDB Users Guide pointing to http://www.tokutek.com/wp-content/uploads/2014/05/mariadb-5.5.37-tokudb-7.1.6-users-guide.pdf TokuDB Quick Start Guide pointing to http://www.tokutek.com/wp-content/uploads/2014/05/QuickStartGuide-7.1.6.pdf Both links are broken, I assume due to the new version released .. that should be updated too

Hide

Permalink

Stoykov added a comment - 2015-04-17 14:45

Next addition:

There is a typo at the description of the tokudb_row_format system variable:
https://mariadb.com/kb/en/mariadb/tokudb-system-variables/#tokudb_row_format :
===========
Description: Compression algorithm used by default to compress data. Can be overridden by a row format specified in the CREATE TABLE statement. note that the library can be specified directly, or an alias used, the mapping of whic may change in future.
===========

whic -> which

Show

Stoykov added a comment - 2015-04-17 14:45 Next addition: There is a typo at the description of the tokudb_row_format system variable: https://mariadb.com/kb/en/mariadb/tokudb-system-variables/#tokudb_row_format : =========== Description: Compression algorithm used by default to compress data. Can be overridden by a row format specified in the CREATE TABLE statement. note that the library can be specified directly, or an alias used, the mapping of whic may change in future. =========== whic -> which

Hide

Permalink

Ian Gilfillan added a comment - 2015-05-20 12:51

Thanks for the detailed feedback, these issues have been addressed.

Show

Ian Gilfillan added a comment - 2015-05-20 12:51 Thanks for the detailed feedback, these issues have been addressed.

Update MariaDB documenation for TokuDB installation instructions

Details

Description

Gliffy Diagrams

Attachments

Activity

People

Dates

Agile