
======================================================
Parallel Universe Usage Guide (Version 5.5)
   Compatible with MySQL 5.5
======================================================

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.  Allocate sufficient
   InnoDB buffer pool.  (paralleluniverse-5.5-* is the installation dir)

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

   $ bin/mysqld_safe --mysqld=paralleluniversed
     --lc-messages-dir=/usr/local/paralleluniverse-5.5-*/share
     --datadir="your MySQL data dir" --socket=/tmp/paralleluniverse.sock
     --pid-file=/tmp/paralleluniverse.pid --port=3307 --innodb_buffer_pool_size=1G &

   Typical data dir locations
     RPM Installation:
     /var/lib/mysql

     Binary Installation:
     /usr/local/mysql/data

     Source Installation:
     /usr/local/var

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
      .
      .
      .

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";
   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)

   Parallel Universe> quit

10.Shut down the server.

   $ 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 Performance Tuning
======================================================

A user can fine tune 2 new server parameters in addition to existing MySQL 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.

   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)
