==========================
Using the MySQL Data Store
By Nightblade
==========================

Contents:
---------
1. Installation
2. Maintenance
3. Support


1. Installation
---------------

Requirements:
* MySQL Server 3.23 or above
* At least (storesize + 1 gigabyte) disk space free, or (storesize * 2) disk
  space free if you are using a storesize less than 1 gigabyte

1. Install MySQL.  Almost all operating systems already have a port or package
to make this process easier.  I developed this using MySQL 4.0 but it should
work with no changes on MySQL 4.1.  It also works on MySQL 3.23.

You might need to make some adjustments to your operating system's installation
procedure.  For example, on FreeBSD the databases are stored in /var/db/mysql by
default.  That isn't good because the /var partition on most Unix systems is not
very large.  If you want to have a 20 gigabyte data store, you will have to have
at LEAST 21 gigabytes free on the partition where your databases are stored. 
(The extra 1 gig is to make room for the database optimization process.)

2. Add a user for Entropy in the MySQL database.  At the minimum this user needs
to have permission to create, drop, and optimize tables, and to insert, select,
update, and delete data.  For detailed instructions, see
http://www.mysql.com/doc/en/User_Account_Management.html

3. Create a database for the Entropy data store.  If you don't know how to do
that, the instructions are at http://www.mysql.com/doc/en/Database_use.html

Do NOT create any tables for the database.  Entropy will automatically do that
when you run it for the first time.

4. Reconfigure Entropy by running './configure --with-mysql' followed by make. 
If you get an error message like "can't find <mysql.h>", try running configure
again with the option --with-mysql=/usr/local

5. Adjust the mysql_* configuration variables in the Entropy configuration file
(entropy.conf by default).  The descriptions of these are in the conf file, and
it should be self-explanatory for the most part.

Also check the storesize setting.  It should be set to whatever size you want
the database to be.

The storedepth setting specifies the number of tables to use.  The largest any
database table can be is one gigabyte, so you can find the number of tables you 
need by doing (storesize / 1 gigabyte).  If you can't figure out what to set
storedepth to, you can just leave it at 1 and Entropy will force it to the
correct setting for your storesize when it runs.  You can check the logfile to
see what it has been forced to, and put that number in for storedepth in the
configuration.

I recommend you set mysql_optimize to 1.  If you don't optimize your tables,
they will become fragmented (like a filesystem) and the database performance
will be poor.

6. Start Entropy.

If the startup process appears to hang, don't kill the process right away.  It
can take quite a while to start, especially if you have a large data store.  The
best thing to do would be to take a look at the Entropy log file (entropy.log)
in another window.  If it is having trouble connecting to the database, it will
tell you.

If for some reason you have to interrupt the startup procedure (like via ctrl+c)
be sure to check if all the processes are dead (ps x | grep entropy).  Sometimes
if Entropy is improperly terminated, some stray processes will be left running.


2. Maintenance
--------------

Entropy will optimize the database every time you restart your node if
mysql_optimize in the configuration file is set to 1.  Optimization is a very
slow process, and if you have a large store it could take a half hour or more!

If you want to change the size of your data store, just change storesize in the
configuration.  If the new size is smaller than the old size, the changes may
not make a difference in disk space until the store has been optimized.

Note that the store version information is stored in your storepath in a file
called version.  If you want to test the MySQL store without deleting your old
store, you should first move your store directory to another name, so it doesn't
touch your old `version' file.


3. Support
----------

Support is available starting at $60 / hour.  Just kidding... try the Entropy
Forum.  My name is Nightblade there.
