【PHP8.x】SQLite3::backup()メソッドの使い方

Copy
1<?php
2
3/**
4 * SQLiteデータベースをバックアップするサンプル関数。
5 *
6 * この関数は、指定されたソースSQLiteデータベースの内容を
7 * 別の指定されたファイルパスにバックアップします。
8 * システムエンジニアを目指す初心者向けに、SQLite3::backup() メソッドの基本的な使用法を示します。
9 *
10 * @param string $sourceDbPath バックアップ元のSQLiteデータベースファイルのパス。
11 * @param string $destinationDbPath バックアップ先のSQLiteデータベースファイルのパス。
12 * @return bool バックアップが成功した場合は true、失敗した場合は false。
13 */
14function backupSqliteDatabase(string $sourceDbPath, string $destinationDbPath): bool
15{
16    // 既存のバックアップファイルを削除し、クリーンな状態から開始します。
17    if (file_exists($destinationDbPath)) {
18        unlink($destinationDbPath);
19    }
20
21    $sourceDb = null;
22    $destinationDb = null;
23
24    try {
25        // ソースデータベース（バックアップ元）を開きます。
26        // ファイルが存在しない場合はエラーとなるため、事前に存在確認または作成が必要です。
27        if (!file_exists($sourceDbPath)) {
28            // ソースデータベースが存在しない場合は、サンプル用に作成します。
29            $sourceDb = new SQLite3($sourceDbPath);
30            $sourceDb->exec('CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT)');
31            $sourceDb->exec("INSERT INTO users (name) VALUES ('Alice'), ('Bob'), ('Charlie')");
32            $sourceDb->close();
33            echo "サンプル用にソースデータベース '{$sourceDbPath}' を作成し、データを投入しました。\n";
34        }
35
36        // ソースデータベースを読み取りモードで再度開きます。
37        $sourceDb = new SQLite3($sourceDbPath, SQLITE3_OPEN_READONLY);
38        if (!$sourceDb) {
39            throw new Exception("ソースデータベース '{$sourceDbPath}' を開けませんでした。");
40        }
41
42        // バックアップ先データベースを開きます。
43        // ファイルが存在しない場合は新規作成されます。
44        $destinationDb = new SQLite3($destinationDbPath, SQLITE3_OPEN_READWRITE | SQLITE3_OPEN_CREATE);
45        if (!$destinationDb) {
46            throw new Exception("バックアップ先データベース '{$destinationDbPath}' を開けませんでした。");
47        }
48
49        // SQLite3::backup() メソッドを呼び出してバックアップを開始します。
50        // このメソッドは SQLite3Backup オブジェクトを返します。
51        $backup = $sourceDb->backup($destinationDb);
52
53        if ($backup) {
54            // バックアッププロセスを完了させます。
55            // step() メソッドを繰り返し呼び出して、進行状況を更新することも可能ですが、
56            // シンプルな一括バックアップでは finish() を呼び出すだけで十分です。
57            $backupCompleted = $backup->finish();
58
59            if ($backupCompleted) {
60                echo "データベース '{$sourceDbPath}' のバックアップが '{$destinationDbPath}' に成功しました。\n";
61
62                // バックアップが成功したことを確認するために、バックアップ先データベースからデータを読み込みます。
63                $destinationDb->close(); // 一度接続を閉じて、再度開く
64                $destinationDb = new SQLite3($destinationDbPath, SQLITE3_OPEN_READONLY);
65                $result = $destinationDb->query('SELECT COUNT(*) AS count FROM users');
66                $row = $result->fetchArray(SQLITE3_ASSOC);
67                echo "バックアップ先データベースのユーザー数: " . ($row['count'] ?? '0') . "\n";
68                return true;
69            } else {
70                echo "エラー: データベースバックアップの完了中に問題が発生しました。\n";
71                return false;
72            }
73        } else {
74            echo "エラー: データベースバックアップの開始に失敗しました。\n";
75            return false;
76        }
77
78    } catch (Exception $e) {
79        echo "エラーが発生しました: " . $e->getMessage() . "\n";
80        return false;
81    } finally {
82        // 開いているデータベース接続があれば閉じます。
83        if ($sourceDb instanceof SQLite3) {
84            $sourceDb->close();
85        }
86        if ($destinationDb instanceof SQLite3) {
87            $destinationDb->close();
88        }
89    }
90}
91
92// スクリプトの実行部分
93$sourceDbFilename = 'my_application.sqlite';
94$backupDbFilename = 'my_application_backup.sqlite';
95
96if (backupSqliteDatabase($sourceDbFilename, $backupDbFilename)) {
97    echo "バックアップ処理全体が完了しました。\n";
98} else {
99    echo "バックアップ処理全体が失敗しました。\n";
100}
101
102// 作成したデータベースファイルをクリーンアップします。
103if (file_exists($sourceDbFilename)) {
104    unlink($sourceDbFilename);
105}
106if (file_exists($backupDbFilename)) {
107    unlink($backupDbFilename);
108}
109echo "一時データベースファイルをクリーンアップしました。\n";
110
111?>

