[ Index ]

PHP Cross Reference of Unnamed Project

title

Body

[close]

/se3-unattended/var/se3/unattended/install/linuxaux/opt/perl/lib/site_perl/5.10.0/i586-linux-thread-multi/DBD/ -> mysql.pm (source)

   1  #   -*- cperl -*-
   2  
   3  package DBD::mysql;
   4  use strict;
   5  use vars qw(@ISA $VERSION $err $errstr $drh);
   6  
   7  use DBI ();
   8  use DynaLoader();
   9  use Carp ();
  10  @ISA = qw(DynaLoader);
  11  
  12  $VERSION = '2.9008';
  13  
  14  bootstrap DBD::mysql $VERSION;
  15  
  16  
  17  $err = 0;    # holds error code   for DBI::err
  18  $errstr = "";    # holds error string for DBI::errstr
  19  $drh = undef;    # holds driver handle once initialised
  20  
  21  sub driver{
  22      return $drh if $drh;
  23      my($class, $attr) = @_;
  24  
  25      $class .= "::dr";
  26  
  27      # not a 'my' since we use it above to prevent multiple drivers
  28      $drh = DBI::_new_drh($class, { 'Name' => 'mysql',
  29                     'Version' => $VERSION,
  30                     'Err'    => \$DBD::mysql::err,
  31                     'Errstr' => \$DBD::mysql::errstr,
  32                     'Attribution' => 'DBD::mysql by Rudy Lippan'
  33                   });
  34  
  35      $drh;
  36  }
  37  
  38  sub CLONE {
  39    undef $drh;
  40  }
  41  
  42  sub _OdbcParse($$$) {
  43      my($class, $dsn, $hash, $args) = @_;
  44      my($var, $val);
  45      if (!defined($dsn)) {
  46      return;
  47      }
  48      while (length($dsn)) {
  49      if ($dsn =~ /([^:;]*)[:;](.*)/) {
  50          $val = $1;
  51          $dsn = $2;
  52      } else {
  53          $val = $dsn;
  54          $dsn = '';
  55      }
  56      if ($val =~ /([^=]*)=(.*)/) {
  57          $var = $1;
  58          $val = $2;
  59          if ($var eq 'hostname'  ||  $var eq 'host') {
  60          $hash->{'host'} = $val;
  61          } elsif ($var eq 'db'  ||  $var eq 'dbname') {
  62          $hash->{'database'} = $val;
  63          } else {
  64          $hash->{$var} = $val;
  65          }
  66      } else {
  67          foreach $var (@$args) {
  68          if (!defined($hash->{$var})) {
  69              $hash->{$var} = $val;
  70              last;
  71          }
  72          }
  73      }
  74      }
  75  }
  76  
  77  sub _OdbcParseHost ($$) {
  78      my($class, $dsn) = @_;
  79      my($hash) = {};
  80      $class->_OdbcParse($dsn, $hash, ['host', 'port']);
  81      ($hash->{'host'}, $hash->{'port'});
  82  }
  83  
  84  sub AUTOLOAD {
  85      my ($meth) = $DBD::mysql::AUTOLOAD;
  86      my ($smeth) = $meth;
  87      $smeth =~ s/(.*)\:\://;
  88  
  89      my $val = constant($smeth, @_ ? $_[0] : 0);
  90      if ($! == 0) { eval "sub $meth { $val }"; return $val; }
  91  
  92      Carp::croak "$meth: Not defined";
  93  }
  94  
  95  1;
  96  
  97  
  98  package DBD::mysql::dr; # ====== DRIVER ======
  99  use strict;
 100  use DBI qw(:sql_types);
 101  
 102  sub connect {
 103      my($drh, $dsn, $username, $password, $attrhash) = @_;
 104      my($port);
 105      my($cWarn);
 106  
 107      # Avoid warnings for undefined values
 108      $username ||= '';
 109      $password ||= '';
 110  
 111      # create a 'blank' dbh
 112      my($this, $privateAttrHash) = (undef, $attrhash);
 113      $privateAttrHash = { %$privateAttrHash,
 114      'Name' => $dsn,
 115      'user' => $username,
 116      'password' => $password
 117      };
 118  
 119      DBD::mysql->_OdbcParse($dsn, $privateAttrHash,
 120                      ['database', 'host', 'port']);
 121  
 122      if (!defined($this = DBI::_new_dbh($drh, {'Name' => $dsn},
 123                         $privateAttrHash))) {
 124      return undef;
 125      }
 126  
 127      # Call msqlConnect func in mSQL.xs file
 128      # and populate internal handle data.
 129      DBD::mysql::db::_login($this, $dsn, $username, $password)
 130        or $this = undef;
 131  
 132      if ($this && ($ENV{MOD_PERL} || $ENV{GATEWAY_INTERFACE})) {
 133          $this->{mysql_auto_reconnect} = 1;
 134      }
 135      $this;
 136  }
 137  
 138  sub data_sources {
 139      my($self) = shift;
 140      my($attributes) = shift;
 141      my($host, $port, $user, $password) = ('', '', '', '');
 142      if ($attributes) {
 143        $host = $attributes->{host} || '';
 144        $port = $attributes->{port} || '';
 145        $user = $attributes->{user} || '';
 146        $password = $attributes->{password} || '';
 147      }
 148      my(@dsn) = $self->func($host, $port, $user, $password, '_ListDBs');
 149      my($i);
 150      for ($i = 0;  $i < @dsn;  $i++) {
 151      $dsn[$i] = "DBI:mysql:$dsn[$i]";
 152      }
 153      @dsn;
 154  }
 155  
 156  sub admin {
 157      my($drh) = shift;
 158      my($command) = shift;
 159      my($dbname) = ($command eq 'createdb'  ||  $command eq 'dropdb') ?
 160      shift : '';
 161      my($host, $port) = DBD::mysql->_OdbcParseHost(shift(@_) || '');
 162      my($user) = shift || '';
 163      my($password) = shift || '';
 164  
 165      $drh->func(undef, $command,
 166             $dbname || '',
 167             $host || '',
 168             $port || '',
 169             $user, $password, '_admin_internal');
 170  }
 171  
 172  package DBD::mysql::db; # ====== DATABASE ======
 173  use strict;
 174  use DBI qw(:sql_types);
 175  
 176  %DBD::mysql::db::db2ANSI = ("INT"   =>  "INTEGER",
 177                 "CHAR"  =>  "CHAR",
 178                 "REAL"  =>  "REAL",
 179                 "IDENT" =>  "DECIMAL"
 180                            );
 181  
 182  ### ANSI datatype mapping to mSQL datatypes
 183  %DBD::mysql::db::ANSI2db = ("CHAR"          => "CHAR",
 184                 "VARCHAR"       => "CHAR",
 185                 "LONGVARCHAR"   => "CHAR",
 186                 "NUMERIC"       => "INTEGER",
 187                 "DECIMAL"       => "INTEGER",
 188                 "BIT"           => "INTEGER",
 189                 "TINYINT"       => "INTEGER",
 190                 "SMALLINT"      => "INTEGER",
 191                 "INTEGER"       => "INTEGER",
 192                 "BIGINT"        => "INTEGER",
 193                 "REAL"          => "REAL",
 194                 "FLOAT"         => "REAL",
 195                 "DOUBLE"        => "REAL",
 196                 "BINARY"        => "CHAR",
 197                 "VARBINARY"     => "CHAR",
 198                 "LONGVARBINARY" => "CHAR",
 199                 "DATE"          => "CHAR",
 200                 "TIME"          => "CHAR",
 201                 "TIMESTAMP"     => "CHAR"
 202                );
 203  
 204  sub prepare {
 205      my($dbh, $statement, $attribs)= @_;
 206  
 207      # create a 'blank' dbh
 208      my $sth = DBI::_new_sth($dbh, {'Statement' => $statement});
 209  
 210      # Populate internal handle data.
 211      if (!DBD::mysql::st::_prepare($sth, $statement, $attribs)) {
 212      $sth = undef;
 213      }
 214  
 215      $sth;
 216  }
 217  
 218  sub db2ANSI {
 219      my $self = shift;
 220      my $type = shift;
 221      return $DBD::mysql::db::db2ANSI{"$type"};
 222  }
 223  
 224  sub ANSI2db {
 225      my $self = shift;
 226      my $type = shift;
 227      return $DBD::mysql::db::ANSI2db{"$type"};
 228  }
 229  
 230  sub admin {
 231      my($dbh) = shift;
 232      my($command) = shift;
 233      my($dbname) = ($command eq 'createdb'  ||  $command eq 'dropdb') ?
 234      shift : '';
 235      $dbh->{'Driver'}->func($dbh, $command, $dbname, '', '', '',
 236                 '_admin_internal');
 237  }
 238  
 239  sub _SelectDB ($$) {
 240      die "_SelectDB is removed from this module; use DBI->connect instead.";
 241  }
 242  
 243  {
 244      my $names = ['TABLE_CAT', 'TABLE_SCHEM', 'TABLE_NAME',
 245           'TABLE_TYPE', 'REMARKS'];
 246  
 247      sub table_info ($) {
 248      my $dbh = shift;
 249      my $sth = $dbh->prepare("SHOW TABLES");
 250      return undef unless $sth;
 251      if (!$sth->execute()) {
 252        return DBI::set_err($dbh, $sth->err(), $sth->errstr());
 253          }
 254      my @tables;
 255      while (my $ref = $sth->fetchrow_arrayref()) {
 256        push(@tables, [ undef, undef, $ref->[0], 'TABLE', undef ]);
 257          }
 258      my $dbh2;
 259      if (!($dbh2 = $dbh->{'~dbd_driver~_sponge_dbh'})) {
 260          $dbh2 = $dbh->{'~dbd_driver~_sponge_dbh'} =
 261          DBI->connect("DBI:Sponge:");
 262          if (!$dbh2) {
 263              DBI::set_err($dbh, 1, $DBI::errstr);
 264          return undef;
 265          }
 266      }
 267      my $sth2 = $dbh2->prepare("SHOW TABLES", { 'rows' => \@tables,
 268                             'NAME' => $names,
 269                             'NUM_OF_FIELDS' => 5 });
 270      if (!$sth2) {
 271          DBI::set_err($sth2, $dbh2->err(), $dbh2->errstr());
 272      }
 273      $sth2;
 274      }
 275  }
 276  
 277  sub _ListTables {
 278    my $dbh = shift;
 279    if (!$DBD::mysql::QUIET) {
 280      warn "_ListTables is deprecated, use \$dbh->tables()";
 281    }
 282    return map { $_ =~ s/.*\.//; $_ } $dbh->tables();
 283  }
 284  
 285  
 286  sub column_info {
 287      my ($dbh, $catalog, $schema, $table, $column) = @_;
 288      return $dbh->set_err(1, "column_info doesn't support table wildcard")
 289      if $table !~ /^\w+$/;
 290      return $dbh->set_err(1, "column_info doesn't support column selection")
 291      if $column ne "%";
 292  
 293      my $table_id = $dbh->quote_identifier($catalog, $schema, $table);
 294  
 295      my @names = qw(
 296      TABLE_CAT TABLE_SCHEM TABLE_NAME COLUMN_NAME
 297      DATA_TYPE TYPE_NAME COLUMN_SIZE BUFFER_LENGTH DECIMAL_DIGITS
 298      NUM_PREC_RADIX NULLABLE REMARKS COLUMN_DEF
 299      SQL_DATA_TYPE SQL_DATETIME_SUB CHAR_OCTET_LENGTH
 300      ORDINAL_POSITION IS_NULLABLE CHAR_SET_CAT
 301      CHAR_SET_SCHEM CHAR_SET_NAME COLLATION_CAT COLLATION_SCHEM COLLATION_NAME
 302      UDT_CAT UDT_SCHEM UDT_NAME DOMAIN_CAT DOMAIN_SCHEM DOMAIN_NAME
 303      SCOPE_CAT SCOPE_SCHEM SCOPE_NAME MAX_CARDINALITY
 304      DTD_IDENTIFIER IS_SELF_REF
 305      mysql_is_pri_key mysql_type_name mysql_values
 306      );
 307      my %col_info;
 308  
 309      local $dbh->{FetchHashKeyName} = 'NAME_lc';
 310      my $desc_sth = $dbh->prepare("DESCRIBE $table_id");
 311      my $desc = $dbh->selectall_arrayref($desc_sth, { Columns=>{} });
 312      my $ordinal_pos = 0;
 313      foreach my $row (@$desc) {
 314      my $type = $row->{type};
 315      $type =~ m/^(\w+)(?:\((.*?)\))?\s*(.*)/;
 316      my $basetype = lc($1);
 317  
 318      my $info = $col_info{ $row->{field} } = {
 319          TABLE_CAT   => $catalog,
 320          TABLE_SCHEM => $schema,
 321          TABLE_NAME  => $table,
 322          COLUMN_NAME => $row->{field},
 323          NULLABLE    => ($row->{null} eq 'YES') ? 1 : 0,
 324          IS_NULLABLE => ($row->{null} eq 'YES') ? "YES" : "NO",
 325          TYPE_NAME   => uc($basetype),
 326          COLUMN_DEF  => $row->{default},
 327          ORDINAL_POSITION => ++$ordinal_pos,
 328          mysql_is_pri_key => ($row->{key}  eq 'PRI'),
 329          mysql_type_name  => $row->{type},
 330      };
 331      # This code won't deal with a pathalogical case where a value
 332      # contains a single quote followed by a comma, and doesn't unescape
 333      # any escaped values. But who would use those in an enum or set?
 334      my @type_params = ($2 && index($2,"'")>=0)
 335              ? ("$2," =~ /'(.*?)',/g)  # assume all are quoted
 336              : split /,/, $2||'';      # no quotes, plain list
 337      s/''/'/g for @type_params;                # undo doubling of quotes
 338      my @type_attr = split / /, $3||'';
 339      #warn "$type: $basetype [@type_params] [@type_attr]\n";
 340  
 341      $info->{DATA_TYPE} = SQL_VARCHAR();
 342      if ($basetype =~ /^(char|varchar|\w*text|\w*blob)/) {
 343          $info->{DATA_TYPE} = SQL_CHAR() if $basetype eq 'char';
 344          if ($type_params[0]) {
 345          $info->{COLUMN_SIZE} = $type_params[0];
 346          }
 347          else {
 348          $info->{COLUMN_SIZE} = 65535;
 349          $info->{COLUMN_SIZE} = 255        if $basetype =~ /^tiny/;
 350          $info->{COLUMN_SIZE} = 16777215   if $basetype =~ /^medium/;
 351          $info->{COLUMN_SIZE} = 4294967295 if $basetype =~ /^long/;
 352          }
 353      }
 354      elsif ($basetype =~ /^(binary|varbinary)/) {
 355          $info->{COLUMN_SIZE} = $type_params[0];
 356          # SQL_BINARY & SQL_VARBINARY are tempting here but don't match the
 357          # semantics for mysql (not hex). SQL_CHAR &  SQL_VARCHAR are correct here.
 358          $info->{DATA_TYPE} = ($basetype eq 'binary') ? SQL_CHAR() : SQL_VARCHAR();
 359      }
 360      elsif ($basetype =~ /^(enum|set)/) {
 361          if ($basetype eq 'set') {
 362          $info->{COLUMN_SIZE} = length(join ",", @type_params);
 363          }
 364          else {
 365          my $max_len = 0;
 366          length($_) > $max_len and $max_len = length($_) for @type_params;
 367          $info->{COLUMN_SIZE} = $max_len;
 368          }
 369          $info->{"mysql_values"} = \@type_params;
 370      }
 371      elsif ($basetype =~ /int/) { # big/medium/small/tiny etc + unsigned?
 372          $info->{DATA_TYPE} = SQL_INTEGER();
 373          $info->{NUM_PREC_RADIX} = 10;
 374          $info->{COLUMN_SIZE} = $type_params[0];
 375      }
 376      elsif ($basetype =~ /^decimal/) {
 377          $info->{DATA_TYPE} = SQL_DECIMAL();
 378          $info->{NUM_PREC_RADIX} = 10;
 379          $info->{COLUMN_SIZE}    = $type_params[0];
 380          $info->{DECIMAL_DIGITS} = $type_params[1];
 381      }
 382      elsif ($basetype =~ /^(float|double)/) {
 383          $info->{DATA_TYPE} = ($basetype eq 'float') ? SQL_FLOAT() : SQL_DOUBLE();
 384          $info->{NUM_PREC_RADIX} = 2;
 385          $info->{COLUMN_SIZE} = ($basetype eq 'float') ? 32 : 64;
 386      }
 387      elsif ($basetype =~ /date|time/) { # date/datetime/time/timestamp
 388          if ($basetype eq 'time' or $basetype eq 'date') {
 389          $info->{DATA_TYPE}   = ($basetype eq 'time') ? SQL_TYPE_TIME() : SQL_TYPE_DATE();
 390          $info->{COLUMN_SIZE} = ($basetype eq 'time') ? 8 : 10;
 391          }
 392          else { # datetime/timestamp
 393          $info->{DATA_TYPE}     = SQL_TYPE_TIMESTAMP();
 394          $info->{SQL_DATA_TYPE} = SQL_DATETIME();
 395              $info->{SQL_DATETIME_SUB} = $info->{DATA_TYPE} - ($info->{SQL_DATA_TYPE} * 10);
 396          $info->{COLUMN_SIZE}   = ($basetype eq 'datetime') ? 19 : $type_params[0] || 14;
 397          }
 398          $info->{DECIMAL_DIGITS} = 0; # no fractional seconds
 399      }
 400      elsif ($basetype eq 'year') {    # no close standard so treat as int
 401          $info->{DATA_TYPE} = SQL_INTEGER();
 402          $info->{NUM_PREC_RADIX} = 10;
 403          $info->{COLUMN_SIZE} = 4;
 404      }
 405      else {
 406          Carp::carp("column_info: unrecognized column type '$basetype' of $table_id.$row->{field} treated as varchar");
 407      }
 408      $info->{SQL_DATA_TYPE} ||= $info->{DATA_TYPE};
 409      #warn Dumper($info);
 410      }
 411  
 412      my $sponge = DBI->connect("DBI:Sponge:", '','')
 413      or return $dbh->DBI::set_err($DBI::err, "DBI::Sponge: $DBI::errstr");
 414      my $sth = $sponge->prepare("column_info $table", {
 415      rows => [ map { [ @{$_}{@names} ] } values %col_info ],
 416      NUM_OF_FIELDS => scalar @names,
 417      NAME => \@names,
 418      }) or return $dbh->DBI::set_err($sponge->err(), $sponge->errstr());
 419  
 420      return $sth;
 421  }
 422  
 423  
 424  
 425  ####################
 426  # get_info()
 427  # Generated by DBI::DBD::Metadata
 428  
 429  sub get_info {
 430      my($dbh, $info_type) = @_;
 431      require DBD::mysql::GetInfo;
 432      my $v = $DBD::mysql::GetInfo::info{int($info_type)};
 433      $v = $v->($dbh) if ref $v eq 'CODE';
 434      return $v;
 435  }
 436  
 437  
 438  
 439  package DBD::mysql::st; # ====== STATEMENT ======
 440  use strict;
 441  
 442  1;
 443  
 444  __END__
 445  
 446  =pod
 447  
 448  =head1 NAME
 449  
 450  DBD::mysql - MySQL driver for the Perl5 Database Interface (DBI)
 451  
 452  =head1 SYNOPSIS
 453  
 454      use DBI;
 455  
 456      $dsn = "DBI:mysql:database=$database;host=$hostname;port=$port";
 457  
 458      $dbh = DBI->connect($dsn, $user, $password);
 459  
 460  
 461      $drh = DBI->install_driver("mysql");
 462      @databases = DBI->data_sources("mysql");
 463         or
 464      @databases = DBI->data_sources("mysql",
 465                     {"host" => $host, "port" => $port});
 466  
 467      $sth = $dbh->prepare("SELECT * FROM foo WHERE bla");
 468         or
 469      $sth = $dbh->prepare("LISTFIELDS $table");
 470         or
 471      $sth = $dbh->prepare("LISTINDEX $table $index");
 472      $sth->execute;
 473      $numRows = $sth->rows;
 474      $numFields = $sth->{'NUM_OF_FIELDS'};
 475      $sth->finish;
 476  
 477      $rc = $drh->func('createdb', $database, $host, $user, $password, 'admin');
 478      $rc = $drh->func('dropdb', $database, $host, $user, $password, 'admin');
 479      $rc = $drh->func('shutdown', $host, $user, $password, 'admin');
 480      $rc = $drh->func('reload', $host, $user, $password, 'admin');
 481  
 482      $rc = $dbh->func('createdb', $database, 'admin');
 483      $rc = $dbh->func('dropdb', $database, 'admin');
 484      $rc = $dbh->func('shutdown', 'admin');
 485      $rc = $dbh->func('reload', 'admin');
 486  
 487  
 488  =head1 EXAMPLE
 489  
 490    #!/usr/bin/perl
 491  
 492    use strict;
 493    use DBI();
 494  
 495    # Connect to the database.
 496    my $dbh = DBI->connect("DBI:mysql:database=test;host=localhost",
 497                           "joe", "joe's password",
 498                           {'RaiseError' => 1});
 499  
 500    # Drop table 'foo'. This may fail, if 'foo' doesn't exist.
 501    # Thus we put an eval around it.
 502    eval { $dbh->do("DROP TABLE foo") };
 503    print "Dropping foo failed: $@\n" if $@;
 504  
 505    # Create a new table 'foo'. This must not fail, thus we don't
 506    # catch errors.
 507    $dbh->do("CREATE TABLE foo (id INTEGER, name VARCHAR(20))");
 508  
 509    # INSERT some data into 'foo'. We are using $dbh->quote() for
 510    # quoting the name.
 511    $dbh->do("INSERT INTO foo VALUES (1, " . $dbh->quote("Tim") . ")");
 512  
 513    # Same thing, but using placeholders
 514    $dbh->do("INSERT INTO foo VALUES (?, ?)", undef, 2, "Jochen");
 515  
 516    # Now retrieve data from the table.
 517    my $sth = $dbh->prepare("SELECT * FROM foo");
 518    $sth->execute();
 519    while (my $ref = $sth->fetchrow_hashref()) {
 520      print "Found a row: id = $ref->{'id'}, name = $ref->{'name'}\n";
 521    }
 522    $sth->finish();
 523  
 524    # Disconnect from the database.
 525    $dbh->disconnect();
 526  
 527  
 528  =head1 DESCRIPTION
 529  
 530  B<DBD::mysql> is the Perl5 Database Interface driver for the MySQL
 531  database. In other words: DBD::mysql is an interface between the Perl
 532  programming language and the MySQL programming API that comes with
 533  the MySQL relational database management system. Most functions
 534  provided by this programming API are supported. Some rarely used
 535  functions are missing, mainly because noone ever requested
 536  them. :-)
 537  
 538  In what follows we first discuss the use of DBD::mysql,
 539  because this is what you will need the most. For installation, see the
 540  sections on L<INSTALLATION>, and L<WIN32 INSTALLATION>
 541  below. See L<EXAMPLE> for a simple example above.
 542  
 543  From perl you activate the interface with the statement
 544  
 545      use DBI;
 546  
 547  After that you can connect to multiple MySQL database servers
 548  and send multiple queries to any of them via a simple object oriented
 549  interface. Two types of objects are available: database handles and
 550  statement handles. Perl returns a database handle to the connect
 551  method like so:
 552  
 553    $dbh = DBI->connect("DBI:mysql:database=$db;host=$host",
 554                $user, $password, {RaiseError => 1});
 555  
 556  Once you have connected to a database, you can can execute SQL
 557  statements with:
 558  
 559    my $query = sprintf("INSERT INTO foo VALUES (%d, %s)",
 560                $number, $dbh->quote("name"));
 561    $dbh->do($query);
 562  
 563  See L<DBI(3)> for details on the quote and do methods. An alternative
 564  approach is
 565  
 566    $dbh->do("INSERT INTO foo VALUES (?, ?)", undef,
 567         $number, $name);
 568  
 569  in which case the quote method is executed automatically. See also
 570  the bind_param method in L<DBI(3)>. See L<DATABASE HANDLES> below
 571  for more details on database handles.
 572  
 573  If you want to retrieve results, you need to create a so-called
 574  statement handle with:
 575  
 576    $sth = $dbh->prepare("SELECT * FROM $table");
 577    $sth->execute();
 578  
 579  This statement handle can be used for multiple things. First of all
 580  you can retreive a row of data:
 581  
 582    my $row = $sth->fetchow_hashref();
 583  
 584  If your table has columns ID and NAME, then $row will be hash ref with
 585  keys ID and NAME. See L<STATEMENT HANDLES> below for more details on
 586  statement handles.
 587  
 588  But now for a more formal approach:
 589  
 590  
 591  =head2 Class Methods
 592  
 593  =over
 594  
 595  =item B<connect>
 596  
 597      use DBI;
 598  
 599      $dsn = "DBI:mysql:$database";
 600      $dsn = "DBI:mysql:database=$database;host=$hostname";
 601      $dsn = "DBI:mysql:database=$database;host=$hostname;port=$port";
 602  
 603      $dbh = DBI->connect($dsn, $user, $password);
 604  
 605  A C<database> must always be specified.
 606  
 607  =over
 608  
 609  =item host
 610  
 611  =item port
 612  
 613  The hostname, if not specified or specified as '', will default to an
 614  MySQL daemon running on the local machine on the default port
 615  for the UNIX socket.
 616  
 617  Should the MySQL daemon be running on a non-standard port number,
 618  you may explicitly state the port number to connect to in the C<hostname>
 619  argument, by concatenating the I<hostname> and I<port number> together
 620  separated by a colon ( C<:> ) character or by using the  C<port> argument.
 621  
 622  
 623  =item mysql_client_found_rows
 624  
 625  Enables (TRUE value) or disables (FALSE value) the flag CLIENT_FOUND_ROWS
 626  while connecting to the MySQL server. This has a somewhat funny effect:
 627  Without mysql_client_found_rows, if you perform a query like
 628  
 629    UPDATE $table SET id = 1 WHERE id = 1
 630  
 631  then the MySQL engine will always return 0, because no rows have changed.
 632  With mysql_client_found_rows however, it will return the number of rows
 633  that have an id 1, as some people are expecting. (At least for compatibility
 634  to other engines.)
 635  
 636  =item mysql_compression
 637  
 638  As of MySQL 3.22.3, a new feature is supported: If your DSN contains
 639  the option "mysql_compression=1", then the communication between client
 640  and server will be compressed.
 641  
 642  =item mysql_connect_timeout
 643  
 644  If your DSN contains the option "mysql_connect_timeout=##", the connect
 645  request to the server will timeout if it has not been successful after
 646  the given number of seconds.
 647  
 648  =item mysql_read_default_file
 649  
 650  =item mysql_read_default_group
 651  
 652  These options can be used to read a config file like /etc/my.cnf or
 653  ~/.my.cnf. By default MySQL's C client library doesn't use any config
 654  files unlike the client programs (mysql, mysqladmin, ...) that do, but
 655  outside of the C client library. Thus you need to explicitly request
 656  reading a config file, as in
 657  
 658      $dsn = "DBI:mysql:test;mysql_read_default_file=/home/joe/my.cnf";
 659      $dbh = DBI->connect($dsn, $user, $password)
 660  
 661  The option mysql_read_default_group can be used to specify the default
 662  group in the config file: Usually this is the I<client> group, but
 663  see the following example:
 664  
 665      [client]
 666      host=localhost
 667  
 668      [perl]
 669      host=perlhost
 670  
 671  (Note the order of the entries! The example won't work, if you reverse
 672  the [client] and [perl] sections!)
 673  
 674  If you read this config file, then you'll be typically connected to
 675  I<localhost>. However, by using
 676  
 677      $dsn = "DBI:mysql:test;mysql_read_default_group=perl;"
 678          . "mysql_read_default_file=/home/joe/my.cnf";
 679      $dbh = DBI->connect($dsn, $user, $password);
 680  
 681  you'll be connected to I<perlhost>. Note that if you specify a
 682  default group and do not specify a file, then the default config
 683  files will all be read.  See the documentation of
 684  the C function mysql_options() for details.
 685  
 686  =item mysql_socket
 687  
 688  As of MySQL 3.21.15, it is possible to choose the Unix socket that is
 689  used for connecting to the server. This is done, for example, with
 690  
 691      mysql_socket=/dev/mysql
 692  
 693  Usually there's no need for this option, unless you are using another
 694  location for the socket than that built into the client.
 695  
 696  =item mysql_ssl
 697  
 698  A true value turns on the CLIENT_SSL flag when connecting to the MySQL
 699  database:
 700  
 701    mysql_ssl=1
 702  
 703  This means that your communication with the server will be encrypted.
 704  
 705  If you turn mysql_ssl on, you might also wish to use the following
 706  flags:
 707  
 708  =item mysql_ssl_client_key
 709  
 710  =item mysql_ssl_client_cert
 711  
 712  =item mysql_ssl_ca_file
 713  
 714  =item mysql_ssl_ca_path
 715  
 716  =item mysql_ssl_cipher
 717  
 718  These are used to specify the respective parameters of a call
 719  to mysql_ssl_set, if mysql_ssl is turned on.  
 720  
 721  
 722  =item mysql_local_infile
 723  
 724  As of MySQL 3.23.49, the LOCAL capability for LOAD DATA may be disabled
 725  in the MySQL client library by default. If your DSN contains the option
 726  "mysql_local_infile=1", LOAD DATA LOCAL will be enabled.  (However,
 727  this option is *ineffective* if the server has also been configured to
 728  disallow LOCAL.)
 729  
 730  
 731  =back
 732  
 733  =back
 734  
 735  
 736  =head2 Private MetaData Methods
 737  
 738  =over
 739  
 740  =item B<ListDBs>
 741  
 742      my $drh = DBI->install_driver("mysql");
 743      @dbs = $drh->func("$hostname:$port", '_ListDBs');
 744      @dbs = $drh->func($hostname, $port, '_ListDBs');
 745      @dbs = $dbh->func('_ListDBs');
 746  
 747  Returns a list of all databases managed by the MySQL daemon
 748  running on C<$hostname>, port C<$port>. This method
 749  is rarely needed for databases running on C<localhost>: You should
 750  use the portable method
 751  
 752      @dbs = DBI->data_sources("mysql");
 753  
 754  whenever possible. It is a design problem of this method, that there's
 755  no way of supplying a host name or port number to C<data_sources>, that's
 756  the only reason why we still support C<ListDBs>. :-(
 757  
 758  =back
 759  
 760  
 761  =head2 Server Administration
 762  
 763  =over
 764  
 765  =item admin
 766  
 767      $rc = $drh->func("createdb", $dbname, [host, user, password,], 'admin');
 768      $rc = $drh->func("dropdb", $dbname, [host, user, password,], 'admin');
 769      $rc = $drh->func("shutdown", [host, user, password,], 'admin');
 770      $rc = $drh->func("reload", [host, user, password,], 'admin');
 771  
 772        or
 773  
 774      $rc = $dbh->func("createdb", $dbname, 'admin');
 775      $rc = $dbh->func("dropdb", $dbname, 'admin');
 776      $rc = $dbh->func("shutdown", 'admin');
 777      $rc = $dbh->func("reload", 'admin');
 778  
 779  For server administration you need a server connection. For obtaining
 780  this connection you have two options: Either use a driver handle (drh)
 781  and supply the appropriate arguments (host, defaults localhost, user,
 782  defaults to '' and password, defaults to ''). A driver handle can be
 783  obtained with
 784  
 785      $drh = DBI->install_driver('mysql');
 786  
 787  Otherwise reuse the existing connection of a database handle (dbh).
 788  
 789  There's only one function available for administrative purposes, comparable
 790  to the m(y)sqladmin programs. The command being execute depends on the
 791  first argument:
 792  
 793  =over
 794  
 795  =item createdb
 796  
 797  Creates the database $dbname. Equivalent to "m(y)sqladmin create $dbname".
 798  
 799  =item dropdb
 800  
 801  Drops the database $dbname. Equivalent to "m(y)sqladmin drop $dbname".
 802  
 803  It should be noted that database deletion is
 804  I<not prompted for> in any way.  Nor is it undo-able from DBI.
 805  
 806      Once you issue the dropDB() method, the database will be gone!
 807  
 808  These method should be used at your own risk.
 809  
 810  =item shutdown
 811  
 812  Silently shuts down the database engine. (Without prompting!)
 813  Equivalent to "m(y)sqladmin shutdown".
 814  
 815  =item reload
 816  
 817  Reloads the servers configuration files and/or tables. This can be particularly
 818  important if you modify access privileges or create new users.
 819  
 820  =back
 821  
 822  =back
 823  
 824  
 825  =head1 DATABASE HANDLES
 826  
 827  The DBD::mysql driver supports the following attributes of database
 828  handles (read only):
 829  
 830    $errno = $dbh->{'mysql_errno'};
 831    $error = $dbh->{'mysql_error};
 832    $info = $dbh->{'mysql_hostinfo'};
 833    $info = $dbh->{'mysql_info'};
 834    $insertid = $dbh->{'mysql_insertid'};
 835    $info = $dbh->{'mysql_protoinfo'};
 836    $info = $dbh->{'mysql_serverinfo'};
 837    $info = $dbh->{'mysql_stat'};
 838    $threadId = $dbh->{'mysql_thread_id'};
 839  
 840  These correspond to mysql_errno(), mysql_error(), mysql_get_host_info(),
 841  mysql_info(), mysql_insert_id(), mysql_get_proto_info(),
 842  mysql_get_server_info(), mysql_stat() and mysql_thread_id(),
 843  respectively.
 844  
 845  
 846   $info_hashref = $dhb->{mysql_dbd_stats}
 847  
 848  DBD::mysql keeps track of some statistics in the mysql_dbd_stats attribute.
 849  The following stats are being maintained:
 850  
 851  =over
 852  
 853  =item auto_reconnects_ok
 854  
 855  The number of times that DBD::mysql successfully reconnected to the mysql 
 856  server.
 857  
 858  =item auto_reconnects_failed
 859  
 860  The number of times that DBD::mysql tried to reconnect to mysql but failed.
 861  
 862  =back
 863  
 864  The DBD::mysql driver also supports the following attribute(s) of database
 865  handles (read/write):
 866  
 867   $bool_value = $dbh->{mysql_auto_reconnect};
 868   $dbh->{mysql_auto_reconnect} = $AutoReconnect ? 1 : 0;
 869  
 870  
 871  =item mysql_auto_reconnect
 872  
 873  This attribute determines whether DBD::mysql will automatically reconnect
 874  to mysql if the connection be lost. This feature defaults to off; however,
 875  if either the GATEWAY_INTERFACE or MOD_PERL envionment variable is set, 
 876  DBD::mysql will turn mysql_auto_reconnect on.  Setting mysql_auto_reconnect 
 877  to on is not advised if 'lock tables' is used because if DBD::mysql reconnect 
 878  to mysql all table locks will be lost.  This attribute is ignored when
 879  AutoCommit is turned off, and when AutoCommit is turned off, DBD::mysql will
 880  not automatically reconnect to the server.
 881  
 882  =head1 STATEMENT HANDLES
 883  
 884  The statement handles of DBD::mysql support a number
 885  of attributes. You access these by using, for example,
 886  
 887    my $numFields = $sth->{'NUM_OF_FIELDS'};
 888  
 889  Note, that most attributes are valid only after a successfull I<execute>.
 890  An C<undef> value will returned in that case. The most important exception
 891  is the C<mysql_use_result> attribute: This forces the driver to use
 892  mysql_use_result rather than mysql_store_result. The former is faster
 893  and less memory consuming, but tends to block other processes. (That's why
 894  mysql_store_result is the default.)
 895  
 896  To set the C<mysql_use_result> attribute, use either of the following:
 897  
 898    my $sth = $dbh->prepare("QUERY", { "mysql_use_result" => 1});
 899  
 900  or
 901  
 902    my $sth = $dbh->prepare("QUERY");
 903    $sth->{"mysql_use_result"} = 1;
 904  
 905  Column dependent attributes, for example I<NAME>, the column names,
 906  are returned as a reference to an array. The array indices are
 907  corresponding to the indices of the arrays returned by I<fetchrow>
 908  and similar methods. For example the following code will print a
 909  header of table names together with all rows:
 910  
 911    my $sth = $dbh->prepare("SELECT * FROM $table");
 912    if (!$sth) {
 913        die "Error:" . $dbh->errstr . "\n";
 914    }
 915    if (!$sth->execute) {
 916        die "Error:" . $sth->errstr . "\n";
 917    }
 918    my $names = $sth->{'NAME'};
 919    my $numFields = $sth->{'NUM_OF_FIELDS'};
 920    for (my $i = 0;  $i < $numFields;  $i++) {
 921        printf("%s%s", $i ? "," : "", $$names[$i]);
 922    }
 923    print "\n";
 924    while (my $ref = $sth->fetchrow_arrayref) {
 925        for (my $i = 0;  $i < $numFields;  $i++) {
 926        printf("%s%s", $i ? "," : "", $$ref[$i]);
 927        }
 928        print "\n";
 929    }
 930  
 931  For portable applications you should restrict yourself to attributes with
 932  capitalized or mixed case names. Lower case attribute names are private
 933  to DBD::mysql. The attribute list includes:
 934  
 935  =over
 936  
 937  =item ChopBlanks
 938  
 939  this attribute determines whether a I<fetchrow> will chop preceding
 940  and trailing blanks off the column values. Chopping blanks does not
 941  have impact on the I<max_length> attribute.
 942  
 943  =item mysql_insertid
 944  
 945  MySQL has the ability to choose unique key values automatically. If this
 946  happened, the new ID will be stored in this attribute. An alternative
 947  way for accessing this attribute is via $dbh->{'mysql_insertid'}.
 948  (Note we are using the $dbh in this case!)
 949  
 950  =item mysql_is_blob
 951  
 952  Reference to an array of boolean values; TRUE indicates, that the
 953  respective column is a blob. This attribute is valid for MySQL only.
 954  
 955  =item mysql_is_key
 956  
 957  Reference to an array of boolean values; TRUE indicates, that the
 958  respective column is a key. This is valid for MySQL only.
 959  
 960  =item mysql_is_num
 961  
 962  Reference to an array of boolean values; TRUE indicates, that the
 963  respective column contains numeric values.
 964  
 965  =item mysql_is_pri_key
 966  
 967  Reference to an array of boolean values; TRUE indicates, that the
 968  respective column is a primary key.
 969  
 970  =item mysql_is_auto_increment
 971  
 972  Reference to an array of boolean values; TRUE indicates that the
 973  respective column is an AUTO_INCREMENT column.  This is only valid
 974  for MySQL.
 975  
 976  =item mysql_length
 977  
 978  =item mysql_max_length
 979  
 980  A reference to an array of maximum column sizes. The I<max_length> is
 981  the maximum physically present in the result table, I<length> gives
 982  the theoretically possible maximum. I<max_length> is valid for MySQL
 983  only.
 984  
 985  =item NAME
 986  
 987  A reference to an array of column names.
 988  
 989  =item NULLABLE
 990  
 991  A reference to an array of boolean values; TRUE indicates that this column
 992  may contain NULL's.
 993  
 994  =item NUM_OF_FIELDS
 995  
 996  Number of fields returned by a I<SELECT> or I<LISTFIELDS> statement.
 997  You may use this for checking whether a statement returned a result:
 998  A zero value indicates a non-SELECT statement like I<INSERT>,
 999  I<DELETE> or I<UPDATE>.
1000  
1001  =item mysql_table
1002  
1003  A reference to an array of table names, useful in a I<JOIN> result.
1004  
1005  =item TYPE
1006  
1007  A reference to an array of column types. The engine's native column
1008  types are mapped to portable types like DBI::SQL_INTEGER() or
1009  DBI::SQL_VARCHAR(), as good as possible. Not all native types have
1010  a meaningfull equivalent, for example DBD::mysql::FIELD_TYPE_INTERVAL
1011  is mapped to DBI::SQL_VARCHAR().
1012  If you need the native column types, use I<mysql_type>. See below.
1013  
1014  =item mysql_type
1015  
1016  A reference to an array of MySQL's native column types, for example
1017  DBD::mysql::FIELD_TYPE_SHORT() or DBD::mysql::FIELD_TYPE_STRING().
1018  Use the I<TYPE> attribute, if you want portable types like
1019  DBI::SQL_SMALLINT() or DBI::SQL_VARCHAR().
1020  
1021  =item mysql_type_name
1022  
1023  Similar to mysql, but type names and not numbers are returned.
1024  Whenever possible, the ANSI SQL name is preferred.
1025  
1026  =back
1027  
1028  
1029  =head1 TRANSACTION SUPPORT
1030  
1031  Beginning with DBD::mysql 2.0416, transactions are supported.
1032  The transaction support works as follows:
1033  
1034  =over
1035  
1036  =item *
1037  
1038  By default AutoCommit mode is on, following the DBI specifications.
1039  
1040  =item *
1041  
1042  If you execute
1043  
1044      $dbh->{'AutoCommit'} = 0;
1045  
1046  or
1047  
1048      $dbh->{'AutoCommit'} = 1;
1049  
1050  then the driver will set the MySQL server variable autocommit to 0 or
1051  1, respectively. Switching from 0 to 1 will also issue a COMMIT,
1052  following the DBI specifications.
1053  
1054  =item *
1055  
1056  The methods
1057  
1058      $dbh->rollback();
1059      $dbh->commit();
1060  
1061  will issue the commands COMMIT and ROLLBACK, respectively. A
1062  ROLLBACK will also be issued if AutoCommit mode is off and the
1063  database handles DESTROY method is called. Again, this is following
1064  the DBI specifications.
1065  
1066  =back
1067  
1068  Given the above, you should note the following:
1069  
1070  =over
1071  
1072  =item *
1073  
1074  You should never change the server variable autocommit manually,
1075  unless you are ignoring DBI's transaction support.
1076  
1077  =item *
1078  
1079  Switching AutoCommit mode from on to off or vice versa may fail.
1080  You should always check for errors, when changing AutoCommit mode.
1081  The suggested way of doing so is using the DBI flag RaiseError.
1082  If you don't like RaiseError, you have to use code like the
1083  following:
1084  
1085    $dbh->{'AutoCommit'} = 0;
1086    if ($dbh->{'AutoCommit'}) {
1087      # An error occurred!
1088    }
1089  
1090  =item *
1091  
1092  If you detect an error while changing the AutoCommit mode, you
1093  should no longer use the database handle. In other words, you
1094  should disconnect and reconnect again, because the transaction
1095  mode is unpredictable. Alternatively you may verify the transaction
1096  mode by checking the value of the server variable autocommit.
1097  However, such behaviour isn't portable.
1098  
1099  =item *
1100  
1101  DBD::mysql has a "reconnect" feature that handles the so-called
1102  MySQL "morning bug": If the server has disconnected, most probably
1103  due to a timeout, then by default the driver will reconnect and
1104  attempt to execute the same SQL statement again. However, this
1105  behaviour is disabled when AutoCommit is off: Otherwise the
1106  transaction state would be completely unpredictable after a
1107  reconnect.  
1108  
1109  =item *
1110  
1111  The "reconnect" feature of DBD::mysql can be toggled by using the
1112  L<mysql_auto_reconnect> attribute. This behaviour should be turned off
1113  in code that uses LOCK TABLE because if the database server time out
1114  and DBD::mysql reconnect, table locks will be lost without any 
1115  indication of such loss.
1116  
1117  =back
1118  
1119  
1120  =head1 SQL EXTENSIONS
1121  
1122  Certain metadata functions of MySQL that are available on the
1123  C API level, haven't been implemented here. Instead they are implemented
1124  as "SQL extensions" because they return in fact nothing else but the
1125  equivalent of a statement handle. These are:
1126  
1127  =over
1128  
1129  =item LISTFIELDS $table
1130  
1131  Returns a statement handle that describes the columns of $table.
1132  Ses the docs of mysql_list_fields (C API) for details.
1133  
1134  =back
1135  
1136  
1137  
1138  =head1 COMPATIBILITY ALERT
1139  
1140  The statement attribute I<TYPE> has changed its meaning, as of
1141  DBD::mysql 2.0119. Formerly it used to be the an array
1142  of native engine's column types, but it is now an array of
1143  portable SQL column types. The old attribute is still available
1144  as I<mysql_type>.
1145  
1146  DBD::mysql is a moving target, due to a number of reasons:
1147  
1148  =over
1149  
1150  =item -
1151  
1152  Of course we have to conform the DBI guidelines and developments.
1153  
1154  =item -
1155  
1156  We have to keep track with the latest MySQL developments.
1157  
1158  =item -
1159  
1160  And, surprisingly, we have to be as close to ODBC as possible: This is
1161  due to the current direction of DBI.
1162  
1163  =item -
1164  
1165  And, last not least, as any tool it has a little bit life of its own.
1166  
1167  =back
1168  
1169  This means that a lot of things had to and have to be changed.
1170  As I am not interested in maintaining a lot of compatibility kludges,
1171  which only increase the drivers code without being really usefull,
1172  I did and will remove some features, methods or attributes.
1173  
1174  To ensure a smooth upgrade, the following policy will be applied:
1175  
1176  =over
1177  
1178  =item Obsolete features
1179  
1180  The first step is to declare something obsolete. This means, that no code
1181  is changed, but the feature appears in the list of obsolete features. See
1182  L<Obsolete Features> below.
1183  
1184  =item Deprecated features
1185  
1186  If the feature has been obsolete for quite some time, typically in the
1187  next major stable release, warnings will be inserted in the code. You
1188  can suppress these warnings by setting
1189  
1190      $DBD::mysql = 1;
1191  
1192  In the docs the feature will be moved from the list of obsolete features
1193  to the list of deprecated features. See L<Deprecated Features> below.
1194  
1195  =item Removing features
1196  
1197  Finally features will be removed silently in the next major stable
1198  release. The feature will be shown in the list of historic features.
1199  See L<Historic Features> below.
1200  
1201  =back
1202  
1203  Example: The statement handle attribute
1204  
1205      $sth->{'LENGTH'}
1206  
1207  was declared obsolete in DBD::mysql 2.00xy. It was considered
1208  deprecated in DBD::mysql 2.02xy and removed in 2.04xy.
1209  
1210  
1211  =head2 Obsolete Features
1212  
1213  =over
1214  
1215  =item Database handle attributes
1216  
1217  The following database handle attributes are declared obsolete
1218  in DBD::mysql 2.09. They will be deprecated in 2.11 and removed
1219  in 2.13.
1220  
1221  =over
1222  
1223  =item C<$dbh->{'errno'}>
1224  
1225  Replaced by C<$dbh->{'mysql_errno'}>
1226  
1227  =item C<$dbh->{'errmsg'}>
1228  
1229  Replaced by C<$dbh->{'mysql_error'}>
1230  
1231  =item C<$dbh->{'hostinfo'}>
1232  
1233  Replaced by C<$dbh->{'mysql_hostinfo'}>
1234  
1235  =item C<$dbh->{'info'}>
1236  
1237  Replaced by C<$dbh->{'mysql_info'}>
1238  
1239  =item C<$dbh->{'protoinfo'}>
1240  
1241  Replaced by C<$dbh->{'mysql_protoinfo'}>
1242  
1243  =item C<$dbh->{'serverinfo'}>
1244  
1245  Replaced by C<$dbh->{'mysql_serverinfo'}>
1246  
1247  =item C<$dbh->{'stats'}>
1248  
1249  Replaced by C<$dbh->{'mysql_stat'}>
1250  
1251  =item C<$dbh->{'thread_id'}>
1252  
1253  Replaced by C<$dbh->{'mysql_thread_id'}>
1254  
1255  =back
1256  
1257  =back
1258  
1259  
1260  =head2 Deprecated Features
1261  
1262  =over
1263  
1264  =item _ListTables
1265  
1266  Replace with the standard DBI method C<$dbh->tables()>. See also
1267  C<$dbh->table_info()>. Portable applications will prefer
1268  
1269      @tables = map { $_ =~ s/.*\.//; $_ } $dbh->tables()
1270  
1271  because, depending on the engine, the string "user.table" will be
1272  returned, user being the table owner. The method will be removed
1273  in DBD::mysql version 2.11xy.
1274  
1275  =back
1276  
1277  
1278  =head2 Historic Features
1279  
1280  =over
1281  
1282  =item _CreateDB
1283  
1284  =item _DropDB
1285  
1286  The methods
1287  
1288      $dbh->func($db, '_CreateDB');
1289      $dbh->func($db, '_DropDB');
1290  
1291  have been used for creating or dropping databases. They have been removed
1292  in 1.21_07 in favour of
1293  
1294      $drh->func("createdb", $dbname, $host, "admin")
1295      $drh->func("dropdb", $dbname, $host, "admin")
1296  
1297  =item _ListFields
1298  
1299  The method
1300  
1301      $sth = $dbh->func($table, '_ListFields');
1302  
1303  has been used to list a tables columns names, types and other attributes.
1304  This method has been removed in 1.21_07 in favour of
1305  
1306      $sth = $dbh->prepare("LISTFIELDS $table");
1307  
1308  =item _ListSelectedFields
1309  
1310  The method
1311  
1312      $sth->func('_ListSelectedFields');
1313  
1314  use to return a hash ref of attributes like 'IS_NUM', 'IS_KEY' and so
1315  on. These attributes are now accessible via
1316  
1317      $sth->{'mysql_is_num'};
1318      $sth->{'mysql_is_key'};
1319  
1320  and so on. Thus the method has been removed in 1.21_07.
1321  
1322  =item _NumRows
1323  
1324  The method
1325  
1326      $sth->func('_NumRows');
1327  
1328  used to be equivalent to
1329  
1330      $sth->rows();
1331  
1332  and has been removed in 1.21_07.
1333  
1334  =item _InsertID
1335  
1336  The method
1337  
1338      $dbh->func('_InsertID');
1339  
1340  used to be equivalent with
1341  
1342      $dbh->{'mysql_insertid'};
1343  
1344  =item Statement handle attributes
1345  
1346  =over
1347  
1348  =item affected_rows
1349  
1350  Replaced with $sth->{'mysql_affected_rows'} or the result
1351  of $sth->execute().
1352  
1353  =item format_default_size
1354  
1355  Replaced with $sth->{'PRECISION'}.
1356  
1357  =item format_max_size
1358  
1359  Replaced with $sth->{'mysql_max_length'}.
1360  
1361  =item format_type_name
1362  
1363  Replaced with $sth->{'TYPE'} (portable) or
1364  $sth->{'mysql_type_name'} (MySQL specific).
1365  
1366  =item format_right_justify
1367  
1368  Replaced with $sth->{'TYPE'} (portable) or
1369  $sth->{'mysql_is_num'} (MySQL specific).
1370  
1371  =item insertid
1372  
1373  Replaced with $sth->{'mysql_insertid'}.
1374  
1375  =item IS_BLOB
1376  
1377  Replaced with $sth->{'TYPE'} (portable) or
1378  $sth->{'mysql_is_blob'} (MySQL specific).
1379  
1380  =item is_blob
1381  
1382  Replaced with $sth->{'TYPE'} (portable) or
1383  $sth->{'mysql_is_blob'} (MySQL specific).
1384  
1385  =item IS_PRI_KEY
1386  
1387  Replaced with $sth->{'mysql_is_pri_key'}.
1388  
1389  =item is_pri_key
1390  
1391  Replaced with $sth->{'mysql_is_pri_key'}.
1392  
1393  =item IS_NOT_NULL
1394  
1395  Replaced with $sth->{'NULLABLE'} (do not forget to invert
1396  the boolean values).
1397  
1398  =item is_not_null
1399  
1400  Replaced with $sth->{'NULLABLE'} (do not forget to invert
1401  the boolean values).
1402  
1403  =item IS_NUM
1404  
1405  Replaced with $sth->{'TYPE'} (portable) or
1406  $sth->{'mysql_is_num'} (MySQL specific).
1407  
1408  =item is_num
1409  
1410  Replaced with $sth->{'TYPE'} (portable) or
1411  $sth->{'mysql_is_num'} (MySQL specific).
1412  
1413  =item IS_KEY
1414  
1415  Replaced with $sth->{'mysql_is_key'}.
1416  
1417  =item is_key
1418  
1419  Replaced with $sth->{'mysql_is_key'}.
1420  
1421  =item MAXLENGTH
1422  
1423  Replaced with $sth->{'mysql_max_length'}.
1424  
1425  =item maxlength
1426  
1427  Replaced with $sth->{'mysql_max_length'}.
1428  
1429  =item LENGTH
1430  
1431  Replaced with $sth->{'PRECISION'} (portable) or
1432  $sth->{'mysql_length'} (MySQL specific)
1433  
1434  =item length
1435  
1436  Replaced with $sth->{'PRECISION'} (portable) or
1437  $sth->{'mysql_length'} (MySQL specific)
1438  
1439  =item NUMFIELDS
1440  
1441  Replaced with $sth->{'NUM_OF_FIELDS'}.
1442  
1443  =item numfields
1444  
1445  Replaced with $sth->{'NUM_OF_FIELDS'}.
1446  
1447  =item NUMROWS
1448  
1449  Replaced with the result of $sth->execute() or
1450  $sth->{'mysql_affected_rows'}.
1451  
1452  =item TABLE
1453  
1454  Replaced with $sth->{'mysql_table'}.
1455  
1456  =item table
1457  
1458  Replaced with $sth->{'mysql_table'}.
1459  
1460  =back
1461  
1462  =back
1463  
1464  
1465  =head1 MULTITHREADING
1466  
1467  The multithreading capabilities of DBD::mysql depend completely
1468  on the underlying C libraries: The modules are working with handle data
1469  only, no global variables are accessed or (to the best of my knowledge)
1470  thread unsafe functions are called. Thus DBD::mysql is believed
1471  to be completely thread safe, if the C libraries are thread safe
1472  and you don't share handles among threads.
1473  
1474  The obvious question is: Are the C libraries thread safe?
1475  In the case of MySQL the answer is "mostly" and, in theory, you should
1476  be able to get a "yes", if the C library is compiled for being thread
1477  safe (By default it isn't.) by passing the option -with-thread-safe-client
1478  to configure. See the section on I<How to make a threadsafe client> in
1479  the manual.
1480  
1481  
1482  =head1 INSTALLATION
1483  
1484  Windows users may skip this section and pass over to L<WIN32
1485  INSTALLATION> below. Others, go on reading.
1486  
1487  First of all, you do not need an installed MySQL server for installing
1488  DBD::mysql. However, you need at least the client
1489  libraries and possibly the header files, if you are compiling DBD::mysql
1490  from source. In the case of MySQL you can create a
1491  client-only version by using the configure option --without-server.
1492  If you are using precompiled binaries, then it may be possible to
1493  use just selected RPM's like MySQL-client and MySQL-devel or something
1494  similar, depending on the distribution.
1495  
1496  First you need to install the DBI module. For using I<dbimon>, a
1497  simple DBI shell it is recommended to install Data::ShowTable another
1498  Perl module.
1499  
1500  I recommend trying automatic installation via the CPAN module. Try
1501  
1502    perl -MCPAN -e shell
1503  
1504  If you are using the CPAN module for the first time, it will prompt
1505  you a lot of questions. If you finally receive the CPAN prompt, enter
1506  
1507    install Bundle::DBD::mysql
1508  
1509  If this fails (which may be the case for a number of reasons, for
1510  example because you are behind a firewall or don't have network
1511  access), you need to do a manual installation. First of all you
1512  need to fetch the archives from any CPAN mirror, for example
1513  
1514    ftp://ftp.funet.fi/pub/languages/perl/CPAN/modules/by-module
1515  
1516  The following archives are required (version numbers may have
1517  changed, I choose those which are current as of this writing):
1518  
1519    DBI/DBI-1.15.tar.gz
1520    Data/Data-ShowTable-3.3.tar.gz
1521    DBD/DBD-mysql-2.1001.tar.gz
1522  
1523  Then enter the following commands:
1524  
1525    gzip -cd DBI-1.15.tar.gz | tar xf -
1526    cd DBI-1.15
1527    perl Makefile.PL
1528    make
1529    make test
1530    make install
1531  
1532    cd ..
1533    gzip -cd Data-ShowTable-3.3.tar.gz | tar xf -
1534    cd Data-ShowTable-3.3
1535    perl Makefile.PL
1536    make
1537    make install  # Don't try make test, the test suite is broken
1538  
1539    cd ..
1540    gzip -cd DBD-mysql-2.1001.tar.gz | tar xf -
1541    cd DBD-mysql-2.1001
1542    perl Makefile.PL
1543    make
1544    make test
1545    make install
1546  
1547  During "perl Makefile.PL" you will be prompted some questions.
1548  Other questions are the directories with header files and libraries.
1549  For example, of your file F<mysql.h> is in F</usr/include/mysql/mysql.h>,
1550  then enter the header directory F</usr>, likewise for
1551  F</usr/lib/mysql/libmysqlclient.a> or F</usr/lib/libmysqlclient.so>.
1552  
1553  
1554  =head1 WIN32 INSTALLATION
1555  
1556  If you are using ActivePerl, you may use ppm to install DBD-mysql.
1557  For Perl 5.6, upgrade to Build 623 or later, then it is sufficient
1558  to run
1559  
1560    ppm install DBI
1561    ppm install DBD::mysql
1562  
1563  If you need an HTTP proxy, you might need to set the environment
1564  variable http_proxy, for example like this:
1565  
1566    set http_proxy=http://myproxy.com:8080/
1567  
1568  As of this writing, DBD::mysql is missing in the ActivePerl 5.8.0
1569  repository. However, Randy Kobes has kindly donated an own
1570  distribution and the following might succeed:
1571  
1572    ppm install http://theoryx5.uwinnipeg.ca/ppms/DBD-mysql.ppd
1573  
1574  Otherwise you definitely *need* a C compiler. And it *must* be the same
1575  compiler that was being used for compiling Perl itself. If you don't
1576  have a C compiler, the file README.win32 from the Perl source
1577  distribution tells you where to obtain freely distributable C compilers
1578  like egcs or gcc. The Perl sources are available on any CPAN mirror in
1579  the src directory, for example
1580  
1581      ftp://ftp.funet.fi/pub/languages/perl/CPAN/src/latest.tar.gz
1582  
1583  I recommend using the win32clients package for installing DBD::mysql
1584  under Win32, available for download on www.tcx.se. The following steps
1585  have been required for me:
1586  
1587  =over
1588  
1589  =item -
1590  
1591  The current Perl versions (5.6, as of this writing) do have a problem
1592  with detecting the C libraries. I recommend to apply the following
1593  patch:
1594  
1595    *** c:\Perl\lib\ExtUtils\Liblist.pm.orig Sat Apr 15 20:03:40 2000
1596    --- c:\Perl\lib\ExtUtils\Liblist.pm      Sat Apr 15 20:03:45 2000
1597    ***************
1598    *** 230,235 ****
1599    --- 230,239 ----
1600        # add "$Config{installarchlib}/CORE" to default search path
1601        push @libpath, "$Config{installarchlib}/CORE";
1602  
1603    +     if ($VC  and  exists($ENV{LIB})  and  defined($ENV{LIB})) {
1604    +       push(@libpath, split(/;/, $ENV{LIB}));
1605    +     }
1606    +
1607        foreach (Text::ParseWords::quotewords('\s+', 0, $potential_libs)){
1608  
1609          $thislib = $_;
1610                                                                         
1611  =item -
1612  
1613  Extract sources into F<C:\>. This will create a directory F<C:\mysql>
1614  with subdirectories include and lib.
1615  
1616  IMPORTANT: Make sure this subdirectory is not shared by other TCX
1617  files! In particular do *not* store the MySQL server in the same
1618  directory. If the server is already installed in F<C:\mysql>,
1619  choose a location like F<C:\tmp>, extract the win32clients there.
1620  Note that you can remove this directory entirely once you have
1621  installed DBD::mysql.
1622  
1623  =item -
1624  
1625  Extract the DBD::mysql sources into another directory, for
1626  example F<C:\src\siteperl>
1627  
1628  =item -
1629  
1630  Open a DOS shell and change directory to F<C:\src\siteperl>.
1631  
1632  =item -
1633  
1634  The next step is only required if you repeat building the modules: Make
1635  sure that you have a clean build tree by running
1636  
1637    nmake realclean
1638  
1639  If you don't have VC++, replace nmake with your flavour of make. If
1640  error messages are reported in this step, you may safely ignore them.
1641  
1642  =item -
1643  
1644  Run
1645  
1646    perl Makefile.PL
1647  
1648  which will prompt you for some settings. The really important ones are:
1649  
1650    Which DBMS do you want to use?
1651  
1652  enter a 1 here (MySQL only), and
1653  
1654    Where is your mysql installed? Please tell me the directory that
1655    contains the subdir include.
1656  
1657  where you have to enter the win32clients directory, for example
1658  F<C:\mysql> or F<C:\tmp\mysql>.
1659  
1660  =item -
1661  
1662  Continued in the usual way:
1663  
1664    nmake
1665    nmake install
1666  
1667  =back
1668  
1669  If you want to create a PPM package for the ActiveState Perl version, then
1670  modify the above steps as follows: Run
1671  
1672    perl Makefile.PL NAME=DBD-mysql BINARY_LOCATION=DBD-mysql.tar.gz
1673    nmake ppd
1674    nmake
1675  
1676  Once that is done, use tar and gzip (for example those from the CygWin32
1677  distribution) to create an archive:
1678  
1679    mkdir x86
1680    tar cf x86/DBD-mysql.tar blib
1681    gzip x86/DBD-mysql.tar
1682  
1683  Put the files x86/DBD-mysql.tar.gz and DBD-mysql.ppd onto some WWW server
1684  and install them by typing
1685  
1686    install http://your.server.name/your/directory/DBD-mysql.ppd
1687  
1688  in the PPM program.
1689  
1690  
1691  =head1 AUTHORS
1692  
1693  The current version of B<DBD::mysql> is almost completely written
1694  by Jochen Wiedmann, and is now being maintained by
1695  Rudy Lippan (I<rlippan@remotelinux.com>). The first version's author
1696  was Alligator Descartes (I<descarte@symbolstone.org>), who has been
1697  aided and abetted by Gary Shea, Andreas König and Tim Bunce
1698  amongst others.
1699  
1700  The B<Mysql> module was originally written by Andreas König
1701  <koenig@kulturbox.de>. The current version, mainly an emulation
1702  layer, is from Jochen Wiedmann.
1703  
1704  
1705  =head1 COPYRIGHT
1706  
1707  
1708  This module is Copyright (c) 2003 Rudolf Lippan; Large Portions 
1709  Copyright (c) 1997-2003 Jochen Wiedmann, with code portions 
1710  Copyright (c)1994-1997 their original authors This module is
1711  released under the same license as Perl itself. See the Perl README
1712  for details.
1713  
1714  
1715  =head1 MAILING LIST SUPPORT
1716  
1717  This module is maintained and supported on a mailing list,
1718  
1719      perl@lists.mysql.com
1720  
1721  To subscribe to this list, send a mail to
1722  
1723      perl-subscribe@lists.mysql.com
1724  
1725  or
1726  
1727      perl-digest-subscribe@lists.mysql.com
1728  
1729  Mailing list archives are available at
1730  
1731      http://www.progressive-comp.com/Lists/?l=msql-mysql-modules
1732  
1733  
1734  Additionally you might try the dbi-user mailing list for questions about
1735  DBI and its modules in general. Subscribe via
1736  
1737      http://www.fugue.com/dbi
1738  
1739  Mailing list archives are at
1740  
1741       http://www.rosat.mpe-garching.mpg.de/mailing-lists/PerlDB-Interest/
1742       http://outside.organic.com/mail-archives/dbi-users/
1743       http://www.coe.missouri.edu/~faq/lists/dbi.html
1744  
1745  
1746  =head1 ADDITIONAL DBI INFORMATION
1747  
1748  Additional information on the DBI project can be found on the World
1749  Wide Web at the following URL:
1750  
1751      http://www.symbolstone.org/technology/perl/DBI
1752  
1753  where documentation, pointers to the mailing lists and mailing list
1754  archives and pointers to the most current versions of the modules can
1755  be used.
1756  
1757  Information on the DBI interface itself can be gained by typing:
1758  
1759      perldoc DBI
1760  
1761  right now!
1762  
1763  =cut
1764  
1765  


Generated: Tue Mar 17 22:47:18 2015 Cross-referenced by PHPXref 0.7.1