Skip to the content
Documentation
Help Start
Reading in:
  • German: 9,110 of 9,110 pages
About the help in other languages
All help pages

Clustering mit SQLite: das Ein-Knoten-DFS-Backend im Kernel

Diese Seite ist für Administratoren, die die Dateien einer SQLite-Website in einem DFS-Cluster auf einem Server halten wollen, und für Entwickler, die die Cluster-Tests ohne Datenbankserver ausführen. Ab Exponential…

Download as PDF

Address: https://doc.exponential.earth/exphelp/viewer/features/6.0/sqlite-dfs-cluster.md

On this page

This page is a translation. Read the English original

Clustering mit SQLite: das Ein-Knoten-DFS-Backend im Kernel

Diese Seite ist für Administratoren, die die Dateien einer SQLite-Website in einem DFS-Cluster auf einem Server halten wollen, und für Entwickler, die die Cluster-Tests ohne Datenbankserver ausführen. Ab Exponential 6.0.15 hält der DFS-Cluster des Kernels seine Datei-Metadaten auch in SQLite, neben MySQL/MariaDB und PostgreSQL: Das Backend, seine Tabellen und sein Datei-Gateway gehören zum Kernel.

SQLite clustert eine Maschine, nie mehrere. Eine SQLite-Datenbank ist eine Datei, und ihre Sperren sind die des Dateisystems. Auf einer Netzwerkfreigabe (NFS, SMB) sind diese Sperren nicht verlässlich, und die Dokumentation von SQLite selbst rät davon ab, eine Datenbank von mehreren Maschinen aus zu schreiben. Das SQLite-Backend ist deshalb für:

  • einen Ein-Knoten-Cluster: die PHP-Server eines Hosts (PHP-FPM und Velocity oder zwei FPM-Pools) auf einer Freigabe und einer Datenbankdatei, sodass die Website schon im Cluster-Modus läuft und ein späterer Wechsel zu MySQL/MariaDB oder PostgreSQL eine Änderung der Einstellungen ist;
  • Tests: Die Paritätsprüfungen aller Cluster-Backends laufen mit SQLite, ohne dass etwas zu installieren ist.

Eine Website auf mehreren Webservern hält ihre Cluster-Metadaten in MySQL/MariaDB oder PostgreSQL.

Inhalt

  1. Herkunft und Dank
  2. Was der Kernel mitbringt
  3. Wie es sperrt: ein Schreiber zur Zeit
  4. Erprobte Beispielkonfiguration
  5. Ein Ein-Knoten-Cluster mit exp:cluster:enable
  6. Tests
  7. Grenzen
  8. Verwandte Seiten

Herkunft und Dank

Das SQLite-Backend folgt dem Aufbau des PostgreSQL-Backends des Kernels, das eine Überarbeitung und Integration von ezpostgresqlcluster von eZ Systems AS ist (GNU General Public License Version 2, github.com/ezsystems/ezpostgresqlcluster) und des Forks von 7x, se7enxweb/ezpostgresqlcluster. Der Entwurf, den es beibehält (eine Zeile je Cluster-Datei, die .generating-Zeilen, mit denen ein Prozess eine Cache-Datei erzeugt, während die anderen warten, die Speicher- und die Cache-Tabelle), ist der Entwurf des Cluster-Codes von eZ Systems. Die SQLite-Klasse ist eine neue Umsetzung desselben Vertrags, Methode für Methode am MySQLi-Backend des Kernels geschrieben, unter derselben Lizenz (GNU General Public License Version 2 oder später).

Was der Kernel mitbringt

DateiWas sie ist
kernel/private/classes/clusterfilehandlers/dfsbackends/sqlite.phpexpDFSFileHandlerSQLiteBackend, das Metadaten-Backend
kernel/sql/sqlite/cluster_dfs_schema.sqldie Tabellen ezdfsfile und ezdfsfile_cache
kernel/clustering/dfssqlite.phpdas Gateway, das index_cluster.php für CLUSTER_STORAGE_BACKEND dfssqlite lädt

Nötig ist SQLite 3.24 oder neuer (INSERT ... ON CONFLICT DO UPDATE) mit der PHP-Erweiterung pdo_sqlite. PHP 7.4 ist nutzbar; PHP 8.0 bis 8.5 laufen sauber (ab PHP 8.4 werden die Konstanten von Pdo\Sqlite verwendet, sodass PHP 8.5 keine Deprecation meldet).

Wie es sperrt: ein Schreiber zur Zeit

