pg_lo_read() reads a block of bytes from an open PostgreSQL large-object handle. This guide explains the function with focused examples and the decisions that matter in real applications.
What Is pg_lo_read() in PHP?
Reads a block of bytes from an open PostgreSQL large-object handle.
A typical call looks like this:
<?php
pg_lo_read($largeObject, 512);
The input arguments shown in the call identify the relevant connection, resource, value, path or configuration for the operation. Pay attention to argument order and to the return value demonstrated below.
In the examples, $databaseConnection is a PostgreSQL connection created with pg_connect(). A $queryResult is produced by pg_query(). Large-object handles are transaction-scoped. A false result should be treated as a failed operation, not as empty data.
Example 1: Basic Usage
This first example uses pg_lo_read() directly to demonstrate its basic purpose.
<?php
$connectionString = getenv("PG_CONNECTION_STRING");
if (!$connectionString) { throw new RuntimeException("Configure PG_CONNECTION_STRING first."); }
$databaseConnection = pg_connect($connectionString);
if ($databaseConnection === false) { throw new RuntimeException("Connection failed."); }
pg_query($databaseConnection, "BEGIN");
$objectIdentifier = pg_lo_create($databaseConnection);
if ($objectIdentifier === false) { throw new RuntimeException("Cannot create large object."); }
$largeObject = pg_lo_open($databaseConnection, $objectIdentifier, "rw");
if ($largeObject === false) { throw new RuntimeException("Cannot open large object."); }
$binaryData = "Sample bytes";
$exportPath = sys_get_temp_dir() . "/sample-lo.bin";
$secondPath = sys_get_temp_dir() . "/other-lo.bin";
$importPath = $exportPath;
$secondIdentifier = $objectIdentifier;
pg_lo_write($largeObject, "Sample bytes");
pg_lo_seek($largeObject, 0);
$result = pg_lo_read($largeObject, 512);
var_dump($result);
pg_query($databaseConnection, "ROLLBACK");
This call works with the particular connection or result object created above. The exact rows or database diagnostics depend on the example database.
Example 2: A Different Input or Option
The next example changes the input or option, showing another supported use of pg_lo_read().
<?php
$connectionString = getenv("PG_CONNECTION_STRING");
if (!$connectionString) { throw new RuntimeException("Configure PG_CONNECTION_STRING first."); }
$databaseConnection = pg_connect($connectionString);
if ($databaseConnection === false) { throw new RuntimeException("Connection failed."); }
pg_query($databaseConnection, "BEGIN");
$objectIdentifier = pg_lo_create($databaseConnection);
if ($objectIdentifier === false) { throw new RuntimeException("Cannot create large object."); }
$largeObject = pg_lo_open($databaseConnection, $objectIdentifier, "rw");
if ($largeObject === false) { throw new RuntimeException("Cannot open large object."); }
$binaryData = "Sample bytes";
$exportPath = sys_get_temp_dir() . "/sample-lo.bin";
$secondPath = sys_get_temp_dir() . "/other-lo.bin";
$importPath = $exportPath;
$secondIdentifier = $objectIdentifier;
pg_lo_write($largeObject, "Sample bytes");
pg_lo_seek($largeObject, 0);
$result = pg_lo_read($largeObject, 1024);
var_dump($result);
pg_query($databaseConnection, "ROLLBACK");
This call works with the particular connection or result object created above. The exact rows or database diagnostics depend on the example database.
Practical Example: Applying the Function
In application code, pg_lo_read() belongs in a controlled workflow with input validation, a checked result and cleanup where needed.
<?php
$connectionString = getenv("PG_CONNECTION_STRING");
if (!$connectionString) { throw new RuntimeException("Configure PG_CONNECTION_STRING first."); }
$databaseConnection = pg_connect($connectionString);
if ($databaseConnection === false) { throw new RuntimeException("Connection failed."); }
pg_query($databaseConnection, "BEGIN");
$objectIdentifier = pg_lo_create($databaseConnection);
if ($objectIdentifier === false) { throw new RuntimeException("Cannot create large object."); }
$largeObject = pg_lo_open($databaseConnection, $objectIdentifier, "rw");
if ($largeObject === false) { throw new RuntimeException("Cannot open large object."); }
$binaryData = "Sample bytes";
$exportPath = sys_get_temp_dir() . "/sample-lo.bin";
$secondPath = sys_get_temp_dir() . "/other-lo.bin";
$importPath = $exportPath;
$secondIdentifier = $objectIdentifier;
pg_lo_write($largeObject, "Sample bytes");
pg_lo_seek($largeObject, 0);
$result = pg_lo_read($largeObject, 4096);
var_dump($result);
pg_query($databaseConnection, "ROLLBACK");
This call works with the particular connection or result object created above. The exact rows or database diagnostics depend on the example database.
Important Behavior and Edge Cases
- Main behavior: Reads a block of bytes from an open PostgreSQL large-object handle.
- Important limitation: Reads are binary; do not assume a single read returns the entire object.
- Requirements: PostgreSQL must be available, the pgsql extension must be enabled, and the connection must have suitable privileges.
Comparison With Related Functions
| Function or Approach | When to Use It |
|---|---|
pg_lo_read() | Reads a block of bytes from an open PostgreSQL large-object handle. |
pg_lo_write | Writes binary data to an open PostgreSQL large-object handle. |
Common Beginner Mistakes
| Mistake | Correct Approach |
|---|---|
Ignoring the specific limits or preconditions of pg_lo_read(). | Reads are binary; do not assume a single read returns the entire object. |
| Assuming every environment produces the same result. | PostgreSQL must be available, the pgsql extension must be enabled, and the connection must have suitable privileges. |
Key Takeaways
- Reads a block of bytes from an open PostgreSQL large-object handle.
- Reads are binary; do not assume a single read returns the entire object.
- PostgreSQL must be available, the pgsql extension must be enabled, and the connection must have suitable privileges.
Use pg_lo_read() when its behavior matches your task, and verify the relevant return value before taking further action. These examples are illustrative and require an existing PostgreSQL database containing the named example tables; do not run them against production data.