$dbc = Bio::EnsEMBL::DBSQL::DBConnection->new(
    -user   => 'anonymous',
    -dbname => 'homo_sapiens_core_20_34c',
    -host   => 'ensembldb.ensembl.org',
    -driver => 'mysql',
  );

  # SQL statements should be created/executed through this modules
  # prepare() and do() methods.

  $sth = $dbc->prepare("SELECT something FROM yourtable");

  $sth->execute();

  # do something with rows returned ...

  $sth->finish();

    my $self = shift;
    my $sql = shift;
    my $max_number = shift;

    my $new_sql = '';
    if ($self->driver eq 'mysql'){
	$new_sql = $sql . ' LIMIT ' . $max_number;
    }
    elsif ($self->driver eq 'odbc'){
	#need to get anything after the SELECT statement
	$sql =~ /select(.*)/i;
	$new_sql = 'SELECT TOP ' . $max_number . $1;
    }
    else{
	warning("Not possible to convert $sql to an unknow database driver: ", $self->driver, " no limit applied");
	$new_sql = $sql;
    }
    return $new_sql;

  my $self = shift;

  return if($self->connected);
  $self->connected(1);

  if(defined($self->db_handle()) and $self->db_handle()->ping()) {
    warning("unconnected db_handle is still pingable, reseting connected boolean\n");
  }

  my ($dsn, $dbh);
  if ( $self->driver() eq "Oracle" ) {
    $dsn = "DBI:" . $self->driver . ":";
    eval { $dbh = DBI->connect($dsn,
                               $self->username . "\@" . $self->dbname,
                               $self->password,
                               {'RaiseError' => 1, 'PrintError' => 0});
    };
  } elsif ( $self->driver() eq "ODBC" ) {
    $dsn = "DBI:" . $self->driver() . ":" . $self->dbname();
    eval{ $dbh = DBI->connect($dsn,
                              $self->username(),
                              $self->password(),
                              {'LongTruncOk' => 1,
                               'LongReadLen' => 2**16 - 8,
                               'RaiseError' => 1,
                               'PrintError' => 0,
                               'odbc_cursortype' => 2});
    };
  }
