mSQL module for Python, v1.0
============================

What is this?
------------
"MiniSQL, or mSQL is a lightweight database engine designed to provide
fast access to stored data with low memory requirements. As it's name
implies, mSQL offers a subset of SQL as it's query interface"

It was written by David 'Bambi' Hughes as part of his Minerva network
management environment.

For more info, look in bond.edu.au:/pub/Bond_Uni/Minerva/msql. The
current release of mSQL is 0.2pl2.
mSQL also has a mailing list - msql-list@bond.edu.au

How do I build this?
-------------------
Well, you'll need to build python and mSQL first - then edit the
Setup.in file to point to where you put msql.h and libmsql.a. This
builds the same way as any other python extension -

make -f Makefile.pre.in Makefile
make

Also provided is Makefile.share, which I use to build a shared dynamic
object.

Cool. Now how do I use it?
--------------------------

Documentation? Ha! You want documentation? Well, ok, here's some minimal
docs, by way of an example or two.

import msql
msqlobj=msql.Connect("host")
	    returns None, raises exception on error.
msqlobj.SelectDB("dbname")
	    returns None, raises exception on error.
msqlobj.ListDBs()
	    returns a list of database names.
msqlobj.ListTables()
	    returns a list of table names. You have to have selected a DB
	    first.
msqlobj.ListFields("table")
	    returns a list of ( fieldname, tablename, type, length, flags)
	    tuples, one per field.

msqlres=msqlobj.Query("some SQL query")

msqlres will be a list of tuples - even if only one thing is returned.
(even if nothing is returned - then it will be a list of 1 empty tuple)

You can also do:

msqlres=msqlobj["some SQL query"]

which is much nicer, IMHO.

Attempts to assign to msqlobj[] will raise an exception.

Note the 'not null'/'primary key' information as returned by the C API's
msqlFetchField() on a query result is not available through the query
interface at the moment - I'm not convinced it's useful, and I can't
think of a nice way to make it available. If you _really_ need it, use
ListFields, and parse it. If you _really_ _really_ want it, mail me, and
suggest a way to return it.

(Note that all of the methods that are mixed case can also be called all
in lowercase, eg listdbs instead of ListDBs, if you are like me and hate
the shift key)

For further examples, look at relshow.py and test.py

TODO 
----

Currently all data returned from a query is a string. This should be
fixed. Still, it should make tcl/tk programmers feel at home :-)

The FetchField stuff (see above)

More docs.

------------------------------------------------------------------

Comments, &c. to me on <anthony.baxter@aaii.oz.au>. Please feed any
changes back to me.

Anthony, Thu Sep  8 22:04:57 EST 1994


MISC NOTES:

There are a variety of things that strings being passed cannot contain (as
of mSQL 0.2pl2). Use the example decode_str and encode_str functions in
msql_misc.py to get around this.

mSQL has, by default, fairly low maximum numbers of fields per table and
query length. Careful of this. You can up them by recompiling.