Drupal 7 Module Development

Appendix A
A Merge query says, in essence, "If this record exists, update it with this query
otherwise create it with this other query". The syntax for it is somewhat verbose,
but it is a very powerful concept. It is most useful for setting records that may or
may not exist yet, that is, merging data into the table. It can also be very useful for
incrementing counters.
A true merge query is atomic, that is, we're guaranteed that it will run as a single
uninterrupted operation or fail completely. Since most of the databases Drupal
works with do not directly support Merge queries, Drupal emulates them with
multiple queries and a transaction, which in most cases is close enough.
The syntax should be familiar based on the other queries we've looked at already.
The following example is straight out of the variable system:
db_merge('variable')
->key(array('name' => $name))
->fields(array('value' => serialize($value)))
->execute();
The key() method takes an associative array of field/value pairs that are the pivot
of the query. The fields() method is about the fields to set, and works the same as
it does on Update or Insert queries. The above query can be read as "If there is a
record where the field 'name' has the value $name, set the 'value' field. If not, insert a
new record with name equal to $name and value equal to the given string." (Isn't the
query above so much easier to say?)
We can also define more complex logic using the insertFields() and
updateFields() methods. Those work exactly like fields() but, as we
might expect, apply only when taking the insert or update branches.
db_merge('people')
->key(array('job' => 'Speaker'))
->insertFields(array(
'age' => 31,
'name' => 'Meredith',
))
->updateFields(array(
'name' => 'Tiffany',
))
->execute();
In this case, if there is already a record whose job field is "Speaker" its name field will
be updated to Tiffany. If not, a new record will be created with 'job' as Speaker and
'name' as Meredith. (Yes, this example is rather contrived.)
[ 371 ]