Documentation

Pgsql extends Base
in package

PDO_PostgreSQL Horde_Db_Adapter

Tags
author

Mike Naberezny mike@maintainable.com

author

Derek DeVries derek@maintainable.com

author

Chuck Hagenbuch chuck@horde.org

category

Horde

copyright

2007 Maintainable Software, LLC

copyright

2008-2021 Horde LLC

license

http://www.horde.org/licenses/bsd

subpackage

Adapter

Table of Contents

$active  : bool
Is connection active?
$cache  : Horde_Cache
Cache object.
$cachePrefix  : string
Cache prefix.
$config  : array<string|int, mixed>
Config options.
$connection  : mixed
DB connection.
$lastQuery  : string
The last query sent to the database.
$logger  : Horde_Log_Logger
Log object.
$logQueries  : bool
Log query flag
$rowCount  : int
Row count of last action.
$runtime  : int
Runtime of last query.
$schema  : Schema
Schema object.
$schemaClass  : string
$schemaMethods  : array<string|int, mixed>
List of schema methods.
$transactionStarted  : int
Has a transaction been started?
__call()  : mixed
Delegate calls to the schema object.
__construct()  : mixed
Constructor.
__destruct()  : mixed
Free any resources that are open.
__sleep()  : mixed
Serialize callback.
__wakeup()  : mixed
Unserialize callback.
adapterName()  : string
addLimitOffset()  : string
Appends LIMIT and OFFSET options to a SQL statement.
addLock()  : mixed
Appends a locking clause to an SQL statement.
beginDbTransaction()  : mixed
Begins the transaction (and turns off auto-committing).
cacheRead()  : string|false
Reads values from the cache handler.
cacheWrite()  : mixed
Writes values to the cache handler.
commitDbTransaction()  : mixed
Commits the transaction (and turns on auto-committing).
connect()  : mixed
Connect to the db.
delete()  : int
Executes the delete statement and returns the number of rows affected.
disconnect()  : mixed
Disconnect from db.
emptyInsertStatement()  : string
TODO
getCache()  : Horde_Cache
getLastQuery()  : string
Get the last query run
getLogger()  : mixed
return Horde_Log_Logger
getOption()  : mixed
Returns an adaptor option set through the constructor.
insert()  : int
Inserts a row into a table.
insertBlob()  : int
Inserts a row including BLOBs into a table.
insertFixture()  : mixed
Inserts the given fixture into the table. Overridden in adapters that require something beyond a simple insert (eg. Oracle).
isActive()  : bool
Is the connection active?
prefetchPrimaryKey()  : bool
Should primary key values be selected from their corresponding sequence before the insert statement? If true, next_sequence_value is called before each insert to set the record's primary key.
quote()  : void
quoteColumnName()  : string
quoteString()  : string
Quotes a string, escaping any ' (single quote) and \ (backslash) characters.
quoteTableName()  : string
rawConnection()  : resource
Provides access to the underlying database connection. Useful for when you need to call a proprietary method such as postgresql's lo_* methods.
reconnect()  : mixed
Reconnect to the db.
resetRuntime()  : int
Reset the timer
rollbackDbTransaction()  : mixed
Rolls back the transaction (and turns on auto-committing). Must be done if the transaction block raises an exception or returns false.
sanitizeLimit()  : mixed
TODO
select()  : Result
Returns an array of records with the column names as keys, and column values as values.
selectAll()  : array<string|int, mixed>
Returns an array of record hashes with the column names as keys and column values as values.
selectAssoc()  : array<string|int, mixed>
Returns an array where the keys are the first column of a select, and the values are the second column:
selectOne()  : array<string|int, mixed>
Returns a record hash with the column names as keys and column values as values.
selectValue()  : string
Returns a single value from a record
selectValues()  : array<string|int, mixed>
Returns an array of the values of the first column in a select: selectValues("SELECT id FROM companies LIMIT 3") => [1,2,3]
setCache()  : mixed
Set a cache object.
setLogger()  : mixed
Set a logger object.
supportsCountDistinct()  : bool
Does this adapter support using DISTINCT within COUNT? This is +true+ for all adapters except sqlite.
supportsInsertWithReturning()  : mixed
supportsInterval()  : bool
Does this adapter support using INTERVAL statements? This is +true+ for all adapters except sqlite.
supportsMigrations()  : bool
supportsStandardConformingStrings()  : bool
Does PostgreSQL support standard conforming strings?
transactionStarted()  : bool
Check if a transaction has been started.
update()  : int
Executes the update statement and returns the number of rows affected.
updateBlob()  : mixed
Updates rows including BLOBs into a table.
buildDsnString()  : mixed
cacheKey()  : string
Returns the prefixed cache key to use.
checkRequiredConfig()  : mixed
Checks if required configuration keys are present.
configureConnection()  : mixed
Configures the encoding, verbosity, and schema search path of the connection.
executePrepared()  : mixed
Use a PDO prepared statement to execute a query. Used when passing values to insert/update as a stream resource.
formatLogEntry()  : string
Formats the log entry.
lastInsertId()  : mixed
Returns the current ID of a table's sequence.
logError()  : mixed
logInfo()  : mixed
Logs the SQL query for debugging.
normalizeConfig()  : mixed
parseConfig()  : array<string|int, mixed>
Parse configuration array into options for PDO constructor.
replaceParameters()  : string
Replace ? in a SQL statement with quoted values from $args
selectRaw()  : mixed

