include/database/DBManager.php

Show: inherited
Table of Contents

\DBManager

Package: SugarCRM

Base database driver implementation

Children
\MssqlManager
\MysqlManager
Api
 

Properties

Propertyprotected  $capabilities= 'array()'

Capabilities this DB supports. Supported list: affected_rows Can report query affected rows for UPDATE/DELETE implement getAffectedRowCount() select_rows Can report row count for SELECT implement getRowCount() case_sensitive Supports case-sensitive text columns fulltext Supports fulltext search indexes inline_keys Supports defining keys together with the table auto_increment_sequence Autoincrement support implemented as sequence limit_subquery Supports LIMIT clauses in subqueries create_user Can create users for Sugar create_db Can create databases collation Supports setting collations disable_keys Supports temporarily disabling keys (for upgrades, etc.)

Default valuearray()Details
Type
n/a
Abstract
Special cases: fix:expandDatabase - needs expandDatabase fix, see expandDatabase.php TODO: verify if we need these cases  
Propertypublicresource  $database= 'null'

Name of database

Default valuenullDetails
Type
resource
Propertyprotected  $dieOnError= 'false'

Indicates whether we should die when we get an error from the DB

Default valuefalseDetails
Type
n/a
Propertyprotected  $encode= 'true'

Indicates whether we should html encode the results from a query by default

Default valuetrueDetails
Type
n/a
Propertyprotectedarray  $index_descriptions= 'array()'
static

Index descriptions

