
DBD::mysql  -- a mysql interface for Perl 5.


1.) WHAT IS IT?
---------------

DBD::mysql is an interface driver for connecting the DBMS independent
Perl-API DBI to the mysql DBMS. When you want to use mysql from
within perl, DBI and DBD::mysql are your best choice: Unlike "mysqlperl",
another option, this is based on a common standard, so your sources
will easily be portable to other DBMS's.

DBD::mysql is a port of DBD::msql, done by Michael 'Monty' Widenius.
DBD::msql was developed by Alligator Descartes and in turn a port of
DBD::Oracle by Tim Bunce. The current maintainer of DBD::mysql is
Jochen Wiedmann. Ask yourself, to whom to give the copyright. :-)
The following might be applied:

  DBD::Oracle is Copyright (c) 1994,1995,1996,1997  Tim Bunce
  DBD::msql   is Copyright (c) 1994,1995,1996,1997  Alligator Descartes
  DBD::mysql  is Copyright (c) 1995,1996,1997       Michael 'Monty' Widenius
    portions are Copyright (c) 1997                 Jochen Wiedmann

Luckily we all have a common distribution license:

   You may distribute under the terms of either the GNU General Public
   License or the Artistic License, as specified in the Perl README file,
   with the exception that it cannot be placed on a CD-ROM or similar media
   for commercial distribution without the prior approval of the author.

   PLEASE READ THE ENTIRE README FILE CAREFULLY !

WARNING:

   THE DBD::mysql MODULE IS ALPHA SOFTWARE. It is *only* 'Alpha'
   because the interface (api) is not finalised. The Alpha status does
   not reflect code quality or stability.


2.) RECENT CHANGES
------------------

If you have already used DBD::mysql, you should notice the following
user visible changes:

  DBD::mysql 2.00	The connect method has changed drastically
			and conforms now to DBI. See the DBI or
			DBD::mysql man pages or try "man DBI" or
			"man DBD::mysql".

3.) HOW ABOUT COMPATIBILITY TO MYSQLPERL?
-----------------------------------------

Msqlperl was the original perl5 interface to mSQL databases. The DBD::mSQL
driver was developed after the initial success of Msqlperl, making it a
tough job to replace that module across sites across the Internet. In a
similar vein to that taken by DBD::Oracle regarding the oraperl module,
an Msqlperl emulation layer has been written that allows scripts written
using the Msqlperl API to run on top of DBI.



4.) QUICK START GUIDE
---------------------

The DBI requires one or more 'driver' modules to talk to databases.
Fetch, build and install the DBI module as per it's README file.
Then delete its source directory tree since it's no longer needed.
Use the 'perldoc DBI' command to read the DBI documentation.
Fetch the DBD::mysql driver module and unpack it.
Follow the guidelines in this README file caefully.


*BEFORE* BUILDING, TESTING AND INSTALLING this you will need to:

    Build, test and install Perl 5 (at least 5.003).
    It is very important to TEST it and INSTALL it!

    Build, test and install the DBI module (at least DBI 0.88).
    It is very important to TEST it and INSTALL it!

    Remember to *read* the DBI README file and this one fully!

    Install mysql, including the header files and libraries; this
    is of special importance when you use a prepackaged mysql like
    RPM files for Linux; you need the mysql-devel package in that
    case.


BUILDING:

    perl Makefile.PL            # use a perl that's in your PATH
    make

If you have problems see the 'IF YOU HAVE PROBLEMS' section below.
If it's builds without error you can then run the tests. For the
main test to work it must be able to connect to an mysql database.

Don't worry about most warnings, specifically "end-of-loop code not
reached", "ANSI C forbids braced-groups within expressions", "cast
increases required alignment of target type" and "passing arg 2 of
`oerhms' with different width due to prototype".

The supplied test will connect to the database using the value of the
MYSQL_USER environment variable so you should set that to the correct
value before starting the test. Please read README.login.

    make test

    make install (if the tests look okay)


5.) IF YOU HAVE PROBLEMS
------------------------

Make sure you are using a recent perl 5.003 or preferably 5.004 and
make sure it's on your path so you can say 'perl Makefile.PL' and
not '/path/to/perl Makefile.PL'.

If you have build/link problems try using "perl Makefile.PL -p".
If that helps then *please* let me know.

Do not hand edit the generated Makefile unless you are completely sure
you understand the implications! Always try to make changes via the
Makefile.PL command line and/or editing the Makefile.PL.

You should not need to make any changes. If you do *please* let me
know so that I can try to make it automatic in a later release.

If you just can't login or login takes a long time then read
README.login and edit test.pl to suit.

If you can't get it to build on a minimally configured client system
then read README.client, it might help but basically I can't help much.
Others on the dbi-users mailing list probably can.

If you have linking problems (errors related to libraries or functions)
then you could try forcing a 'static' build using:

	make realclean
	perl Makefile.PL LINKTYPE=static
	make
	make perl (you'll need to use and install _this_ new perl binary)
	make test
	make -f Makefile.aperl inst_perl MAP_TARGET=perl
	make install

Also read the README.help file which is full of useful tips and
workarounds for various problems of various systems.

Please don't post problems to comp.lang.perl.misc or perl5-porters.
This software is supported via the dbi-users mailing list.  For more
information and to keep informed about progress you can join the a
mailing list via http://www.fugue.com/dbi (if you are unable to use the
web you can subscribe by sending a message to dbi-request@fugue.com, it
may take a few days to be processed).

Please post details of any problems (or changes you needed to make) to
dbi-users@fugue.com and CC them to me at wiedmann@neckar-alb.de. But note...

** IT IS IMPORTANT TO INCLUDE *ALL* THE FOLLOWING INFORMATION:

  - A complete log of a all steps of the build, e.g.:

    (do a make realclean first)
	perl Makefile.PL -v        (note the -v for verbose)
	make
	make test
	make test TEST_VERBOSE=1   (only if any of the t/* tests fail)

  - Full details of which version of mysql you're using.

  - The output of perl -V

  - If you get errors like "undefined symbol", "symbol not found"
    or "Text relocation remains" then include the output of
    "perl Makefile.PL -s XXX" where XXX is the name of one of the
    symbols.  Please don't send the entire output of this command,
    just any obviously 'interesting' parts (if there are any).
    See also the LINKTYPE=static notes above.

  - If you get a core dump, rebuild DBD::mysql with debugging
    enabled by executing: perl Makefile.PL -g  (note the -g option)
    then rerun the code to get a new core dump file, finally use a 
    debugger (gdb, sdb, dbx, adb etc) to get a stack trace from it.
    NOTE: I may not be able to help you much without a stack trace!
    It is worth fetching and building the GNU GDB debugger (4.15) if
    you don't have a good debugger on your system. If desparate try:
     make perl; ./perl script; echo '$c' | adb ./perl core

  - If the stack trace mentions XS_DynaLoader_dl_load_file then rerun
    make test after setting the environment variable PERL_DL_DEBUG to 2.

It is important to check that you are using the latest version before
posting. If you're not then I'm *very* likely to simply say "upgrade to
the latest". You would do yourself a favour by upgrading beforehand.

Please remember that I'm _very_ busy. Try to help yourself first,
then try to help me help you by following these guidelines carefully.


6.) EXAMPLES AND OTHER INFO
---------------------------

DBI 'home page': http://www.hermetica.com/technologia/DBI

Master archive site for Perl DB information:
    ftp://ftp.demon.co.uk/pub/perl/db/
Mailing list archive:                /DBI/perldb-interest/

Searchable index of the dbi-users mailing list:
http://www.coe.missouri.edu/~faq/lists/dbiusers/

mysql home page: http://www.tcx.se

End.