Properties

$active

Is connection active?

protected bool $active = null

$cache

Cache object.

protected Horde_Cache $cache

$cachePrefix

Cache prefix.

protected string $cachePrefix

$config

Config options.

protected array<string|int, mixed> $config = []

$connection

DB connection.

protected mixed $connection = null

$lastQuery

The last query sent to the database.

protected string $lastQuery

$logger

Log object.

protected Horde_Log_Logger $logger

$logQueries

Log query flag

protected bool $logQueries = false

$rowCount

Row count of last action.

protected int $rowCount = null

$runtime

Runtime of last query.

protected int $runtime

$schema

Schema object.

protected Schema $schema = null

$schemaClass

protected string $schemaClass = \Horde\Db\Adapter\Postgresql\Schema::class

$schemaMethods

List of schema methods.

protected array<string|int, mixed> $schemaMethods = []

$transactionStarted

Has a transaction been started?

protected int $transactionStarted = 0

Methods

__call()

Delegate calls to the schema object.

public __call(string $method, array<string|int, mixed> $args) : mixed
Parameters
$method : string
$args : array<string|int, mixed>
Tags
throws
BadMethodCallException
Return values
mixed

TODO

__construct()

Constructor.

public __construct(array<string|int, mixed> $config) : mixed
Parameters
$config : array<string|int, mixed>

Configuration options and optional objects:

'charset' - (string) TODO
Return values
mixed

__destruct()

Free any resources that are open.

public __destruct() : mixed
Return values
mixed

__sleep()

Serialize callback.

public __sleep() : mixed
Return values
mixed

__wakeup()

Unserialize callback.

public __wakeup() : mixed
Return values
mixed

adapterName()

public adapterName() : string
Return values
string

addLimitOffset()

Appends LIMIT and OFFSET options to a SQL statement.

public addLimitOffset(string $sql, array<string|int, mixed> $options) : string
Parameters
$sql : string

SQL statement.

$options : array<string|int, mixed>

Hash with 'limit' and (optional) 'offset' values.

Return values
string

addLock()

Appends a locking clause to an SQL statement.

public addLock(string &$sql[, array<string|int, mixed> $options = [] ]) : mixed

This method modifies the +sql+ parameter.

TODO: BC BREAK Rather return the modified string

SELECT * FROM suppliers FOR UPDATE

add_lock! 'SELECT * FROM suppliers', :lock => true add_lock! 'SELECT * FROM suppliers', :lock => ' FOR UPDATE'

Parameters
$sql : string

SQL statment.

$options : array<string|int, mixed> = []

TODO.

Return values
mixed

beginDbTransaction()

Begins the transaction (and turns off auto-committing).

public beginDbTransaction() : mixed
Return values
mixed

cacheRead()

Reads values from the cache handler.

public cacheRead(string $key) : string|false

The key is automatically prefixed to avoid collisions when using different adapters or different configurations.

Parameters
$key : string

A cache key.

Tags
since

Horde_Db 2.1.0

Return values
string|false

A value.

cacheWrite()

Writes values to the cache handler.

public cacheWrite(string $key, string $value) : mixed

The key is automatically prefixed to avoid collisions when using different adapters or different configurations.

Parameters
$key : string

A cache key.

$value : string

A value.

Tags
since

Horde_Db 2.1.0

Return values
mixed

commitDbTransaction()

Commits the transaction (and turns on auto-committing).

public commitDbTransaction() : mixed
Return values
mixed

connect()

Connect to the db.

public connect() : mixed
Tags
throws
DbException
Return values
mixed

delete()

Executes the delete statement and returns the number of rows affected.

public delete(string $sql[, mixed $arg1 = null ][, string $arg2 = null ]) : int
Parameters
$sql : string

SQL statement.

$arg1 : mixed = null

Either an array of bound parameters or a query name.

$arg2 : string = null

If $arg1 contains bound parameters, the query name.

Tags
throws
DbException
Return values
int

Number of rows affected.

disconnect()

Disconnect from db.

public disconnect() : mixed
Return values
mixed

emptyInsertStatement()

TODO

public emptyInsertStatement(string $tableName) : string
Parameters
$tableName : string

TODO

Return values
string

TODO

getCache()

public getCache() : Horde_Cache
Return values
Horde_Cache

getLastQuery()

Get the last query run

public getLastQuery() : string
Return values
string

getLogger()

return Horde_Log_Logger

public getLogger() : mixed
Return values
mixed

getOption()

Returns an adaptor option set through the constructor.

public getOption(string $option) : mixed
Parameters
$option : string

The option to return.

Return values
mixed

The option value or null if option doesn't exist or is not set.

insert()

Inserts a row into a table.

public insert(string $sql[, array<string|int, mixed>|string $arg1 = null ][, string $arg2 = null ][, string $pk = null ][, mixed $idValue = null ][, string $sequenceName = null ]) : int
Parameters
$sql : string

SQL statement.

$arg1 : array<string|int, mixed>|string = null

Either an array of bound parameters or a query name.

$arg2 : string = null

If $arg1 contains bound parameters, the query name.

$pk : string = null

The primary key column.

$idValue : mixed = null

The primary key value. This parameter is required if the primary key is inserted manually.

$sequenceName : string = null

The sequence name.

Tags
throws
DbException
Return values
int

Last inserted ID.

insertBlob()

Inserts a row including BLOBs into a table.

public insertBlob(string $table, array<string|int, mixed> $fields[, string $pk = null ][, mixed $idValue = null ]) : int
Parameters
$table : string

The table name.

$fields : array<string|int, mixed>

A hash of column names and values. BLOB/CLOB columns must be provided as Horde_Db_Value objects.

$pk : string = null

The primary key column.

$idValue : mixed = null

The primary key value. This parameter is required if the primary key is inserted manually.

Tags
since

Horde_Db 2.1.0

throws
DbException
Return values
int

Last inserted ID.

insertFixture()

Inserts the given fixture into the table. Overridden in adapters that require something beyond a simple insert (eg. Oracle).

public insertFixture(mixed $fixture, string $tableName) : mixed
Parameters
$fixture : mixed

TODO

$tableName : string

TODO

Return values
mixed

isActive()

Is the connection active?

public isActive() : bool
Return values
bool

prefetchPrimaryKey()

Should primary key values be selected from their corresponding sequence before the insert statement? If true, next_sequence_value is called before each insert to set the record's primary key.

public prefetchPrimaryKey([mixed $tableName = null ]) : bool

This is false for all adapters but Firebird.

Parameters
$tableName : mixed = null
Tags
deprecated
Return values
bool

quote()

public quote(mixed $value, mixed $column) : void
Parameters
$value : mixed
$column : mixed
Return values
void

quoteColumnName()

public quoteColumnName(string $name) : string
Parameters
$name : string
Return values
string

quoteString()

Quotes a string, escaping any ' (single quote) and \ (backslash) characters.

public quoteString(string $string) : string

.

Parameters
$string : string
Return values
string

quoteTableName()

public quoteTableName(string $name) : string
Parameters
$name : string
Return values
string

rawConnection()

Provides access to the underlying database connection. Useful for when you need to call a proprietary method such as postgresql's lo_* methods.

public rawConnection() : resource
Return values
resource

reconnect()

Reconnect to the db.

public reconnect() : mixed
Return values
mixed

resetRuntime()

Reset the timer

public resetRuntime() : int
Return values
int

rollbackDbTransaction()

Rolls back the transaction (and turns on auto-committing). Must be done if the transaction block raises an exception or returns false.

