Thread: Using the vBulletin Database Class

Note: This tutorial assumes that you are familier with PHP and SQL, and will introduce you to the vBulletin way of running SQL commands

Using the vBulletin Database Class

Introduction

Like most large web-based software, vBulletin includes a Database Abstraction Layer. This allows you to read and write to databases without having to use database-specific functions such as mysql_query, or pgsql_query. The database abstraction layer allows you to run SQL without having to worry about what database server is being used as it will all be handled in the background.

This article is a brief introduction to the vBulletin Database class which handles all database abstraction within vBulletin and the add-ons that you create.

Accessing the Database functions

When vBulletin loads any page, the database object is created and stored in the $db variable. This object contains all of the functions that you will use to access the vBulletin database.

Note: You can also access the $db variable as $vbulletin->db, but for readability, I will refer to it as $db for the rest of this article.

Table Prefix

We'll start with the most important part of reading and writing data within vBulletin, the TABLE_PREFIX constant. As you've probably noticed, you can choose a string to prefix all of your database tables within vBulletin. By default, this is "vb_". So your users table would be called "vb_user", your posts table "vb_post" and so on.

It is important that you remember that not everyone will be using the same prefix (if any) as you, so hard-coding "vb_" into your script will not work for a lot of users.

Luckily, vBulletin provides the TABLE_PREFIX constant for us to use. TABLE_PREFIX should be fairly self-explanatory, it contains the table prefix for the vBulletin database tables. For example, if in your config.php, you set the table prefix to be "vb36_", then TABLE_PREFIX would contain "vb36_". TABLE_PREFIX is set automaticly when vBulletin runs so will be available in every vBulletin page.

Example:
PHP Code:

$db->query_read("SELECT username FROM " . TABLE_PREFIX . "user WHERE userid = 1");

As you can see in this example, we escape out of our SQL query string to include the TABLE_PREFIX constant. This is vitally important in every query that you run! If you leave it out of a query, your script will likely break for a lot of users.

For ease of reading, I will be leaving the TABLE_PREFIX constant out of my example queries below, but you should not!

Selecting Data

Almost every addon will need to read some data from a database table at some point. vBulletin provides the query_read() function for this purpose.

Example:
PHP Code:

$result = $db->query_read("SELECT column FROM table");

query_read() takes the SQL that you wish to execute as its paramater, and returns a database result set containing the results. This is the equivilent to mysql_query()

Handling the Result Set

As query_read() returns a database result set, rather than an array, we will need a function to read the result set and provide us with an array which we can then use. vBulletin provides a few functions which will do the job, namely:

• fetch_field()
• fetch_row()
• fetch_array()

We will be concentrating on the last function, fetch_array() as that is the one you will find yourself using day-to-day.

Example:
PHP Code:

$array = $db->fetch_array($result);

fetch_array() takes a result set as it's paramater and returns an array with the current row. Because it will only return 1 row at a time, you will need to use it in a while() loop if you are fetching more than 1 row.

Example:
PHP Code:

while ($array = $db->fetch_array($result))
{
// Do something with the current row here
}

As you can see, each time fetch_array() is run within the while() loop, it moves on to the next row in the result set.

Selecting a single row

If you know that you will just be selecting a single row of data from your table (ie, a users details, or a single forum post), then vBulletin provides a handy function called query_first() which will not only run your SQL query, but also return the row as an array for you.

Example:
PHP Code:

$array = $db->query_first("SELECT userid, username FROM user WHERE email = 'this@example.com' LIMIT 1);

In this example, you can see that query_first() takes your SQL query as it's paramater and returns an array, rather than a result set. The query_first() function is handy when you know that you will only be selecting a single row from the table.

Writing to the Database

At some point, it is likely you will need to save some data to the database, or update an existing table with some changed data. To do this, vBulletin provides the query_write() function.

Example:
PHP Code:

$db->query_write("INSERT INTO table (column) 'value'");

As you can see, query_write() takes the SQL statement as its paramater.

Another useful function when writing to the database is the affected_rows() function. This will tell us how many rows where affected by the last INSERT, UPDATE or REPLACE query.

Example:
PHP Code:

$row_count = $db->affected_rows();

This function takes no paramaters as it only works with the last write query that was performed, and will return the number of rows affected.

Fetching the last Auto-Increment number

If you have ever used PHP's MySQL functions, you'll likely be aware of the mysql_insert_id() function. When you have written a new row to a table that contains an Auto Increment field, mysql_insert_id() will return the Auto-Increment number for the new row.

Thankfully, vBulletin provides us with the insert_id() function which does the same job.

Example:
PHP Code:

$id = $db->insert_id();

This function takes no paramaters and will return the most recent Auto-Increment field.

Handling Errors

vBulletin provides 2 functions that allow us to see if any errors have occured when we run our SQL. These are error() and errno().

$db->error() will return the Error Text for the most recent database operation.
$db->errno() will return the Error Number for the most recent database operation.

By default, if an SQL error occurs, vBulletin will display an error page with details of the SQL error on it. You can prevent this by using the hide_errors() function. When using this, be sure to perform your own manual error checking.

You can show the error page again by using the show_errors() function.

Freeing up Memory

vBulletin will destroy all of your result sets once the page has loaded. However, if you are running queries that are returning a lot of rows, you should unset the result set yourself once you are finished with it to free up memory.

vBulletin provides the free_result() function for this purpose.

Example:
PHP Code:

$db->free_result($huge_result_set);

free_result() takes the result set as it's paramater

Cleaning User Input

Most of us need to to run some form of SQL query that includes data submitted by the user. When using this data, you should never assume that it matches the data you have told the user to provide, as not all users are as honest as us

Thankfully, vBulletin provides us with some functions that will clean input for us. escape_string() and escape_string_like() being 2 of them.

escape_string() does exactly what it says on the tin. It will escape (usually using backslashes, although some Database Servers use a different method) any string value that you parse it.

Example:
PHP Code:

$db->query_read("SELECT * FROM user WHERE username = '" . $db->escape_string($username) . "'");

escape_string_like() does exactly the same, but should be used when you are using the LIKE statement in your query.

Example:
PHP Code:

$db->query_read("SELECT * FROM user WHERE username LIKE '" . $db->escale_string_like($username) . "'");

Important! You should never use addslashes() in your SQL queries. addslashes() was not designed to escape SQL strings, and doesn't do a particularly good job at doing it. Always use escape_string() or escape_string_like() to make strings safer


Conclusion

To sum up, vBulletin provides you with functions to perform all common SQL tasks, without you having to worry about which database system is being used.

You should always use the vBulletin provided functions rather than database specific functions, as not everyone will be using the same database server as you. What's that you say? Only you will be using the script and you use MySQL? ok, but what happens 2 years down the line when you decide to switch to MySQLi, or PostgreSQL? Do you really want to have to go through your script replacing all the functions?

Good luck using your new found knowledge of the vBulletin Database Abstraction Layer, and remember: If you get stuck, just ask! Knowledge sharing is what vBulletin.org is all about!


(Note: If you want to reproduce this article anywhere, I have no objections, but I do request that you give me credit for writing it, and a PM letting me know would be appreciated )

http://www.vbulletin.org/forum/showthread.php?t=119350

Similar Threads:

• What class do you think will be on top in pvp ?
• .Class File
• >:3's Database of legit buyers/sellers.
• Average day in my A+/NET+ class...
• [please-help] - java / class file