このPHPサンプルコードは、SQLiteデータベースを安全にバックアップする方法をシステムエンジニアを目指す初心者向けに示しています。backupSqliteDatabase関数は、指定されたソースデータベースファイルの内容を、別の指定されたファイルパスへ正確にコピーします。

主要な処理は、SQLite3クラスのbackup()メソッドで行われます。このメソッドは、第一引数にバックアップ先のデータベースを表すSQLite3オブジェクトを受け取ります。第二、第三引数には、バックアップ元のデータベース（通常は'main'）とバックアップ先のデータベース（これも通常は'main'）の論理名を文字列で指定しますが、通常はデフォルト値のままで問題ありません。

backup()メソッドは、バックアップ処理を管理するSQLite3Backupオブジェクトを戻り値として返します。実際のバックアップ操作を完了させるには、このSQLite3Backupオブジェクトが持つfinish()メソッドを呼び出す必要があります。

コードでは、まずソースデータベースを開き、存在しない場合はサンプルデータを作成します。次に、バックアップ先のデータベースを開き、backup()メソッドで処理を開始し、その後finish()でデータをコピーします。バックアップが成功したかを確認するため、バックアップ先データベースからデータの件数を取得する処理も含まれています。エラーが発生した場合には例外を捕捉し、データベース接続を確実に閉じるためのfinallyブロックも備えています。これにより、データベースのバックアップ処理の基本的な手順とエラーハンドリングを学ぶことができます。

