Add explain method to query builder

classes/idb_sql.php

@@ -31,6 +31,14 @@ interface iDB_SQL {
 	 * @return string
 	 */
 	public function limit($sql, $limit, $offset=FALSE);
+	
+	/**
+	 * Modify the query to get the query plan
+	 *
+	 * @param string $sql
+	 * @return string
+	 */
+	public function explain($sql);
 
 	/**
 	 * Get the sql for random ordering
@@ -113,4 +121,4 @@ interface iDB_SQL {
 	public function column_list($table);
 
 }
-// End of db_sql.php
+// End of db_sql.php

classes/iquery_builder.php

@@ -85,6 +85,15 @@ interface iQuery_Builder {
 	 * @return $this
 	 */
 	public function distinct();
+	
+	// --------------------------------------------------------------------------
+	
+	/**
+	 * Shows the query plan for the query
+	 *
+	 * @return $this
+	 */
+	public function explain();
 
 	// --------------------------------------------------------------------------
 
@@ -181,9 +190,10 @@ interface iQuery_Builder {
 	 *
 	 * @param mixed $key
 	 * @param mixed $val
+	 @ @param bool $escape
 	 * @return $this
 	 */
-	public function where($key, $val=array());
+	public function where($key, $val=array(), $escape = NULL);
 
 	// --------------------------------------------------------------------------
 

classes/query_builder.php

@@ -92,6 +92,9 @@ class Query_Builder implements iQuery_Builder {
 
 	// List of sql queries executed
 	public $queries;
+	
+	// Whether to do only an explain on the query
+	protected $explain = FALSE;
 
 	// --------------------------------------------------------------------------
 	// ! Methods
@@ -267,6 +270,19 @@ class Query_Builder implements iQuery_Builder {
 		$this->select_string = ' DISTINCT '.$this->select_string;
 		return $this;
 	}
+	
+	// --------------------------------------------------------------------------
+	
+	/**
+	 * Tell the database to give you the query plan instead of result set
+	 *
+	 * @return $this
+	 */
+	public function explain()
+	{
+		$this->explain = TRUE;
+		return $this;
+	}
 
 	// --------------------------------------------------------------------------
 
@@ -593,9 +609,10 @@ class Query_Builder implements iQuery_Builder {
 	 *
 	 * @param mixed $key
 	 * @param mixed $val
+	 * @param mixed $escape
 	 * @return $this
 	 */
-	public function where($key, $val=array())
+	public function where($key, $val=array(), $escape=NULL)
 	{
 		return $this->_where_string($key, $val, 'AND');
 	}
@@ -1382,8 +1399,14 @@ class Query_Builder implements iQuery_Builder {
 		{
 			$sql = $this->sql->limit($sql, $this->limit, $this->offset);
 		}
+		
+		// See what needs to happen to only return the query plan
+		if (isset($this->explain) && $this->explain === TRUE)
+		{
+			$sql = $this->sql->explain($sql);
+		}
 
 		return $sql;
 	}
 }
-// End of query_builder.php
+// End of query_builder.php

drivers/firebird/firebird_sql.php

@@ -45,6 +45,19 @@ class Firebird_SQL implements iDB_SQL {
 
 		return $sql;
 	}
+	
+	// --------------------------------------------------------------------------
+	
+	/**
+	 * Get the query plan for the sql query
+	 *
+	 * @param string $sql
+	 * @return string
+	 */
+	public function explain($sql)
+	{
+		return $sql;
+	}
 
 	// --------------------------------------------------------------------------
 
@@ -255,4 +268,4 @@ SQL;
 	}
 
 }
-//End of firebird_sql.php
+//End of firebird_sql.php

drivers/mysql/mysql_driver.php

@@ -65,4 +65,4 @@ class MySQL extends DB_PDO {
 		$this->query("TRUNCATE `{$table}`");
 	}
 }
-//End of mysql_driver.php
+//End of mysql_driver.php

drivers/mysql/mysql_sql.php

@@ -38,6 +38,19 @@ class MySQL_SQL implements iDB_SQL {
 
 		return $sql." LIMIT {$offset}, {$limit}";
 	}
+	
+	// --------------------------------------------------------------------------
+	
+	/**
+	 * Get the query plan for the sql query
+	 *
+	 * @param string $sql
+	 * @return string
+	 */
+	public function explain($sql)
+	{
+		return "EXPLAIN EXTENDED {$sql}";
+	}
 
 	// --------------------------------------------------------------------------
 
@@ -178,4 +191,4 @@ class MySQL_SQL implements iDB_SQL {
 		return "SHOW FULL COLUMNS FROM {$table}";
 	}
 }
-//End of mysql_sql.php
+//End of mysql_sql.php

drivers/odbc/odbc_driver.php

@@ -70,4 +70,4 @@ class ODBC extends DB_PDO {
 		return NULL;
 	}
 }
-// End of odbc_driver.php
+// End of odbc_driver.php

drivers/odbc/odbc_sql.php

@@ -33,6 +33,19 @@ class ODBC_SQL implements iDB_SQL {
 	{
 		return $sql;
 	}
+	
+	// --------------------------------------------------------------------------
+	
+	/**
+	 * Get the query plan for the sql query
+	 *
+	 * @param string $sql
+	 * @return string
+	 */
+	public function explain($sql)
+	{
+		return $sql;
+	}
 
 	// --------------------------------------------------------------------------
 
@@ -168,4 +181,4 @@ class ODBC_SQL implements iDB_SQL {
 	}
 	
 }
