P  A  R  A  L  L  E  L     U  N  I  V  E  R  S  E


======================================================
Usage Guide (Version 5.5-2)
   Compatible with MySQL 5.5 and Percona 5.5 servers
======================================================


1. Start Parallel Universe with either paralleluniversed or mysqld_safe with
   --mysqld option.  Use a different data dir if MySQL server is already running, see
   MySQL 5.5 Manual 5.6.3 Running Multiple MySQL Instances on Unix.
   (paralleluniverse-5.5-2-* is the installation dir)

   $ cd /usr/local/paralleluniverse-5.5-2-*

   $ bin/mysqld_safe --mysqld=paralleluniversed
     --lc-messages-dir=/usr/local/paralleluniverse-5.5-2-*/share
     --datadir=/usr/local/paralleluniverse-5.5-2-*/data "or your MySQL data dir"
     --socket=/tmp/paralleluniverse.sock --pid-file=/tmp/paralleluniverse.pid
     --port=3307 "your other server parameters" &

2. Connect to Parallel Universe with MySQL client and confirm that you are connected to
   the right server.

   $ bin/mysql --socket=/tmp/paralleluniverse.sock -u root
      .
      .
      .
   Your MySQL connection id is 1
   Server version:  Parallel Universe 5.5-2
      .
      .
      .

3. Change the prompt(optional) and select a database.

   mysql> prompt "Parallel Universe> " (without quotes)
   PROMPT set to 'Parallel Universe> '

   Parallel Universe> use my_database;
   Reading table information for completion of table and column names
   You can turn off this feature to get a quicker startup with -A

   Database changed

4. Run explain on the query you want to parallel process.

   Parallel Universe> explain select * from t1,t2,t3,t4 where my_select_cond;
   +----+-------------+-------+-
   | id | select_type | table | 
   +----+-------------+-------+-
   |  1 | SIMPLE      | t1    | 
   |  1 | SIMPLE      | t2    |    ...
   |  1 | SIMPLE      | t3    | 
   |  1 | SIMPLE      | t4    | 
   +----+-------------+-------+-
   4 rows in set (0.00 sec)

5. Enable parallel processing for the last 2 tables in the table join order and run
   explain again(optional to confirm parallel processing).

   Parallel Universe> set @parallel_table_list="my_database.t3,my_database.t4"; (default=null)
   Query OK, 0 rows affected (0.00 sec)

   Parallel Universe> explain select * from t1,t2,t3,t4 where my_select_cond;
   +----+-------------+-------+-         -+------------------------------------+
   | id | select_type | table |           | Extra                              |
   +----+-------------+-------+-         -+------------------------------------+
   |  1 | SIMPLE      | t1    |           |                                    |
   |  1 | SIMPLE      | t2    |    ...    |                                    |
   |  1 | SIMPLE      | t3    |           | Processed in parallel              |
   |  1 | SIMPLE      | t4    |           | Processed in parallel              |
   +----+-------------+-------+-         -+------------------------------------+
   4 rows in set (0.00 sec)

6. Run the query.

   Parallel Universe> select * from t1,t2,t3,t4 where my_select_cond;

   Performance gain may not be obtained until more tables are parallel processed.
   Not all queries can benefit from parallel processing.

7. Add next table to the list and run the query.

   Parallel Universe> set @parallel_table_list="my_database.t2,my_database.t3,my_database.t4";
   Parallel Universe> select * from t1,t2,t3,t4 where my_select_cond;

8. Continue adding tables until reaching performance plateau beyond which only marginal
   gain is obtained.

9. Assign null to the list to disable parallel processing.

   Parallel Universe> set @parallel_table_list="";
   Query OK, 0 rows affected (0.00 sec)

10.Or set the maximum number of parallel tables to 1 to disable parallel processing.
   You can limit the number of tables to be processed in parallel with this user variable.
   (regardless of what's in @parallel_table_list)

   Parallel Universe> set @max_parallel_tables=1; (default=0, unlimited)
   Query OK, 0 rows affected (0.00 sec)

11.Shut down the server.

   Parallel Universe> quit

   $ bin/mysqladmin --socket=/tmp/paralleluniverse.sock -u root shutdown



======================================================
Restrictions on Tables Processed in Parallel
======================================================

1. Tables processed in parallel must be the last consecutive tables in table join
   order of the query.

2. Tables which are part of nested outer join or outer join with more than one inner
   table are excluded.

3. Temporary tables created by the query are excluded.

4. Tables in subselect(subquery) are excluded.



======================================================
Parallel Universe Server Performance Tuning
======================================================

A user can fine tune 2 new server parameters in addition to existing MySQL 5.5 and Percona 5.5
server parameters.

1. @inter_table_buffer_size user variable which specifies the size of buffer which
   stores records from previous tables in parallel processing.  The sum of used fields in the
   query and overhead must fit in this buffer therefore if the sum exceeds this value then the
   query will fail. (server error #1722: ER_INTER_TABLE_BUFFER_OVERFLOW)

   Parallel Universe> set @inter_table_buffer_size=16384; (=default=16KB)

2. --exclusive_key_buffer_size server command line option (applicable only to MyISAM
   tables) which specifies the size of exclusive key buffer allocated for every MyISAM
   table processed in parallel.

   $ bin/mysqld_safe ... --exclusive_key_buffer_size=8M & (=default=8,388,608)