Algemene begrippen

Het database-niveau van Drupal is gebouwd bovenop de PDO-bibliotheek van PHP. PDO biedt een uniforme objectgeoriënteerde API voor toegang tot verschillende databases, maar voorziet niet in abstractie voor de verschillende SQL-dialecten die door verschillende databases worden gebruikt.

Drivers

Omdat verschillende databases verschillende soorten interactie vereisen, heeft het database-niveau van Drupal een driver nodig voor elk type database. Een driver bestaat uit een reeks bestanden die zich bevinden in include/database/driver, waarbij driver een string is die een unieke sleutel voor die driver vertegenwoordigt. In de meeste gevallen is de driversleutel de kleine letters versie van de databasenaam, zoals “mysql”, “pgsql” of “mycustomdriver”.

Elke driver bestaat uit meerdere klassen die zijn afgeleid van bovenliggende klassen in het basale databasesysteem. Deze driverspecifieke klassen kunnen elk gedrag overschrijven dat nodig is om dat type database correct te ondersteunen. Driverspecifieke klassen worden altijd benoemd naar hun bovenliggende klasse, gevolgd door een underscore en daarna de naam van de driver. Bijvoorbeeld: de MySQL-specifieke versie van InsertQuery heet InsertQuery_mysql.

Connecties

Een connectie is een object van de klasse DatabaseConnection, die zelf afstamt van de klasse PDO. Voor elke database waarmee Drupal verbinding maakt, bestaat er één connectieobject. Dit connectieobject moet voor elke afzonderlijke driver verder worden uitgebreid in subklassen.

Om toegang te krijgen tot (en indien nodig een connectie te openen), gebruik je:

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

Als services nog niet beschikbaar zijn, kan \Drupal\Core\Database\Database::getConnection() een databaseverbinding ophalen.

Voor meer informatie over de doelstelling en de connectiesleutel, zie de documentatiepagina over databaseconfiguratie.

Om toegang te krijgen tot de huidige actieve connectie, gebruik je:

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

Dit haalt het standaarddoel van de actieve connectie op.

Merk op dat je in de overgrote meerderheid van de gevallen niet rechtstreeks een connectieobject hoeft aan te vragen. Meestal zullen procedurele wrappers dit voor je doen. De enige reden om ooit direct toegang te willen hebben tot het connectieobject is wanneer je complexe manipulaties met meerdere databases uitvoert en je de actieve database niet wilt wijzigen.

Om een actieve connectie in te stellen, gebruik je:

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

Zie de volgende sectie, Databaseconfiguratie, voor gedetailleerde informatie over connectiesleutels en doelen.

Queries

Een query is een SQL-instructie die naar de databaseconnectie wordt gestuurd. Het databasesysteem ondersteunt zes soorten queries: statisch, dynamisch, insert, update, delete en merge. Sommige queries worden geschreven als SQL-stringtemplates (prepared statements), terwijl andere gebruik maken van objectgeoriënteerde query builders. “Query object” verwijst naar een instantie van een query builder voor een van de verschillende soorten queries.

Statements

Een statementobject is het resultaat van een SELECT-query. Het zal altijd van het type DatabaseStatement zijn, of eventueel een subklasse van DatabaseStatement. DatabaseStatement breidt de PDOStatement-klasse uit.

Drupal gebruikt prepared statements voor alle queries. Een prepared statement is een querytemplate waarin waarden worden ingevoegd voor uitvoering. Beschouw een prepared statement als het SQL-equivalent van een functie die vervolgens met parameters wordt aangeroepen.

In gewone PDO moet je expliciet een statementobject voorbereiden en het vervolgens uitvoeren met specifieke waarden die aan de placeholders in de query zijn gebonden. Daarna kan het statement worden doorlopen als een resultset. In feite zijn statement en resultset synoniem, maar alleen nadat het statement is uitgevoerd.

Drupal stelt het prepared statement niet direct bloot. In plaats daarvan gebruikt een moduleontwikkelaar een queryobject of een eenmalige SQL-string om een query uit te voeren, en het statementobject voor die query wordt dan teruggegeven. Daarom zijn de termen “statementobject” en “resultsetobject” min of meer synoniem.