【PHP8.x】PDO::CURSOR_FWDONLY定数の使い方

Copy
1<?php
2
3/**
4 * PDO::CURSOR_FWDONLY を使用してデータベースに接続し、
5 * クエリ実行後に PDOStatement::closeCursor() を呼び出す例。
6 *
7 * PDO::CURSOR_FWDONLY は、カーソルを前方のみに移動する設定です。
8 * これは、結果セットをすべてメモリに読み込むのではなく、必要な時に順次取得する際に役立ちます。
9 * PDOStatement::closeCursor() は、ステートメントに関連付けられたカーソルを閉じ、
10 * データベースサーバーのリソースを解放します。これにより、同じ PDOStatement オブジェクトを
11 * 再利用して別のクエリを実行できるようになります。
12 *
13 * このサンプルは SQLite インメモリデータベースを使用しており、特別な設定なしで実行可能です。
14 */
15function demonstratePdoCursorManagement(): void
16{
17    // SQLite インメモリデータベースを使用するDSN (データソース名)
18    // これにより、一時的なデータベースがメモリ内に作成され、スクリプト終了時に破棄されます。
19    $dsn = 'sqlite::memory:';
20    $username = null; // SQLiteはユーザー名不要
21    $password = null; // SQLiteはパスワード不要
22
23    // PDO オプション配列
24    $options = [
25        PDO::ATTR_ERRMODE            => PDO::ERRMODE_EXCEPTION, // エラー発生時に例外をスロー
26        PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,       // 結果を連想配列でフェッチするよう設定
27        PDO::ATTR_EMULATE_PREPARES   => false,                  // プリペアドステートメントのエミュレーションを無効化 (推奨)
28        PDO::ATTR_CURSOR             => PDO::CURSOR_FWDONLY,    // カーソルを前方のみに設定
29    ];
30
31    try {
32        // データベースに接続
33        $pdo = new PDO($dsn, $username, $password, $options);
34        echo "データベースに接続しました。(SQLite インメモリ)\n";
35
36        // テーブルが存在しない場合は作成し、初期データを挿入
37        $pdo->exec("
38            CREATE TABLE IF NOT EXISTS users (
39                id INTEGER PRIMARY KEY,
40                name TEXT NOT NULL
41            );
42            INSERT OR IGNORE INTO users (id, name) VALUES (1, 'Alice');
43            INSERT OR IGNORE INTO users (id, name) VALUES (2, 'Bob');
44            INSERT OR IGNORE INTO users (id, name) VALUES (3, 'Charlie');
45        ");
46        echo "テーブルと初期データが準備されました。\n";
47
48        // SQLステートメントを準備 (プリペアドステートメント)
49        $stmt = $pdo->prepare("SELECT id, name FROM users WHERE id = :id");
50
51        // 最初のクエリを実行 (ID: 1)
52        $stmt->execute([':id' => 1]);
53        echo "\nクエリ (ID: 1) を実行しました。\n";
54
55        // 結果をフェッチ
56        $user = $stmt->fetch();
57        if ($user) {
58            echo "取得したユーザー情報: ID=" . $user['id'] . ", Name=" . $user['name'] . "\n";
59        } else {
60            echo "ユーザー (ID: 1) が見つかりませんでした。\n";
61        }
62
63        // カーソルを閉じ、サーバーのリソースを解放します。
64        // これにより、次のクエリのために PDOStatement オブジェクトを再利用できるようになります。
65        $stmt->closeCursor();
66        echo "カーソルを閉じました。\n";
67
68        // 同じ PDOStatement オブジェクトで別のクエリを実行 (ID: 2)
69        // closeCursor() を呼び出していなければ、この再実行はエラーになる可能性があります。
70        $stmt->execute([':id' => 2]);
71        echo "\nクエリ (ID: 2) を再実行しました。\n";
72        $anotherUser = $stmt->fetch();
73        if ($anotherUser) {
74            echo "2回目のクエリで取得したユーザー情報: ID=" . $anotherUser['id'] . ", Name=" . $anotherUser['name'] . "\n";
75        } else {
76            echo "2回目のクエリでユーザー (ID: 2) が見つかりませんでした。\n";
77        }
78
79        // 再度カーソルを閉じます。
80        $stmt->closeCursor();
81        echo "2回目のカーソルを閉じました。\n";
82
83    } catch (PDOException $e) {
84        // データベース接続またはクエリ実行エラーが発生した場合
85        echo "エラーが発生しました: " . $e->getMessage() . "\n";
86    }
87}
88
89// サンプル関数を実行
90demonstratePdoCursorManagement();
91
92?>

このPHPサンプルコードは、データベース操作におけるカーソル管理の基礎を、PDO::CURSOR_FWDONLY定数とPDOStatement::closeCursor()メソッドを通じて初心者にもわかりやすく解説します。

PDO::CURSOR_FWDONLYは、PHPのPDO拡張機能でデータベースに接続する際に設定するオプションの一つです。この定数を指定すると、結果セットのカーソルが常に前方のみに移動するようになります。これは、大量のデータを含む結果セットをメモリに全て読み込むことなく、必要に応じてデータを順次取得する際に特に有効で、サーバーのリソースを効率的に利用できます。

一方、PDOStatement::closeCursor()メソッドは、現在開いているカーソルを閉じ、データベースサーバーに関連付けられたリソースを解放するために使用されます。このメソッドは引数を受け取らず、戻り値もありません。主な目的は、同じPDOStatementオブジェクトを再利用して別のクエリを実行できるようにすることです。前のクエリが結果セットを返していた場合、closeCursor()を呼び出さずに新しいクエリを実行しようとすると、リソース競合やエラーが発生する可能性があります。

サンプルコードでは、SQLiteインメモリデータベースへの接続時にPDO::CURSOR_FWDONLYを設定しています。その後、プリペアドステートメントで最初のクエリを実行し結果をフェッチした後に$stmt->closeCursor()を呼び出してカーソルを明示的に閉じます。これにより、同じ$stmtオブジェクトを再利用して異なる条件で2回目のクエリを実行できることを示しており、データベースリソースの適切な管理方法を実演しています。

Copy
1<?php
2
3/**
4 * PDO::CURSOR_FWDONLY 定数を使用したデータベース接続とデータ取得のサンプル。
5 *
6 * この定数は、PDOインスタンスの作成時やプリペアドステートメントの準備時に、
7 * カーソルタイプを「前方参照のみ（forward-only）」に設定するために使用されます。
8 * 前方参照のみのカーソルは、結果セットを順方向に一度だけ読み込むことができ、
9 * 通常、メモリ使用量が少なく、大量のデータを順次処理する際に効率的です。
10 *
11 * @param string $dsn データベース接続文字列 (Data Source Name)。
12 * @param string $username データベースユーザー名。
13 * @param string $password データベースパスワード。
14 * @return void
15 */
16function demonstratePdoCursorFwdOnly(
17    string $dsn = 'sqlite::memory:',
18    string $username = '',
19    string $password = ''
20): void {
21    try {
22        // PDO::ATTR_CURSOR 属性に PDO::CURSOR_FWDONLY を指定してPDOインスタンスを生成
23        // これにより、この接続から生成されるステートメントのデフォルトカーソルが前方参照のみになります。
24        $pdo = new PDO($dsn, $username, $password, [
25            PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,        // エラーモードを例外に設定
26            PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,   // デフォルトのフェッチモードを連想配列に設定
27            PDO::ATTR_CURSOR => PDO::CURSOR_FWDONLY,            // 前方参照のみのカーソルを指定
28        ]);
29
30        echo "データベースに接続しました。\n\n";
31
32        // サンプルテーブルを作成
33        $pdo->exec("CREATE TABLE IF NOT EXISTS products (
34            id INTEGER PRIMARY KEY AUTOINCREMENT,
35            name TEXT NOT NULL,
36            price INTEGER NOT NULL
37        )");
38        echo "テーブル 'products' を作成しました (存在しない場合)。\n\n";
39
40        // サンプルデータを挿入
41        $insertStmt = $pdo->prepare("INSERT INTO products (name, price) VALUES (?, ?)");
42        $insertStmt->execute(['Apple', 100]);
43        $insertStmt->execute(['Banana', 50]);
44        $insertStmt->execute(['Orange', 75]);
45        echo "3つの製品データを挿入しました。\n\n";
46
47        // データを取得
48        // このプリペアドステートメントは、PDOインスタンス作成時に設定した
49        // PDO::CURSOR_FWDONLY のカーソルタイプを使用します。
50        $selectStmt = $pdo->prepare("SELECT id, name, price FROM products ORDER BY id");
51        $selectStmt->execute();
52
53        echo "製品情報を取得します (前方参照のみのカーソル使用):\n";
54        while ($row = $selectStmt->fetch()) {
55            echo "ID: " . $row['id'] . ", 名前: " . $row['name'] . ", 価格: " . $row['price'] . "円\n";
56        }
57        echo "\nデータの取得が完了しました。\n";
58
59    } catch (PDOException $e) {
60        // データベース接続またはクエリ実行中にエラーが発生した場合の処理
61        echo "データベースエラーが発生しました: " . $e->getMessage() . "\n";
62    }
63}
64
65// サンプル関数の実行
66demonstratePdoCursorFwdOnly();

このサンプルコードは、PHPのPDO拡張機能において、PDO::CURSOR_FWDONLY定数を利用してデータベースを操作する方法を説明しています。この定数は、データベースから取得した結果セットのデータを読み進めるカーソルのタイプを「前方参照のみ」に設定するために使用されます。前方参照のみのカーソルは、一度読み込んだデータを後方に戻って再度読み込むことはできませんが、メモリの使用量を抑えることができ、特に大量のデータを順次処理する際に効率的です。

コードでは、データベースに接続する際にnew PDOコンストラクタのオプションとして、PDO::ATTR_CURSOR属性にPDO::CURSOR_FWDONLYを指定しています。これにより、このPDO接続から作成されるすべてのステートメントは、デフォルトで前方参照のみのカーソルを使用するようになります。続いて、サンプル用のテーブルを作成し、データを挿入しています。

データ取得の際には、SELECT文を実行し、while ($row = $selectStmt->fetch())ループを使って結果セットを1行ずつ順に取得しています。この処理において、先に設定した前方参照のみのカーソルが効果的に機能し、効率的なデータアクセスが実現されます。関数demonstratePdoCursorFwdOnlyは、データベース接続に必要なDSN、ユーザー名、パスワードを引数として受け取りますが、これらにはデフォルト値が設定されており、関数自体は特に値を返しません。データベース接続やクエリ実行中にエラーが発生した場合は、try-catchブロックで捕捉し、エラーメッセージを表示します。