Drupal 7 透過 `$databases` 陣列支援多資料庫連線,但實際操作中常遇到連線切換失敗、查詢錯誤、前綴衝突等問題。本文完整說明設定方法、切換機制、跨庫查詢策略與除錯技巧。
<?php
$databases = array(
// 預設連線(必要)
'default' => array(
'default' => array(
'database' => 'drupal_main',
'username' => 'db_user',
'password' => 'db_pass',
'host' => 'localhost',
'port' => '3306',
'driver' => 'mysql',
'prefix' => 'main_', // 表前綴
),
),
// 第二個資料庫
'external' => array(
'default' => array(
'database' => 'external_db',
'username' => 'ext_user',
'password' => 'ext_pass',
'host' => '192.168.1.100',
'driver' => 'mysql',
'prefix' => '',
),
),
// 第三個:唯讀從庫
'replica' => array(
'default' => array(
'database' => 'drupal_main',
'username' => 'readonly_user',
'password' => 'readonly_pass',
'host' => '192.168.1.101',
'driver' => 'mysql',
'prefix' => 'main_',
),
),
);
<?php
// 切換到 external 資料庫
db_set_active('external');
// 執行查詢(使用 external 連線)
$results = db_query("SELECT * FROM external_table WHERE status = 1")->fetchAll();
// 切回預設連線(重要!避免後續查詢錯誤)
db_set_active('default');
<?php
function withDatabase(string $key, callable $callback) {
$previous = db_set_active($key);
try {
return $callback();
} finally {
db_set_active($previous); // 確保還原,即使拋出異常
}
}
// 使用
$users = withDatabase('external', function() {
return db_query("SELECT uid, name FROM users WHERE active = 1")->fetchAll();
});
// 預設連線自動還原,安全無慮
原因:切換連線後,資料表前綴仍套用預設連線的 prefix,導致 SQL 錯誤。
<?php
// 錯誤示範
db_set_active('external');
db_query("SELECT * FROM {users}"); // 產生 SELECT * FROM main_users,但 external 無此表
// 正確做法 1:不使用大括號,直接寫表名
db_query("SELECT * FROM users"); // 使用 external 實際表名
// 正確做法 2:設定 external 連線的 prefix 為空或正確值
// settings.php 中 'prefix' => ''
Drupal Database API 不支援跨連線 JOIN。解決方案:
<?php
// 方案 A:應用層 JOIN(分兩次查詢,PHP 合併)
$localUsers = db_query("SELECT uid, name FROM {users} WHERE uid IN (:uids)", [':uids' => $uids])->fetchAllKeyed();
$externalData = withDatabase('external', function() use ($uids) {
return db_query("SELECT user_id, meta FROM user_meta WHERE user_id IN (:uids)", [':uids' => $uids])->fetchAllKeyed();
});
// PHP 合併
foreach ($localUsers as $uid => $name) {
$result[$uid] = ['name' => $name, 'meta' => $externalData[$uid] ?? null];
}
// 方案 B:資料庫層級同步/複寫(推薦高效能場景)
// 使用 MySQL Replication、FEDERATED 引擎、或 ETL 同步至單一庫
<?php
// 危險模式
function outer() {
db_set_active('external');
inner(); // 內部也呼叫 db_set_active
// 這裡以為回到 external,實際可能已被 inner 切回 default
db_query("..."); // 錯誤連線!
db_set_active('default');
}
function inner() {
db_set_active('default');
// ...
db_set_active('external'); // 還原?但外層不知道
}
// 安全模式:使用 withDatabase 包裝器(上方程式碼)
當多個 Drupal 站點共用用戶表時,使用 `$db_prefix` 映射特定表到共享資料庫。
<?php
// settings.php
$db_prefix = array(
'default' => 'site1_', // 本站表前綴
'users' => 'shared.', // users 表使用 shared 資料庫(無前綴)
'sessions' => 'shared.', // sessions 共用
'role' => 'shared.',
'users_roles' => 'shared.',
'authmap' => 'shared.',
);
// 效果:
// db_query("SELECT * FROM {users}") → SELECT * FROM shared.users
// db_query("SELECT * FROM {node}") → SELECT * FROM site1_node
<?php
// 1. 取得當前活躍連線鍵
$activeKey = Database::getActiveConnection(); // 回傳 'default'/'external' 等
// 2. 檢查連線資訊
$conn = Database::getConnection($activeKey);
echo "Driver: " . $conn->driver(); // mysql, pgsql, sqlite
echo "Database: " . $conn->getDatabaseName();
// 3. 開啟查詢日誌(開發環境)
$conn->setLogger('default', new \Drupal\Core\Database\Log\StandardLogger());
// 或 settings.php: $conf['dev_query_log'] = TRUE;
// 4. 直接取得 PDO 實例進行原生操作
$pdo = $conn->getConnection();