File/PgQuery.php

Description

PostgreSQL query class and associated functions

This subpackage provides some functions that are useful around database activity and a PgQuery class to simplify handling of database queries.

The class is intended to be a very lightweight wrapper with no pretentions towards database independence, but it does include some features that have proved useful in developing and debugging web-based applications:

  • All queries are timed, and an expected time can be provided.
  • Parameters replaced into the SQL will be escaped correctly in order to minimise the chances of SQL injection errors.
  • Queries which fail, or which exceed their expected execution time, will be logged for potential further analysis.
  • Debug logging of queries may be enabled globally, or restricted to particular sets of queries.
  • Simple syntax for iterating through a result set.
The database should be connected in a variable $dbconn before PgQuery.php is included. If not already connected, PgQuery will attempt to connect to the database, successively applying connection parameters from the array in $c->pg_connect.

We will die if the database is not currently connected and we fail to find a working connection.

Classes
Class Description
 class PgQuery The PgQuery Class.
Includes
 require_once ("AWLUtilities.php") (line 55)
Variables
resource $dbconn The database connection. (line 105)
  • name: $dbconn The database connection.
Functions
awl_replace_sql_args (line 217)

Replaces PostgreSQL query with escaped parameters in preparation for execution.

The function takes a variable number of arguments, the first is the SQL string, with replaceable '?' characters (a la DBI). The subsequent parameters being the values to replace into the SQL string.

The values passed to the routine are analyzed for type, and quoted if they appear to need quoting. This can go wrong for (e.g.) NULL or other special SQL values which are not straightforwardly identifiable as needing quoting (or not). In such cases the parameter can be forced to be inserted unquoted by passing it as "array( 'plain' => $param )".

This function is outside the PgQuery class because it is sometimes desirable to build SQL command strings in circumstances where there is no benefit to using the class.

  • return: built query string
The awl_replace_sql_args (string 0, mixed 1)
  • string 0: The query string with replacable '?' characters.
  • mixed 1: The values to replace into the SQL string.
clean_string (line 180)

Clean a string of many suspicious characters

While this is a fairly aggressive approach, it applies in many circumstances where various strings should not contain things that might screw up (e.g.) filesystem semantics. Although not strictly a PgQuery function it's here for the time being until I invent a new "generally useful functions" include.

  • return: The pristine uncontaminated string we can safely use for Just About Anything(tm).
string clean_string (string $unclean, [ $type = 'full'])
  • string $unclean: The dirty filthy string needing washing.
  • $type
connect_configured_database (line 60)

Connect to the database defined in the $c->dbconn[] array

void connect_configured_database ()
duration (line 119)

A duration (in decimal seconds) between two times which are the result of calls to microtime()

This simple function is used by the PgQuery class because the microtime function doesn't return a decimal time, so a simple subtraction is not sufficient.

  • return: difference
double duration (microtime $t1, microtime $t2)
  • microtime $t1: start time
  • microtime $t2: end time
qpg (line 145)

Quote the given string (depending on its type) so that it can be used safely in a PostgreSQL query without fear of SQL injection errors.

Although this function effectively achieves a similar goal to the pg_escape_string() function, it is needed for older versions of PHP (< 4.2.0) and older versions of PostgreSQL (< 7.2.0), however. PgQuery does not attempt to use the newer pg_escape_string() function at this stage.

This function is outside the PgQuery class because it is sometimes desirable to quote values for SQL command strings in circumstances where there is no benefit to using the class.

  • return: NULL, TRUE, FALSE, a plain number, or the original string quoted and with ' and \ characters escaped
string qpg ([mixed $str = null])
  • mixed $str: Data to be converted to a string suitable for including as a value in SQL.

Documentation generated on Thu, 15 Apr 2010 20:23:06 +1200 by phpDocumentor 1.3.2