Copy
1<?php
2
3/**
4 * SQLite3 データベースのバックアップを実行します。
5 *
6 * この関数は、指定されたバックアップ元データベースの全データを、
7 * 指定されたバックアップ先データベースにコピーします。
8 * 大規模なデータベースでもメモリを圧迫しないように、段階的な処理が可能です。
9 *
10 * @param string $sourcePath バックアップ元のSQLiteデータベースファイルのパス。
11 * @param string $destinationPath バックアップ先のSQLiteデータベースファイルのパス。
12 * @return bool バックアップが成功した場合は true、失敗した場合は false。
13 */
14function performSqliteBackup(string $sourcePath, string $destinationPath): bool
15{
16    // バックアップ元のデータベースを開きます。
17    // ファイルが存在しない場合や破損している場合は、SQLite3コンストラクタで例外がスローされることがあります。
18    try {
19        $sourceDb = new SQLite3($sourcePath);
20    } catch (Exception $e) {
21        error_log("Failed to open source database '{$sourcePath}': " . $e->getMessage());
22        return false;
23    }
24
25    // バックアップ先のデータベースを開きます。
26    // ファイルが存在しない場合は新規作成されます。
27    try {
28        $destinationDb = new SQLite3($destinationPath);
29    } catch (Exception $e) {
30        error_log("Failed to open destination database '{$destinationPath}': " . $e->getMessage());
31        $sourceDb->close(); // ソースDBの接続を閉じる
32        return false;
33    }
34
35    echo "Attempting to backup from '{$sourcePath}' to '{$destinationPath}'...\n";
36
37    try {
38        // SQLite3::backup メソッドを呼び出してバックアップ処理を開始します。
39        // このメソッドは、呼び出し元のオブジェクト（$sourceDb）のデータを
40        // 引数で指定されたSQLite3オブジェクト（$destinationDb）にバックアップします。
41        // 'main' はバックアップ元とバックアップ先のデータベース名（通常は 'main'）。
42        $backup = $sourceDb->backup($destinationDb, 'main', 'main');
43
44        if ($backup === false) {
45            // backupオブジェクトの作成に失敗した場合
46            error_log("SQLite backup failed to initialize. Error: " . $sourceDb->lastErrorMsg());
47            return false;
48        }
49
50        // バックアップ処理を段階的に実行します。
51        // step() メソッドは、まだコピーするページがある場合に true を返します。
52        // 全てのページがコピーされるまでループを続けます。
53        while ($backup->step()) {
54            // 必要に応じてバックアップの進行状況を表示できます。
55            // 例: echo "."; // 実行すると進捗がドットで表示されます
56        }
57
58        // バックアップ処理が完全に完了したことを確認します。
59        // finish() メソッドは、バックアップが成功すると true を返します。
60        if ($backup->finish()) {
61            echo "SQLite database backup successful.\n";
62            return true;
63        } else {
64            // finish() が false を返した場合、バックアップ中にエラーが発生した可能性があります。
65            error_log("SQLite backup failed to finish. Error: " . $sourceDb->lastErrorMsg());
66            return false;
67        }
68    } catch (Exception $e) {
69        // 予期せぬエラーが発生した場合
70        error_log("SQLite backup error: " . $e->getMessage());
71        return false;
72    } finally {
73        // データベース接続を必ず閉じます。
74        // これにより、リソースが解放され、データベースファイルが正しくロック解除されます。
75        if ($sourceDb) {
76            $sourceDb->close();
77        }
78        if ($destinationDb) {
79            $destinationDb->close();
80        }
81    }
82}
83
84// --- スクリプトの実行部分 ---
85
86// バックアップ元のファイル名とバックアップ先のファイル名を定義
87$sourceDbFile = 'my_source_database.db';
88$backupDbFile = 'my_backup_database.db';
89
90// --- サンプルデータ生成 (テスト用: 実際の運用では既存のデータベースを指定します) ---
91// この部分は、バックアップ元のデータベースファイルが存在しない場合に、
92// テスト用のダミーデータベースを作成します。
93// 既に 'my_source_database.db' が存在する場合は、そのデータベースが使用されます。
94if (!file_exists($sourceDbFile)) {
95    try {
96        $db = new SQLite3($sourceDbFile);
97        $db->exec('CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)');
98        $db->exec("INSERT INTO users (name) VALUES ('Alice')");
99        $db->exec("INSERT INTO users (name) VALUES ('Bob')");
100        $db->close();
101        echo "Sample source database '{$sourceDbFile}' created with some data.\n";
102    } catch (Exception $e) {
103        echo "Failed to create sample source database: " . $e->getMessage() . "\n";
104        exit(1); // データベース作成に失敗した場合はスクリプトを終了
105    }
106} else {
107    echo "Using existing source database: '{$sourceDbFile}'.\n";
108}
109// --- サンプルデータ生成終わり ---
110
111// 定義した関数を呼び出してバックアップ処理を実行
112if (performSqliteBackup($sourceDbFile, $backupDbFile)) {
113    echo "Backup process completed successfully for '{$sourceDbFile}'. Result stored in '{$backupDbFile}'.\n";
114} else {
115    echo "Backup process failed.\n";
116}

このPHPサンプルコードは、SQLite3::backupメソッドを使用してSQLiteデータベースのバックアップを実行する方法を示しています。まず、バックアップ元のデータベースとバックアップ先のデータベースをそれぞれSQLite3オブジェクトとして開きます。

SQLite3::backupメソッドは、呼び出し元のSQLite3オブジェクト（バックアップ元）のデータを、引数で指定された別のSQLite3オブジェクト（バックアップ先）にコピーするために利用されます。引数$destinationにはバックアップ先のSQLite3オブジェクト、$sourceDatabaseと$destinationDatabaseにはそれぞれバックアップ元と先のデータベース名を文字列で指定し、通常は「main」が用いられます。このメソッドは、バックアップ処理を管理するSQLite3Backupオブジェクトを返します。

バックアップ処理は、返されたSQLite3Backupオブジェクトのstep()メソッドをループで繰り返し呼び出すことで段階的に実行されます。これにより、大規模なデータベースでもメモリを圧迫せずに効率的にデータをコピーできます。全てのデータがコピーされた後、finish()メソッドを呼び出してバックアップ処理を完了させます。

コードでは、データベースのオープンやバックアップ処理中に発生する可能性のあるエラーをtry-catchブロックで適切に処理し、finallyブロックでデータベース接続を確実に閉じ、リソースを解放しています。スクリプトの実行部分では、バックアップ元のダミーデータベースを生成し、定義したバックアップ関数を呼び出して実際の動作を確認しています。