Version: current

# Class DB

Global database interface, complete with static methods. Use this class for interacting with the database.

Package: sapphire\model
Located at sapphire/core/model/DB.php

## Methods summary

`public static` | # `setConn( `SS_Database` $connection, mixed $name = 'default' )` Set the global database connection. Pass an object that's a subclass of SS_Database. This object will be used when `DB::query()` is called. Set the global database connection. Pass an object that's a subclass of SS_Database. This object will be used when `DB::query()` is called. #### Parameters $connection $connection The connecton object to set as the connection. $name $name The name to give to this connection. If you omit this argument, the connection will be the default one used by the ORM. However, you can store other named connections to be accessed through DB::getConn($name). This is useful when you have an application that needs to connect to more than one database.
`public static `SS_Database`` | # `getConn( mixed $name = 'default' )` Get the global database connection. Get the global database connection. #### Parameters $name $name An optional name given to a connection in the DB::setConn() call. If omitted, the default connection is returned. #### Returns ``SS_Database`` SS_Database
`public static` | # `set_alternative_database_name( mixed $dbname )` Set an alternative database to use for this browser session. This is useful when using testing systems other than SapphireTest; for example, Windmill. Set it to null to revert to the main database. Set an alternative database to use for this browser session. This is useful when using testing systems other than SapphireTest; for example, Windmill. Set it to null to revert to the main database.
`public static` | # `get_alternative_database_name( )` Get the name of the database in use Get the name of the database in use
`public static` | # `connect( array $databaseConfig )` Connect to a database. Given the database configuration, this method will create the correct subclass of SS_Database, and set it as the global connection. Connect to a database. Given the database configuration, this method will create the correct subclass of SS_Database, and set it as the global connection. #### Parameters $databaseConfig array $database A map of options. The 'type' is the name of the subclass of SS_Database to use. For the rest of the options, see the specific class.
`public static` | # `connection_attempted( )` Returns true if a database connection has been attempted. In particular, it lets the caller know if we're still so early in the execution pipeline that we haven't even tried to connect to the database yet. Returns true if a database connection has been attempted. In particular, it lets the caller know if we're still so early in the execution pipeline that we haven't even tried to connect to the database yet.
`public static string` | # `getConnect( array $parameters )` Build the connection string from input. Build the connection string from input. #### Parameters $parameters array $parameters The connection details. #### Returns `string` $connect The connection string.
`public static `SS_Query`` | # `query( string $sql, integer $errorLevel = E_USER_ERROR )` Execute the given SQL query. Execute the given SQL query. #### Parameters $sql string $sql The SQL query to execute $errorLevel int $errorLevel The level of error reporting to enable for the query #### Returns ``SS_Query`` SS_Query
`public static` | # `manipulate( array $manipulation )` Execute a complex manipulation on the database. A manipulation is an array of insert / or update sequences. The keys of the array are table names, and the values are map containing 'command' and 'fields'. Command should be 'insert' or 'update', and fields should be a map of field names to field values, including quotes. The field value can also be a SQL function or similar. Execute a complex manipulation on the database. A manipulation is an array of insert / or update sequences. The keys of the array are table names, and the values are map containing 'command' and 'fields'. Command should be 'insert' or 'update', and fields should be a map of field names to field values, including quotes. The field value can also be a SQL function or similar. #### Parameters $manipulation array $manipulation
`public static integer` | # `getGeneratedID( mixed $table )` Get the autogenerated ID from the previous INSERT query. Get the autogenerated ID from the previous INSERT query. #### Returns `integer` int
`public static boolean` | # `isActive( )` Check if the connection to the database is active. Check if the connection to the database is active. #### Returns `boolean` boolean
`public static boolean` | # `createDatabase( string $connect, string $username, string $password, string $database )` Create the database and connect to it. This can be called if the initial database connection is not successful because the database does not exist. Create the database and connect to it. This can be called if the initial database connection is not successful because the database does not exist. #### Parameters $connect string $connect Connection string $username string $username SS_Database username $password string $password SS_Database Password $database string $database SS_Database to which to create #### Returns `boolean` Returns true if successful
`public static The` | # `createTable( mixed $table, mixed $fields = null, mixed $indexes = null, mixed $options = null )` Create a new table. Create a new table. #### Parameters $table $tableName The name of the table $fields $fields A map of field names to field types $indexes $indexes A map of indexes $options $options An map of additional options. The available keys are as follows: - 'MSSQLDatabase'/'MySQLDatabase'/'PostgreSQLDatabase' - database-specific options such as "engine" for MySQL. - 'temporary' - If true, then a temporary table will be created #### Returns `The` table name generated. This may be different from the table name, for example with temporary tables.
`public static` | # `createField( string $table, string $field, string $spec )` Create a new field on a table. Create a new field on a table. #### Parameters $table string $table Name of the table. $field string $field Name of the field to add. $spec string $spec The field specification, eg 'INTEGER NOT NULL'
`public static` | # `requireTable( string $table, string $fieldSchema = null, string $indexSchema = null, boolean $hasAutoIncPK = true, string $options = null, mixed $extensions = null )` Generate the following table in the database, modifying whatever already exists as necessary. Generate the following table in the database, modifying whatever already exists as necessary. #### Parameters $table string $table The name of the table $fieldSchema string $fieldSchema A list of the fields to create, in the same form as DataObject::$db $indexSchema string $indexSchema A list of indexes to create. The keys of the array are the names of the index. $hasAutoIncPK boolean $hasAutoIncPK A flag indicating that the primary key on this table is an autoincrement type The values of the array can be one of: - true: Create a single column index on the field named the same as the index. - array('fields' => array('A','B','C'), 'type' => 'index/unique/fulltext'): This gives you full control over the index. $options string $options SQL statement to append to the CREATE TABLE call. $extensions
`public static` | # `requireField( string $table, string $field, string $spec )` Generate the given field on the table, modifying whatever already exists as necessary. Generate the given field on the table, modifying whatever already exists as necessary. #### Parameters $table string $table The table name. $field string $field The field name. $spec string $spec The field specification.
`public static` | # `requireIndex( string $table, string $index, string|boolean $spec )` Generate the given index in the database, modifying whatever already exists as necessary. Generate the given index in the database, modifying whatever already exists as necessary. #### Parameters $table string $table The table name. $index string $index The index name. $spec string|boolean $spec The specification of the index. See requireTable() for more information.
`public static` | # `dontRequireTable( string $table )` If the given table exists, move it out of the way by renaming it to _obsolete_(tablename). If the given table exists, move it out of the way by renaming it to _obsolete_(tablename). #### Parameters $table string $table The table name.
`public static` | # `dontRequireField( string $table, string $fieldName )` See SS_Database->dontRequireField(). See SS_Database->dontRequireField(). #### Parameters $table string $table The table name. $fieldName string $fieldName
`public static boolean` | # `checkAndRepairTable( mixed $table )` Checks a table's integrity and repairs it if necessary. Checks a table's integrity and repairs it if necessary. #### Returns `boolean` Return true if the table has integrity after the method is complete. #### Var string $tableName The name of the table.
`public static integer` | # `affectedRows( )` Return the number of rows affected by the previous operation. Return the number of rows affected by the previous operation. #### Returns `integer` int
`public static array` | # `tableList( )` Returns a list of all tables in the database. The table names will be in lower case. Returns a list of all tables in the database. The table names will be in lower case. #### Returns `array` array
`public static array` | # `fieldList( string $table )` Get a list of all the fields for the given table. Returns a map of field name => field spec. Get a list of all the fields for the given table. Returns a map of field name => field spec. #### Parameters $table string $table The table name. #### Returns `array` array
`public static` | # `quiet( )` Enable supression of database messages. Enable supression of database messages.
`public static` | # `alteration_message( mixed $message, mixed $type = "" )` Show a message about database alteration. Show a message about database alteration.

### Magic methods summary

## Constants summary

`boolean` | `USE_ANSI_SQL` | `true` | # This constant was added in SilverStripe 2.4 to indicate that SQL-queries should now use ANSI-compatible syntax. The most notable affect of this change is that table and field names should be escaped with double quotes and not backticks This constant was added in SilverStripe 2.4 to indicate that SQL-queries should now use ANSI-compatible syntax. The most notable affect of this change is that table and field names should be escaped with double quotes and not backticks

## Properties summary

`public static string` | $lastQuery | # The last SQL query run. The last SQL query run.

[Raise a SilverStripe Framework issue/bug](https://github.com/silverstripe/silverstripe-framework/issues/new)
- [Raise a SilverStripe CMS issue/bug](https://github.com/silverstripe/silverstripe-cms/issues/new)
- Please use the Silverstripe Forums to ask development related questions. -