Obtaining the Number of Rows Affected by a Query

9.2.1 Problem

You want to know how many rows were changed by a query.

9.2.2 Solution

Some APIs provide the count as the return value of the function that issues the query. Others have a separate function that you call after issuing the query.

9.2.3 Discussion

For queries that affect rows (UPDATE, DELETE, INSERT, REPLACE), each API provides a way to determine the number of rows involved. For MySQL, "affected by" normally means "changed by," so rows that are not changed by a query are not counted, even if they match the conditions specified in the query. For example, the following UPDATE statement would result in an "affected by" value of zero because it does not change any columns from their current values, no matter how many rows the WHERE clause matches:

UPDATE limbs SET arms = 0 WHERE arms = 0;

9.2.4 Perl

In DBI scripts, the affected-rows count is returned by do( ) or by execute( ), depending on how you execute the query:

# execute $query using do( )
my $count = $dbh->do ($query);
# report 0 rows if an error occurred
printf "%d rows were affected
", (defined ($count) ? $count : 0);

# execute query using prepare( ) plus execute( )
my $sth = $dbh->prepare ($query);
my $count = $sth->execute ( );
printf "%d rows were affected
", (defined ($count) ? $count : 0);

When you use DBI, you have the option of asking MySQL to return the "matched by" value rather than the "affected by" value. To do this, specify mysql_client_found_rows=1 in the options part of the data source name argument of the connect( ) call when you connect to the MySQL server. Here's an example:

my $dsn =
 "DBI:mysql:cookbook:localhost;mysql_client_found_rows=1";
my $dbh = DBI->connect ($dsn, "cbuser", "cbpass",
 { PrintError => 0, RaiseError => 1 });

mysql_client_found_rows changes the row-reporting behavior for the duration of the connection.

9.2.5 PHP

In PHP, invoke the mysql_affected_rows( ) function to find out how many rows a query changed:

$result_id = mysql_query ($query, $conn_id);
# report 0 rows if the query failed
$count = ($result_id ? mysql_affected_rows ($conn_id) : 0);
print ("$count rows were affected
");

The argument to mysql_affected_rows( ) is a connection identifier. If you omit the argument, the current connection is used.

9.2.6 Python

Python's DB-API makes the row count available as the value of the query cursor's rowcount attribute:

cursor = conn.cursor ( )
cursor.execute (query)
print "%d rows were affected" % cursor.rowcount

9.2.7 Java

The Java JDBC interface provides row counts two different ways, depending on the method you invoke to execute the query. If you use executeUpdate( ), it returns the row count directly:

Statement s = conn.createStatement ( );
int count = s.executeUpdate (query);
s.close ( );
System.out.println (count + " rows were affected");

If you use execute( ), that method returns true or false to indicate whether or not the statement produces a result set. For statements such as UPDATE or DELETE that return no result set, the row count is available by calling the getUpdateCount( ) method:

Statement s = conn.createStatement ( );
if (!s.execute (query))
{
 // there is no result set, print the row count
 System.out.println (s.getUpdateCount ( ) + " rows were affected");
}
s.close ( );

For statements that modify rows, the MySQL Connector/J JDBC driver provides a rows-matched value for the row count, rather than a rows-affected value.