SQL coding conventions
Drupal version: Drupal 4.5.x or older, Drupal 4.6.x, Drupal 4.7.x, Drupal 5.x, Drupal 6.x
Audience: Developers and coders
Last modified: August 9, 2010
Don't use Reserved Words
Don't use (ANSI) SQL / MySQL / PostgreSQL / MS SQL Server / ... Reserved Words for
column and/or table names. Even if this may work with your (MySQL) installation, it may
not with others or with other databases. Some references:
(ANSI) SQL Reserved Words
MySQL Reserved Words: 5.1, 5.0, 3.23.x, 4.0, 4.1
PostgreSQL Reserved Words
Oracle Reserved Words (in particular UID is a problem in our context)
MS SQL Server Reserved Words
DB2 Reserved Words
Some commonly misused keywords: TIMESTAMP, TYPE, TYPES, MODULE, DATA, DATE,
TIME, ...
See also [bug] SQL Reserved Words.
Capitalization and user-supplied data
Make SQL reserved words UPPERCASE. This is not a suggestion. Drupal db
abstraction commands will fail if this convention is not followed.
Make column and constraint names lowercase.
Enclose each table name with {} (this allows Drupal to prefix table names).
Variable arguments (which are often user-supplied) should be moved out of the
query body and passed in as separate parameters to db_query(), db_query_range(),
and db_query_temporary(), etc. The query body should instead contain placeholders
specifying the type of each argument (%d|%s|%%|%f|%b). This ensures that the data will be
properly escaped and prevents SQL injection attacks.
Preventing SQL injection is easy; db_query provides a way to use parametrized
queries. Drupal's database functions replace the sprintf-like placeholders with the properly
escaped arguments in order of appearance:
%d - integers
%f - floats
%s - strings, enclose in single quotes
%b - binary data, do not enclose in single quotes
%% - replaced with %
Read more about Database Access
Literal (constant) arguments can either be included in the query body or handled in
the same way as variable arguments.
Any string literal or %s placeholder must be enclosed by single quotes: ' . Never use
double quotes.
Example:
<?php
db_query("INSERT INTO {filters} (format, module, delta, weight) VALUES (%d, 'php', 0,
0)", $format);
?>
NOTE: as of Drupal 6.x, table definitions and constraints (e.g. primary keys, unique
keys, indexes) should be always handled by the Schema API, which solves cross-
database compatibility concerns automatically.
Naming
Use singular nouns for table names since they describe the entity the table
represents. Drupal 6.x mixed singular/plural usage and this convention changed for Drupal
7.x.
Name every constraint (primary, foreign, unique keys) yourself. Otherwise, you'll see
funny-looking system-generated names in error messages. This happened with
the moderation_roles table which initially defined a key without explicit name as KEY (mid).
This got mysqldump'ed as KEY mid (mid) which resulted in a syntax error as mid() is a
mysql function (see [bug] mysql --ansi cannot import install database).
Index names should begin with the name of the table they depend on, eg. INDEX
users_sid_idx.
NOTE: as of Drupal 6.x, table definitions and constraints should be always handled
by the Schema API.
Configure your Database server for standard compliance
Most Database Servers use extension to standard SQL. However, many of them can be
configured to run in a (more) standard compliant mode. Every developer is encouraged to
use the mode most standard compliant to avoid sloppy coding and compatibility problems.
MySQL
Enable ANSI and Strict Mode
Please help growing this list for other database servers!
References
Joe Celko - Ten Things I Hate About You
Joe Celko - SQL for Smarties: Advanced SQL Programming
RDBMS Naming conventions
Indentation
Drupal does not have a standard method for indentation or formating of longer SQL queries
on multiple lines. Some competing strategies include:
<?php
if (!(db_query(
"
INSERT INTO {mlsp_media_file_type}
SET extension = '%s',
attributes = '%s'
",
$file_type_entry['extension'],
$selected_attributes
))) {
$errors = TRUE;
}
?>
or
<?php
$sql = "SELECT t.*, j1.col1, j2.col2"
. " FROM {table} AS t"
. " LEFT JOIN {join1} AS j1 ON j1.id = t.jid"
. " LEFT JOIN {join2} AS j2 ON j2.id = t.jjid"
. " WHERE t.col LIKE '%s'"
. " ORDER BY %s"
;
$result = db_query($sql, 'findme', 't.weight');
?>
Avoid "SELECT * FROM ..."
List of SQL reserved words
‹ PHP ExceptionsupAvoid "SELECT * FROM ..." ›
Login or register to post comments
Comments
In the past I used the
Posted by foobar3000 on February 18, 2010 at 12:49pm
In the past I used the version with a lot of dots, which was at some point not good
anymore.
I do prefer a simmilar style like the first example above, but with a little twist.
<?php
$sql = "
SELECT t.*
, j1.col1
, j2.col2
FROM {table} AS t
LEFT JOIN {join1} AS j1 ON j1.id = t.jid
LEFT JOIN {join2} AS j2 ON j2.id = t.jjid
WHERE t.col LIKE '%s'
AND t.status = 1
AND t.type = 'foobar'
ORDER BY t.bogus ASC
, t.bar DESC
LIMIT 10, 30
";
$result = db_query($sql, 'findme');
?>
This type of SQL statement is, at least for me, very good readable even for quite long sql
statements and you can add comments inside the sql statement very easy:
<?php
$sql = "
SELECT t.*
, j1.col1
, j2.col2
-- , j2.col3
FROM {table} AS t
LEFT JOIN {join1} AS j1 ON j1.id = t.jid
LEFT JOIN {join2} AS j2 ON j2.id = t.jjid
WHERE t.col LIKE '%s'
AND t.status = 1
AND t.type = 'foobar'
ORDER BY t.bogus ASC
-- , t.bar DESC
LIMIT 10, 30
";
$result = db_query($sql, 'findme');
?>
Another Example:
<?php
$sql = "
SELECT t.*
, j1.col1
, j2.col2
, j2.col3
, (
SELECT b.dateme
FROM {date_persons} AS dp
WHERE dp.person_id = t.person_id
LIMIT 1
) AS dateme
FROM {table} AS t
LEFT JOIN {join1} AS j1 ON j1.id = t.jid
LEFT JOIN {join2} AS j2 ON j2.id = t.jjid
WHERE t.col LIKE '%s'
AND t.status = 1
AND t.type = 'foobar'
AND t.person_id IN(
SELECT t.id
FROM {persons}
WHERE t.name LIKE '%s%%'
)
ORDER BY t.bogus ASC
, t.bar DESC
LIMIT 10, 30
";
$result = db_query($sql, 'findme', 'A');
?>
I think you get the idea. I like readability in SQL querys very much in my code.
