Designoplasty Web Design and Development Blog

Today I did some experimentation with the dbDelta function in WordPress. I’ll get right to the point, I don’t recommend it. I read about the function in the article Creating Tables with Plugins which talks about adding tables to WordPress from a plugin. This is exactly what I was doing.

I want to make it clear that this post isn’t a rant about the poor quality of dbDelta or the shameful state of its documentation. It’s just clear that for now it’s a function used by WordPress but not really up to snuff for use by others. This post was written while version 2.7.1 was the latest version of WordPress and dbDelta may improve in the future. I just want to warn other people against its use because it’s difficult to find documentation on it and I don’t want people to have to go through what I did to figure out that they shouldn’t use it.

Here are the reasons.

dbDelta Fails Silently

More than any other reason, this is the reason you should not use dbDelta. When dbDelta encounters a problem and cannot make alterations to an existing table it just fails silently. In fact, if you explore the returned value, it will tell you it created the table. This is sort of odd because you were essentially asking dbDelta to alter the table, but whatever. Because it fails silently you have no idea what happened. If you just run sql you get notified of a failure and and have access to an error message.

dbDelta isn’t Documented

For now, dbDelta isn’t documented. The article I link to is the closest you’ll get to documentation. Even the source code, which is usually a great place to look, doesn’t have documentation. If you browse the source you can see this function is used by WordPress and most likely maintained for the sole purpose of keeping WordPress going.

My Experience with dbDelta

Just to let you know what I was doing. I was lured in by the fact that dbDelta would automatically make alterations to the table structure for you, that’s a great idea. Even with its minor restrictions, it seemed like a good deal. This was a great time to try it out because I was just starting out and I knew I would be making lots of changes to my table structure and it would be a good test to see if dbDelta could deliver.

The problem is, there are all sorts of reasons that MySQL won’t allow alterations to a table, and dbDelta apparently is not good at catching those. One common reason you might run into is changing an existing column to NOT NULL. This won’t be accepted by MySQL because it doesn’t know what value to put in for existing rows with a NULL value for that column.

It may be the case that if you give dbDelta acceptable inputs that it will work fine, but if you don’t, wouldn’t you like to know? Furthermore changing a column to NOT NULL might be something you actually need to do, and then dbDelta wouldn’t work for you anyway. Which brings us to a good point. How often will you alter the structure of a table without having to do any data manipulation? Probably not very often, so again, dbDelta isn’t really going to be that much of a friend to you.

But again, dbDelta clearly works for WordPress, I’m not trying to criticize it. I’m just trying to save you some time by letting you know that these aren’t the droids you’re looking for.