1.. _myrocks_install:
2
3==================================
4Percona MyRocks Installation Guide
5==================================
6
7
8Percona MyRocks is distributed as a separate package
9that can be enabled as a plugin for Percona Server 5.7 and later versions.
10
11.. note:: File formats across different MyRocks variants may not be compatible.
12   Percona Server supports only *Percona MyRocks*.
13   Migrating from one variant to another
14   requires a logical data dump and reload.
15
16.. contents::
17   :local:
18
19Installing Percona MyRocks
20==========================
21
22It is recommended to install Percona software from official repositories:
23
241. Configure Percona repositories as described in
25   `Percona Software Repositories Documentation
26   <https://www.percona.com/doc/percona-repo-config/index.html>`_.
27
28#. Install Percona MyRocks using the corresponding package manager:
29
30   * For Debian or Ubuntu::
31
32      $ sudo apt install percona-server-rocksdb-5.7
33
34   * For RHEL or CentOS::
35
36      $ sudo yum install Percona-Server-rocksdb-57.x86_64
37
38After you install the Percona MyRocks package,
39you should see the following output::
40
41 * This release of Percona Server is distributed with RocksDB storage engine.
42 * Run the following script to enable the RocksDB storage engine in Percona Server:
43
44        ps-admin --enable-rocksdb -u <mysql_admin_user> -p[mysql_admin_pass] [-S <socket>] [-h <host> -P <port>]
45
46.. _enable-myrocks:
47
48.. rubric:: Enable MyRocks with ps-admin
49
50Run the ``ps-admin`` script as system root user or with :program:`sudo`
51and provide the MySQL root user credentials
52to properly enable the RocksDB (MyRocks) storage engine:
53
54.. code-block:: bash
55
56   $ sudo ps-admin --enable-rocksdb -u root -pPassw0rd
57
58   Checking if RocksDB plugin is available for installation ...
59   INFO: ha_rocksdb.so library for RocksDB found at /usr/lib64/mysql/plugin/ha_rocksdb.so.
60
61   Checking RocksDB engine plugin status...
62   INFO: RocksDB engine plugin is not installed.
63
64   Installing RocksDB engine...
65   INFO: Successfully installed RocksDB engine plugin.
66
67.. note::
68
69    Running the ``ps-admin`` script to enable Percona MyRocks also
70    installs and enables the RocksDB plugin.
71
72If the script returns no errors,
73Percona MyRocks should be successfully enabled on the server.
74You can verify it as follows:
75
76.. code-block:: mysql
77
78   mysql> SHOW ENGINES;
79   +---------+---------+----------------------------------------------------------------------------+--------------+------+------------+
80   | Engine  | Support | Comment                                                                    | Transactions | XA   | Savepoints |
81   +---------+---------+----------------------------------------------------------------------------+--------------+------+------------+
82   | ROCKSDB | YES     | RocksDB storage engine                                                     | YES          | YES  | YES        |
83   ...
84   | InnoDB  | DEFAULT | Percona-XtraDB, Supports transactions, row-level locking, and foreign keys | YES          | YES  | YES        |
85   +---------+---------+----------------------------------------------------------------------------+--------------+------+------------+
86   10 rows in set (0.00 sec)
87
88Note that the RocksDB engine is not set to be default,
89new tables will still be created using the InnoDB (XtraDB) storage engine.
90To make RocksDB storage engine default,
91set ``default-storage-engine=rocksdb`` in the ``[mysqld]`` section
92of :file:`my.cnf` and restart Percona Server.
93
94Alternatively, you can add ``ENGINE=RocksDB``
95after the ``CREATE TABLE`` statement
96for every table that you create.
97
98.. rubric:: Installing MyRocks Plugins
99
100You can install MyRocks manually with a series of `INSTALL PLUGIN <https://dev.mysql.com/doc/refman/5.7/en/install-plugin.html>`_ statements. You must have the ``INSERT`` privilege for the ``mysql.plugin`` system table.
101
102The following statements install MyRocks:
103
104.. code-block:: mysql
105
106    INSTALL PLUGIN ROCKSDB SONAME 'ha_rocksdb.so';
107    INSTALL PLUGIN ROCKSDB_CFSTATS SONAME 'ha_rocksdb.so';
108    INSTALL PLUGIN ROCKSDB_DBSTATS SONAME 'ha_rocksdb.so';
109    INSTALL PLUGIN ROCKSDB_PERF_CONTEXT SONAME 'ha_rocksdb.so';
110    INSTALL PLUGIN ROCKSDB_PERF_CONTEXT_GLOBAL SONAME 'ha_rocksdb.so';
111    INSTALL PLUGIN ROCKSDB_CF_OPTIONS SONAME 'ha_rocksdb.so';
112    INSTALL PLUGIN ROCKSDB_GLOBAL_INFO SONAME 'ha_rocksdb.so';
113    INSTALL PLUGIN ROCKSDB_COMPACTION_STATS SONAME 'ha_rocksdb.so';
114    INSTALL PLUGIN ROCKSDB_DDL SONAME 'ha_rocksdb.so';
115    INSTALL PLUGIN ROCKSDB_INDEX_FILE_MAP SONAME 'ha_rocksdb.so';
116    INSTALL PLUGIN ROCKSDB_LOCKS SONAME 'ha_rocksdb.so';
117    INSTALL PLUGIN ROCKSDB_TRX SONAME 'ha_rocksdb.so';
118    INSTALL PLUGIN ROCKSDB_DEADLOCK SONAME 'ha_rocksdb.so';
119
120Removing Percona MyRocks
121========================
122
123It will not be possible to access tables created using the RocksDB engine
124with another storage engine after you remove Percona MyRocks.
125If you need this data, alter the tables to another storage engine.
126For example, to alter the ``City`` table to InnoDB, run the following:
127
128.. code-block:: mysql
129
130   mysql> ALTER TABLE City ENGINE=InnoDB;
131
132To disable and uninstall the RocksDB engine plugins,
133use the ``ps-admin`` script as follows:
134
135.. code-block:: bash
136
137   $ sudo ps-admin --disable-rocksdb -u root -pPassw0rd
138
139   Checking RocksDB engine plugin status...
140   INFO: RocksDB engine plugin is installed.
141
142   Uninstalling RocksDB engine plugin...
143   INFO: Successfully uninstalled RocksDB engine plugin.
144
145After the engine plugins have been uninstalled,
146remove the Percona MyRocks package:
147
148* For Debian or Ubuntu::
149
150  $ sudo apt remove percona-server-rocksdb-5.7
151
152* For RHEL or CentOS::
153
154  $ sudo yum remove Percona-Server-rocksdb-57.x86_64
155
156Finally, remove all the :ref:`myrocks_server_variables`
157from the configuration file (:file:`my.cnf`)
158and restart Percona Server.
159
160.. rubric:: Uninstall MyRocks Plugins
161
162You can `uninstall the plugins <https://dev.mysql.com/doc/refman/5.7/en/uninstall-plugin.html>`_ for MyRocks. You must have the ``DELETE`` privilege for the ``mysql.plugin`` system table.
163
164The following statements remove the MyRocks plugins:
165
166.. code-block:: mysql
167
168    UNINSTALL PLUGIN ROCKSDB;
169    UNINSTALL PLUGIN ROCKSDB_CFSTATS;
170    UNINSTALL PLUGIN ROCKSDB_DBSTATS;
171    UNINSTALL PLUGIN ROCKSDB_PERF_CONTEXT;
172    UNINSTALL PLUGIN ROCKSDB_PERF_CONTEXT_GLOBAL;
173    UNINSTALL PLUGIN ROCKSDB_CF_OPTIONS;
174    UNINSTALL PLUGIN ROCKSDB_GLOBAL_INFO;
175    UNINSTALL PLUGIN ROCKSDB_COMPACTION_STATS;
176    UNINSTALL PLUGIN ROCKSDB_DDL;
177    UNINSTALL PLUGIN ROCKSDB_INDEX_FILE_MAP;
178    UNINSTALL PLUGIN ROCKSDB_LOCKS;
179    UNINSTALL PLUGIN ROCKSDB_TRX;
180    UNINSTALL PLUGIN ROCKSDB_DEADLOCK;
181
182
183