then congratulations—you have successfully connected to the test database.
Select, Insert, Update, and Delete Queries
You will routinely perform four types of queries when using any type of database. The insert query will place items in the database, the update query will update information that is already in the database, the select query will display information in the database, and the delete query will delete items from the database. When you query databases from inside PHP, you will allocate memory when a database connection is made and when the result set is returned from your query. When your script is finished executing, all memory will be freed, but it is good programming practice to free the result by using the pg_FreeResult() function and to close the connection by using the pg_Close() function.
Insert Queries
We will use the following example to insert information into our newly created database. This example consists of two parts. The first part is a simple form that enables the user to input specific information to be added to the database. This form calls the PHP script that takes the form variables, and then creates and executes the insert query. The HTML form looks like this:
<html>
<head>
<title>Insert Record</title>
</head>
<body>
<b>Please provide us with the following:</b></font>
<p><font size="2" face="Arial, Helvetica, sans-serif">
<form action="insert.php" method="POST" enablecab="Yes">
Full Name (Last, First MI):<br>
<input type="Text" name="FullName" align="LEFT" required="Yes"
size="59" value=""><br>
Address:<br>
<input type="Text" name="Address" align="LEFT" required="Yes"
size="59" value=""><br>
City:<br>
<input type="Text" name="City" align="LEFT" required="Yes"
size="29" value=""><br>
State:<br>
<input type="Text" name="State" align="LEFT" required="Yes"
size="2" value=""><br>
Zip:<br>
<input type="Text" name="Zip" align="LEFT" required="Yes"
size="10" value=""><br>
Phone:<br>
<input type="Text" name="Phone" align="LEFT" required="No"
size="25" value=""><br>
Fax:<br>
<input type="Text" name="Fax" align="LEFT" required="Yes"
size="25" value=""><br>
Email:<br>
<input type="Text" name="Email" align="LEFT" required="Yes"
size="59" value=""><br>
<input type="Submit" name="Submit" value="Submit" align="MIDDLE">
</form>
</body>
</html>
Notice that the form variables in the example are FullName, Address, City, State, Zip, Phone, Fax, and Email. The PHP script, which is named insert.php, refers to these posted form variables as $FirstName, $Address, $City, $State, $Zip, $Phone, $Fax, and $Email. The PHP script looks like this:
<html>
<head>
<title>Insert the Form Data</title>
</head>
<body>
<?
// Connect to the Postgres Database
$conn = pg_Connect("localhost", "5432", "", "", "test");
if (!$conn) {echo "An database connection error occurred.\n"; exit;}
// Insert the form values into the database
$result = pg_Exec($conn,"INSERT INTO contacts VALUES (NEXTVAL('c'),'$FullName',
'$Address','$City','$State','$Zip', '$Phone','$Fax','$Email');");
if (!$result) {echo "An INSERT query error occurred.\n"; exit;}
// Get the last record inserted
$oid = pg_getlastoid($result);
if (!$oid) {echo "An OID error occurred.\n"; exit;}
// Select the record that was last entered
$result = pg_Exec($conn,"SELECT cid FROM contacts WHERE oid=$oid;");
if (!$result) {echo "A SELECT query error occurred.\n"; exit;}
// Place the result into the variable $CID
$CID = pg_Result($result, 0, "cid");
if (!$CID) {echo "There is a problem returning the Contact ID.\n"; exit;}
// Print out the Contact ID
else { echo "The record was successfully entered and the Contact ID is:
$CID \n";}
// Free the result
pg_FreeResult($result);
// Close the connection
pg_Close($conn);
?>
</body>
</html>
The code for this example first inserts the information from the form into the database and then uses the pg_getlastoid() function to get the last record entered. It then uses the retrieved object identifier (OID) to query the database, and returns the customer identifier (CID) of the last record. If all goes well, the contact ID is printed to the browser window. The last part of this example is not needed to insert records using PHP, but it is included to illustrate the use of the pg_getlastoid() function.
Select Queries with PHP
We gave you a taste of a select query in the previous section. This section takes the result set from the select query and formats it for presentation in a Web page. The select query often displays information that you would like to either change or delete. Notice in the following example that edit and delete links are included. We will create these pages later in this chapter. For now, let’s look at this example:
<html>
<head>
<title>Select Query</title>
<?
$conn = pg_Connect("localhost", "5432", "", "", "test");
if (!$conn) {echo "An database connection error occurred.\n"; exit;}
$result = pg_Exec($conn,"SELECT cid, name, address, city, state, zip, phone,
fax, email FROM contacts ORDER BY name");
if (!$result) {echo "A query error occurred.\n"; exit;}
$ContactNum = pg_NumRows($result);
$i = 0;
while ($i < $ContactNum) {
$CID[$i] = pg_Result($result, $i, "cid");
$CName[$i] = pg_Result($result, $i, "name");
$CAddress[$i] = pg_Result($result, $i, "address");
$CCity[$i] = pg_Result($result, $i, "city");
$CState[$i] = pg_Result($result, $i, "state");
$CZip[$i] = pg_Result($result, $i, "zip");
$CPhone[$i] = pg_Result($result, $i, "phone");
$CFax[$i] = pg_Result($result, $i, "fax");
$CEmail[$i] = pg_Result($result, $i, "email");
$i++;
}
pg_FreeResult($result);
pg_Close($conn);
?>
</head>
<body>
<table>
<TR>
<TD></TD>
<TD><b>Full Name</b></TD>
<TD><b>Address</b></TD>
<TD><b>City</b></TD>
<TD><b>State</b></TD>
<TD><b>Zip</b></TD>
<TD><b>Phone</b></TD>
<TD><b>Fax</b></TD>
<TD><b>Email</b></TD>
</TR>
<?
$i = 0;
while ($i < $ContactNum) {
echo "<TR><TD><A href=editform.php?ID=".$CID[$i].">[Edit]</A>";
echo "<A href=delete.php?ID=".$CID[$i].">[Delete]</A></TD>";
echo "<TD>".$CName[$i]."</TD>";
echo "<TD>".$CAddress[$i]."</TD>";
echo "<TD>".$CCity[$i]."</TD>";
echo "<TD>".$CState[$i]."</TD>";
echo "<TD>".$CZip[$i]."</TD>";
echo "<TD>".$CPhone[$i]."</TD>";
echo "<TD>".$CFax[$i]."</TD>";
echo "<TD>".$CEmail[$i]."</TD></TR>";
$i++;
}
?>
</table>
</body>
</html>
The next section examines this example and explains how to work with the data that is returned from the query.
Working with the Result Set
One of the main features of the preceding example is the use of an array to store the items that are returned from the select query. The while loop uses the pg_Result() function to get the records that are returned from the select query and stores them in variables. These variables are used later in the script to present the information to the Web browser. The pg_NumRows() function is used to return the number of returned records and, therefore, the number of times that the while loop should be executed to store all the returned information. Notice that a while loop is once again used to step through the array and print the variables in the appropriate place in an HTML table. The CID is used as an identifier in all the returned rows. After the edit and delete links are completed, this identifier will be used in subsequent queries to keep track of the record.
Update Queries
This section continues with the example that was started with the select query. After you click on the Edit hyperlink on the Select Query page, the CID is passed to the Edit Record page. The code listing for this page follows:
<html>
<head>
<title>Edit Record Form</title>
<?
$conn = pg_Connect("localhost", "5432", "", "", "test");
if (!$conn) {echo "An database connection error occurred.\n"; exit;}
$result = pg_Exec($conn,"SELECT cid, name, address, city, state, zip,
phone, fax, email FROM contacts WHERE cid = $ID");
if (!$result) {echo "A query error occurred.\n"; exit;}
$CID = pg_Result($result, $i, "cid");
$CName = pg_Result($result, $i, "name");
$CAddress = pg_Result($result, $i, "address");
$CCity = pg_Result($result, $i, "city");
$CState = pg_Result($result, $i, "state");
$CZip = pg_Result($result, $i, "zip");
$CPhone = pg_Result($result, $i, "phone");
$CFax = pg_Result($result, $i, "fax");
$CEmail = pg_Result($result, $i, "email");
pg_FreeResult($result);
pg_Close($conn);
?><
</head>
<body>
<b>Please update the following:</b></font>
<p><font size="2" face="Arial, Helvetica, sans-serif">
<form action="edit.php?ID=<? echo $CID ?>" method="POST" enablecab="Yes">
Full Name (Last, First MI):<br>
<input type="Text" name="FullName" align="LEFT" required="Yes" size="59"
value="<? echo $CName ?>"><br>
Address:<br>
<input type="Text" name="Address" align="LEFT" required="Yes" size="59"
value="<? echo $CAddress ?>"><br>
City:<br>
<input type="Text" name="City" align="LEFT" required="Yes" size="29"
value="<? echo $CCity ?>"><br>
State:<br>
<input type="Text" name="State" align="LEFT" required="Yes" size="2"
value="<? echo $CState ?>"><br>
Zip:<br>
<input type="Text" name="Zip" align="LEFT" required="Yes" size="10"
value="<? echo $CZip ?>"><br>
Phone:<br>
<input type="Text" name="Phone" align="LEFT" required="No" size="25"
value="<? echo $CPhone ?>"><br>
Fax:<br>
<input type="Text" name="Fax" align="LEFT" required="Yes" size="25"
value="<? echo $CFax ?>"><br>
Email:<br>
<input type="Text" name="Email" align="LEFT" required="Yes" size="59"
value="<? echo $CEmail ?>"><br>
<input type="Submit" name="Submit" value="Submit" align="MIDDLE">
</form>
</body>
</html>
This script’s first task is to determine, through the CID, which record is to be edited. This is done with a simple select query. The result set of this query is placed into variables to be used later in the HTML form. Notice that because only one record is to be returned, we do not need to use a while loop and an array to return multiple records. The returned variables are placed into the HTML input tag as the value of the field. This places the information in the input field and enables the end user to edit the information.
After the Submit button is pressed, the second part of this script performs the update query. The form variables are passed to this script and are used to create the update query that is sent to the database.
<html>
<head>
<title>Edit Record</title>
<?
$conn = pg_Connect("localhost", "5432", "", "", "test");
if (!$conn) {echo "An database connection error occurred.\n"; exit;}
$result = pg_Exec($conn,"UPDATE contacts SET name='$FullName',
address='$Address', city='$City', state='$State', zip='$Zip',
phone='$Phone', fax='$Fax', email='$Email' WHERE cid='$ID'");
if (!$result) {echo "An UPDATE query error occurred.\n"; exit;}
$result = pg_Exec($conn,"SELECT cid, name, address, city, state, zip,
phone, fax, email FROM contacts WHERE cid=$ID;");
if (!$result) {echo "A query error occurred.\n"; exit;}
$CID = pg_Result($result, $i, "cid");
$CName = pg_Result($result, $i, "name");<
$CAddress = pg_Result($result, $i, "address");
$CCity = pg_Result($result, $i, "city");
$CState = pg_Result($result, $i, "state");
$CZip = pg_Result($result, $i, "zip");
$CPhone = pg_Result($result, $i, "phone");
$CFax = pg_Result($result, $i, "fax");
$CEmail = pg_Result($result, $i, "email");
pg_FreeResult($result);
pg_Close($conn);
?>
</head>
<body>
<b>The information has been changed to:</b><br>
Full Name (Last, First MI):<br>
<b><? echo $CName ?></b><br>
Address:<br>
<b><? echo $CAddress ?></b><br>
City:<br>
<b><? echo $CCity ?></b><br>
State:<br>
<b><? echo $CState ?></b><br>
Zip:<br>
<b><? echo $CZip ?></b><br>
Phone:<br>
<b><? echo $CPhone ?></b><br>
Fax:<br>
<b><? echo $CFax ?></b><br>
Email:<br>
<b><? echo $CEmail ?></b><br><br>
<a href=select.php>Back to Select Page</a>
</body>
</html>
Notice that this script verifies that information in the database was changed by performing a select query, which displays the changed information in the browser window.
Delete Queries
The delete query is the last of our simple examples. If the delete link is clicked from the initial select query page, the CID ID is passed to the following script:
<title>Delete Record</title>
<?
$conn = pg_Connect("localhost", "5432", "", "", "test");
if (!$conn) {echo "An database connection error occurred.\n"; exit;}
$result = pg_Exec($conn,"DELETE FROM contacts WHERE cid='$ID'");
if (!$result) {echo "A DELETE query error occurred.\n"; exit;}
pg_FreeResult($result);
pg_Close($conn);
?>
</head>
<body>
<b>The record was deleted</b><br><br>
<a href=select.php>Back to Select Page</a>
</body>
</html>
This script simply deletes the record defined by the CID from the database. You can click the Back to Select Page link to verify that the record was deleted.
This concludes the four functions that all database applications perform. We illustrated how PHP accomplishes insert, select, update, and delete queries using PostgreSQL as the database. We also gave some examples of how to use PHP to display and manipulate the information in the Web browser.
Other Database Functions
Many other database functions can be performed other than the basic queries that were demonstrated earlier. The PHP interface to PostgreSQL enables you to specify how the information is returned from the database. You can return information as an array by using pg_Fetch_Array() or pg_Fetch_Row(). You can return information as an object by using pg_Fetch_Object(). Other functions will return the size and type of the field or column or the name or number of fields. The description and use of each of these functions is included in Chapter 10, “Database Extensions.” Many useful bits of information and properties can be returned through the use of these database functions. A detailed description with examples of each of these functions is beyond the scope of this book, but each is fairly straightforward and should be easy to implement.
Error Messages
It is always a good idea to capture and print all error messages. The PHP interface to PostgreSQL includes a function that allows for this functionality. This function is pg_errormessage() and it accepts the database connection handle and returns the string of the error. This string is the text of the error message that is generated from the database back end.
The following example illustrates how to use the pg_errormessage() function to return an error string. The pg_Connect() function in the example attempts to connect to a database that does not exist. If the function returns an error (as it does in this case), the connection handle is used in the pg_errormessage() function to echo the string to the browser.
<html>
<head>
<title>Generate an Error</title>
</head>
<body>
<?
// Generate an error connecting to a Postgres Database
$conn = pg_Connect("localhost", "5432", "", "", "testerror");
if (!$conn) {echo pg_errormessage($conn); exit;}
?>
</body>
</html>
This example prints out the following error message to the browser window:
FATAL 1: Database testerror does not exist in pg_database
Transaction Management
As your database-enabled Web applications become bigger and more complex, you will find the need to lock tables and manage the transactions on the database to eliminate data corruption. When two queries access the same tables to perform any operation other than a simple select query, there is the possibility for the data to become corrupted.
The following simple example illustrates how to set up a transaction, perform the query or set of queries, and then commit the transaction. If the transaction fails at any point, the entire sequence is rolled back.
<html>
<head>
<title>Managing the Transaction</title>
</head>
<body>
<?
// Connect to the Postgres Database
$conn = pg_Connect("localhost", "5432", "", "", "test");
if (!$conn) {echo "An database connection error occurred.\n"; exit;}
// Begin the Transaction
$result = pg_exec($conn, "begin work;");
if (!$result) {echo "An error occurred beginning the transaction.\n"; exit;}
// Lock the table
$result = pg_exec($conn, "lock contacts;");
if (!$result) {echo "An error occurred locking the contacts table.\n"; exit;}
// Insert the static values into the database
$result = pg_Exec($conn,"INSERT INTO contacts VALUES (NEXTVAL('c'),
'Test Name','Test Address','Test City','TS','11111','111.222.3333',
'444.555.6666','me@email.com');");
if (!$result) {echo "An INSERT query error occurred.\n"; exit;}
// Get the last record inserted
$oid = pg_getlastoid($result);
if (!$oid) {echo "An OID error occurred.\n"; exit;}
// Select the record that was last entered
$result = pg_Exec($conn,"SELECT cid FROM contacts WHERE oid=$oid;");
if (!$result) {echo "A SELECT query error occurred.\n"; exit;}
// Place the result into the variable $CID
$CID = pg_Result($result, 0, "cid");
if (!$CID) {echo "There is a problem returning the Contact ID.\n"; exit;}
// Print out the Contact ID
else { echo "The record was successfully entered and the Contact ID is:
$CID \n";}
// Commit the transaction
pg_exec($conn, "commit work;");
// End the transaction
pg_exec($conn, "end work;");
// Free the result
pg_FreeResult($result);<
// Close the connection
pg_Close($conn);
?>
</body>
</html>
Notice that the new portions of this insert query include a BEGIN statement that denotes the start of the transaction. The transaction in this example is named work. The next statement is the LOCK statement. This particular statement locks the entire table while the transaction is being performed. There are many types of locks—both table level and row level—that can be placed on a database while transactions are being performed. A discussion of the pros and cons of each of these types of locks is beyond the scope of this book. Please consult your database documentation for a description of the locks that are available.
In the preceding example, the next bit of code performs the database insert and query. This section of code is very elementary, but it is included for illustration purposes. The next two pg_exec() statements end the transaction; the first commits the work transaction, and the second ends the transaction.
Persistent Database Connections
One of the biggest performance increases that you can make to your database application is to use persistent connections. The establishment of a database connection can often take 90% of the total time of the query. In other words, if you can reuse database connections, your application can make all the queries 90% faster. If your application is database intensive, the overall speed of the application can be affected in a positive manner by using persistent connections.
The pg_pConnect() function is the mechanism that you can use to make a persistent database connection. When a connection to the database is requested, PHP checks for an existing connection. If one exists, PHP does not open another connection but reuses the existing connection. If a connection does not exist, PHP opens one.
From the user’s perspective, the pg_pConnect() function works exactly the same as its nonpersistent counterpart, pg_connect().
Large Objects
Sometimes it might be necessary to store binary objects in a database. PostgreSQL enables you to do this through the use of inversion of large objects. This is the method used to store images, PDF files, and entire Web pages in a database. The use of large objects requires the database table to be set up to accept an object identifier (OID). The create table statement looks something like this:
create table contacts (
cid int4 DEFAULT NEXTVAL('a'),
name char (50),
address char (50),
city char (50),
state char (2),
zip char (10),
phone char (25),
fax char (25),
email char (50),
resume oid,
primary key (cid));
This script creates a contacts table with the usual information and another item called resume that is of type oid.
To enter data in this table, including the resume field, the insert query looks like this:
INSERT INTO contacts VALUES (NEXTVAL('c'),'Test Name','Test Address',
'Test City', 'TS','11111','111.222.3333','444.555.6666','me@email.com',
lo_import('/resumes/rcox.doc'));
This query takes a file named rcox.doc from the /resumes directory and imports it into the database as a large object.
Similarly, a select query to pull the resume out of the database looks like this:
SELECT cid, name, address, city, state, zip, phone, fax, email,
lo_export(resume,'/resumes/rcox.doc') FROM contacts WHERE cid=101;
This exports the resume from the database, places it in the /resumes directory, and names the file rcox.doc.
The following example illustrates how to use the PHP large object functionality to insert a large object into the database:
<html>
<head>
<title>Large Objects</title>
</head>
<body>
<?
// Connect to the Postgres Database
$conn = pg_Connect("localhost", "5432", "", "", "test");
if (!$conn) {echo "An database connection error occurred.\n"; exit;}<
// Begin the Transaction
$result = pg_exec($conn, "begin;");
if (!$result) {echo "An error occurred beginning the transaction.\n"; exit;}
// Lock the table
$oid = pg_locreate($conn);
echo ("The Large Object is created with Object ID = $oid<br>");
$handle = pg_loopen ($conn, $oid, "w");
echo ("The Large Object is opened in Write mode with Handle = $handle<br>");
pg_lowrite ($handle, "/resumes/rcox.doc");
pg_loclose ($handle);
pg_exec ($conn, "INSERT INTO contacts VALUES (NEXTVAL('c'),'Test Name',
'Test Address','Test City','TS','11111','111.222.3333',
'444.555.6666','me@email.com', $oid);");
pg_exec ($conn, "commit;");
pg_exec ($conn, "end;");
// Free the result
pg_FreeResult($result);
// Close the connection
pg_Close($conn);
?>
</body>
</html>
The output of this script should look something like this:
The Large Object is created with Object ID = 24097
The Large Object is opened in Write mode with Handle = Resource id #3
The ordinary Web programmer would not use large objects on a regular basis. Instead of directly storing binaries in the database, it is usually preferable to store the link to the file and allow the binary to reside on the operating system’s filesystem. Storing only the link allows the database to stay lean, and when the information is served to the Web browser, the Web server can include the path to the binary on the filesystem.