MySQL These functions allow you to access MySQL database servers. In order to have these functions available, you must compile php with mysql support by using the --with-mysql option. If you use this option without specifying the path to mysql, php will use the built-in mysql client libraries. Users who run other applications that use mysql (for example, running php3 and php4 as concurrent apache modules, or auth-mysql) should always specify the path to mysql: --with-mysql=/path/to/mysql. This will force php to use the client libraries installed by mysql, avoiding any conflicts. More information about MySQL can be found at &url.mysql;. Documentation for MySQL can be found at &url.mysql.docs;. mysql_affected_rows Get number of affected rows in previous MySQL operation int mysql_affected_rows resource link_identifier mysql_affected_rows returns the number of rows affected by the last INSERT, UPDATE or DELETE query associated with link_identifier. If the link identifier isn't specified, the last link opened by mysql_connect is assumed. If you are using transactions, you need to call mysql_affected_rows after your INSERT, UPDATE, or DELETE query, not after the commit. If the last query was a DELETE query with no WHERE clause, all of the records will have been deleted from the table but this function will return zero. When using UPDATE, MySQL will not update columns where the new value is the same as the old value. This creates the possiblity that mysql_affected_rows may not actually equal the number of rows matched, only the number of rows that were literally affected by the query. mysql_affected_rows does not work with SELECT statements; only on statements which modify records. To retrieve the number of rows returned by a SELECT, use mysql_num_rows. If the last query failed, this function will return -1. See also: mysql_num_rows. mysql_change_user Change logged in user of the active connection int mysql_change_user string user string password string database resource link_identifier mysql_change_user changes the logged in user of the current active connection, or the connection given by the optional parameter link_identifier. If a database is specified, this will default or current database after the user has been changed. If the new user and password authorization fails, the current connected user stays active. This function was introduced in PHP 3.0.13 and requires MySQL 3.23.3 or higher. mysql_close Close MySQL connection bool mysql_close resource link_identifier Returns: true on success, false on error. mysql_close closes the connection to the MySQL server that's associated with the specified link identifier. If link_identifier isn't specified, the last opened link is used. Using mysql_close isn't usually necessary, as non-persistent open links are automatically closed at the end of the script's execution. See also freeing resources. mysql_close will not close persistent links created by mysql_pconnect. <?php $link = mysql_connect ("kraemer", "marliesle", "secret") or die ("Could not connect"); print ("Connected successfully"); mysql_close ($link); ?> See also: mysql_connect, and mysql_pconnect. mysql_connect Open a connection to a MySQL Server resource mysql_connect string hostname :port :/path/to/socket string username string password Returns a MySQL link identifier on success, or FALSE on failure. mysql_connect establishes a connection to a MySQL server. The following defaults are assumed for missing optional parameters: host:port = 'localhost:3306', username = name of the user that owns the server process and password = empty password. The hostname string can also include a port number. eg. "hostname:port" or a path to a socket eg. ":/path/to/socket" for the localhost. Support for ":port" was added in PHP 3.0B4. Support for ":/path/to/socket" was added in PHP 3.0.10. You can suppress the error message on failure by prepending '@' to the function name. If a second call is made to mysql_connect with the same arguments, no new link will be established, but instead, the link identifier of the already opened link will be returned. The link to the server will be closed as soon as the execution of the script ends, unless it's closed earlier by explicitly calling mysql_close. <?php $link = mysql_connect ("localhost", "username", "secret") or die ("Could not connect"); print ("Connected successfully"); mysql_close ($link); ?> See also mysql_pconnect, and mysql_close. mysql_create_db Create a MySQL database int mysql_create_db string database name resource link_identifier mysql_create_db attempts to create a new database on the server associated with the specified link identifier. <?php $link = mysql_pconnect ("kron", "jutta", "geheim") or die ("Could not connect"); if (mysql_create_db ("my_db")) { print ("Database created successfully\n"); } else { printf ("Error creating database: %s\n", mysql_error ()); } ?> For downwards compatibility mysql_createdb can also be used. See also: mysql_drop_db. mysql_data_seek Move internal result pointer bool mysql_data_seek resource result_identifier int row_number Returns: true on success, false on failure. mysql_data_seek moves the internal row pointer of the MySQL result associated with the specified result identifier to point to the specified row number. The next call to mysql_fetch_row would return that row. Row_number starts at 0. <?php $link = mysql_pconnect ("kron", "jutta", "geheim") or die ("Could not connect"); mysql_select_db ("samp_db") or die ("Could not select database"); $query = "SELECT last_name, first_name FROM friends"; $result = mysql_query ($query) or die ("Query failed"); # fetch rows in reverse order for ($i = mysql_num_rows ($result) - 1; $i >=0; $i--) { if (!mysql_data_seek ($result, $i)) { echo "Cannot seek to row $i\n"; continue; } if(!($row = mysql_fetch_object ($result))) continue; echo ("$row->last_name $row->first_name<BR>\n"; } mysql_free_result ($result); ?> mysql_db_name Get result data string mysql_db_name resource result int row mixed field mysql_db_name takes as its first parameter the result pointer from a call to mysql_list_dbs. The row parameter is an index into the result set. If an error occurs, FALSE is returned. Use mysql_errno and mysql_error to determine the nature of the error. <?php error_reporting(E_ALL); mysql_connect('dbhost', 'username', 'password'); $db_list = mysql_list_dbs(); $i = 0; $cnt = mysql_num_rows($db_list); while ($i < $cnt) { echo mysql_db_name($db_list, $i) . "\n"; $i++; } ?> For backward compatibility, mysql_dbname is also accepted. This is deprecated, however. mysql_db_query Send a MySQL query resource mysql_db_query string database string query resource link_identifier Returns: A positive MySQL result resource to the query result, or false on error. mysql_db_query selects a database and executes a query on it. If the optional link identifier isn't specified, the function will try to find an open link to the MySQL server and if no such link is found it'll try to create one as if mysql_connect was called with no arguments See also mysql_connect and mysql_query. For downwards compatibility mysql can also be used. mysql_drop_db Drop (delete) a MySQL database bool mysql_drop_db string database_name resource link_identifier Returns: true on success, false on failure. mysql_drop_db attempts to drop (remove) an entire database from the server associated with the specified link identifier. See also: mysql_create_db. For downward compatibility mysql_dropdb can also be used. mysql_errno Returns the numerical value of the error message from previous MySQL operation int mysql_errno resource link_identifier Returns the error number from the last mySQL function, or 0 (zero) if no error occurred. Errors coming back from the mySQL database backend no longer issue warnings. Instead, use mysql_errno to retrieve the error code. Note that this function only returns the error code from the most recently executed mySQL function (not including mysql_error and mysql_errno), so if you want to use it, make sure you check the value before calling another mySQL function. <?php mysql_connect("marliesle"); echo mysql_errno().": ".mysql_error()."<BR>"; mysql_select_db("nonexistentdb"); echo mysql_errno().": ".mysql_error()."<BR>"; $conn = mysql_query("SELECT * FROM nonexistenttable"); echo mysql_errno().": ".mysql_error()."<BR>"; ?> See also: mysql_error mysql_error Returns the text of the error message from previous MySQL operation string mysql_error resource link_identifier Returns the error text from the last mySQL function, or '' (the empty string) if no error occurred. Errors coming back from the mySQL database backend no longer issue warnings. Instead, use mysql_error to retrieve the error text. Note that this function only returns the error text from the most recently executed mySQL function (not including mysql_error and mysql_errno), so if you want to use it, make sure you check the value before calling another mySQL function. <?php mysql_connect("marliesle"); echo mysql_errno().": ".mysql_error()."<BR>"; mysql_select_db("nonexistentdb"); echo mysql_errno().": ".mysql_error()."<BR>"; $conn = mysql_query("SELECT * FROM nonexistenttable"); echo mysql_errno().": ".mysql_error()."<BR>"; ?> See also: mysql_errno mysql_fetch_array Fetch a result row as an associative array, a numeric array, or both. array mysql_fetch_array resource result int result_type Returns an array that corresponds to the fetched row, or false if there are no more rows. mysql_fetch_array is an extended version of mysql_fetch_row. In addition to storing the data in the numeric indices of the result array, it also stores the data in associative indices, using the field names as keys. If two or more columns of the result have the same field names, the last column will take precedence. To access the other column(s) of the same name, you must the numeric index of the column or make an alias for the column. select t1.f1 as foo t2.f1 as bar from t1, t2 An important thing to note is that using mysql_fetch_array is NOT significantly slower than using mysql_fetch_row, while it provides a significant added value. The optional second argument result_type in mysql_fetch_array is a constant and can take the following values: MYSQL_ASSOC, MYSQL_NUM, and MYSQL_BOTH. (This feature was added in PHP 3.0.7) For further details, see also mysql_fetch_row and mysql_fetch_assoc. <?php mysql_connect ($host, $user, $password); $result = mysql_db_query ("database","select user_id, fullname from table"); while ($row = mysql_fetch_array ($result)) { echo "user_id: ".$row["user_id"]."<br>\n"; echo "user_id: ".$row[0]."<br>\n"; echo "fullname: ".$row["fullname"]."<br>\n"; echo "fullname: ".$row[1]."<br>\n"; } mysql_free_result ($result); ?> mysql_fetch_assoc Fetch a result row as an associative array array mysql_fetch_assoc resource result Returns an associative array that corresponds to the fetched row, or false if there are no more rows. mysql_fetch_assoc is equivalent to calling mysql_fetch_array with MYSQL_ASSOC for the optional second parameter. It only returns an associative array. This is the way mysql_fetch_array originally worked. If you need the numeric indices as well as the associative, use mysql_fetch_array. If two or more columns of the result have the same field names, the last column will take precedence. To access the other column(s) of the same name, you must use mysql_fetch_array and have it return the numeric indices as well. An important thing to note is that using mysql_fetch_assoc is NOT significantly slower than using mysql_fetch_row, while it provides a significant added value. For further details, see also mysql_fetch_row and mysql_fetch_array. <?php mysql_connect ($host, $user, $password); $result = mysql_db_query ("database","select * from table"); while ($row = mysql_fetch_assoc ($result)) { echo $row["user_id"]; echo $row["fullname"]; } mysql_free_result ($result); ?> mysql_fetch_field Get column information from a result and return as an object object mysql_fetch_field resource result int field_offset Returns an object containing field information. mysql_fetch_field can be used in order to obtain information about fields in a certain query result. If the field offset isn't specified, the next field that wasn't yet retrieved by mysql_fetch_field is retrieved. The properties of the object are: name - column name table - name of the table the column belongs to max_length - maximum length of the column not_null - 1 if the column cannot be null primary_key - 1 if the column is a primary key unique_key - 1 if the column is a unique key multiple_key - 1 if the column is a non-unique key numeric - 1 if the column is numeric blob - 1 if the column is a BLOB type - the type of the column unsigned - 1 if the column is unsigned zerofill - 1 if the column is zero-filled <?php mysql_connect ($host, $user, $password) or die ("Could not connect"); $result = mysql_db_query ("database", "select * from table") or die ("Query failed"); # get column metadata $i = 0; while ($i < mysql_num_fields ($result)) { echo "Information for column $i:<BR>\n"; $meta = mysql_fetch_field ($result); if (!$meta) { echo "No information available<BR>\n"; } echo "<PRE> blob: $meta->blob max_length: $meta->max_length multiple_key: $meta->multiple_key name: $meta->name not_null: $meta->not_null numeric: $meta->numeric primary_key: $meta->primary_key table: $meta->table type: $meta->type unique_key: $meta->unique_key unsigned: $meta->unsigned zerofill: $meta->zerofill </PRE>"; $i++; } mysql_free_result ($result); ?> See also mysql_field_seek. mysql_fetch_lengths Get the length of each output in a result array mysql_fetch_lengths resource result Returns: An array that corresponds to the lengths of each field in the last row fetched by mysql_fetch_row, or false on error. mysql_fetch_lengths stores the lengths of each result column in the last row returned by mysql_fetch_row, mysql_fetch_array, and mysql_fetch_object in an array, starting at offset 0. See also: mysql_fetch_row. mysql_fetch_object Fetch a result row as an object object mysql_fetch_object resource result int result_type Returns an object with properties that correspond to the fetched row, or false if there are no more rows. mysql_fetch_object is similar to mysql_fetch_array, with one difference - an object is returned, instead of an array. Indirectly, that means that you can only access the data by the field names, and not by their offsets (numbers are illegal property names). The optional argument result_type is a constant and can take the following values: MYSQL_ASSOC, MYSQL_NUM, and MYSQL_BOTH. Speed-wise, the function is identical to mysql_fetch_array, and almost as quick as mysql_fetch_row (the difference is insignificant). <?php mysql_connect ($host, $user, $password); $result = mysql_db_query ("database", "select * from table"); while ($row = mysql_fetch_object ($result)) { echo $row->user_id; echo $row->fullname; } mysql_free_result ($result); ?> See also: mysql_fetch_array and mysql_fetch_row. mysql_fetch_row Get a result row as an enumerated array array mysql_fetch_row resource result Returns: An array that corresponds to the fetched row, or false if there are no more rows. mysql_fetch_row fetches one row of data from the result associated with the specified result identifier. The row is returned as an array. Each result column is stored in an array offset, starting at offset 0. Subsequent call to mysql_fetch_row would return the next row in the result set, or false if there are no more rows. See also: mysql_fetch_array, mysql_fetch_object, mysql_data_seek, mysql_fetch_lengths, and mysql_result. mysql_field_flags Get the flags associated with the specified field in a result string mysql_field_flags resource result int field_offset mysql_field_flags returns the field flags of the specified field. The flags are reported as a single word per flag separated by a single space, so that you can split the returned value using explode. The following flags are reported, if your version of MySQL is current enough to support them: "not_null", "primary_key", "unique_key", "multiple_key", "blob", "unsigned", "zerofill", "binary", "enum", "auto_increment", "timestamp". For downward compatibility mysql_fieldflags can also be used. mysql_field_name Get the name of the specified field in a result string mysql_field_name resource result int field_index mysql_field_name returns the name of the specified field index. result must be a valid result identifier and field_index is the numerical offset of the field. field_index starts at 0. e.g. The index of the third field would actually be 2, the index of the fourth field would be 3 and so on. // The users table consists of three fields: // user_id // username // password. $res = mysql_db_query("users", "select * from users", $link); echo mysql_field_name($res, 0) . "\n"; echo mysql_field_name($res, 2); The above example would produce the following output: user_id password For downwards compatibility mysql_fieldname can also be used. mysql_field_len Returns the length of the specified field int mysql_field_len resource result int field_offset mysql_field_len returns the length of the specified field. For downward compatibility mysql_fieldlen can also be used. mysql_field_seek Set result pointer to a specified field offset int mysql_field_seek resource result int field_offset Seeks to the specified field offset. If the next call to mysql_fetch_field doesn't include a field offset, the field offset specified in mysql_field_seek will be returned. See also: mysql_fetch_field. mysql_field_table Get name of the table the specified field is in string mysql_field_table resource result int field_offset Returns the name of the table that the specifed field is in. For downward compatibility mysql_fieldtable can also be used. mysql_field_type Get the type of the specified field in a result string mysql_field_type iresource result int field_offset mysql_field_type is similar to the mysql_field_name function. The arguments are identical, but the field type is returned instead. The field type will be one of "int", "real", "string", "blob", and others as detailed in the MySQL documentation. <?php mysql_connect ("localhost:3306"); mysql_select_db ("wisconsin"); $result = mysql_query ("SELECT * FROM onek"); $fields = mysql_num_fields ($result); $rows = mysql_num_rows ($result); $i = 0; $table = mysql_field_table ($result, $i); echo "Your '".$table."' table has ".$fields." fields and ".$rows." records <BR>"; echo "The table has the following fields <BR>"; while ($i < $fields) { $type = mysql_field_type ($result, $i); $name = mysql_field_name ($result, $i); $len = mysql_field_len ($result, $i); $flags = mysql_field_flags ($result, $i); echo $type." ".$name." ".$len." ".$flags."<BR>"; $i++; } mysql_close(); ?> For downward compatibility mysql_fieldtype can also be used. mysql_free_result Free result memory int mysql_free_result resource result mysql_free_result will free all memory associated with the result identifier result. mysql_free_result only needs to be called if you are concerned about how much memory is being used for queries that return large result sets. All associated result memory is automatically freed at the end of the script's execution. For downward compatibility mysql_freeresult can also be used. mysql_insert_id Get the id generated from the previous INSERT operation int mysql_insert_id resource link_identifier mysql_insert_id returns the ID generated for an AUTO_INCREMENT column by the previous INSERT query using the given link_identifier. If link_identifier isn't specified, the last opened link is assumed. mysql_insert_id returns 0 if the previous query does not generate an AUTO_INCREMENT value. If you need to save the value for later, be sure to call mysql_insert_id() immediately after the query that generates the value. The value of the MySQL SQL function LAST_INSERT_ID() always contains the most recently generated AUTO_INCREMENT value, and is not reset between queries. mysql_insert_id converts the return type of the native MySQL C API function mysql_insert_id() to a type of long. If your AUTO_INCREMENT column has a column type of BIGINT, the value returned by mysql_insert_id will be incorrect. Instead, use the internal MySQL SQL function LAST_INSERT_ID(). mysql_list_dbs List databases available on a MySQL server resource mysql_list_dbs resource link_identifier mysql_list_dbs will return a result pointer containing the databases available from the current mysql daemon. Use the mysql_tablename function to traverse this result pointer. $link = mysql_connect('localhost', 'myname', 'secret'); $db_list = mysql_list_dbs($link); while ($row = mysql_fetch_object($db_list)) { echo $row->Database . "\n"; } The above example would produce the following output: database1 database2 database3 ... The above code would just as easily work with mysql_fetch_row or other similar functions. For downward compatibility mysql_listdbs can also be used. See also mysql_db_name mysql_list_fields List MySQL result fields resource mysql_list_fields string database_name string table_name resource link_identifier mysql_list_fields retrieves information about the given tablename. Arguments are the database name and the table name. A result pointer is returned which can be used with mysql_field_flags, mysql_field_len, mysql_field_name, and mysql_field_type. $link = mysql_connect('localhost', 'myname', 'secret'); $fields = mysql_list_fields("database1", "table1", $link); $columns = mysql_num_fields($fields); for ($i = 0; $i < $columns; $i++) { echo mysql_field_name($fields, $i) . "\n";; } The above example would produce the following output: field1 field2 field3 ... For downward compatibility mysql_listfields can also be used. mysql_list_tables List tables in a MySQL database resource mysql_list_tables string database resource link_identifier mysql_list_tables takes a database name and returns a result pointer much like the mysql_db_query function. The mysql_tablename function should be used to extract the actual table names from the result pointer. For downward compatibility mysql_listtables can also be used. mysql_num_fields Get number of fields in result int mysql_num_fields resource result mysql_num_fields returns the number of fields in a result set. See also: mysql_db_query, mysql_query, mysql_fetch_field, mysql_num_rows. For downward compatibility mysql_numfields can also be used. mysql_num_rows Get number of rows in result int mysql_num_rows resource result mysql_num_rows returns the number of rows in a result set. This command is only valid for SELECT statements. To retrieve the number of rows returned from a INSERT, UPDATE or DELETE query, use mysql_affected_rows. <?php $link = mysql_connect("localhost", "username", "password"); mysql_select_db("database", $link); $result = mysql_query("SELECT * FROM table1", $link); $num_rows = mysql_num_rows($result); echo "$num_rows Rows\n"; ?> See also: mysql_affected_rows, mysql_connect, mysql_select_db and mysql_query. For downward compatibility mysql_numrows can also be used. mysql_pconnect Open a persistent connection to a MySQL Server resource mysql_pconnect string hostname :port :/path/to/socket string username string password Returns: A positive MySQL persistent link identifier on success, or false on error. mysql_pconnect establishes a connection to a MySQL server. The following defaults are assumed for missing optional parameters: host:port = 'localhost:3306', username = name of the user that owns the server process and password = empty password. The hostname string can also include a port number. eg. "hostname:port" or a path to a socket eg. ":/path/to/socket" for the localhost. Support for ":port" wass added in 3.0B4. Support for the ":/path/to/socket" was added in 3.0.10. mysql_pconnect acts very much like mysql_connect with two major differences. First, when connecting, the function would first try to find a (persistent) link that's already open with the same host, username and password. If one is found, an identifier for it will be returned instead of opening a new connection. Second, the connection to the SQL server will not be closed when the execution of the script ends. Instead, the link will remain open for future use (mysql_close will not close links established by mysql_pconnect). This type of links is therefore called 'persistent'. mysql_query Send a MySQL query resource mysql_query string query resource link_identifier mysql_query sends a query to the currently active database on the server that's associated with the specified link identifier. If link_identifier isn't specified, the last opened link is assumed. If no link is open, the function tries to establish a link as if mysql_connect was called with no arguments, and use it. The query string should not end with a semicolon. mysql_query returns TRUE (non-zero) or FALSE to indicate whether or not the query succeeded. A return value of TRUE means that the query was legal and could be executed by the server. It does not indicate anything about the number of rows affected or returned. It is perfectly possible for a query to succeed but affect no rows or return no rows. The following query is syntactically invalid, so mysql_query fails and returns FALSE: <?php $result = mysql_query ("SELECT * WHERE 1=1") or die ("Invalid query"); ?> The following query is semantically invalid if my_col is not a column in the table my_tbl, so mysql_query fails and returns FALSE: <?php $result = mysql_query ("SELECT my_col FROM my_tbl") or die ("Invalid query"); ?> mysql_query will also fail and return FALSE if you don't have permission to access the table(s) referenced by the query. Assuming the query succeeds, you can call mysql_num_rows to find out how many rows were returned for a SELECT statment or mysql_affected_rows to find out how many rows were affected by a DELETE, INSERT, REPLACE, or UPDATE statement. For SELECT statements, mysql_query returns a new result identifier that you can pass to mysql_result. When you are done with the result set, you can free the resources associated with it by calling mysql_free_result. Although, the memory will automatically be freed at the end of the script's execution. See also: mysql_affected_rows, mysql_db_query, mysql_unbuffered_query, mysql_free_result, mysql_result, mysql_select_db, and mysql_connect. mysql_unbuffered_query Send an SQL query to MySQL, without fetching and buffering the result rows resource mysql_unbuffered_query string query resource link_identifier int result_mode mysql_unbuffered_query sends a SQL query to MySQL, without fetching and buffering the result rows automatically, as mysql_query does. On the one hand, this saves a considerable amount of memory with SQL queries that produce large result sets. On the other hand, you can start working on the result set immediately after the first row has been retrieved: you don't have to wait until the complete SQL query has been performed. The benefits of mysql_unbuffered_query come at a cost: You cannot use mysql_num_rows on a result set returned from mysql_unbuffered_query. You also have to fetch all result rows from an unbuffered SQL query, before you can send a new SQL query to MySQL. See also: mysql_query. mysql_result Get result data mixed mysql_result resource result int row mixed field mysql_result returns the contents of one cell from a MySQL result set. The field argument can be the field's offset, or the field's name, or the field's table dot field's name (tabledname.fieldname). If the column name has been aliased ('select foo as bar from...'), use the alias instead of the column name. When working on large result sets, you should consider using one of the functions that fetch an entire row (specified below). As these functions return the contents of multiple cells in one function call, they're MUCH quicker than mysql_result. Also, note that specifying a numeric offset for the field argument is much quicker than specifying a fieldname or tablename.fieldname argument. Calls to mysql_result should not be mixed with calls to other functions that deal with the result set. Recommended high-performance alternatives: mysql_fetch_row, mysql_fetch_array, and mysql_fetch_object. mysql_select_db Select a MySQL database bool mysql_select_db string database_name resource link_identifier Returns: true on success, false on error. mysql_select_db sets the current active database on the server that's associated with the specified link identifier. If no link identifier is specified, the last opened link is assumed. If no link is open, the function will try to establish a link as if mysql_connect was called, and use it. Every subsequent call to mysql_query will be made on the active database. See also: mysql_connect, mysql_pconnect, and mysql_query. For downward compatibility mysql_selectdb can also be used. mysql_tablename Get table name of field string mysql_tablename resource result int i mysql_tablename takes a result pointer returned by the mysql_list_tables function as well as an integer index and returns the name of a table. The mysql_num_rows function may be used to determine the number of tables in the result pointer. <?php mysql_connect ("localhost:3306"); $result = mysql_list_tables ("wisconsin"); $i = 0; while ($i < mysql_num_rows ($result)) { $tb_names[$i] = mysql_tablename ($result, $i); echo $tb_names[$i] . "<BR>"; $i++; } ?>