iPhone Programming Tutorials » database

Simple Sqlite Database Interaction Using FMDB

brandontreb — Fri, 04 Nov 2011 19:52:19 +0000

Introduction

In the age where Core Data is king, the database that started it all is often overlooked. I’m talking of course about sqlite. As you may or may not know, prior to core data, sqlite was the preferred method of storing relational data on iOS devices.

Although, most developers don’t interact with sqlite directly, they still use it under the hood as the primary data store for core data. This is great and all, but there are often times when raw sqlite is still the preferred storage method.

A few of these might include:

Caching
Preferences
Simple objects
Portability
Cross platform applications

Recently, I have had to make heave use of raw sqlite as a caching strategy in a new project that I’m working on. Being that we are developing a framework for other developers to include in their projects, we can’t always assume that they have their environment set up to use core data. When I was but a n00b iOS developer I did all of the crazy sqlite management by hand. See This post series, but don’t spend too much time there because it’s embarrassing.

Gross right? Now, there is a much easier way to manage and interact with your sqlite databases. This library has been around for quite some time and I wish I had known about it earyly on.

FMDB

FMDB stands for Flying Meat Database. What a great name… This project aims to be a fully featured wrapper for sqlite.

You can clone their repository on their github.

This tutorial will give you a brief introduction to using FMDB to create a database, create a table, insert, fetch, and delete data.

Project Set Up

The first step is to download/clone fmdb from the url above. Once downloaded drag everything inside of the src folder into your project except fmdb.m. That file contains unit tests and a main, which will cause some conflicts in your project.

The next step is to link in the sqlite library. To do this:

Click your project in the left column of XCode
Click the main target in the middle column. In our case it’s “FMDBTest”
Click the “Build Phases” tab in the third column
Expand the arrow next to “Link Binary With Libraries”
Click the “+” button
Search for libsqlite3.0.dylib and double click it

When you are all done, it should look like this:

Now, that we have the library in place, let’s write some code.

Creating A Database

Obviously where you create your database is up to you, but we are going to do it in the appDelegate.

In addition to working with existing databases, fmdb can easily create any number of databases for you on the fly. After importing FMDatabase.h in our AppDelegate.m file, we can add the following code to the application:didFinishLaunching method.

NSArray *paths = NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES);
NSString *docsPath = [paths objectAtIndex:0];
NSString *path = [docsPath stringByAppendingPathComponent:@"database.sqlite"];
 
FMDatabase *database = [FMDatabase databaseWithPath:path];

First, we resolve the path to the documents directory. Be careful, if you don’t need your database to be backed up, use the cache directory instead. When you send a path to the databaseWithPath method of fmdb, it first checks if the database exists, and if not, it creates it. Similarly, we could copy an existing database to the documents directory and source it the exact same way.

Opening The Database And Creating Tables

In order to perform any action on the database, it must first be opened. Here is the code to open the database and create a users table. Don’t worry about closing it right now, we will do that when we are all done.

[database open];
[database executeUpdate:@"create table user(name text primary key, age int)"];

Here we first call the open method of the database to open it. Next, we use the executeUpdate method to create the table. Make sure you use this method and not executeQuery when creating a table. This is a common error. The database should look like this after our update:

After we are all done here we close the database.

Inserting And Deleting Data

Inserting data using sqlite is very straight forward. You can either build your strings and pass them in directly OR use the sqlite format using “?’s” and letting fmdb do the work. Below is an example of each:

// Building the string ourself
NSString *query = [NSString stringWithFormat:@"insert into user values ('%@', %d)",
@"brandontreb", 25];
[database executeUpdate:query];
 
// Let fmdb do the work
[database executeUpdate:@"insert into user(name, age) values(?,?)",
@"cruffenach",[NSNumber numberWithInt:25],nil];

Generally, the second route is preferred as fmdb will do some of the sanitizing for your (such as add slashes to single quotes).

Now that we have some data in our database, let’s delete it. The following code will delete all users with an age of 25:

[database executeUpdate:@"delete from user where age = 25"];

And that should remove both of the records that we inserted.

Querying The Database