public rollbackDbTransaction() : mixed
Return values
mixed

sanitizeLimit()

TODO

public sanitizeLimit(mixed $limit) : mixed
Parameters
$limit : mixed
Return values
mixed

select()

Returns an array of records with the column names as keys, and column values as values.

public select(string $sql[, mixed $arg1 = null ][, string $arg2 = null ]) : Result
Parameters
$sql : string

SQL statement.

$arg1 : mixed = null

Either an array of bound parameters or a query name.

$arg2 : string = null

If $arg1 contains bound parameters, the query name.

Tags
throws
DbException
Return values
Result

selectAll()

Returns an array of record hashes with the column names as keys and column values as values.

public selectAll(string $sql[, mixed $arg1 = null ][, string $arg2 = null ]) : array<string|int, mixed>
Parameters
$sql : string

SQL statement.

$arg1 : mixed = null

Either an array of bound parameters or a query name.

$arg2 : string = null

If $arg1 contains bound parameters, the query name.

Tags
throws
DbException
Return values
array<string|int, mixed>

selectAssoc()

Returns an array where the keys are the first column of a select, and the values are the second column:

public selectAssoc(string $sql[, mixed $arg1 = null ][, string $arg2 = null ]) : array<string|int, mixed>

selectAssoc("SELECT id, name FROM companies LIMIT 3") => [1 => 'Ford', 2 => 'GM', 3 => 'Chrysler']

Parameters
$sql : string

SQL statement.

$arg1 : mixed = null

Either an array of bound parameters or a query name.

$arg2 : string = null

If $arg1 contains bound parameters, the query name.

Tags
throws
DbException
Return values
array<string|int, mixed>

selectOne()

Returns a record hash with the column names as keys and column values as values.

public selectOne(string $sql[, mixed $arg1 = null ][, string $arg2 = null ]) : array<string|int, mixed>
Parameters
$sql : string

SQL statement.

$arg1 : mixed = null

Either an array of bound parameters or a query name.

$arg2 : string = null

If $arg1 contains bound parameters, the query name.

Tags
throws
DbException
Return values
array<string|int, mixed>

selectValue()

Returns a single value from a record

public selectValue(string $sql[, mixed $arg1 = null ][, string $arg2 = null ]) : string
Parameters
$sql : string

SQL statement.

$arg1 : mixed = null

Either an array of bound parameters or a query name.

$arg2 : string = null

If $arg1 contains bound parameters, the query name.

Tags
throws
DbException
Return values
string

selectValues()

Returns an array of the values of the first column in a select: selectValues("SELECT id FROM companies LIMIT 3") => [1,2,3]

public selectValues(string $sql[, mixed $arg1 = null ][, string $arg2 = null ]) : array<string|int, mixed>
Parameters
$sql : string

SQL statement.

$arg1 : mixed = null

Either an array of bound parameters or a query name.

$arg2 : string = null

If $arg1 contains bound parameters, the query name.

Tags
throws
DbException
Return values
array<string|int, mixed>

setCache()

Set a cache object.

public setCache(Horde_Cache $cache) : mixed
Parameters
$cache : Horde_Cache

The cache object.

Tags
inject
Return values
mixed

setLogger()

Set a logger object.

public setLogger(Horde_Log_Logger $logger[, mixed $log_queries = false ]) : mixed
Parameters
$logger : Horde_Log_Logger
$log_queries : mixed = false
Tags
inject
Return values
mixed

supportsCountDistinct()

Does this adapter support using DISTINCT within COUNT? This is +true+ for all adapters except sqlite.

public supportsCountDistinct() : bool
Return values
bool

supportsInsertWithReturning()

public supportsInsertWithReturning() : mixed
Return values
mixed

supportsInterval()

Does this adapter support using INTERVAL statements? This is +true+ for all adapters except sqlite.

public supportsInterval() : bool
Return values
bool

supportsMigrations()

public supportsMigrations() : bool
Return values
bool

supportsStandardConformingStrings()

Does PostgreSQL support standard conforming strings?

public supportsStandardConformingStrings() : bool
Return values
bool

transactionStarted()

Check if a transaction has been started.

public transactionStarted() : bool
Return values
bool

True if transaction has been started.

update()

Executes the update statement and returns the number of rows affected.

public update(string $sql[, mixed $arg1 = null ][, string $arg2 = null ]) : int
Parameters
$sql : string