SQLite hat keine Zeilensperren: Ein Schreibvorgang sperrt die ganze Datenbank. Das Backend nutzt das anstelle des SELECT ... FOR UPDATE der Server-Datenbanken:

  • Jede Transaktion ist BEGIN IMMEDIATE. Sie nimmt die Schreibsperre gleich zu Beginn, sodass sich nichts, was die Transaktion gelesen hat, ändern kann, bevor sie schreibt, und zwei Schreiber treffen sich nie mitten in einer Transaktion (kein Deadlock, kein SQLITE_BUSY_SNAPSHOT).
  • Das Warten ist begrenzt. Eine Verbindung wartet bis zu ihrem Busy-Timeout auf die Sperre, [eZDFSClusteringSettings] DBLockTimeout Sekunden (Standard 10). Eine Transaktion, die die Sperre in dieser Zeit nicht bekam (SQLITE_BUSY, Ergebniscode 5, oder SQLITE_LOCKED, 6), versucht das Backend erneut, bis zu DBExecuteRetries Versuche, mit einer kurzen, wachsenden Pause (höchstens 0,2 s). Die Arbeit einer Transaktion läuft nie außerhalb von ihr: Bekommt BEGIN IMMEDIATE die Sperre nicht, wartet die Arbeit auf den nächsten Versuch.
  • Leser warten nie. Die Datenbank wird bei der ersten Verbindung auf den Journal-Modus WAL gestellt (der Modus bleibt in der Datei), sodass Seiten und das Datei-Gateway lesen, während ein Schreiber schreibt.
  • Eine Erzeugung je Cache-Datei. _startCacheGeneration() legt die .generating-Zeile mit INSERT ... ON CONFLICT (name_hash) DO NOTHING an: Ein Prozess bekommt die Zeile, die anderen sollen warten oder die veraltete Datei ausliefern, wie bei den anderen Datenbanken.