-// End of odbc_sql.php
+// End of odbc_sql.php

drivers/pgsql/pgsql_sql.php

@@ -39,6 +39,19 @@ class PgSQL_SQL implements iDB_SQL {
 
 		return $sql;
 	}
+	
+	// --------------------------------------------------------------------------
+	
+	/**
+	 * Get the query plan for the sql query
+	 *
+	 * @param string $sql
+	 * @return string
+	 */
+	public function explain($sql)
+	{
+		return "EXPLAIN VERBOSE {$sql}";
+	}
 
 	// --------------------------------------------------------------------------
 
@@ -227,4 +240,4 @@ SQL;
 SQL;
 	}
 }
-//End of pgsql_manip.php
+//End of pgsql_manip.php

drivers/sqlite/sqlite_sql.php

@@ -38,6 +38,19 @@ class SQLite_SQL implements iDB_SQL {
 
 		return $sql." LIMIT {$offset}, {$limit}";
 	}
+	
+	// --------------------------------------------------------------------------
+	
+	/**
+	 * Get the query plan for the sql query
+	 *
+	 * @param string $sql
+	 * @return string
+	 */
+	public function explain($sql)
+	{
+		return "EXPLAIN QUERY PLAN {$sql}";
+	}
 
 	// --------------------------------------------------------------------------
 
@@ -180,4 +193,4 @@ SQL;
 	}
 
 }
-//End of sqlite_sql.php
+//End of sqlite_sql.php

tests/databases/firebird/firebird-qb.php

@@ -90,4 +90,5 @@ class FirebirdQBTest extends QBTest {
 
 		$this->assertTrue(is_array($res));
 	}
+
 }

tests/databases/mysql/mysql-qb.php

@@ -49,4 +49,35 @@ class MySQLQBTest extends QBTest {
 	{
 		$this->assertTrue(in_array('mysql', PDO::getAvailableDrivers()));
 	}
+	
+	// --------------------------------------------------------------------------
+	
+	public function testQueryExplain()
+	{
+		$query = $this->db->select('id, key as k, val')
+			->explain()
+			->where('id >', 1)
+			->where('id <', 900)
+			->get('create_test', 2, 1);
+			
+		$res = $query->fetchAll(PDO::FETCH_ASSOC);
+		
+		$expected = array (
+		  array (
+		    'id' => '1',
+		    'select_type' => 'SIMPLE',
+		    'table' => 'create_test',
+		    'type' => 'range',
+		    'possible_keys' => 'PRIMARY',
+		    'key' => 'PRIMARY',
+		    'key_len' => '4',
+		    'ref' => NULL,
+		    'rows' => '1',
+		    'filtered' => '100.00',
+		    'Extra' => 'Using where',
+		  )
+		);
+		
+		$this->assertEqual($expected, $res);
+	}
 }

tests/databases/pgsql/pgsql-qb.php

@@ -48,4 +48,43 @@ class PgSQLQBTest extends QBTest {
 	{
 		$this->assertTrue(in_array('pgsql', PDO::getAvailableDrivers()));
 	}
+	
+	// --------------------------------------------------------------------------
+	
+	public function testQueryExplain()
+	{
+		$query = $this->db->select('id, key as k, val')
+			->explain()
+			->where('id >', 1)
+			->where('id <', 900)
+			->get('create_test', 2, 1);
+			
+		$res = $query->fetchAll(PDO::FETCH_ASSOC);
+		
+		$expected = array (
+		  array (
+		    'QUERY PLAN' => 'Limit  (cost=6.41..10.64 rows=2 width=68)',
+		  ),
+		  array (
+		    'QUERY PLAN' => '  Output: id, key, val',
+		  ),
+		  array (
+		    'QUERY PLAN' => '  ->  Bitmap Heap Scan on public.create_test  (cost=4.29..12.76 rows=4 width=68)',
+		  ),
+		  array (
+		    'QUERY PLAN' => '        Output: id, key, val',
+		  ),
+		  array (
+		    'QUERY PLAN' => '        Recheck Cond: ((create_test.id > 1) AND (create_test.id < 900))',
+		  ),
+		  array (
+		    'QUERY PLAN' => '        ->  Bitmap Index Scan on create_test_pkey  (cost=0.00..4.29 rows=4 width=0)',
+		  ),
+		  array (
+		    'QUERY PLAN' => '              Index Cond: ((create_test.id > 1) AND (create_test.id < 900))',
+		  ),
+		);
+		
+		$this->assertEqual($expected, $res);
+	}
 }

tests/databases/sqlite/sqlite-qb.php

@@ -60,4 +60,28 @@
 
 		$this->assertNull($query);
 	}
+	
+	// --------------------------------------------------------------------------
+	
+	public function testQueryExplain()
+	{
+		$query = $this->db->select('id, key as k, val')
+			->explain()
+			->where('id >', 1)
+			->where('id <', 900)
+			->get('create_test', 2, 1);
+			
+		$res = $query->fetchAll(PDO::FETCH_ASSOC);
+		
+		$expected = array (
+		  array (
+		    'selectid' => '0',
+		    'order' => '0',
+		    'from' => '0',
+		    'detail' => 'SEARCH TABLE create_test USING INTEGER PRIMARY KEY (rowid>? AND rowid<?)',
+		  ),
+		);
+		
+		$this->assertEqual($expected, $res);
+	}
 }