SQL statement.

$arg1 : mixed = null

Either an array of bound parameters or a query name.

$arg2 : string = null

If $arg1 contains bound parameters, the query name.

Tags
throws
DbException
Return values
int

Number of rows affected.

updateBlob()

Updates rows including BLOBs into a table.

public updateBlob(string $table, array<string|int, mixed> $fields[, string|array<string|int, mixed> $where = null ]) : mixed
Parameters
$table : string

The table name.

$fields : array<string|int, mixed>

A hash of column names and values. BLOB/CLOB columns must be provided as Horde_Db_Value objects.

$where : string|array<string|int, mixed> = null

A WHERE clause. Either a complete clause or an array containing a clause with placeholders and a list of values.

Tags
since

Horde_Db 2.2.0

throws
DbException
Return values
mixed

buildDsnString()

protected buildDsnString(mixed $params) : mixed
Parameters
$params : mixed
Return values
mixed

cacheKey()

Returns the prefixed cache key to use.

protected cacheKey(string $key) : string
Parameters
$key : string

A cache key.

Return values
string

Prefixed cache key.

checkRequiredConfig()

Checks if required configuration keys are present.

protected checkRequiredConfig(array<string|int, mixed> $required) : mixed
Parameters
$required : array<string|int, mixed>

Required configuration keys.

Tags
throws
DbException

if a required key is missing.

Return values
mixed

configureConnection()

Configures the encoding, verbosity, and schema search path of the connection.

protected configureConnection() : mixed

This is called by connect() and should not be called manually.

Return values
mixed

executePrepared()

Use a PDO prepared statement to execute a query. Used when passing values to insert/update as a stream resource.

protected executePrepared(string $sql, array<string|int, mixed> $values, array<string|int, mixed> $binary_values) : mixed
Parameters
$sql : string

The SQL statement. Includes '?' placeholder for binding non-stream values. Stream values are bound using a placeholders named like ':binary0', ':binary1' etc...

$values : array<string|int, mixed>

An array of non-stream values.

$binary_values : array<string|int, mixed>

An array of stream resources.

Tags
throws
DbException
Return values
mixed

formatLogEntry()

Formats the log entry.

protected formatLogEntry(string $message, string $sql) : string
Parameters
$message : string

Message.

$sql : string

SQL statment.

Return values
string

Formatted log entry.

lastInsertId()

Returns the current ID of a table's sequence.

protected lastInsertId(mixed $table, mixed $sequenceName) : mixed

NOTE: This requires that the sequence was already used to INSERT a value in this session.

Parameters
$table : mixed
$sequenceName : mixed
Tags
todo

Remove unused $table parameter.

Return values
mixed

logError()

protected logError(mixed $error, mixed $name[, mixed $runtime = null ]) : mixed
Parameters
$error : mixed
$name : mixed
$runtime : mixed = null
Return values
mixed

logInfo()

Logs the SQL query for debugging.

protected logInfo(string $sql, array<string|int, mixed> $values[, string $name = null ][, float $runtime = null ]) : mixed
Parameters
$sql : string

SQL statement.

$values : array<string|int, mixed>

An array of values to substitute for placeholders.

$name : string = null

Optional queryname.

$runtime : float = null

Runtime interval.

Return values
mixed

normalizeConfig()

protected normalizeConfig(mixed $params) : mixed
Parameters
$params : mixed
Return values
mixed

parseConfig()

Parse configuration array into options for PDO constructor.

protected parseConfig() : array<string|int, mixed>
Tags
throws
DbException
Return values
array<string|int, mixed>

[dsn, username, password]

replaceParameters()

Replace ? in a SQL statement with quoted values from $args

protected replaceParameters(string $sql, array<string|int, mixed> $args[, bool $no_binary = false ]) : string
Parameters
$sql : string

SQL statement.

$args : array<string|int, mixed>

An array of values to bind.

$no_binary : bool = false

If true, do not replace any Horde_Db_Value_Binary values. Used for logging purposes.

Tags
throws
DbException
Return values
string

Modified SQL statement.

selectRaw()

protected selectRaw(mixed $sql[, mixed $arg1 = null ][, mixed $arg2 = null ]) : mixed
Parameters
$sql : mixed
$arg1 : mixed = null
$arg2 : mixed = null
Tags
TODO
Return values
mixed

Search results