diff -urN drupal-7.x-dev/includes/database/mysql/query.inc drupal-7.x-dev-comments/includes/database/mysql/query.inc --- includes/database/mysql/query.inc 2010-04-19 14:43:05.000000000 +1000 +++ includes/database/mysql/query.inc 2010-05-07 13:40:23.752229806 +1000 @@ -43,6 +43,8 @@ } public function __toString() { + // Create a comments string to prepend to the query. + $comments = (!empty($this->comments)) ? '/* ' . implode('; ', $this->comments) . ' */ ' : ''; // Default fields are always placed first for consistency. $insert_fields = array_merge($this->defaultFields, $this->insertFields); @@ -50,10 +52,10 @@ // If we're selecting from a SelectQuery, finish building the query and // pass it back, as any remaining options are irrelevant. if (!empty($this->fromQuery)) { - return "INSERT INTO {" . $this->table . '} (' . implode(', ', $insert_fields) . ') ' . $this->fromQuery; + return $comments . 'INSERT INTO {' . $this->table . '} (' . implode(', ', $insert_fields) . ') ' . $this->fromQuery; } - $query = "INSERT INTO {" . $this->table . '} (' . implode(', ', $insert_fields) . ') VALUES '; + $query = $comments . 'INSERT INTO {' . $this->table . '} (' . implode(', ', $insert_fields) . ') VALUES '; $max_placeholder = 0; $values = array(); @@ -143,6 +145,8 @@ public function __toString() { + // Create a comments string to prepend to the query. + $comments = (!empty($this->comments)) ? '/* ' . implode('; ', $this->comments) . ' */ ' : ''; // Set defaults. if ($this->updateFields) { @@ -164,7 +168,7 @@ $insert_fields = $this->insertFields + $this->keyFields; - $query = "INSERT INTO {" . $this->table . '} (' . implode(', ', array_keys($insert_fields)) . ') VALUES '; + $query = $comments . 'INSERT INTO {' . $this->table . '} (' . implode(', ', array_keys($insert_fields)) . ') VALUES '; $max_placeholder = 0; $values = array(); diff -urN drupal-7.x-dev/includes/database/pgsql/query.inc drupal-7.x-dev-comments/includes/database/pgsql/query.inc --- includes/database/pgsql/query.inc 2009-09-11 12:47:11.000000000 +1000 +++ includes/database/pgsql/query.inc 2010-05-07 13:40:23.793479900 +1000 @@ -71,6 +71,8 @@ } public function __toString() { + // Create a comments string to prepend to the query. + $comments = (!empty($this->comments)) ? '/* ' . implode('; ', $this->comments) . ' */ ' : ''; // Default fields are always placed first for consistency. $insert_fields = array_merge($this->defaultFields, $this->insertFields); @@ -78,10 +80,10 @@ // If we're selecting from a SelectQuery, finish building the query and // pass it back, as any remaining options are irrelevant. if (!empty($this->fromQuery)) { - return "INSERT INTO {" . $this->table . '} (' . implode(', ', $insert_fields) . ') ' . $this->fromQuery; + return $comments . 'INSERT INTO {' . $this->table . '} (' . implode(', ', $insert_fields) . ') ' . $this->fromQuery; } - $query = "INSERT INTO {" . $this->table . '} (' . implode(', ', $insert_fields) . ') VALUES '; + $query = $comments . 'INSERT INTO {' . $this->table . '} (' . implode(', ', $insert_fields) . ') VALUES '; $max_placeholder = 0; $values = array(); diff -urN drupal-7.x-dev/includes/database/query.inc drupal-7.x-dev-comments/includes/database/query.inc --- includes/database/query.inc 2010-04-19 14:43:05.000000000 +1000 +++ includes/database/query.inc 2010-05-15 09:07:59.705537971 +1000 @@ -239,6 +239,13 @@ */ protected $nextPlaceholder = 0; + /** + * An array of comments that can be prepended to a query. + * + * @var array + */ + protected $comments = array(); + public function __construct(DatabaseConnection $connection, $options) { $this->connection = $connection; $this->queryOptions = $options; @@ -262,6 +269,44 @@ public function nextPlaceholder() { return $this->nextPlaceholder++; } + + /** + * Adds a comment to the query. + * + * By adding a comment to a query, you can more easily find it in your + * query log or the list of active queries on an sql server. This allows + * for easier debugging and allows you to more easily find where a query + * with a performance problem is being generated. + * + * @param $comment + * The comment string to be inserted into the query. + * @return Query + * The called object. + */ + public function comment($comment) { + $this->comments[] = $comment; + return $this; + } + + /** + * Returns a reference to the comments array for the query. + * + * Because this method returns by reference, alter hooks may edit the comments + * array directly to make their changes. If just adding comments, however, the + * use of comment() is preferred. + * + * Note that this method must be called by reference as well: + * + * @code + * $comments =& $query->getComments(); + * @endcode + * + * @return + * A reference to the comments array structure. + */ + public function &getComments() { + return $this->comments; + } } /** @@ -467,11 +512,14 @@ public function __toString() { + // Create a comments string to prepend to the query. + $comments = (!empty($this->comments)) ? '/* ' . implode('; ', $this->comments) . ' */ ' : ''; + // Default fields are always placed first for consistency. $insert_fields = array_merge($this->defaultFields, $this->insertFields); if (!empty($this->fromQuery)) { - return "INSERT INTO {" . $this->table . '} (' . implode(', ', $insert_fields) . ') ' . $this->fromQuery; + return $comments . 'INSERT INTO {' . $this->table . '} (' . implode(', ', $insert_fields) . ') ' . $this->fromQuery; } // For simplicity, we will use the $placeholders array to inject @@ -481,7 +529,7 @@ $placeholders = array_pad($placeholders, count($this->defaultFields), 'default'); $placeholders = array_pad($placeholders, count($this->insertFields), '?'); - return 'INSERT INTO {' . $this->table . '} (' . implode(', ', $insert_fields) . ') VALUES (' . implode(', ', $placeholders) . ')'; + return $comments . 'INSERT INTO {' . $this->table . '} (' . implode(', ', $insert_fields) . ') VALUES (' . implode(', ', $placeholders) . ')'; } /** @@ -899,7 +947,11 @@ } public function __toString() { - $query = 'DELETE FROM {' . $this->connection->escapeTable($this->table) . '} '; + + // Create a comments string to prepend to the query. + $comments = (!empty($this->comments)) ? '/* ' . implode('; ', $this->comments) . ' */ ' : ''; + + $query = $comments . 'DELETE FROM {' . $this->connection->escapeTable($this->table) . '} '; if (count($this->condition)) { @@ -939,7 +991,10 @@ } public function __toString() { - return 'TRUNCATE {' . $this->connection->escapeTable($this->table) . '} '; + // Create a comments string to prepend to the query. + $comments = (!empty($this->comments)) ? '/* ' . implode('; ', $this->comments) . ' */ ' : ''; + + return $comments . 'TRUNCATE {' . $this->connection->escapeTable($this->table) . '} '; } } @@ -1099,6 +1154,10 @@ } public function __toString() { + + // Create a comments string to prepend to the query. + $comments = (!empty($this->comments)) ? '/* ' . implode('; ', $this->comments) . ' */ ' : ''; + // Expressions take priority over literal fields, so we process those first // and remove any literal fields that conflict. $fields = $this->fields; @@ -1113,7 +1172,7 @@ $update_fields[] = $field . '=:db_update_placeholder_' . ($max_placeholder++); } - $query = 'UPDATE {' . $this->connection->escapeTable($this->table) . '} SET ' . implode(', ', $update_fields); + $query = $comments . 'UPDATE {' . $this->connection->escapeTable($this->table) . '} SET ' . implode(', ', $update_fields); if (count($this->condition)) { $this->condition->compile($this->connection, $this); diff -urN drupal-7.x-dev/includes/database/select.inc drupal-7.x-dev-comments/includes/database/select.inc --- includes/database/select.inc 2010-04-28 22:36:26.000000000 +1000 +++ includes/database/select.inc 2010-05-07 13:40:23.793479900 +1000 @@ -1286,8 +1286,11 @@ public function __toString() { + // Create a comments string to prepend to the query. + $comments = (!empty($this->comments)) ? '/* ' . implode('; ', $this->comments) . ' */ ' : ''; + // SELECT - $query = 'SELECT '; + $query = $comments . 'SELECT '; if ($this->distinct) { $query .= 'DISTINCT '; } diff -urN drupal-7.x-dev/includes/database/sqlite/query.inc drupal-7.x-dev-comments/includes/database/sqlite/query.inc --- includes/database/sqlite/query.inc 2009-11-02 11:19:27.000000000 +1100 +++ includes/database/sqlite/query.inc 2010-05-07 13:40:23.793479900 +1000 @@ -33,16 +33,19 @@ } public function __toString() { + // Create a comments string to prepend to the query. + $comments = (!empty($this->comments)) ? '/* ' . implode('; ', $this->comments) . ' */ ' : ''; + // Produce as many generic placeholders as necessary. $placeholders = array_fill(0, count($this->insertFields), '?'); // If we're selecting from a SelectQuery, finish building the query and // pass it back, as any remaining options are irrelevant. if (!empty($this->fromQuery)) { - return "INSERT INTO {" . $this->table . '} (' . implode(', ', $this->insertFields) . ') ' . $this->fromQuery; + return $comments . 'INSERT INTO {' . $this->table . '} (' . implode(', ', $this->insertFields) . ') ' . $this->fromQuery; } - return 'INSERT INTO {' . $this->table . '} (' . implode(', ', $this->insertFields) . ') VALUES (' . implode(', ', $placeholders) . ')'; + return $comments . 'INSERT INTO {' . $this->table . '} (' . implode(', ', $this->insertFields) . ') VALUES (' . implode(', ', $placeholders) . ')'; } } @@ -143,7 +146,10 @@ */ class TruncateQuery_sqlite extends TruncateQuery { public function __toString() { - return 'DELETE FROM {' . $this->connection->escapeTable($this->table) . '} '; + // Create a comments string to prepend to the query. + $comments = (!empty($this->comments)) ? '/* ' . implode('; ', $this->comments) . ' */ ' : ''; + + return $comments . 'DELETE FROM {' . $this->connection->escapeTable($this->table) . '} '; } } diff -urN drupal-7.x-dev/modules/simpletest/tests/database_test.test drupal-7.x-dev-comments/modules/simpletest/tests/database_test.test --- modules/simpletest/tests/database_test.test 2010-04-27 20:42:58.000000000 +1000 +++ modules/simpletest/tests/database_test.test 2010-05-14 13:05:23.126785710 +1000 @@ -1015,7 +1015,6 @@ $this->assertEqual($num_records_before, $num_records_after + $num_deleted, t('Deletion adds up.')); } - /** * Confirm that we can truncate a whole table successfully. */ @@ -1275,6 +1274,27 @@ } /** + * Test rudimentary SELECT statement with a COMMENT. + */ + function testSimpleComment() { + $query = db_select('test')->comment('Testing query comments'); + $name_field = $query->addField('test', 'name'); + $age_field = $query->addField('test', 'age', 'age'); + $result = $query->execute(); + + $num_records = 0; + foreach ($result as $record) { + $num_records++; + } + + $query = (string)$query; + $expected = "/* Testing query comments */ SELECT test.name AS name, test.age AS age\nFROM \n{test} test"; + + $this->assertEqual($num_records, 4, t('Returned the correct number of rows.')); + $this->assertEqual($query, $expected, t('The flattened query contains the comment string.')); + } + + /** * Test basic conditionals on SELECT statements. */ function testSimpleSelectConditional() {