Namenssuchen verwenden GLOB statt LIKE. LIKE ignoriert in SQLite die Groß- und Kleinschreibung und hat standardmäßig kein Escape-Zeichen; GLOB vergleicht mit Groß- und Kleinschreibung, wie MySQLs LIKE auf der binären Spalte name, und ein Präfix (var/site/cache/*) nutzt den Index auf name. Aus dem % eines LIKE-Musters wird *, ein Unterstrich bleibt ein Zeichen (wie im MySQLi-Backend), und *, ? und [ in einem Dateinamen sind Zeichen. Ein Shell-Wildcard mit Alternativen ({a,b}.txt) wird zu einem GLOB-Muster je Alternative.

Erprobte Beispielkonfiguration

[ClusteringSettings]
FileHandler=eZDFSFileHandler

[eZDFSClusteringSettings]
MountPointPath=/var/www/vhosts/example.com/dfs
DBBackend=expDFSFileHandlerSQLiteBackend
# die Datenbankdatei: ein absoluter Pfad oder ein Name in var/storage/sqlite3 der Installation
DBName=/var/www/vhosts/example.com/dfs-db/cluster.db
# optional: Sekunden, die ein Schreibvorgang auf die Sperre der Datenbank wartet, bevor seine Transaktion erneut läuft
DBLockTimeout=10
DBExecuteRetries=20

DBHost, DBPort, DBSocket, DBUser und DBPassword werden nicht verwendet. Die Datenbankdatei wird ohne das Create-Flag von SQLite geöffnet: Ein falscher DBName ist ein Verbindungsfehler, nie eine neue leere Datenbank. Einmal mit den Tabellen anlegen:

sqlite3 /var/www/vhosts/example.com/dfs-db/cluster.db < kernel/sql/sqlite/cluster_dfs_schema.sql

Der Ordner der Datei muss für jeden PHP-Benutzer der Website beschreibbar sein (der WAL-Modus legt cluster.db-wal und cluster.db-shm daneben) und darf vom Webserver nicht ausgeliefert werden: unter var/storage wird er es nicht, und ein Ordner außerhalb des Document Root ist noch sicherer.

<?php
// config.cluster.php
define( 'CLUSTER_STORAGE_BACKEND', 'dfssqlite' );
define( 'CLUSTER_STORAGE_DB', '/var/www/vhosts/example.com/dfs-db/cluster.db' );
define( 'CLUSTER_STORAGE_CHARSET', 'utf8' );
define( 'CLUSTER_MOUNT_POINT_PATH', '/var/www/vhosts/example.com/dfs' );

Die Datenbank der Website und die des Clusters sind getrennte Entscheidungen: Eine Website mit MySQL kann ihre Cluster-Metadaten auf einem Ein-Knoten-Server in einer SQLite-Datei halten, und eine Website mit SQLite in ihrer eigenen Datenbankdatei.

Ein Ein-Knoten-Cluster mit exp:cluster:enable

Auf einer Website mit SQLite als Datenbank (DatabaseImplementation=sqlite3) wählt ./console exp:cluster:enable --apply das SQLite-Backend von selbst (--backend=sqlite nennt es ausdrücklich): Der Befehl legt die Freigabe an, erzeugt die Cluster-Tabellen in der Datenbankdatei der Website, schreibt die Einstellungen und config.cluster.php (dfssqlite, die Database der Website als CLUSTER_STORAGE_DB) und verschiebt die gespeicherten Dateien hinein. exp:cluster:disable nimmt es zurück. Ein DFS-Cluster mit einem Knoten in einem Befehl beschreibt beide Befehle.

Website und Cluster teilen dann eine Datenbankdatei und ihre eine Schreibsperre. Bei einer viel schreibenden Website hält eine eigene Cluster-Datei (DBName oben) die Schreibvorgänge des Clusters aus der Warteschlange der Website.

Tests

TestWas er prüftBraucht
expDFSFileHandlerSQLiteBackendTestErgebniscodes und das erneute Versuchen eines belegten BEGIN IMMEDIATE, die Datenbankdatei aus DBName, LIKE- und Wildcard-Muster als GLOB-Muster, Name Trunks, die Verbindungsoptionen, die Methodenparität mit dem MySQLi-Backend, die Schemadatei, das Gatewaynichts
expDFSSQLiteBackendIntegrationTestdie Paritätsprüfungen aller Backends (expDFSBackendParityChecks), dazu WAL-Modus, Indexnutzung bei Präfixsuchen, Groß- und Kleinschreibung von Namen, GLOB-Zeichen in Namen, eine fehlende Datenbankdatei und das Gateway mit Metadaten und Byte-Bereichenpdo_sqlite (und pcntl, posix für die Prüfungen mit mehreren Prozessen)

Die Paritätsprüfungen sind dieselben, die das MySQLi- und das PostgreSQL-Backend bestehen, darunter vier Prozesse, die gleichzeitig eine Cache-Datei erzeugen wollen (einer erzeugt, drei warten, keiner scheitert) und eine Sperre einer anderen Verbindung: Ein zweiter Prozess hält BEGIN IMMEDIATE, das Speichern wartet eine Sekunde, wird erneut versucht und gelingt, sobald die Sperre weg ist, oder gibt nach DBExecuteRetries Versuchen mit SQLITE_BUSY auf, statt zu hängen. Alle 29 bestehen. Beide Testklassen brauchen keinen Server; sie laufen in der Standard-Suite und im Job "DFS cluster backends" von GitHub Actions.

Gemessen am 19. November 2026 auf alpha: die Paritätssuite 29 von 29; ein Ein-Knoten-Cluster über den echten eZDFSFileHandler (Speichern und Holen einer 2-MB-Datei, Kopieren, Umbenennen, Löschen, Purge, ein View-Cache, erzeugt, über seinen Name Trunk abgelaufen und neu erzeugt); das Gateway index_cluster.php mit dfssqlite (eine ganze Datei, ein Byte-Bereich, ein 404); zwei PHP-Server eines Hosts (PHP 8.5 und PHP 8.4, jeder mit eigenem lokalem var, eine Freigabe, eine Datenbankdatei) fragen gleichzeitig nach einem Cache-Schlüssel, 20 Runden: genau eine Erzeugung je Runde, kein Fehler, die langsamste Antwort etwa 1 Sekunde; und eine Laufzeitprüfung des Backends unter PHP 7.4, 8.0, 8.1, 8.2, 8.3, 8.4 und 8.5 ohne Notice oder Deprecation.

Grenzen

  • Eine Maschine. Mehrere Webserver können eine SQLite-Datei nicht sicher teilen; für sie MySQL/MariaDB oder PostgreSQL verwenden. Die Freigabe (MountPointPath) eines Ein-Knoten-Clusters kann trotzdem ein NFS-Export sein, damit ein zweiter Server sie einhängen kann, sobald die Metadaten auf eine Server-Datenbank umziehen.
  • Ein Schreiber zur Zeit. Schreibvorgänge warten auf die Sperre der Datenbank; auf einer viel schreibenden Website warten die Schreibvorgänge des Clusters und die der Website (wenn sie eine Datei teilen) aufeinander. Leser warten nie.
  • Noch kein eZDFSFileHandlerTest mit SQLite: Der Datenbank-Testlauf des Kernels richtet MySQL-, PostgreSQL-, Oracle- und MongoDB-Datenbanken ein; das SQLite-Backend wird stattdessen mit den Paritätsprüfungen oben getestet.

Verwandte Seiten

Something wrong on this page? Report an error

Documentation license

This documentation is free documentation, licensed under the GNU Free Documentation License 1.3 or later.

Exponential Copyright © 1998-2026 Exponential Foundation and 7x