Querying the database is a bit more tricky than inserting and deleting. FMDB has some great utility methods for helping us out in certain circumstances, but for this tutorial, we will assume the don’t exist and show you how to fetch data out. If you are following along in a sample application, put this code before your delete code (so that we actually have some data to work with).

Below is an example of fetching all users from the database:

FMResultSet *results = [database executeQuery:@"select * from user"];
while([results next]) {
    NSString *name = [results stringForColumn:@"name"];
    NSInteger age  = [results intForColumn:@"age"];        
    NSLog(@"User: %@ - %d",name, age);
}
[database close];

We first query the database using the executeQuery method. This returns to us an FMResultsSet. Next we start a while loop that continues while there are results to be retrieved and fetch out each of our data points. Finally, we just print out each user.

And finally, our database gets close…

Conclusion

This concludes our sqlite using fmdb tutorial. As always, if you have any questions, please leave them here or write me on twitter.

You can download the source for this tutorial here

Happy iCoding!

iPhone Programming Tutorial – Creating a ToDo List Using SQLite Part 4

brandontreb — Mon, 22 Sep 2008 23:47:39 +0000

This is the final installment of our 4 part series of creating a Todo list for the iPhone. In this tutorial, I will detail how to add and delete new todo objects from the SQLite database. Make sure that you have completed the following tutorials before you begin this one:

When you have completed this tutorial, you should have a main screen that looks something like this:

Let’s get started…

The first thing we need to do is add the UIBarButtonItem items to the NavigationBar so that we get the “Edit” and “Add” button. Open up RootViewController.m and add the following code to the viewDidLoad method.

The first thing we see is the line that sets the leftBarButtonItem to self.editButtonItem. This automatically adds the “Edit” button to the NavigationController. Also, it sets up the functionality that allows the “delete” buttons to be displayed when the button is pressed. You can see this functionality if you do a “Build and Go” at this step. Next, I have manually created a UIBarButtonItem and added it to the navigationbar. This can be done in Interface Builder, but I wanted to show you how to do it manually and assign an action to it (I’m sure you will require this functionality in a future program). Here is a break down of the parameters:

initWithTitle – The text to be displayed on the button
style – How the button will look
target – The class object that handles the messages sent from this button
action – The method to be called when the button is passed. We can use @selector and give it the name of the function to call.

Finally, we assign this button to the rightBarButtonItem. If you do a Build and Go, it should error since we haven’t created the addTodo method. We will do that in a bit. Now, let’s create a method inside of our Todo object that will add new Todos to the database.

Open up Todo.h and add the following code:

So in addition to the insertNewTodoIntoDatabase method, we also see the deleteFromDatabase method signature. I have just added this so I don’t have to come back to it later. We will be implementing this when I show you how to delete todos from the database. One thing to note about the insertNewTodoIntoDatabase method is it has a “+” rather than a “-” sign. This means that it is a static method. Static methods are associated with the class not the instance meaning we can call this method without instanciating this class. So we can do stuff like Todo.insertNewTodoIntoDatabase. Now we will implement this method.

Before we can do this, we must declare a few more static sqlite3_statement’s. Add the following statements to the top of Todo.m

Nothing new here…Now implement the following method:

This is similar to our update method. Notice that we are inserting default values into the database. This is so we don’t run into any problems with null or nil values. The most important part of this method is the fact that it returns the primary key of the newly created todo object. This will be used later so we can immediately transition to the todo when the “Add” button is pressed. The last thing we need to do to the todo object is update the dehydrate method so that the todoText gets saved if it gets changed. Update the dehydrate method to look like this:

There are only a few minor changes here. First we see the “text = ?” part added to the sql statement. This is simply so we can update the text of the todo. The other change is we bound the self.text property to the 1st question mark in the sql statement. One thing to notice is we call [self.text UTF8String]. This is because sqlite3_bind_text takes a (char *). This will convert an NSString to an acceptable format.

Now we need to add a method inside of our RootViewController to add a todo. This is the method that will be called when the user presses the “Add” button. Inside of RootViewController.m add the following code:

First, we get a reference to the appDelegate object. This is because we need to call its addTodo method. Next, we instantiate the TodoViewController if it has not already been instantiated. We need this around because we will push it on to the view stack and transition to it after we create our new todo object. After this is done, we call the addTodo method of the appDelegate. It will return the newly created todo object and the view will be transitioned to its detail screen in order to update its details. Now we need to implement the method addTodo inside of our appDelegate. Open up todoAppDelegate.h and add the following code to create the method signature.

Now, let’s implement this method. Open up todoAppDelegate.m and add the following code:

First, we are calling the insertNewTodoIntoDatabase method of the Todo object. Notice that we are simply calling the method without first building an instance of a todo object. As I said in tutorial 3, this is because that method is static and gets called without building an instance of the class. Next, we insatiate the todo object that was just created by calling its initWithPrimaryKey method. This will give us reference to the new todo object. Finally, we append this todo to the end of our todos array. Since our UITableView is updated with this array, it will automatically include the new todo object. The last line just returns this todo object.

Remember is the last tutorial we made it so the users could update the status and the priority of a todo? Well, now we also need to give them the ability to update the text of the todo. So open up TodoViewController.h and add the following code:

Ok, so I’m guessing you are wondering why the UITextView for the todoText object has been changed to a UITextField. Well, I will tell you. UITextView doesn’t have the methods that we need to save the text with our current design. We will also be changing this on our Interface inside of Interface Builder. So for now, just believe me and anywhere it says UITextView, change it to UITextField. The only additional code we added here is the method signature for the updateText method. It’s an IBAction that will get called when the user presses the “Done” button on the keyboard after setting the text for the todo. Next, we need to implement this method. Open up TodoViewController.m and add the following code:

All this does is update the text of the todo to the text that the user entered inside of the UITextField. The last thing we need to do in order to add a todo is to replace the UITextView with a UITextField and connect it to our updateText method. Double click on your TodoViewController.xib file to open it in Interface Builder.

Now click on the UITextView on your interface and press the delete key on your keyboard to delete it. Now, drag a UITextField from the library and drop it onto your interface. Resize it to fit. When you have completed that, your interface should look something like this:

Now we need to connect this component. Make sure it is selected and click Tools -> Connections Inspector to open up the connections inspector. Drag from the circle next to the method “Did End On Exit” to the “File’s Owner” object. The words udpateText should pop up. Click on them to make the connection. Next, click in the circle next to “New Referencing Outlet” and drag it to the “File’s Owner” object. Select todoText when it pops up. The Connections Inspector should look like this:

Now we are done with Interface Builder. Go ahead and close it. We are now able to add todos. The last thing we need to do is give the ability to delete todos from the list as well as our database. This is all done in code, and we won’t need interface builder for this.

Let’s start by adding the methods to the appDelegate to handle the deletion of todos. Open up todoAppDelegate.h and add the following code:

All we see here is a signature for the removeTodo method. Also, be sure to add a #import “Todo.h” statement to the top of this file so that we can interface with the todo objects. Now let’s implement the removeTodo method. Open up todoAppDelegate.m and add the following code:

The first line looks up the todo in the todos NSArray. It returns the index in the array of the todo to be deleted. Then, we call the deleteFromDatabase method on the todo object and then remove it from the todos array. Since the UITableView is updated via this array, it will automatically remove the todo without any additional code on our part.

Now, let’s create the removeTodo method for the todo object. We have already written the method signature in Todo.h in a previous step, so open up Todo.m and add the following code:

Remember the delete_statement variable is a static sqlite3_stmt that we declared in a previous step. First, we check to see if it is nil. If it is we compile the statement using the sqlite3_prepare statement. Next, we bind the primary key of the current todo to the “?” in the sqlite3 statement. Next, we just step the statement to execute it and reset it. The last thing we need to do to delete todos from the database is to specify what happens when the user presses the “delete” button. Open up RootViewController.m and add the following code:

The first step (like the first step of many functions) is to get a reference to the appDelegate. Next, we check to see if we are currently editing. If so, call the removeTodo method on appDelegate. The next line, removes the row from the UITableView at the given indexPath.

Now click Build and Go! You should now be able to add and delete todo items from the database. This concludes our four part series of creating a todo list for the iPhone. As always, if you have any questions feel free to leave them in the comments section. If you get lost at any time you can download the sample code here.

Happy iCoding!