elsif ( $self->driver() eq "Sybase" ) {

  $dsn = "DBI:" . $self->driver() .
    
    ":server=" . $self->host() .
      
      ";database=" . $self->dbname() .
	
	";tdsLevel=CS_TDS_495";
  
  eval{ $dbh = DBI->connect($dsn,
			    
			    $self->username(),
			    
			    $self->password(),
			    
			    {'LongTruncOk' => 1,
			     
			     'RaiseError' => 1,
			     
			     'PrintError' => 0});
	
      };

  }
  else{ 
    $dsn = "DBI:" . $self->driver() .
      ":database=". $self->dbname() .
	";host=" . $self->host() .
	  ";port=" . $self->port();
    eval{ $dbh = DBI->connect($dsn,
                              $self->username(),
                              $self->password(),
                              {'RaiseError' => 1});
	};
  }
  
  if(!$dbh || $@ || !$dbh->ping()) {
    warn("Could not connect to database " . $self->dbname() .
         " as user " . $self->username() . 
         " using [$dsn] as a locator:\n" . $DBI::errstr);
    $self->connected(0);
    throw("Could not connect to database " . $self->dbname() .
          " as user " . $self->username() .
          " using [$dsn] as a locator:\n" . $DBI::errstr);
  }
  $self->db_handle($dbh);
  if($self->timeout()){
    $dbh->do("SET SESSION wait_timeout=".$self->timeout());
  }
  #print("CONNECT\n");

  my $self = shift;

  # Use the process id ($$) as part of the key for the connected flag.
  # This forces the opening of another connection in a forked subprocess.
  $self->{'connected'.$$} = shift if(@_);
  return $self->{'connected'.$$};

   my $self = shift;

   # Use the process id ($$) as part of the key for the database handle
   # this makes this object fork safe.  fork() does not makes copies
   # of the open socket which creates problems when one of the forked
   # processes disconnects,
   return $self->{'db_handle'.$$} = shift if(@_);
   return $self->{'db_handle'.$$} if($self->connected);

   $self->connect();
   return $self->{'db_handle'.$$};

  my ($self, $arg ) = @_;
  ( defined $arg ) &&
    ( $self->{_dbname} = $arg );
  $self->{_dbname};

  my $self = shift;
  return $self->{'disconnect_count'} = shift if(@_);
  $self->{'disconnect_count'}=0 unless(defined($self->{'disconnect_count'}));
  return $self->{'disconnect_count'};

  my $self = shift;

  return 0 if(!$self->connected());
  my $db_handle = $self->db_handle();
  return 0 unless(defined($db_handle));

  #printf("disconnect_if_idle : kids=%d activekids=%d\n",
  #       $db_handle->{Kids}, $db_handle->{ActiveKids});

  #If InactiveDestroy is set, don't disconnect.
  #To comply with DBI specification
  return 0 if($db_handle->{InactiveDestroy});

  #If any statement handles are still active, don't allow disconnection
  #In this case it is being called before a query has been fully processed
  #either by not reading all rows of data returned, or not calling ->finish
  #on the statement handle.  Don't disconnect, send warning
  if($db_handle->{ActiveKids} != 0) {
     warn("Problem disconnect : kids=",$db_handle->{Kids},
            " activekids=",$db_handle->{ActiveKids},"\n");
     return 1;
  }
  
  $db_handle->disconnect();
  $self->connected(undef);
  $self->disconnect_count($self->disconnect_count()+1);
  #print("DISCONNECT\n");
  $self->db_handle(undef);
  return 0;

  my $self = shift;

  if(@_) {
    my $val = shift;
    $self->{'disconnect_when_inactive'} = $val;
    if($val) {
      $self->disconnect_if_idle();
    }
  }
  
  return $self->{'disconnect_when_inactive'};

   my ($self,$string) = @_;

   if( ! $string ) {
     throw("Attempting to do an empty SQL query.");
   }

   #info("SQL(".$self->dbname."):$string");

   my $result = $self->db_handle->do($string);

   # disconnect if the disconnect when inactive flag is set and
   # there are no active statement handles

   if($self->disconnect_when_inactive()) {
     $self->disconnect_if_idle();
   }
  
   $self->query_count($self->query_count()+1);
 
   return $result;

  my($self, $arg ) = @_;

  (defined $arg) &&
    ($self->{_driver} = $arg );
  return $self->{_driver};

  my ($self, $dbc) = @_;


  if($dbc->host() eq $self->host and $dbc->dbname() eq $self->dbname
     and $dbc->driver() eq $self->driver and $dbc->port() eq $self->port
     and $dbc->username() eq $self->username){
    return 1;
  }
  return 0;

    my $self=  shift;
    my $column = shift;

    my $string;
    if ($self->driver eq 'mysql'){
	$string = "UNIX_TIMESTAMP($column)";
    }
    elsif ($self->driver eq 'odbc'){
	$string = "DATEDIFF(second,'JAN 1 1970',$column)";
    }
    else{
	warning("Not possible to convert $column due to an unknown database driver: ", $self->driver);
	return '';
    }    
    return $string;

    my $self=  shift;
    my $seconds = shift;

    my $string;
    if ($self->driver eq 'mysql'){
	if ($seconds){
	    $string = "from_unixtime( ".$seconds.")";
	}
	else{
	    $string = "\"0000-00-00 00:00:00\"";
	}
    }
    elsif ($self->driver eq 'odbc'){
	if ($seconds){
	    $string = "DATEDIFF(date,'JAN 1 1970',$seconds)";
	}
	else{
	    $string = "\"0000-00-00 00:00:00\"";
	}
    }
    else{
	warning("Not possible to convert $seconds due to an unknown database driver: ", $self->driver);
	return '';

    }    
    return $string;
}

