MariaDB Documentation improvements (MDEV-6881)

[MDEV-8007] Update MariaDB documenation for TokuDB installation instructions Created: 2015-04-17  Updated: 2015-05-20  Resolved: 2015-05-20

Status: Closed
Project: MariaDB Server
Component/s: Documentation, Storage Engine - TokuDB
Affects Version/s: 10.0.16, 10.0.17
Fix Version/s: N/A

Type: Technical task Priority: Major
Reporter: Stoykov (Inactive) Assignee: Ian Gilfillan
Resolution: Fixed Votes: 0
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
 
 



 Comments   
Comment by Stoykov (Inactive) [ 2015-04-17 ]

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)]> 
 

Comment by Stoykov (Inactive) [ 2015-04-17 ]

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

Comment by Stoykov (Inactive) [ 2015-04-17 ]

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

Comment by Stoykov (Inactive) [ 2015-04-17 ]

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

Comment by Ian Gilfillan [ 2015-05-20 ]

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

Generated at Thu Feb 08 07:23:56 UTC 2024 using Jira 8.20.16#820016-sha1:9d11dbea5f4be3d4cc21f03a88dd11d8c8687422.