Concetti generali

Il livello del database di Drupal è costruito sopra la libreria PDO di PHP. PDO fornisce un’API unificata e orientata agli oggetti per accedere a diversi database, ma non offre un’astrazione per i vari dialetti SQL usati nei diversi sistemi di database.

Driver

Poiché i diversi database richiedono modalità differenti di interazione, il livello del database di Drupal necessita di un driver per ogni tipo di database. Un driver è composto da una serie di file, collocati in include/database/driver, dove driver è una stringa che rappresenta una chiave univoca per quel driver. Nella maggior parte dei casi la chiave del driver è il nome del database in minuscolo, ad esempio “mysql”, “pgsql” o “mycustomdriver”.

Ogni driver è costituito da diverse classi derivate dalle classi genitore del sistema di database di base. Queste classi specifiche del driver possono sovrascrivere qualsiasi comportamento necessario per supportare correttamente quel tipo di database. Le classi specifiche del driver sono sempre denominate come la loro classe genitore, seguita da un underscore e poi dal nome del driver. Ad esempio, la versione specifica per MySQL di InsertQuery si chiama InsertQuery_mysql.

Connessioni

Una connessione è un oggetto della classe DatabaseConnection, che estende la classe PDO. Ogni database a cui Drupal si connette è associato a un oggetto connessione. Questo oggetto deve essere suddiviso in sottoclassi per ciascun driver specifico.

Per accedere (e se necessario aprire) un oggetto connessione, si usa:

$database = \Drupal::database();
// Oppure
$database = \Drupal::service('database');

Se i servizi non sono ancora disponibili, \Drupal\Core\Database\Database::getConnection() può ottenere una connessione al database.

Per maggiori informazioni su target e chiavi di connessione, vedi la pagina di documentazione sulla configurazione del database.

Per accedere alla connessione attiva corrente, si usa:

$conn = \Drupal\Core\Database\Database::getConnection();

Questo recupera il target predefinito della connessione attiva.

Nota che nella grande maggioranza dei casi non è necessario richiedere direttamente l’oggetto connessione. Piuttosto, le funzioni procedurali wrapper lo faranno per te. L’unico motivo per cui potresti avere bisogno di accedere direttamente all’oggetto connessione è se stai eseguendo manipolazioni complesse su più database e non vuoi cambiare la connessione attiva.

Per impostare la connessione attiva, si usa:

$conn = \Drupal\Core\Database\Database::setActiveConnection('external');

Vedi la sezione successiva, Configurazione del database, per ulteriori dettagli su chiavi di connessione e target.

Query

Una query è un’istruzione SQL che verrà inviata alla connessione del database. Il sistema di database supporta sei tipi di query: statica, dinamica, insert, update, delete e merge. Alcune query sono scritte come stringhe SQL (prepared statements), mentre altre usano i costruttori di query orientati agli oggetti. Con “oggetto query” si intende un’istanza del costruttore di query per uno dei vari tipi di query.

Statements

Un oggetto statement è il risultato di una query SELECT. Sarà sempre di tipo DatabaseStatement o una sottoclasse di DatabaseStatement. DatabaseStatement estende la classe PDOStatement.

Drupal utilizza prepared statements per tutte le query. Un prepared statement è un modello di query nel quale verranno inseriti valori al momento dell’esecuzione. Si può immaginare un prepared statement come l’equivalente di una funzione SQL, che poi viene chiamata con i parametri da usare.

Nel normale PDO, è necessario preparare esplicitamente un oggetto statement e poi eseguirlo con valori specifici legati ai placeholders nella query. Lo statement può poi essere iterato come un result set. In pratica, statement e result set sono sinonimi, ma solo dopo che lo statement è stato eseguito.

Drupal non espone direttamente il prepared statement. Invece, lo sviluppatore del modulo utilizza un oggetto query o una stringa SQL ad hoc per eseguire la query, e l’oggetto statement per quella query viene restituito. Quindi i termini “oggetto statement” e “oggetto result set” sono più o meno sinonimi.