NAME

       tdbc::mysql - TDBC-MYSQL bridge

SYNOPSIS

       package require tdbc::mysql 1.0

       tdbc::mysql::connection create db ?-option value...?
       tdbc::mysql::connection new ?-option value...?

       tdbc::mysql::datasources ?-system|-user?

       tdbc::mysql::drivers

       tdbc::mysql::datasource command driverName ?keyword-value?...
_________________________________________________________________________________________________

DESCRIPTION

       The  tdbc::mysql  driver  provides  a  database  interface  that  conforms to Tcl DataBase
       Connectivity (TDBC) and allows a Tcl script to connect to a MySQL database.

       Connection to an MYSQL database is established by invoking tdbc::mysql::connection create,
       passing  it  the  name  to  give the database handle and a set of -option-value pairs. The
       available options are enumerated under  CONNECTION  OPTIONS  below.   As  an  alternative,
       tdbc::mysql::connection  new  may  be  used  to  create  a  database  connection  with  an
       automatically assigned name. The return value from tdbc::mysql::connection new is the name
       that was chosen for the connection handle.

       The side effect of tdbc::mysql::connection create is to create a new database connection..
       See tdbc::connection(3tcl) for the details of how to use the connection  to  manipulate  a
       database.

CONNECTION OPTIONS

       The  tdbc::mysql::connection  create  object  command  supports the -encoding, -isolation,
       -readonly and -timeout options common to all  TDBC  drivers.  The  -encoding  option  will
       always  fail  unless  the  encoding  is  utf-8;  the database connection always uses UTF-8
       encoding to be able to transfer arbitrary Unicode characters. The -readonly option must be
       0, because MySQL does not offer read-only connections.

       In addition, the following options are recognized:

       -host hostname
              Connects  to the host specified by hostname. This option must be set on the initial
              creation of the connection; it cannot be changed after connecting.  Default  is  to
              connect to the local host.

       -port number
              Connects  to a MySQL server listening on the port specified by number.  This option
              may not be changed after connecting. It is used only when host is specified and  is
              not localhost.

       -socket path
              Connects  to a MySQL server listening on the Unix socket or named pipe specified by
              path . This option may not be changed after connecting.  It is used only when -host
              is not specified or is localhost.

       -user name
              Presents name as the user name to the MySQL server. Default is the current user ID.

       -passwd password

       -password password
              These  two  options  are  synonymous. They present the given password as the user's
              password to the MySQL server. Default is not to present a password.

       -database name

       -db name
              These two options are synonymous.  They present the given name as the name  of  the
              default  database  to  use in MySQL queries. If not specified, the default database
              for the current user is used.

       -interactive flag
              The flag value must be a Boolean value. If it is  true  (or  any  equivalent),  the
              default  timeout  is set for an interactive user, otherwise, the default timeout is
              set for a batch user. This option is meaningful only on  initial  connection.  When
              using the configure method on a MySQL connection use the -timeout option to set the
              timeout desired.

       -ssl_ca string

       -ssl_capath string

       -ssl_cert string

       -ssl_cipher string

       -ssl_key string
              These five options set the  certificate  authority,  certificate  authority  search
              path,  SSL certificate, transfer cipher, and SSL key to the given string arguments.
              These options may be specified only on initial connection to a database, not in the
              configure method of an existing connection. Default is not to use SSL.

EXAMPLES

              tdbc::mysql::connection -user joe -passwd sesame -db joes_database
       Connects  to  the  MySQL  server  on  the  local host using the default connection method,
       presenting user ID 'joe' and password  'sesame'.   Uses  'joes_database'  as  the  default
       database name.

ADDITIONAL CONNECTION METHODS

       In  addition  to  the usual methods on the tdbc::connection(3tcl) object, connections to a
       MySQL database support one additional method:

       $connection evaldirect sqlStatement
              This method takes the given sqlStatement and interprets as MySQL  native  SQL  code
              and  evaluates  it  without  preparing  it.  The statement may not contain variable
              substitutions. The result set is returned as a list of  lists,  with  each  sublist
              being the list of columns of a result row formatted as character strings. Note that
              the string formatting is done by  MySQL  and  not  by  Tcl,  so  details  like  the
              appearance  of  floating point numbers may differ.  This command is not recommended
              for anything where the usual prepare or preparecall methods work correctly.  It  is
              provided  so  that  data management language statements that are not implemented in
              MySQL's prepared statement API, such as CREATE DATABASE or CREATE PROCEDURE, can be
              executed.

SEE ALSO

       tdbc(3tcl), tdbc::connection(3tcl), tdbc::resultset(3tcl), tdbc::statement(3tcl)

KEYWORDS

       TDBC, SQL, MySQL, database, connectivity, connection

COPYRIGHT

       Copyright (c) 2009 by Kevin B. Kenny.