Introduction - Connect -- Connecting and disconnecting a database
Description
To instantiate a database object you have several options.
Table 33-1. Connection functions
| Function | Summary | Description |
|---|
|
factory()
| Efficient |
Will instantiate a new MDB2 instance, but will not
connect to the database until required.
|
|
connect()
| Eager |
Will instantiate a new MDB2 instance, and will establish a
database connection immediately.
|
|
singleton()
| Available |
Returns a MDB2 instance. A new MDB2 object is only
created once, subsequent calls to singleton will return a reference to
the existing object. This method is preferred over declaring your
database object as a global.
|
To connect to a database you have to use the function
factory(),
connect() or
singleton(), which require a valid
DSN
as the first parameter. This parameter can either be a string
or an array. If using an array, the array used gets merged with the
default information:
$dsn = array(
'phptype' => false,
'dbsyntax' => false,
'username' => false,
'password' => false,
'protocol' => false,
'hostspec' => false,
'port' => false,
'socket' => false,
'database' => false,
'new_ink' => false,
); |
Any elements you set override the defaults and the remainder stay at
their defaults.
The second parameter is the optional $options
array that can contain runtime configuration settings for this package.
Table 33-2. List of options
| Name | Type | Description |
|---|
| ssl | boolean |
determines if ssl should be used for connections
|
| field_case | integer |
CASE_LOWER|CASE_UPPER: determines what case to force on field/table names
|
| disable_query | boolean |
determines if queries should be executed
|
| result_class | string |
class used for result sets
|
| buffered_result_class | string |
class used for buffered result sets
|
| result_wrap_class | string |
class used to wrap result sets into
|
| result_buffering | boolean |
should results be buffered or not?
|
| fetch_class | string |
class to use when fetch mode object is used
|
| persistent | boolean |
persistent connection?
|
| debug | integer |
numeric debug level
|
| debug_handler | string |
function/method that captures debug messages
|
| debug_expanded_output | boolean |
BC option to determine if more context information should be send to the debug handler
|
| default_text_field_length | integer |
default text field length to use
|
| lob_buffer_length | integer |
LOB buffer length
|
| log_line_break | string |
line-break format
|
| idxname_format | string |
pattern with '%s' for index name
|
| seqname_format | string |
pattern with '%s' for sequence name
|
| savepoint_format | string |
pattern with '%s' for auto generated savepoint names
|
| seqcol_name | string |
sequence column name
|
| quote_identifier | boolean |
if identifier quoting should be done when check_option is used
|
| use_transactions | boolean |
if transaction use should be enabled
|
| decimal_places | integer |
number of decimal places to handle
|
| portability | integer |
portability constant
|
| modules | array |
short to long module name mapping for __call()
|
| emulate_prepared | boolean |
force prepared statements to be emulated
|
| datatype_map | array |
map user defined datatypes to other primitive datatypes
|
| 'datatype_map_callback | array |
callback function/method that should be called
|
In case of success you get a new instance of the database class.
It is strongly recommened to check this return value with
PEAR::isError()
(will detect PEAR_Error or any subclass) or the MDB2 specific
isError().
To disconnect use the method
disconnect()
from your database class instance.
Example 33-1. Connect and disconnect <?php
require_once 'MDB2.php';
$dsn = 'pgsql://someuser:apasswd@localhost/thedb';
$options = array(
'debug' => 2,
'result_buffering' => false,
);
$mdb2 =& MDB2::factory($dsn, $options);
if (PEAR::isError($mdb2)) {
die($mdb2->getMessage());
}
// ...
$mdb2->disconnect();
?> |
|
Example 33-2. Connect using an array for the DSN information <?php
require_once 'MDB2.php';
$dsn = array(
'phptype' => 'pgsql',
'username' => 'someuser',
'password' => 'apasswd',
'hostspec' => 'localhost',
'database' => 'thedb',
);
$options = array(
'debug' => 2,
'portability' => MDB2_PORTABILITY_ALL,
);
// uses MDB2::factory() to create the instance
// and also attempts to connect to the host
$mdb2 =& MDB2::connect($dsn, $options);
if (PEAR::isError($mdb2)) {
die($mdb2->getMessage());
}
?> |
When connecting to SQLite using a DSN array, the value
of the mode element must be a string:
<?php
$dsn = array(
'phptype' => 'sqlite',
'database' => 'thedb',
'mode' => '0644',
);
?> |
|
Example 33-3.
Connect to MySQLi via SSL
using an array for the DSN information
The ssl element of the
$options array must be set to
TRUE in order for SSL to work. Each of the extra
elements in the $dsn array
(key through cipher
in the example below) are optional.
<?php
require_once 'MDB2.php';
$dsn = array(
'phptype' => 'mysqli',
'username' => 'someuser',
'password' => 'apasswd',
'hostspec' => 'localhost',
'database' => 'thedb',
'key' => 'client-key.pem',
'cert' => 'client-cert.pem',
'ca' => 'cacert.pem',
'capath' => '/path/to/ca/dir',
'cipher' => 'AES',
);
$options = array(
'ssl' => true,
);
// gets an existing instance with the same DSN
// otherwise create a new instance using MDB2::factory()
$mdb2 =& MDB2::singleton($dsn, $options);
if (PEAR::isError($mdb2)) {
die($mdb2->getMessage());
}
?> |
|
Example 33-4. Connect to a PostgreSQL database via a socket <?php
require_once 'MDB2.php';
$dsn = 'pgsql://someuser:apasswd@unix(/tmp)/thedb';
$options = array(
'debug' => 2,
'portability' => MDB2_PORTABILITY_ALL,
);
$mdb2 =& MDB2::factory($dsn, $options);
if (PEAR::isError($mdb2)) {
die($mdb2->getMessage());
}
?> |
|
Example 33-5. Connect using singleton <?php
require_once 'MDB2.php';
$dsn = 'pgsql://someuser:apasswd@localhost/thedb';
$mdb2 =& MDB2::singleton($dsn);
if (PEAR::isError($mdb2)) {
die($mdb2->getMessage());
}
$blah =& new blah();
// is able to use the existing database connection
$blah->foo();
$mdb2->disconnect();
class blah
{
function foo() {
// get a reference to the existing database object
$mdb2 =& MDB2::singleton();
// ...
}
}
?> |
|