####
#deprecated functions
####

  my ($self, $arg ) = @_;
  ( defined $arg ) &&
    ( $self->{_group} = $arg );
  deprecate "group should not be called from DBConnection but from an adaptor\n";
  return $self->{_group};

  my ($self, $arg ) = @_;
  ( defined $arg ) &&
    ( $self->{_host} = $arg );
  $self->{_host};

  my $self = shift;

  my $ref = ref($self);

  return "$ref/host=".$self->host.";port=".$self->port.";dbname=".
    $self->dbname.";user=".$self->username.";pass=".$self->password;

  my $class = shift;

  my ($db,$host,$driver,$user,$password,$port, $inactive_disconnect, $dbconn, $wait_timeout) =
    rearrange([qw(DBNAME HOST DRIVER USER PASS PORT 
                  DISCONNECT_WHEN_INACTIVE DBCONN WAIT_TIMEOUT)], @_);

  my $self = {};
  bless $self, $class;

  if($dbconn) {
    if($db || $host || $driver || $password || $port || $inactive_disconnect) {
      throw("Cannot specify other arguments when -DBCONN argument used.");
    }

    $self->dbname($dbconn->dbname());
    $self->username($dbconn->username());
    $self->host($dbconn->host());
    $self->password($dbconn->password());
    $self->port($dbconn->port());
    $self->driver($dbconn->driver());

    if($dbconn->disconnect_when_inactive()) {
      $self->disconnect_when_inactive(1);
    }
  } else {
    $db   || throw("-DBNAME argument is required.");
    $user || throw("-USER argument is required.");

    $driver ||= 'mysql';
    $host   ||= 'mysql';
    
    if(!defined($port)){
      $port   = 3306;
      if($host eq "ensembldb.ensembl.org"){
	if( $db =~ /\w+_\w+_\w+_(\d+)/){
	  if($1 >= 48){
	    $port = 5306;
	  }
	}
      }
    }

    $wait_timeout   ||= 0;

    $self->username( $user );
    $self->host( $host );
    $self->dbname( $db );
    $self->password( $password );
    $self->port($port);
    $self->driver($driver);
    $self->timeout($wait_timeout);

    if($inactive_disconnect) {
      $self->disconnect_when_inactive($inactive_disconnect);
    }
  }

#  if(defined $dnadb) {
#    $self->dnadb($dnadb);
#  }
  return $self;

  my ( $self, $arg ) = @_;

  if ( defined($arg) ) {
    # Use an anonymous subroutine that will return the password when
    # invoked.  This will prevent the password from being accidentally
    # displayed when using e.g. Data::Dumper on a structure containing
    # one of these objects.

    $self->{_password} = sub { $arg };
  }

  return ( ref( $self->{_password} ) && &{ $self->{_password} } ) || '';

  my ($self, $arg) = @_;

  (defined $arg) && 
    ($self->{_port} = $arg );
  return $self->{_port};

   my ($self,@args) = @_;

   if( ! $args[0] ) {
     throw("Attempting to prepare an empty SQL query.");
   }

#   print STDERR  "SQL(".$self->dbname."):" . join(' ', @args) . "\n";

   my $sth = $self->db_handle->prepare(@args);

   # return an overridden statement handle that provides us with
   # the means to disconnect inactive statement handles automatically
   bless $sth, "Bio::EnsEMBL::DBSQL::StatementHandle";
   $sth->dbc($self);
   $sth->sql($args[0]);

   $self->query_count($self->query_count()+1);
   return $sth;

  my $self = shift;
  return $self->{'_query_count'} = shift if(@_);
  $self->{'_query_count'}=0 unless(defined($self->{'_query_count'}));
  return $self->{'_query_count'};

  my ($self, $arg ) = @_;
  ( defined $arg ) &&
    ( $self->{_species} = $arg );
  deprecate "species should not be called from DBConnection but from an adaptor\n";
  return $self->{_species};
}

1;

  my($self, $arg ) = @_;

  (defined $arg) &&
    ($self->{_timeout} = $arg );

  return $self->{_timeout};

  my ($self, $arg ) = @_;
  ( defined $arg ) &&
    ( $self->{_username} = $arg );
  $self->{_username};

  Copyright (c) 1999-2009 The European Bioinformatics Institute and
  Genome Research Limited.  All rights reserved.

  This software is distributed under a modified Apache license.
  For license details, please see

    /info/about/code_licence.html

  Please email comments or questions to the public Ensembl
  developers list at <ensembl-dev@ebi.ac.uk>.

  Questions may also be sent to the Ensembl help desk at
  <helpdesk@ensembl.org>.

   group is no longer available in DBConnection and should be accessed if needed
   from an adaptor.