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. |
$dsn = array(
'phptype' => false,
'dbsyntax' => false,
'username' => false,
'password' => false,
'protocol' => false,
'hostspec' => false,
'port' => false,
'socket' => false,
'database' => false,
'new_ink' => false,
); |
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
|
Example 33-2. Connect using an array for the DSN information
When connecting to SQLite using a DSN array, the value of the mode element must be a string:
|
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.
|
Example 33-4. Connect to a PostgreSQL database via a socket
|
Example 33-5. Connect using singleton
|