Default valuearray()Details
Type
array
Propertypublicstring  $label= ''''

Driver name label, for install

Default value''Details
Type
string
Absrtact
 
Propertyprotected  $lastResult= ''

Registry of available result sets

Details
Type
n/a
Propertyprotected  $last_error= 'false'

Last error message from the DB backend

Default valuefalseDetails
Type
n/a
Propertyprotected\Logger  $log= ''

PHP Logger

Details
Type
\Logger
Propertyprotectedarray  $maxNameLengths= 'array( 'table' => 64, 'column' => 64, 'index' => 64, 'alias' => 64 )'

Maximum length of identifiers

Default valuearray( 'table' => 64, 'column' => 64, 'index' => 64, 'alias' => 64 )Details
Type
array
Abstract
 
Propertyprotectedarray  $options= 'array()'

Database options

Default valuearray()Details
Type
array
Propertyprotected  $preparedTokens= 'array()'

Array of prepared statements and their correspoding parsed tokens

Default valuearray()Details
Type
n/a
Propertypublicint  $priority= '0'

DB driver priority Higher priority drivers override lower priority ones

Default value0Details
Type
int
Propertyprivate  $queryCount= '0'
static

Current query count

Default value0Details
Type
n/a
Propertyprivate  $queryLimit= '0'
static

Query threshold limit

Default value0Details
Type
n/a
Propertyprotected  $query_time= '0'

Records the execution time of the last query

Default value0Details
Type
n/a
Propertyprotected  $standardQueries= 'array( 'ALTER TABLE' => 'verifyAlterTable', 'DROP TABLE' => 'verifyDropTable', 'CREATE TABLE' => 'verifyCreateTable', 'INSERT INTO' => 'verifyInsertInto', 'UPDATE' => 'verifyUpdate', 'DELETE FROM' => 'verifyDeleteFrom', )'
Default valuearray( 'ALTER TABLE' => 'verifyAlterTable', 'DROP TABLE' => 'verifyDropTable', 'CREATE TABLE' => 'verifyCreateTable', 'INSERT INTO' => 'verifyInsertInto', 'UPDATE' => 'verifyUpdate', 'DELETE FROM' => 'verifyDeleteFrom', )Details
Type
n/a
Propertyprotectedarray  $table_descriptions= 'array()'
static

Table descriptions

Default valuearray()Details
Type
array
Propertyprotected\TimeDate  $timedate= ''

TimeDate instance

Details
Type
\TimeDate
Propertyprotectedarray  $type_class= 'array( 'int' => 'int', 'double' => 'float', 'float' => 'float', 'uint' => 'int', 'ulong' => 'bigint', 'long' => 'bigint', 'short' => 'int', 'date' => 'date', 'datetime' => 'date', 'datetimecombo' => 'date', 'time' => 'time', 'bool' => 'bool', 'tinyint' => 'int', 'currency' => 'float', 'decimal' => 'float', 'decimal2' => 'float', )'

Type classification into: - int - bool - float - date

Default valuearray( 'int' => 'int', 'double' => 'float', 'float' => 'float', 'uint' => 'int', 'ulong' => 'bigint', 'long' => 'bigint', 'short' => 'int', 'date' => 'date', 'datetime' => 'date', 'datetimecombo' => 'date', 'time' => 'time', 'bool' => 'bool', 'tinyint' => 'int', 'currency' => 'float', 'decimal' => 'float', 'decimal2' => 'float', )Details
Type
array
Abstract
 
Propertyprotectedarray  $type_map= 'array()'

Type names map

Default valuearray()Details
Type
array
Abstract
 

Methods

methodpublic__construct( ) : void

Create DB Driver

methodpublic__get( string $p ) : mixed

Wrapper for those trying to access the private and protected class members directly

Parameters
Name Type Description
$p string

var name

Returns
Type Description
mixed
methodprotected_emptyValue( mixed $val, string $type ) : bool

Check if the value is empty value for this type

Parameters
Name Type Description
$val mixed

Value

$type string

Type (one of vardef types)

Returns
Type Description
bool true if the value if empty
methodprotected_getBooleanValue( mixed $val ) : bool

Get truth value for boolean type Allows 'off' to mean false, along with all 'empty' values

Parameters
Name Type Description
$val mixed
Returns
Type Description
bool
methodpublicaddColumn( string $tablename, array $fieldDefs ) : bool

Adds a column to table identified by field def.

Parameters
Name Type Description
$tablename string
$fieldDefs array
Returns
Type Description
bool query result
methodpublicaddColumnSQL( string $tablename, array $fieldDefs ) : string

This method generates sql for adding a column to table identified by field def.

Parameters
Name Type Description
$tablename string
$fieldDefs array
Returns
Type Description
string SQL statement
methodpublicaddIndexes( string $tablename, array $indexes, bool $execute = true ) : string

Adds a new indexes

Parameters
Name Type Description
$tablename string
$indexes array

indexes to add

$execute bool

true if we want to execute the returned sql statement

Returns
Type Description
string SQL statement
methodpublicadd_drop_constraint( string $table, array $definition, bool $drop = false ) : string
abstract

Generates alter constraint statement given a table name and vardef definition.

Supports both adding and droping a constraint.

Parameters
Name Type Description
$table string

tablename

$definition array

field definition

$drop bool

true if we are dropping the constraint, false if we are adding it

Returns
Type Description
string SQL statement
methodpublicalterColumn( string $tablename, array $newFieldDef, bool $ignoreRequired = false ) : bool

Alters old column identified by oldFieldDef to new fieldDef.

Parameters
Name Type Description
$tablename string
$newFieldDef array
$ignoreRequired bool

optional, true if we are ignoring this being a required field

Returns
Type Description
bool query result
methodpublicalterColumnSQL( string $tablename, array $newFieldDefs, bool $ignorerequired = false ) : string | array

This method genrates sql for altering old column identified by oldFieldDef to new fieldDef.

Parameters
Name Type Description
$tablename string
$newFieldDefs array
$ignorerequired bool

Optional, true if we should ignor this being a required field

Returns
Type Description
string | array SQL statement(s)
methodpublicarrayQuote( array $array ) : array

Quote the strings of the passed in array

The array must only contain strings

Parameters
Name Type Description
$array array
Returns
Type Description
array Quoted strings
methodprotectedauditSQL( \SugarBean $bean, array $changes ) : string

Generate query for audit table

Parameters
Name Type Description
$bean \SugarBean

SugarBean that was changed

$changes array

List of changes, contains 'before' and 'after'

Returns
Type Description
string Audit table INSERT query
methodpubliccanInstall( ) : mixed

Check special requirements for DB installation.

Returns
Type Description
mixed
Details
Abstract
If everything is OK, return true. If something's wrong, return array of error code and parameters  
methodprotectedchangeColumnSQL( string $tablename, array $fieldDefs, string $action, bool $ignoreRequired = false ) : string | array
abstract

Generates the SQL for changing columns

Parameters
Name Type Description
$tablename string
$fieldDefs array
$action string
$ignoreRequired bool

Optional, true if we should ignor this being a required field

Returns
Type Description
string | array
methodpubliccheckConnection( ) : void

Checks the current connection; if it is not connected then reconnect

methodpubliccheckError( string $msg = '', bool $dieOnError = false ) : bool

Checks for error happening in the database

Parameters
Name Type Description
$msg string

message to prepend to the error message

$dieOnError bool

true if we want to die immediately on error

Returns
Type Description
bool True if there was an error
methodpubliccheckPrivilege( string $privilege ) : bool

Check if connecting user has certain privilege

Parameters
Name Type Description
$privilege string
Returns
Type Description
bool Privilege allowed?
methodprotectedcheckQuery( string $sql, bool $object_name = false ) : bool

Scans order by to ensure that any field being ordered by is.

It will throw a warning error to the log file - fatal if slow query logging is enabled

Parameters
Name Type Description
$sql string

query to be run

$object_name bool

optional, object to look up indices in

Returns
Type Description
bool true if an index is found false otherwise
methodprotectedcolumnSQLRep( array $fieldDefs, bool $ignoreRequired = false, string $tablename ) : string

Returns SQL defintions for all columns in a table

Parameters
Name Type Description
$fieldDefs array

Vardef-format field def

$ignoreRequired bool

Optional, true if we should ignor this being a required field

$tablename string

Optional, table name

Returns
Type Description
string SQL column definitions
methodpubliccommit( ) : bool

Commits pending changes to the database when the driver is setup to support transactions.

Note that the default implementation is applicable for transaction-less or auto commit scenarios.

Returns
Type Description
bool true if commit succeeded, false if it failed
Details
Abstract
 
methodpubliccompareFieldInTables( string $name, string $table1, string $table2 ) : array

Compare a field in two tables

Parameters
Name Type Description
$name string

field name

$table1 string
$table2 string
Returns
Type Description
array array with keys 'msg','table1','table2'
Details
Deprecated
 
methodpubliccompareVarDefs( array $fielddef1, array $fielddef2, bool $ignoreName = false ) : bool

Compares two vardefs

Parameters
Name Type Description
$fielddef1 array

This is from the database

$fielddef2 array

This is from the vardef

$ignoreName bool

Ignore name-only differences?

Returns
Type Description
bool true if they match, false if they don't
methodpublicconcat( string $table, array $fields, string $space = ' ' ) : string

Returns the database string needed for concatinating multiple database strings together

Parameters
Name Type Description
$table string

table name of the database fields to concat

$fields array

fields in the table to concat together

$space string

Separator between strings, default is single space

Returns
Type Description
string
methodpublicconnect( array $configOptions = null, boolean $dieOnError = false ) : void
abstract

Connects to the database backend

Takes in the database settings and opens a database connection based on those will open either a persistent or non-persistent connection. If a persistent connection is desired but not available it will defualt to non-persistent

configOptions must include db_host_name - server ip db_user_name - database user name db_password - database password

Parameters
Name Type Description
$configOptions array
$dieOnError boolean
methodpublicconvert( string $string, string $type, array $additional_parameters = array() ) : string
abstract

Use when you need to convert a database string to a different value; this function does it in a database-backend aware way Supported conversions: today return current date left Take substring from the left date_format Format date as string, supports %Y-%m-%d, %Y-%m, %Y time_format Format time as string date Convert date string to datetime value time Convert time string to datetime value datetime Convert datetime string to datetime value ifnull If var is null, use default value concat Concatenate strings quarter Quarter number of the date length Length of string month Month number of the date add_date Add specified interval to a date add_time Add time interval to a date text2char Convert text field to varchar

Parameters
Name Type Description
$string string

database string to convert

$type string

type of conversion to do

$additional_parameters array

optional, additional parameters to pass to the db function

Returns
Type Description
string
methodpubliccountQuery( ) : void

This function increments the global $sql_queries variable

methodprotectedcreateConstraintSql( \SugarBean $bean ) : array

returns SQL to create constraints or indices

Parameters
Name Type Description
$bean \SugarBean

SugarBean instance

Returns
Type Description
array list of SQL statements
methodpubliccreateDatabase( string $dbname ) : void
abstract

Create a database

Parameters
Name Type Description
$dbname string
methodpubliccreateDbUser( string $database_name, string $host_name, string $user, string $password ) : void
abstract

Create DB user

Parameters
Name Type Description
$database_name string
$host_name string
$user string
$password string
methodpubliccreateIndex( \SugarBean $bean, array $fieldDefs, string $name, bool $unique = true ) : bool

Creates an index identified by name on the given fields.

Parameters
Name Type Description
$bean \SugarBean

SugarBean instance

$fieldDefs array

Field definitions, in vardef format

$name string

index name

$unique bool

optional, true if we want to create an unique index

Returns
Type Description
bool query result
methodpubliccreateIndexSQL( \SugarBean $bean, array $fields, string $name, bool $unique = true ) : string

Generates SQL for create index statement for a bean.

Parameters
Name Type Description
$bean \SugarBean

SugarBean instance

$fields array

fields used in the index

$name string

index name

$unique bool

Optional, set to true if this is an unique index

Returns
Type Description
string SQL Select Statement
methodpubliccreateTable( \SugarBean $bean ) : void

Implements creation of a db table for a bean.

NOTE: does not handle out-of-table constraints, use createConstraintSQL for that

Parameters
Name Type Description
$bean \SugarBean

Sugarbean instance

methodpubliccreateTableParams( string $tablename, array $fieldDefs, array $indices, string $engine = null ) : bool

Implements creation of a db table

Parameters
Name Type Description
$tablename string
$fieldDefs array

Field definitions, in vardef format

$indices array

Index definitions, in vardef format

$engine string

Engine parameter, used for MySQL engine so far

Returns
Type Description
bool success value
Details
Todo
: refactor engine param to be more generic  
methodpubliccreateTableSQL( \SugarBean $bean ) : string

Generates sql for create table statement for a bean.

NOTE: does not handle out-of-table constraints, use createConstraintSQL for that

Parameters
Name Type Description
$bean \SugarBean

SugarBean instance

Returns
Type Description
string SQL Create Table statement
methodpubliccreateTableSQLParams( string $tablename, array $fieldDefs, array $indices ) : string
abstract

Generates sql for create table statement for a bean.

Parameters
Name Type Description
$tablename string
$fieldDefs array
$indices array
Returns
Type Description
string SQL Create Table statement
methodpublicdbExists( string $dbname ) : void
abstract

Check if certain database exists

Parameters
Name Type Description
$dbname string
methodpublicdelete( \SugarBean $bean, array $where = array() ) : bool

Implements a generic delete for any bean identified by id

Parameters
Name Type Description
$bean \SugarBean

Sugarbean instance

$where array

values with the keys as names of fields. If we want to pass multiple values for a name, pass it as an array If where is not passed, it defaults to id of table

Returns
Type Description
bool query result
methodpublicdeleteAutoIncrement( string $table, string $field_name ) : void

Deletes an auto increment

Parameters
Name Type Description
$table string

tablename

$field_name string
Details
Abstract
 
methodpublicdeleteColumn( \SugarBean $bean, array $fieldDefs ) : bool

Deletes a column identified by fieldDef.

Parameters
Name Type Description
$bean \SugarBean

SugarBean containing the field

$fieldDefs array

Vardef definition of the field

Returns
Type Description
bool query result
methodpublicdeleteColumnSQL( \SugarBean $bean, array $fieldDefs ) : string

This method generates sql that deletes a column identified by fieldDef.

Parameters
Name Type Description
$bean \SugarBean

Sugarbean instance

$fieldDefs array
Returns
Type Description
string SQL statement
methodpublicdeleteSQL( \SugarBean $bean, array $where ) : string

Generates SQL for delete statement identified by id.

Parameters
Name Type Description
$bean \SugarBean

SugarBean instance

$where array

where conditions in an array

Returns
Type Description
string SQL Update Statement
methodprotecteddescribeField( string $name, string $tablename ) : array

Returns the field description for a given field in table

Parameters
Name Type Description
$name string
$tablename string
Returns
Type Description
array
methodprotecteddescribeIndex( string $name, string $tablename ) : array

Returns the index description for a given index in table

Parameters
Name Type Description
$name string
$tablename string
Returns
Type Description
array
methodpublicdisableKeys( string $tableName ) : void

Disable keys on the table

Parameters
Name Type Description
$tableName string
Details
Abstract
 
methodpublicdisconnect( ) : void
abstract

Disconnects from the database

Also handles any cleanup needed

methodpublicdisconnectAll( ) : void

Details
Deprecated
Disconnects all instances  
methodpublicdropColumnSQL( string $tablename, array $fieldDefs ) : string

This method generates sql that drops a column identified by fieldDef.

Designed to work like the other addColumnSQL() and alterColumnSQL() functions

Parameters
Name Type Description
$tablename string
$fieldDefs array
Returns
Type Description
string SQL statement
methodpublicdropDatabase( string $dbname ) : void
abstract

Drop a database

Parameters
Name Type Description
$dbname string
methodpublicdropIndexes( string $tablename, array $indexes, bool $execute = true ) : string

Drops indexes

Parameters
Name Type Description
$tablename string
$indexes array

indexes to drop

$execute bool

true if we want to execute the returned sql statement

Returns
Type Description
string SQL statement
methodpublicdropTable( \SugarBean $bean ) : bool

Drops the table associated with a bean

Parameters
Name Type Description
$bean \SugarBean

SugarBean instance

Returns
Type Description
bool query result
methodpublicdropTableName( string $name ) : bool

Drops the table by name

Parameters
Name Type Description
$name string

Table name

Returns
Type Description
bool query result
methodpublicdropTableNameSQL( string $name ) : string

Generates SQL for dropping a table.

Parameters
Name Type Description
$name string

table name

Returns
Type Description
string SQL statement
methodpublicdropTableSQL( \SugarBean $bean ) : string

Generates SQL for dropping a table.

Parameters
Name Type Description
$bean \SugarBean

Sugarbean instance

Returns
Type Description
string SQL statement
methodprotecteddump_slow_queries( string $query ) : boolean

This method is called by every method that runs a query.

If slow query dumping is turned on and the query time is beyond the time limit, we will log the query. This function may do additional reporting or log in a different area in the future.

Parameters
Name Type Description
$query string

query to log

Returns
Type Description
boolean true if the query was logged, false otherwise
methodpublicemptyValue( string $type ) : mixed

Return representation of an empty value depending on type The value is fully quoted, converted, etc.

Parameters
Name Type Description
$type string
Returns
Type Description
mixed Empty value
methodpublicenableKeys( string $tableName ) : void

Re-enable keys on the table

Parameters
Name Type Description
$tableName string
Details
Abstract
 
methodpublicescape_quote( string $string ) : string

Quotes a string for storing in the database

Parameters
Name Type Description
$string string
Returns
Type Description
string
Details
Deprecated
Return value will be not surrounded by quotes  
methodpublicexecutePreparedQuery( int $stmt, array $data = array() ) : resource

Takes a prepared stmt index and the data to replace and creates the query and runs it.

Parameters
Name Type Description
$stmt int

The index of the prepared statement from preparedTokens

$data array

The array of data to replace the tokens with.

Returns
Type Description
resource result set or false on error
methodprotectedextractTableName( string $query ) : string

Extract table name from a query

Parameters
Name Type Description
$query string

SQL query

Returns
Type Description
string
methodpublicfetchByAssoc( resource $result, bool $encode = true ) : array

Fetches the next row in the query result into an associative array

Parameters
Name Type Description
$result resource
$encode bool

Need to HTML-encode the result?

Returns
Type Description
array returns false if there are no more rows available to fetch
methodpublicfetchOne( string $sql, bool $dieOnError = false, string $msg = '', bool $suppress = false ) : array

Runs a query and returns a single row

Parameters
Name Type Description
$sql string

SQL Statement to execute

$dieOnError bool

True if we want to call die if the query returns errors

$msg string

Message to log if error occurs

$suppress bool

Message to log if error occurs

Returns
Type Description
array single row from the query
methodpublicfetchRow( resource $result ) : array
abstract

Fetches the next row in the query result into an associative array

Parameters
Name Type Description
$result resource
Returns
Type Description
array returns false if there are no more rows available to fetch
methodprotectedfreeDbResult( resource $dbResult ) : void
abstract

Free Database result

Parameters
Name Type Description
$dbResult resource
methodprotectedfreeResult( resource | bool $result = false ) : void

Frees out previous results

Parameters
Name Type Description
$result resource | bool

optional, pass if you want to free a single result instead of all results

methodpublicfromConvert( string $string, string $type ) : string
abstract

Converts from Database data to app data

Supported types - date - time - datetime - datetimecombo - timestamp

Parameters
Name Type Description
$string string

database string to convert

$type string

type of conversion to do

Returns
Type Description
string
methodpublicfull_text_indexing_installed( ) : bool
abstract

Check if the database supports fulltext indexing Note that database driver can be capable of supporting FT (see supports('fulltext)) but particular instance can still have it disabled

Returns
Type Description
bool
methodpublicfull_text_indexing_setup( ) : void

Setup FT indexing

Details
Abstract
 
methodpublicgenerateInsertSQL( \SugarBean $bean, string $select_query, int $start, int $count = -1, string $table, bool $is_related_query = false ) : string

Generate a set of Insert statements based on the bean given

Parameters
Name Type Description
$bean \SugarBean

the bean from which table we will generate insert stmts

$select_query string

the query which will give us the set of objects we want to place into our insert statement

$start int

the first row to query

$count int

the number of rows to query

$table string

the table to query from

$is_related_query bool
Returns
Type Description
string SQL insert statement
Details
Deprecated
 
methodpublicgetAffectedRowCount( resource $result ) : int

Returns the number of rows affected by the last query

Parameters
Name Type Description
$result resource

query result resource

Returns
Type Description
int
Details
Abstract
See also affected_rows capability, will return 0 unless the DB supports it  
methodpublicgetAutoIncrement( string $table, string $field_name ) : string

Returns the next value for an auto increment

Parameters
Name Type Description
$table string

Table name

$field_name string

Field name

Returns
Type Description
string
Details
Abstract
 
methodpublicgetAutoIncrementSQL( string $table, string $field_name ) : string

Returns the sql for the next value in a sequence

Parameters
Name Type Description
$table string

Table name

$field_name string

Field name

Returns
Type Description
string
Details
Abstract
 
methodpublicgetCollationList( ) : array

List of available collation settings

Returns
Type Description
array
Details
Abstract
 
methodpublicgetColumnType( string $type ) : string

Returns the valid type for a column given the type in fieldDef

Parameters
Name Type Description
$type string

field type

Returns
Type Description
string valid type for the given field
methodprotectedgetColumnWhereClause( string $table, array $whereArray = array() ) : string

Returns a where clause without the 'where' key word

The clause returned does not have an 'and' at the beginning and the columns are joined by 'and'.

Parameters
Name Type Description
$table string

table name

$whereArray array

Optional, where conditions in an array

Returns
Type Description
string
methodpublicgetConstraintSql( array $indices, string $table ) : array

returns a SQL query that creates the indices as defined in metadata

Parameters
Name Type Description
$indices array

Assoc array with index definitions from vardefs

$table string

Focus table

Returns
Type Description
array Array of SQL queries to generate indices
methodpublicgetDataChanges( \SugarBean $bean ) : array

Uses the audit enabled fields array to find fields whose value has changed.

The before and after values are stored in the bean. Uses $bean->fetched_row to compare

Parameters
Name Type Description
$bean \SugarBean

Sugarbean instance that was changed

Returns
Type Description
array
methodpublicgetDatabase( ) : resource

Returns the current database handle

Returns
Type Description
resource
methodpublicgetDbInfo( ) : array | null
abstract

Get database configuration information (DB-dependent)

Returns
Type Description
array | null
methodpublicgetDefaultCollation( ) : string

List of available collation settings

Returns
Type Description
string
Details
Abstract
 
methodprotectedgetFieldNameFromSelect( string $string ) : string

returns the field name used in a select

Parameters
Name Type Description
$string string

SELECT query

Returns
Type Description
string
methodpublicgetFieldType( array $fieldDef ) : string

Returns the type of the variable in the field

Parameters
Name Type Description
$fieldDef array

Vardef-format field def

Returns
Type Description
string
methodpublicgetFieldsArray( resource $result, boolean $make_lower_case = false ) : array
abstract

Returns the description of fields based on the result

Parameters
Name Type Description
$result resource
$make_lower_case boolean
Returns
Type Description
array field array
methodpublicgetFromDummyTable( ) : string
abstract

Returns a DB specific FROM clause which can be used to select against functions.

Note that depending on the database that this may also be an empty string.

Returns
Type Description
string
Details
Abstract
 
methodpublicgetFulltextQuery( string $field, array $terms, array $must_terms = array(), array $exclude_terms = array() ) : void
abstract

Generate fulltext query from set of terms

Parameters
Name Type Description
$field string

Field to search against

$terms array

Search terms that may be or not be in the result

$must_terms array

Search terms that have to be in the result

$exclude_terms array

Search terms that have to be not in the result

methodpublicgetGuidSQL( ) : string
abstract

Returns a DB specific piece of SQL which will generate GUID (UUID) This string can be used in dynamic SQL to do multiple inserts with a single query.

I.e. generate a unique Sugar id in a sub select of an insert statement.

Returns
Type Description
string
Details
Abstract
 
methodpublicgetHelper( ) : \DBManager

Returns this instance's DBHelper Actually now returns $this

Returns
Type Description
\DBManager
Details
Deprecated
 
methodpublicgetOne( string $sql, bool $dieOnError = false, string $msg = '' ) : array

Runs a query and returns a single row containing single value

Parameters
Name Type Description
$sql string

SQL Statement to execute

$dieOnError bool

True if we want to call die if the query returns errors

$msg string

Message to log if error occurs

Returns
Type Description
array single value from the query
methodpublicgetOption( string $option ) : mixed

Get DB option by name

Parameters
Name Type Description
$option string

Option name

Returns
Type Description
mixed Option value or null if doesn't exist
methodpublicgetOptions( ) : array

Get DB options

Returns
Type Description
array
methodpublicgetQueryCount( ) : int
static

Returns the static queryCount value

Returns
Type Description
int value of the queryCount static variable
methodpublicgetQueryTime( ) : int

Returns the time the last query took to execute

Returns
Type Description
int
methodpublicgetRowCount( resource $result ) : int

Returns the number of rows returned by the result

This function can't be reliably implemented on most DB, do not use it.

Parameters
Name Type Description
$result resource
Returns
Type Description
int
Details
Abstract
 
Deprecated
 
methodpublicgetScriptName( ) : string

Get DB driver name used for install/upgrade scripts

Returns
Type Description
string
methodpublicgetSelectFieldsFromQuery( string $selectStatement ) : array

Take an SQL statement and produce a list of fields used in that select

Parameters
Name Type Description
$selectStatement string
Returns
Type Description
array
methodpublicgetTableDescription( string $tablename, bool $reload = false ) : array

Get table description

Parameters
Name Type Description
$tablename string
$reload bool

true means load from DB, false allows using cache

Returns
Type Description
array Vardef-format table description
methodpublicgetTablesArray( ) : array | false
abstract

Returns an array of tables for this database

Returns
Type Description
array | false an array of with table names, false if no tables found
methodpublicgetTypeParts( string $type ) : array | bool

retrieves the different components from the passed column type as it is used in the type mapping and vardefs type format: [([,])]

Parameters
Name Type Description
$type string

Column type

Returns
Type Description
array | bool array containing the different components of the passed in type or false in case the type contains illegal characters
methodpublicgetValidDBName( string | array $name, bool | string $ensureUnique = false, string $type = 'column', bool $force = false ) : string | array

Return a version of $proposed that can be used as a column name in any of our supported databases Practically this means no longer than 25 characters as the smallest identifier length for our supported DBs is 30 chars for Oracle plus we add on at least four characters in some places (for indicies for example)

Parameters
Name Type Description
$name string | array

Proposed name for the column

$ensureUnique bool | string

Ensure the name is unique

$type string

Name type (table, column)

$force bool

Force new name

Returns
Type Description
string | array Valid column name trimmed to right length and with invalid characters removed
methodprotectedgetWhereClause( \SugarBean $bean, array $whereArray = array() ) : string

This method returns a complete where clause built from the where values specified.

Parameters
Name Type Description
$bean \SugarBean

SugarBean that describes the table

$whereArray array

Optional, where conditions in an array

Returns
Type Description
string
methodpublicget_columns( string $tablename ) : array
abstract

Returns definitions of all indies for passed table.

return will is a multi-dimensional array that categorizes the index definition by types, unique, primary and index.

 array (
          'name'   => 'field1',
          'type'   => 'varchar',
          'len' => '200'
          )
      )
?>

This format is similar to how indicies are defined in vardef file.

Parameters
Name Type Description
$tablename string
Returns
Type Description
array
methodpublicget_indices( string $tablename ) : array
abstract

Returns definitions of all indies for passed table.

return will is a multi-dimensional array that categorizes the index definition by types, unique, primary and index.

 array (
          'name'   => 'index1',
          'type'   => 'primary',
          'fields' => array('field1','field2')
          )
      )
?>

This format is similar to how indicies are defined in vardef file.

Parameters
Name Type Description
$tablename string
Returns
Type Description
array
methodprotectedhasLimit( string $sql ) : bool

Parameters
Name Type Description
$sql string
Returns
Type Description
bool
Details
Abstract
Check if query has LIMIT clause Relevant for now only for Mysql  
methodpublicinsert( \SugarBean $bean ) : bool

Implements a generic insert for any bean.

Parameters
Name Type Description
$bean \SugarBean

SugarBean instance

Returns
Type Description
bool query result
methodpublicinsertParams( string $table, array $field_defs, array $data, array $field_map = null, bool $execute = true ) : bool

Insert data into table by parameter definition

Parameters
Name Type Description
$table string

Table name

$field_defs array

Definitions in vardef-like format

$data array

Key/value to insert

$field_map array

Fields map from SugarBean

$execute bool

Execute or return query?

Returns
Type Description
bool query result
methodpublicinsertSQL( \SugarBean $bean ) : string

Generates SQL for insert statement.

Parameters
Name Type Description
$bean \SugarBean

SugarBean instance

Returns
Type Description
string SQL Create Table statement
methodpublicinstallConfig( ) : array
abstract

Get install configuration for this DB

Returns
Type Description
array
methodpublicisBooleanType( string $type ) : bool

Check if type is boolean

Parameters
Name Type Description
$type string
Returns
Type Description
bool
methodpublicisDatabaseNameValid( string $name ) : bool

Check if this DB name is valid

Parameters
Name Type Description
$name string
Returns
Type Description
bool
methodpublicisFieldArray( mixed $defArray ) : bool

Checks to see if passed array is truely an array of defitions

Such an array may have type as a key but it will point to an array for a true array of definitions an to a col type for a definition only

Parameters
Name Type Description
$defArray mixed
Returns
Type Description
bool
methodprotectedisNullable( array $vardef ) : bool

Can this field be null? Auto-increment and ID fields can not be null

Parameters
Name Type Description
$vardef array
Returns
Type Description
bool
methodpublicisNumericType( string $type ) : bool

Check if type is a number

Parameters
Name Type Description
$type string
Returns
Type Description
bool
methodprotectedisSelect( string $query ) : bool

Check if the query is a select query

Parameters
Name Type Description
$query string
Returns
Type Description
bool Is query SELECT?
methodpublicisTextType( string $type ) : bool

Parameters
Name Type Description
$type string
Returns
Type Description
bool
Details
Abstract
Does this type represent text (i.e., non-varchar) value?  
methodpubliclastDbError( ) : string | false
abstract

Get last database error This function should return last error as reported by DB driver and should return false if no error condition happened

Returns
Type Description
string | false Error message or false if no error happened
methodpubliclastError( ) : string

Return DB error message for the last query executed

Returns
Type Description
string Last error message
methodpubliclimitQuery( string $sql, int $start, int $count, boolean $dieOnError = false, string $msg = '', bool $execute = true ) : resource
abstract

Runs a limit query: one where we specify where to start getting records and how many to get

Parameters
Name Type Description
$sql string

SELECT query

$start int

Starting row

$count int

How many rows

$dieOnError boolean

True if we want to call die if the query returns errors

$msg string

Message to log if error occurs

$execute bool

Execute or return SQL?

Returns
Type Description
resource query result
methodpubliclimitQuerySql( string $sql, int $start, int $count, bool $dieOnError = false, string $msg = '' ) : resource | bool

Return limit query based on given query

Parameters
Name Type Description
$sql string
$start int
$count int
$dieOnError bool
$msg string
Returns
Type Description
resource | bool query result
Details
See
\DBManager::limitQuery()  
methodpublicmassageFieldDef( array $fieldDef, string $tablename ) : array

Massages the field defintions to fill in anything else the DB backend may add

Parameters
Name Type Description
$fieldDef array
$tablename string
Returns
Type Description
array
methodpublicmassageValue( mixed $val, array $fieldDef ) : mixed

Outputs a correct string for the sql statement according to value

Parameters
Name Type Description
$val mixed
$fieldDef array

field definition

Returns
Type Description
mixed
methodpublicmodifyIndexes( string $tablename, array $indexes, bool $execute = true ) : string

Modifies indexes

Parameters
Name Type Description
$tablename string
$indexes array

indexes to modify

$execute bool

true if we want to execute the returned sql statement

Returns
Type Description
string SQL statement
methodpublicnow( ) : string

Return current time in format fit for insertion into DB (with quotes)

Returns
Type Description
string
methodpublicnumber_of_columns( string $table_name ) : int

Returns the number of columns in a table

Parameters
Name Type Description
$table_name string
Returns
Type Description
int
methodprotectedoneColumnSQLRep( array $fieldDef, bool $ignoreRequired = false, string $table = '', bool $return_as_array = false ) : string

Returns the defintion for a single column

Parameters
Name Type Description
$fieldDef array

Vardef-format field def

$ignoreRequired bool

Optional, true if we should ignore this being a required field

$table string

Optional, table name

$return_as_array bool

Optional, true if we should return the result as an array instead of sql

Returns
Type Description
string or array if $return_as_array is true
methodpublicorderByEnum( string $order_by, array $values, string $order_dir ) : string

Create ORDER BY clause for ENUM type field

Parameters
Name Type Description
$order_by string

Field name

$values array

Possible enum value

$order_dir string

Order direction, ASC or DESC

Returns
Type Description
string
methodpublicpQuery( string $sql, array $data = array() ) : resource

Run both prepare and execute without the client having to run both individually.

Parameters
Name Type Description
$sql string

The sql to parse

$data array

The array of data to replace the tokens with.

Returns
Type Description
resource result set or false on error
methodpublicparseFulltextQuery( string $query ) : array

Parse fulltext search query with mysql syntax: terms quoted by "" + means the term must be included - means the term must be excluded * or % at the end means wildcard

Parameters
Name Type Description
$query string
Returns
Type Description
array of 3 elements - query terms, mandatory terms and excluded terms
methodpublicpostInstall( ) : void

Details
Abstract
Code run on new database after installing  
methodpublicpreInstall( ) : void

Details
Abstract
Code run on new database before installing  
methodpublicprepareQuery( string $sql ) : int

Given a sql stmt attempt to parse it into the sql and the tokens. Then return the index of this prepared statement Tokens can come in the following forms: ? - a scalar which will be quoted ! - a literal which will not be quoted & - binary data to read from a file

Parameters
Name Type Description
$sql string

The sql to parse

Returns
Type Description
int index of the prepared statement to be used with execute
methodpublicquery( string $sql, bool $dieOnError = false, string $msg = '', bool $suppress = false, bool $keepResult = false ) : resource | bool
abstract

Parses and runs queries

Parameters
Name Type Description
$sql string

SQL Statement to execute

$dieOnError bool

True if we want to call die if the query returns errors

$msg string

Message to log if error occurs

$suppress bool

Flag to suppress all error output unless in debug logging mode.

$keepResult bool

Keep query result in the object?

Returns
Type Description
resource | bool result set or success/failure bool
methodpublicqueryArray( array $sqls, bool $dieOnError = false, string $msg = '', bool $suppress = false ) : resource | bool

Execute multiple queries one after another

Parameters
Name Type Description
$sqls array

Queries

$dieOnError bool

Die on error, passed to query()

$msg string

Error message, passed to query()

$suppress bool

Supress errors, passed to query()

Returns
Type Description
resource | bool result set or success/failure bool
methodpublicquote( string $string ) : string
abstract

Quote string in DB-specific manner

Parameters
Name Type Description
$string string
Returns
Type Description
string
methodpublicquoteFormEmail( string $string ) : string

Quotes a string for storing in the database

Parameters
Name Type Description
$string string
Returns
Type Description
string
Details
Deprecated
Return value will be not surrounded by quotes  
methodpublicquoteType( string $type, string $value ) : string

Quote value according to type Numerics aren't quoted Dates are converted and quoted Rest is just quoted

Parameters
Name Type Description
$type string
$value string
Returns
Type Description
string Quoted value
methodpublicquoted( string $string ) : string

Return string properly quoted with ''

Parameters
Name Type Description
$string string
Returns
Type Description
string
methodprotectedregisterError( string $userMessage, string $message, bool $dieOnError = false ) : void

Register database error If die-on-error flag is set, logs the message and dies, otherwise sets last_error to the message

Parameters
Name Type Description
$userMessage string

Message from function user

$message string

Message from SQL driver

$dieOnError bool
methodpublicrenameColumnSQL( string $tablename, string $column, string $newname ) : void
abstract

Rename column in the DB

Parameters
Name Type Description
$tablename string
$column string
$newname string
methodpublicrenameIndexDefs( array $old_definition, array $new_definition, string $table_name ) : string

Renames an index using fields definition

Parameters
Name Type Description
$old_definition array
$new_definition array
$table_name string
Returns
Type Description
string SQL statement
methodpublicrepairTable( \SugarBean $bean, bool $execute = true ) : string

Implements repair of a db table for a bean.

Parameters
Name Type Description
$bean \SugarBean

SugarBean instance

$execute bool

true if we want the action to take place, false if we just want the sql returned

Returns
Type Description
string SQL statement or empty string, depending upon $execute
methodpublicrepairTableParams( string $tablename, array $fielddefs, array $indices, bool $execute = true, string $engine = null ) : string

Builds the SQL commands that repair a table structure

Parameters
Name Type Description
$tablename string
$fielddefs array

Field definitions, in vardef format

$indices array

Index definitions, in vardef format

$execute bool

optional, true if we want the queries executed instead of returned

$engine string

optional, MySQL engine

Returns
Type Description
string
Details
Todo
: refactor engine param to be more generic  
methodpublicresetQueryCount( ) : void
static

Resets the queryCount value to 0

methodpublicretrieve( \SugarBean $bean, array $where = array() ) : resource

Implements a generic retrieve for any bean identified by id

If we want to pass multiple values for a name, pass it as an array If where is not passed, it defaults to id of table

Parameters
Name Type Description
$bean \SugarBean

Sugarbean instance

$where array

values with the keys as names of fields.

Returns
Type Description
resource result from the query
methodpublicretrieveSQL( \SugarBean $bean, array $where ) : string

Generates SQL for select statement for any bean identified by id.

Parameters
Name Type Description
$bean \SugarBean

SugarBean instance

$where array

where conditions in an array

Returns
Type Description
string SQL Select Statement
methodpublicretrieveView( array $beans, array $cols = array(), array $where = array() ) : resource

Implements a generic retrieve for a collection of beans.

These beans will be joined in the sql by the key attribute of field defs. Currently, this function does support outer joins.

Parameters
Name Type Description
$beans array

Sugarbean instance(s)

$cols array

columns to be returned with the keys as names of bean as identified by get_class of bean. Values of this array is the array of fieldDefs to be returned for a bean. If an empty array is passed, all columns are selected.

$where array

values with the keys as names of bean as identified by get_class of bean Each value at the first level is an array of values for that bean identified by name of fields. If we want to pass multiple values for a name, pass it as an array If where is not passed, all the rows will be returned.

Returns
Type Description
resource
methodpublicretrieveViewSQL( array $beans, array $cols = array(), array $whereClause = array() ) : string

This method implements a generic sql for a collection of beans.

Currently, this function does not support outer joins.

Parameters
Name Type Description
$beans array

Array of values returned by get_class method as the keys and a bean as the value for that key. These beans will be joined in the sql by the key attribute of field defs.

$cols array

Optional, columns to be returned with the keys as names of bean as identified by get_class of bean. Values of this array is the array of fieldDefs to be returned for a bean. If an empty array is passed, all columns are selected.

$whereClause array

Optional, values with the keys as names of bean as identified by get_class of bean. Each value at the first level is an array of values for that bean identified by name of fields. If we want to pass multiple values for a name, pass it as an array. If where is not passed, all the rows will be returned.

Returns
Type Description
string SQL Select Statement
methodpublicrollback( ) : bool

Rollsback pending changes to the database when the driver is setup to support transactions.

Note that the default implementation is applicable for transaction-less or auto commit scenarios. Since rollbacks cannot be done, this implementation always returns false.

Returns
Type Description
bool true if rollback succeeded, false if it failed
Details
Abstract
 
methodpublicsave_audit_records( \SugarBean $bean, array $changes ) : bool

Saves changes to module's audit table

Parameters
Name Type Description
$bean \SugarBean

Sugarbean instance that was changed

$changes array

List of changes, contains 'before' and 'after'

Returns
Type Description
bool query result
methodprotectedsetAutoIncrement( string $table, string $field_name ) : string

Either creates an auto increment through queries or returns sql for auto increment that can be appended to the end of column defination (mysql)

Parameters
Name Type Description
$table string

Table name

$field_name string

Field name

Returns
Type Description
string
Details
Abstract
 
methodpublicsetAutoIncrementStart( string $table, string $field_name, int $start_value ) : string

Sets the next auto-increment value of a column to a specific value.

Parameters
Name Type Description
$table string

Table name

$field_name string

Field name

$start_value int

Starting autoincrement value

Returns
Type Description
string
Details
Abstract
 
methodpublicsetDieOnError( bool $value ) : void

Sets the dieOnError value

Parameters
Name Type Description
$value bool
methodpublicsetOptions( array $options ) : \DBManager

Set database options Options are usually db-dependant and derive from $config['dbconfigoption']

Parameters
Name Type Description
$options array
Returns
Type Description
\DBManager
methodpublicsetQueryLimit( int $limit ) : void
static

This function sets the query threshold limit

Parameters
Name Type Description
$limit int

value of query threshold limit

methodpublicsupports( string $cap ) : bool

Check if this DB supports certain capability See $this->capabilities for the list

Parameters
Name Type Description
$cap string
Returns
Type Description
bool
methodpublictableExists( string $tableName ) : bool
abstract

Checks if a table with the name $tableName exists and returns true if it does or false otherwise

Parameters
Name Type Description
$tableName string
Returns
Type Description
bool
methodpublictablesLike( string $like ) : array
abstract

Get tables like expression

Parameters
Name Type Description
$like string

Expression describing tables

Returns
Type Description
array
methodpublictruncate( string $string, int $len ) : string

Truncates a string to a given length

Parameters
Name Type Description
$string string
$len int

length to trim to

Returns
Type Description
string
methodpublictruncateTableSQL( string $name ) : string

Generates SQL for truncating a table.

Parameters
Name Type Description
$name string

table name

Returns
Type Description
string
methodpublicupdate( \SugarBean $bean, array $where = array() ) : bool

Implements a generic update for any bean

Parameters
Name Type Description
$bean \SugarBean

Sugarbean instance

$where array

values with the keys as names of fields. If we want to pass multiple values for a name, pass it as an array If where is not passed, it defaults to id of table

Returns
Type Description
bool query result
methodpublicupdateSQL( \SugarBean $bean, array $where = array() ) : string

Generates SQL for update statement.

Parameters
Name Type Description
$bean \SugarBean

SugarBean instance

$where array

Optional, where conditions in an array

Returns
Type Description
string SQL Create Table statement
methodprotectedupdateWhereArray( \SugarBean $bean, array $where = array() ) : array

This method returns a where array so that it has id entry if where is not an array or is empty

Parameters
Name Type Description
$bean \SugarBean

SugarBean instance

$where array

Optional, where conditions in an array

Returns
Type Description
array
methodpublicuserExists( string $username ) : void
abstract

Check if certain DB user exists

Parameters
Name Type Description
$username string
methodpublicvalid( ) : bool
abstract

Check if this driver can be used

Returns
Type Description
bool
methodprotectedvalidColumnType( string $type ) : bool

returns true if the type can be mapped to a valid column type

Parameters
Name Type Description
$type string
Returns
Type Description
bool
methodpublicvalidateQuery( string $query ) : bool
abstract

Check if this query is valid Validates only SELECT queries

Parameters
Name Type Description
$query string
Returns
Type Description
bool
methodprotectedverifyCreateTable( string $table, string $query ) : string

Tests an CREATE TABLE query

Parameters
Name Type Description
$table string

The table name to get DDL

$query string

The query to test.

Returns
Type Description
string Non-empty if error found
methodpublicverifySQLStatement( string $query, array $skipTables ) : string

Verify SQl statement using per-DB verification function provided the function exists

Parameters
Name Type Description
$query string

Query to verify

$skipTables array

List of blacklisted tables that aren't checked

Returns
Type Description
string
methodpublicversion( ) : string
abstract

Return's the version of the database

Returns
Type Description
string
Documentation was generated by DocBlox 0.18.1.