Drupal でデータベース接続を定義する主な仕組みは、settings.php の $databases 配列です。名前が示すとおり、$databases を使うと複数のデータベース接続を定義できます。また、複数のターゲットの定義もサポートします。接続は、あるコードが初めてデータベースクエリを実行するまで開かれません（つまり接続オブジェクトは作成されません）。

接続キー

接続キーは、データベース接続に割り当てられる一意の識別子です。サイト全体で一意でなければならず、主データベースには default を設定すべきです。ほとんどのサイトでは、接続は 1 つだけになります。

Drupal でのクエリの最も一般的な形式は静的クエリです。静的クエリは、そのままの形で直接データベースに渡されます。静的にできるのは SELECT クエリだけです。

静的クエリは、ごく単純な操作にのみ使ってください。より複雑な、動的に構築される、または変更可能なクエリには、動的クエリを使うべきです。

静的クエリを実行する最も簡単な方法は、query メソッドを使うことです:

<?php $result = $conn->query("SELECT nid, title FROM {node}");
?>

好ましいアプローチは、手続き的なラッパーを使うことです:

<?php $result = db_query("SELECT nid, title FROM {node}");
?>

この db_query() の呼び出しは次と同等です:

これで、Drupal の Database API のおそらく最も面白い部分、動的クエリ に到達しました。これらが「動的」と呼ばれるのは、Drupal がクエリ文字列をその場で組み立てるからです。INSERT、UPDATE、DELETE、MERGE のすべてのクエリは動的にできます。SELECT クエリは静的にも動的にもできます。ただし、SELECT 操作でも動的クエリを使うことが推奨されます。

すべての 動的クエリ は、必要なときに構築するクエリオブジェクトとして作成されます。静的クエリと同様に、ほとんどの動的クエリは手続き的なラッパーを使います。以降のクエリパラメーターは、メソッドチェーンを使ってクエリオブジェクトに追加されます。

db_select() SELECT クエリ

動的 SELECT クエリは db_select() 関数で始まります。たとえば:

Drupal の SELECT クエリは エクステンダー をサポートします。エクステンダーを使うと、実行時に SELECT クエリに機能を追加できます。この機能は、新しいメソッドである場合も、既存のメソッドの動作を上書きする場合もあります。

これはオブジェクト指向プログラミングのデザインパターンを使って実現されます。エクステンダーは Decorator パターン を実装しており、クエリメソッドの柔軟なサブクラスのような拡張を提供することで、動的なオブジェクトに追加の責務を付与します。

エクステンダーの使用

エクステンダーを使うには、クエリオブジェクトから始める必要があります。クエリに対して extend() メソッドを呼び出すと、機能が追加された新しいオブジェクトが返されます。たとえば:

動的 SELECT クエリの重要な特徴は、他のモジュールがこれらのクエリをその場で変更できることです。これにより、モジュールは独自の指示をクエリに挿入し、その動作に影響を与えたり、実行時に変更を適用したりできます――たとえばノードアクセス権限を強制するなどです。クエリをその場で変更するには、タグ付け、メタデータ、hook_query_alter() の 3 つの要素が関わります。

タグ付け

任意の動的 SELECT クエリは、1 つ以上の文字列で「タグ付け」できます。これらのタグはクエリの種類を識別するのに役立ち、それに基づいてアクションをトリガーするのに使えます。タグは英数字で、小文字であり、PHP の変数命名規則に従うべきです。クエリにタグを追加するには addTag() メソッドを使います:

<?php $query->addTag('node_access');
?>

これらのメソッドを使って、クエリオブジェクトにタグがあるかどうかを確認できます:

SELECT クエリは、常にゼロ行以上を含む結果を返します。クエリ結果を処理する方法はいくつかあり、ニーズに最も合ったものを選べます。

最も一般的な方法は、foreach() ループを使うことです:

<?php $result = db_query("SELECT nid, title FROM {node}");
foreach ($result as $record) {
  // Do something with each $record
  $node = node_load($record->nid);
}
?>

結果セットで何をする必要があるかに応じて、レコードを取得する他のメソッドを使えます。次のレコードを明示的に取得するには、次を使います:

挿入クエリは常にクエリビルダーを使うべきです。一部のデータベースは LOB（Large Object、MySQL の text など）や BLOB（Binary Large Object）フィールドに特別なハンドラーを必要とするため、個々の DB ドライバーがこれらのハンドラーを実装できるように抽象化レイヤーが必要です。

挿入クエリは db_insert() 関数で始まります:

<?php $query = db_insert('node', $options);
?>

この挿入クエリは、node テーブルに 1 つ以上のレコードを挿入するクエリオブジェクトを作成します。波括弧は不要であることに注意してください――クエリビルダーが自動的にテーブル名を処理します。

挿入クエリは fluent API を使います。つまり、（execute() を含む）すべてのメソッドがオブジェクト自体を返し、メソッドチェーンを可能にします。

更新クエリは常にクエリビルダーを使うべきです。データベースによって LOB（Large Object、MySQL の TEXT など）や BLOB（Binary Large Object）フィールドの特定のハンドラーが異なるため、個々のデータベースドライバーがこれらの特有の処理を実装できるように、抽象化レイヤーが必要です。

更新クエリは db_update() 関数で始める必要があります:

<?php $query = db_update('node', $options);
?>

この更新クエリオブジェクトを作成することで、node テーブルの 1 つ以上のレコードを変更します。波括弧は不要であることに注意してください――クエリビルダーが自動的にテーブル名を処理します。

更新クエリオブジェクトは Fluent API を使います。つまり、（execute() を除く）すべてのメソッドがクエリオブジェクト自体を返し、メソッドチェーンを可能にします。多くの場合、これはクエリを変数に格納する必要がないことを意味します。

削除クエリはクエリビルダーを使うべきです。db_delete() 関数で始まります:

この削除クエリは、node テーブルからレコードを削除します。テーブル名を波括弧で囲む必要はないことに注意してください――Drupal のクエリビルダーが自動的に処理します。削除クエリは Fluent API を使い、（execute() を除く）すべてのメソッドが、update や insert クエリと同じように、クエリオブジェクト自体を返します。

削除クエリはシンプルで、WHERE 式のみを使います。WHERE 条件については今後のレッスンでさらに詳しく扱いますが、ここでは基本的な削除クエリを見てみましょう:

マージクエリは、データベースクエリの特殊なハイブリッド型です。これらのクエリの構文は SQL 2003 で定義されましたが、実際にサポートしているデータベースはわずかです。しかし、ほとんどのデータベースは特定の構文を使った代替実装を提供しています。Drupal のマージクエリビルダーは、マージクエリの概念をオブジェクト構造に抽象化するため、各データベースの独自の構文に基づいて適切にコンパイルできます。

一般に、マージクエリは insert クエリと update クエリの組み合わせです。条件が満たされる場合――つまり特定のキーを持つ行がすでに存在する場合――一方のクエリ（通常は UPDATE）が実行されます。そうでない場合は、もう一方（通常は INSERT）が実行されます。これは次に似ています: