Dormando's Proxy for MySQL
Copyright 2007 Dormando ([email protected])

This is a "preview" release. Enjoy it as a demo, at your own risk, and don't complain if it's missing features. This code is marked by GPLv2, with some parts LGPL and some parts public domain. The files with alternative licenses are marked as such, by the original authors.

DPM is a general, scriptable proxy which speaks the MySQL protocol. It is built as an event-based network daemon using libevent, and the scripting language is vanilla Lua 5.1.

BUILDING THE PROXY
------------------

The recommended method of building DPM is to use CMake (http://www.cmake.org).
Standard procedure for your platform is to:

- Install the latest libevent.
- Install the latest lua 5.1
- Then from within the source dir: mkdir build ; cd build ; cmake .. ; make ;
  sudo make install
  ... which will use a build directory to compile DPM, then install it and the
  support scripts into /usr/local

There is also a legacy Makefile. If you've installed the required libraries
and run linux, just typing 'make' should build DPM for you.

Type run `dpm --help` or just `dpm` to start it up.

If you want to specify the install prefix, run the `cmake` command like so:
cmake -DCMAKE_INSTALL_PREFIX="/path/to/other/dir" ../path/to/source/dir

DPM has been tested on Linux (gentoo, debian), Mac OS X (PPC, intel) (10.4,
10.5), OpenBSD 4.2, and FreeBSD 6.2. The procedure is roughly the same.
Install dependencies, run cmake, make, make install.

RUNNING THE DEMO
----------------

The included "demo" startup file connects back to a mysqld running on
127.0.0.1 port 3306, using username 'whee' with password 'toast' - you may
edit the startup.lua file to whatever you please if you need to change this.
As long as the daemon is a recent version of MySQL 5.0, it should work fine.

There is a client password hash included in the startup.lua file as well. This
is the stored hash of what clients will have to authenticate against the
proxy. Any auth and protection schemes are handled completely within lua. If
you want to change the username/password combo, edit the startup.lua file
accordingly. To create a new hash: `SELECT PASSWORD('whatever')` from a mysql
client will get what you need.

- Start up the demo, verify that the last line is "Backend ready!" If not,
  troubleshoot until you can connect to mysqld.

- By default the proxy will listen on 127.0.0.1 port 5500, this is editable
  from within startup.lua as well. There's presently no option to listen on
  INADDR_ANY, sorry.

- Connect two mysql CLI clients to the proxy. Run a few basic commands,
  *don't* run \s since it's unsupported right now. Run 'show processlist' a
  few times, select a couple rows from small tables, and watch the output fly
  by in the window.

You will find other demos in the 'lua' directory. The default is named
'startup.lua' (I know, not very inventive).

In order to start a different demo, run with the --startfile command and point
to the file, ie:

./dpm --startfile lua/demo-direct.lua

FEEDBACK
--------

Please give me _constructive_ feedback! I know the code sucks, I can grasp
that I'm doing terrible horrific awful atrocities to the C language. The point
here is the code released works, it might not work well, but it works. I'm
keenly interested in hearing suggestions, directions, detailed bug reports,
and ideas on how to fix bugs or add features.

Drop an e-mail at [email protected] with your comments. I'm also on various
IM services, livejournal, freenode IRC, etc.