README for mSQL version 1.0 14 December 1994 ---------------------------------------------------------------------------- What's new in 1.0 ----------------- 1.0 is actually what was going to be 0.3-release. I decided to give it a "real" number because it has enough features and appears stable enough to be used seriously now (we're even using it in production at Bond hanging of the back of our WWW server and campus user database). 2 months of alpha and beta testing has produced what appears to be a pretty solid hunk of code. 1.0 brings per-database access control, joins, ordering, mmap() support if you have it (and it'll do shared read/write regions - unlike Linux, HPUX etc), distinct, and many bug fixes to mSQL. The doco has also been updated for for this release to reflect the changes to both the SQL supported and also the API and programs. msqladmin now offers a "shutdown" command and also a "reload" command for reloading the access control info on the fly. You can only run msqladmin as root (or whoever you specified as the root user) from the local machine. There's further info about the access control mechanism in the manual. msqladmin also offers a version command. This will report the version of msqladmin, the version of the server it's talking to, and the protocol version used to talk to the server. msql will use the VISUAL environment variable for your editor rather than forcing you to use vi. If it isn't set it'll default to vi anyway. A new program called msqldump is included to generate an ASCII dump of a table or an entire database. The output is formatted as an msql script and includes the "create table" and "insert" commands required to recreate whatever was dumped. It'll work over the net too so you can grab an entire database off a remote box. The MSQL_HOST environment variable has gone. All msql programs now offer a -h option for talking to a remote host. In the API, if msqlConnect() is called with NULL, it forces it to use the UNIX socket on the local host. The lex/flex based scanner has been replaced by a hand written C scanner. This removes a heap of portability problems with various version of lex/flex and the good old "I'm flex but I'll call myself lex" problem on Linux and *BSD. A regression test suite is now available in tests/rtest. Run it after you've compiled and installed the code to ensure that it's working OK. General Info ------------ mSQL has been developed under Sun OS 4.1.1 but has been tested under Solaris 2.3, Ultrix 4.3, Linux, FreeBSD 2, and OSF/1 (cc not gcc). That said, it should "autoconf" and build on most BSD derived systems, SVR4 based systems or POSIX O/S's (that should cover most of them). It has been reported that it works out-of-the-box on HP-UX, NeXT, SCO, Sequent, Cray, Tandem and a few others. I haven't tested these so buyer beware. Installation ------------ To build mSQL, type "make target" in the top directory. This will build a directory where the object files for your system will be made. This mechanism allows you to NFS mount the sources onto different machines and build mSQL on different platforms without having to make copies of the sources. The directory will be under the "targets" directory (e.g. $(TOP)/targets/Solaris-2.3-Sparc ) Once the target directory has been created, change directory into it and run "setup". That will run autoconf and some other configuration scripts. Once that has completed, just type make. You should install the software with "make install" when you're happy with it. The default installation directory is /usr/local/Minerva. This area is shared by all the development of Minerva (including the ESL scripting language and Minerva itself). It's probably a good idea to leave it as that rather than /usr/local/msql or similar if you wish to use ESL (check out doc/Minerva for details on ESL or grab the ESL manual via ftp from Bond.edu.au in /pub/Minerva/esl ) Testing the software -------------------- Once it is installed, you can try the sample mSQL script provided in the msql source directory. Fire up the server using /usr/local/Minerva/bin/msqld& Create a test database using /usr/local/Minerva/bin/msqladmin create test Run the script through the terminal monitor using /usr/local/Minerva/bin/msql test < sample.msql There are also some further test scripts in the tests directory. The "killer" test will produce performance figures about mSQL running on your machine. details such as the number of operations per second for inserts, fills and selects on both keyed and flat tables is generated. For a real test, run the regression test suite (rtest) in the tests directory. Notes : ------ o Because this stuff is pretty new, there's a script in the scripts directory that you may want to use to run the server. It restarts the server if it crashes and mails you a notification of the failure. It's called run_daemon and may save you some heart ache. o If you run this on a Cray (what? you don't have a Y-MP at home? :) you'll have to add -lsocket to EXTRA_LIB in site.mm after you run setup. o OSF/1 and gcc don't appear to like this stuff. If you're using OSF/1 use the standard DEC compiler and everything is fine. o The manual is formatted for an A4 page. I have run the postscript through a filter that should let it print on any paper size although the margins may get stuffed up a bit. If you decide to use mSQL for anything, could you drop me a line. I'd like to keep track of just how many people are using it and what it's being used for. You may also wish to join the mailing list by sending a message to msql-list-request@Bond.edu.au. __ David J. Hughes - Bambi@Bond.edu.au / \ / / / http://Bond.edu.au/People/bambi.html /___/ __ _ ____/ / / _ / \ / \ / \ / / / / / \ / Senior Network Programmer, Bond University \___/ \__// / \__/ \__/ / / / Qld. 4229 AUSTRALIA (+61 75 951450)