fbird_maintain_db — Funktion · PHP-Referenz

Signatur

fbird_maintain_db(resource $service_handle, string $database, int $operation, int $argument = 0): bool

Beschreibung

fbird_maintain_db() ist Teil der Firebird/InterBase-Erweiterung für PHP und ermöglicht es, administrative Wartungsoperationen direkt auf einer Datenbankdatei auszuführen. Die Funktion arbeitet über ein zuvor mit ibase_service_attach() (bzw. fbird_service_attach()) geöffnetes Service-Handle.

Typische Einsatzgebiete sind das kontrollierte Herunterfahren (Shutdown) einer Datenbank für Backup- oder Migrationsarbeiten sowie das anschließende Wiederheranführen der Datenbank in den Online-Betrieb. Die verfügbaren Operationen werden über vordefinierte Konstanten wie IBASE_DB_SHUTDOWN, IBASE_DB_ONLINE oder IBASE_DB_REPAIR angegeben.

Der optionale Parameter $argument gibt bei Shutdown-Operationen die Wartezeit in Sekunden an, die Firebird wartet, bevor neue Verbindungen abgewiesen oder bestehende unterbrochen werden. Bei anderen Operationen wird er in der Regel auf 0 gesetzt.

Die Funktion ist für administrative PHP-Skripte gedacht, die serverseitige Datenbankpflege automatisieren. Sie erfordert entsprechende Administratorrechte auf dem Datenbankserver und sollte nur in gesicherten, serverseitigen Kontexten verwendet werden.

Parameter

Name	Typ	Default	Beschreibung
$service_handle Pflicht	resource		Ein aktives Service-Handle, das zuvor mit `ibase_service_attach()` oder `fbird_service_attach()` geöffnet wurde.
$database Pflicht	string		Der vollständige Pfad zur Datenbankdatei auf dem Server (z. B. `/var/lib/firebird/mydb.fdb`).
$operation Pflicht	int		Die auszuführende Wartungsoperation als Konstante, z. B. `IBASE_DB_SHUTDOWN`, `IBASE_DB_ONLINE` oder `IBASE_RES_CREATE`.
$argument	int	0	Optionaler numerischer Parameter, der je nach Operation unterschiedliche Bedeutung hat — bei Shutdown-Operationen typischerweise die Wartezeit in Sekunden.

Rückgabewert

Typ

bool

Beschreibung

Gibt true zurück, wenn die Wartungsoperation erfolgreich ausgeführt wurde, andernfalls false. Bei einem Fehler kann zusätzlich eine PHP-Warnung ausgelöst werden.

Beispiele

Datenbank herunterfahren und wieder online schalten

<?php
// Service-Verbindung aufbauen
$service = ibase_service_attach('localhost', 'sysdba', 'masterkey');

if (!$service) {
    die('Service-Verbindung fehlgeschlagen.');
}

$dbPath = '/var/lib/firebird/3.0/data/myapp.fdb';

// Datenbank herunterfahren (10 Sekunden Wartezeit)
$result = fbird_maintain_db($service, $dbPath, IBASE_DB_SHUTDOWN, 10);

if ($result) {
    echo 'Datenbank erfolgreich in den Shutdown-Modus versetzt.' . PHP_EOL;

    // Hier können z. B. Backup-Operationen stattfinden
    sleep(2);

    // Datenbank wieder online schalten
    if (fbird_maintain_db($service, $dbPath, IBASE_DB_ONLINE)) {
        echo 'Datenbank ist wieder online.' . PHP_EOL;
    }
} else {
    echo 'Wartungsoperation fehlgeschlagen.' . PHP_EOL;
}

ibase_service_detach($service);

Datenbank erfolgreich in den Shutdown-Modus versetzt. Datenbank ist wieder online.

Fehlerbehandlung bei fehlgeschlagener Wartung

<?php
$service = ibase_service_attach('localhost', 'sysdba', 'masterkey');

if (!$service) {
    die('Verbindung zum Firebird-Dienst nicht möglich.');
}

$dbPath = '/var/lib/firebird/3.0/data/nicht_vorhanden.fdb';

// Versuch, eine nicht existierende Datenbank zu warten
$success = @fbird_maintain_db($service, $dbPath, IBASE_DB_SHUTDOWN, 0);

if ($success === false) {
    echo 'Fehler: Die Wartungsoperation konnte nicht durchgeführt werden.' . PHP_EOL;
    echo 'Ursache: ' . ibase_errmsg() . PHP_EOL;
}

ibase_service_detach($service);

Fehler: Die Wartungsoperation konnte nicht durchgeführt werden. Ursache: I/O error during "open" operation for file "/var/lib/firebird/3.0/data/nicht_vorhanden.fdb"

// Wichtig · Fallstricke

Sicherheitshinweis: Diese Funktion erfordert SYSDBA-Rechte oder vergleichbare administrative Berechtigungen auf dem Firebird-Server. Zugangsdaten dürfen niemals im Quellcode gespeichert oder über unsichere Kanäle übertragen werden — stattdessen Umgebungsvariablen oder gesicherte Konfigurationsdateien nutzen.

Deprecation: Die fbird_*-Funktionen sind Aliase der ibase_*-Funktionen. Die gesamte Firebird/InterBase-Erweiterung (ext/interbase) wurde in PHP 7.4 aus dem PHP-Kern entfernt. Für moderne Projekte sollte stattdessen die separate PECL-Erweiterung oder ein alternatives Datenbankabstraktions-Layer verwendet werden.

Ein Aufruf von fbird_maintain_db() mit einer aktiv genutzten Datenbank ohne ausreichende Wartezeit kann bestehende Verbindungen abrupt unterbrechen und zu Datenverlust führen. Der Einsatz sollte daher stets in Wartungsfenstern mit vorheriger Benachrichtigung der Nutzer erfolgen.

Siehe auch

ibase_service_attach ibase_service_detach ibase_backup ibase_restore ibase_errmsg fbird_service_attach