readme.txt

Module  : dbBrowser
Date    : 4th April, 2002
Author  : Andy Todd 

The current version of dbBrowser only works with MySQL, Gadfly or Oracle. This is an
alpha release so if you are not already using MySQL, Gadfly or Oracle it is probably
best to give this a miss until it is more stable.

To access MySQL databases you will need MySQL installed, get it from:
  http://www.mysql.com/

You will also need the MySQLdb package, which can be found at (rpm, tar.gz, source):
  http://sourceforge.net/projects/mysql-python/

I'm running version 0.9.1 of the MySQLdb package and version 3.23 of MySQL. 
Confirmation that the code works with other version will be most welcome.

If you have MySQL but don't have any database tables or data a sample schema is
included with this sample. From the scripts directory run "python mysql_sample.py"

To access Oracle databases you will need the Oracle client installed, get it from:
  http://www.oracle.com

You will also need access to an Oracle database with the appropriate user name,
password and connection string. Ensure you can connect to your database through
SQL*Plus before attempting to use this application.

You will also need the cx_Oracle package which can be found at:
  http://www.computronix.com/utilities
The versions of Oracle you can connect to will be determined by cx_Oracle. I have
verified that it works on versions 8.1.5, 8.1.6 and 8.1.7

You will need the Gadfly pure Python module from:
  http://gadfly.sourceforge.net/

This has only been tested with release candidate 1 of this module. 

Future versions will use different databases. I'm planning to include support for
PostgreSQL, ODBC and possibly csv files. If you would like to add support for another
RDBMS please send me an e-mail or post a notice to the mailing list
(pythoncard-users@lists.sourceforge.net).

Observations
------------

You will need to know the name of the database you want to connect to. By default
MySQL creates databases called 'test' and 'mysql' when you install it. If you are
stuck try the on line documentation at:
  http://www.mysql.com/doc/
After that you are definitely on your own - unless you send me a really nice e-mail.

By default there are no tables in a fresh installation of MySQL. The application
'ignores' the system tables (columns_priv, db, host, tables_priv, user). For the
application to work you will need to have created and populated your own tables.
Otherwise it will simply connect to the database and then not provide you with any
tables to browse.

If you are connecting to oracle you will need to connect as a schema owner. If the
user you connect to the database with does not own any tables you will not be able to
browse any data. This is because the handler module uses the 'USER' data dictionary
views. Future versions may use the 'ALL' data dictionary views but the best way to
support these would be to write the code yourself, submissions are always welcome.

If you select a database type of 'Gadfly' the connection details will change. You need
to provide a database name and location. Note that there isn't a dialog to select the
location, this may be provided later, but don't count on it.

Change Notices
--------------
11.06.2002 - Added support for the 'new' gadfly module
11.06.2002 - On startup place the cursor in the username field and make the 'connect'
             button the default when the user presses 'enter'.
04.04.2002 - Changed the format of the column definitions passed around by the
             different modules. This should cope with different datatypes in the
             database modules much more elegantly.
20.11.2001 - Moved icon setting code to framework
10.11.2001 - Added support for Oracle as well as MySQL. Changed the version numbering
to date values
0.3 - Moved the login process to a modal dialog. This will pop up on startup.
      It can also be displayed when you select File|Open from the menu allowing
      you to change the database (or schema) the application is connected to.
0.2 - Added dynamic event handling for the navigation buttons/menu items.
      Changed the layout of data widgets to one label and data item per line.
      The focus changes to the table widget after connecting to a database.
      Changed format of date columns to DD-MON-YYYY for MySQL.
      Added some error handling to check for a valid MySQL database connection.