DB
class DB (View source)
Global database interface, complete with static methods.
Use this class for interacting with the database.
Constants
USE_ANSI_SQL |
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 |
ALT_DB_KEY |
Session key for alternative database name |
Properties
protected static | Database | $connections | The global database connection. |
|
protected static | array | $configs | List of configurations for each connection |
|
public static | string | $lastQuery | The last SQL query run. |
Methods
Retrieves the schema manager for the current database
Builds a sql query with the specified connection
Retrieves the connector object for the current database
Set an alternative database in a browser cookie, with the cookie lifetime set to the browser session.
Determines if the name is valid, as a security measure against setting arbitrary databases.
Specify connection to a database
Set config for a lazy-connected database
Helper function for generating a list of parameter placeholders for the given argument(s)
Execute the given SQL parameterised query with the specified arguments
Get the autogenerated ID from the previous INSERT query.
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 a new table.
Create a new field on a table.
Generate the following table in the database, modifying whatever already exists as necessary.
Generate the given field on the table, modifying whatever already exists as necessary.
Generate the given index in the database, modifying whatever already exists as necessary.
If the given table exists, move it out of the way by renaming it to obsolete(tablename).
See SS_Database->dontRequireField().
Checks a table's integrity and repairs it if necessary.
Show a message about database alteration
Details
static
set_conn(Database $connection, string $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.
static Database
get_conn(string $name = 'default')
Get the global database connection.
static
getConn($name = 'default')
deprecated
deprecated
No description
static DBSchemaManager
get_schema(string $name = 'default')
Retrieves the schema manager for the current database
static string
build_sql(SQLExpression $expression, array $parameters, string $name = 'default')
Builds a sql query with the specified connection
static DBConnector
get_connector(string $name = 'default')
Retrieves the connector object for the current database
static
set_alternative_database_name(string $name = null)
Set an alternative database in a browser cookie, with the cookie lifetime set to the browser session.
This is useful for integration testing on temporary databases.
There is a strict naming convention for temporary databases to avoid abuse:
static string|false
get_alternative_database_name()
Get the name of the database in use
static bool
valid_alternative_database_name(string $name)
Determines if the name is valid, as a security measure against setting arbitrary databases.
static Database
connect(array $databaseConfig, string $label = 'default')
Specify connection to a database
Given the database configuration, this method will create the correct subclass of SS_Database.
static
setConfig(array $databaseConfig, string $name = 'default')
Set config for a lazy-connected database
static mixed
getConfig(string $name = 'default')
Get the named connection config
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.
static Query
query(string $sql, int $errorLevel = E_USER_ERROR)
Execute the given SQL query.
static string|null
placeholders(array|int $input, string $join = ', ')
Helper function for generating a list of parameter placeholders for the given argument(s)
static string
inline_parameters(string $sql, array $parameters)
No description
static Query
prepared_query(string $sql, array $parameters, int $errorLevel = E_USER_ERROR)
Execute the given SQL parameterised query with the specified arguments
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.
Example:
array(
// Command: insert
"table name" => array(
"command" => "insert",
"fields" => array(
"ClassName" => "'MyClass'", // if you're setting a literal, you need to escape and provide quotes
"Created" => "now()", // alternatively, you can call DB functions
"ID" => 234,
),
"id" => 234 // an alternative to providing ID in the fields list
),
// Command: update
"other table" => array(
"command" => "update",
"fields" => array(
"ClassName" => "'MyClass'",
"LastEdited" => "now()",
),
"where" => "ID = 234",
"id" => 234 // an alternative to providing a where clause
),
)
You'll note that only one command on a given table can be called. That's a limitation of the system that's due to it being written for DataObject::write(), which needs to do a single write on a number of different tables.
static int
get_generated_id(string $table)
Get the autogenerated ID from the previous INSERT query.
static bool
is_active()
Check if the connection to the database is active.
static bool
create_database(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.
static string
create_table(string $table, array $fields = null, array $indexes = null, array $options = null, array $advancedOptions = null)
Create a new table.
static
create_field(string $table, string $field, string $spec)
Create a new field on a table.
static
require_table(string $table, string $fieldSchema = null, string $indexSchema = null, bool $hasAutoIncPK = true, string $options = null, array $extensions = null)
Generate the following table in the database, modifying whatever already exists as necessary.
static
require_field(string $table, string $field, string $spec)
Generate the given field on the table, modifying whatever already exists as necessary.
static
require_index(string $table, string $index, string|bool $spec)
Generate the given index in the database, modifying whatever already exists as necessary.
static
dont_require_table(string $table)
If the given table exists, move it out of the way by renaming it to obsolete(tablename).
static
dont_require_field(string $table, string $fieldName)
See SS_Database->dontRequireField().
static bool
check_and_repair_table(string $table)
Checks a table's integrity and repairs it if necessary.
static int
affected_rows()
Return the number of rows affected by the previous operation.
static array
table_list()
Returns a list of all tables in the database.
The table names will be in lower case.
static array
field_list(string $table)
Get a list of all the fields for the given table.
Returns a map of field name => field spec.
static
quiet(bool $quiet = true)
Enable suppression of database messages.
static
alteration_message(string $message, string $type = "")
Show a message about database alteration