The current trunk is in production use so the trunk is seldom broken. This update now requires ARC. Previous builds are available in https://svn.karlkraft.com/mysql_connector/versions

Most updates will require no changes. Things will just work better.

MysqlConnection supports an idle loop that sends a periodic request to the MySQL server to keep the connection alive. However this wasn’t protected in multi threaded programs and could crash.

MysqlFetch was creating the name of the field on each row iteration. On large selects this resulted in a large amount of duplicated memory being allocated.

MysqlFetch now supports the DECIMAL type.

MysqlFetch now deals with negative LONG and LONGLONG values. Corrected the size of these types on 64 bit compiles to match the MySQL definition. Also fixed the use of TINY, FLOAT and DOUBLE. Thanks to Bill Allen for contributing this code.

Added support for connecting to multiple servers in a failover pattern. Connection are now created with a MysqlServer instance or array of the same. This will require a code change, and you will need to add MysqlServer to your project.

Fixed some debug messages. Two of them had bad formatting, and one was still using NSLog.

Added a method to check status of autocommit.

Add ability to ignore mysql error when a record is inserted that matches a previously inserted records unique value for 1 or more columns. I have to admit that I ended up not using this code, so it is of dubious value.

The length of data passed to mysql_stmt_prepare needs to be expressed in byte length, not character length. Thanks to Coupez Julien for pointing this out.

Download Objc_Mysql_iPhone_OSX_1.0.zip (7.3 MB), while you read the rest.

Support for iOS

I had been hoping that with the announcement of new devices and versions of iOS, that Apple might add garbage collection to the iOS platform, but this appears to not be happening.  So the time was right to bite the bullet and clean this up so it worked on iOS.

Before you jump with both feet into using MySQL on iOS, let me point out a few reasons you may not want to use this as a solution.

If you are planning on submitting an application with this library to the AppStore, there is no guarantee that it will be accepted by Apple.  While I use this library on a daily basis for my code, I don’t have any plans to submit anything to the Apple Store using this library, for the reasons I will outline shortly.  So an AppStore submission that uses this library will be on the bleeding edge.

While MySQL is popular, it is not designed to be a forward facing internet accessible application.  All of my MySQL deployments are hidden behind firewalls with limited access.    If you use this to allow people to access a public MySQL database, you are asking for trouble, both in terms of load handling and security.  Keep in mind that AppStore apps are not encrypted, only signed.  So extracting the username, password and host from your binary is a trivial exercise.

You may find this useful however for in house iOS applications, which is where I am using it.

Features, functionality and bug fixes

In adition to the major new feature of iOS support, this version has several bug fixes, plus some added functionality.

This version features 6 architectures in a single static library.  The architectures are  armv6 and armv7 for iOS, and ppc, ppc64, i386, and x86_64 for desktop OSX.  While this increases the download size, only the architectures matching your target will be included in your final product.  So if you are building for iPhone 4 only, then only armv7 will be included.  If you are building for Snow Leopard on 64 bit, then only x86_64 will be included.

The iPhone versions should work on 3.0 all the way up to 4.1.

Since the iPhone does not have garbage collection, I had to #ifdef some code to get it working correctly there.  While it has not been tested extensively, the most common cases have been tested with Instruments, and there are no leaks.

Since the most common case for non garbage collected environments is the iPhone, the default size for blobs is is 10K on those platforms and 1M in garbage collected environments.  Blobs under those sizes are grabbed in a single pass, blobs larger than that take a second pass, which is slower, but transparently done after the initial fetch.  Of course, since source is included, you can change that if you have special needs.

MysqlFetchField will now identify which fields are part of the primary key.

Even though the classes were garbage collected, the underlying MySQL ANSI-C connector was not, and there were some bugs related to memory allocation that have been cleaned up.

MysqlConnection now supports strict mode.  In strict mode, if you insert data that is too long for a field it will throw an exception instead of being silently truncated.

While this code is in day to day use in dozens of projects, it by no means is bug free.  Caveat emptor.  In particular, since iOS does not support NSCalendarDate I needed to move to NSDateComponents.  As a result, when invalid dates like ’0000-00-00 00:00:00′ are fetched, they will be munged into something else. (although it appears consistent)

Update: A newer post has a version of this library that works on the iPhone as well.

Over the past 2 years I’ve worked on a small bit of glue to make selects, updates, inserts and deletes work easily from Objective-C.  This includes support for converting MySQL types to Cocoa types, working correctly with garbage collection, and support for reading and writing large blobs.

It is possible to do all these things with the generic MySQL C connector, and if your needs are simple that can be a quick way to access a MySQL databases, since all C libraries can easily be called from Objective-C.  However, once you start dealing with more advanced topics, the C connector can become burdensome.

If you are working on intel platforms only, you should grab the intel only version.  This supports both 32 and 64 bit intel platforms, using version 6.0.2 of the MySQL C Connector.

ObjC_mysql_intel.zip 5.5 MB – 32/64 bit

I still have some client programs running on PPC boxes, but MySQL has dropped support for PPC based OSX in the most recent versions of the mysql_connector.  So I have an older version that I occasionally update, although not as often as the intel only version.  This version uses an older version (5.0.51a) of the MySQL C connector, and supports both 32 bit PPC and Intel platforms.

ObjC_mysql_ppc.zip 2.3 MB – 32 bit intel and PPC.

Both versions use an identical syntax and are for the most part interchangeable.

Both require that garbage collection be enabled in your application.  This means this version won’t support versions of iPhone OS that don’t include garbage collection. Which is pretty much all of them, as of the writing of this post.

Both include the headers and a static library for the MySQL C connector.

While I have used these libraries to process well over half a billion rows of MySQL data, they are not by any means guaranteed to be free of bugs.  The most recent fix was a leak in MysqlUpdate.  If you are interested in getting updates, subscribe to the MySQL Category Feed, or email me for access to the subversion repository for the project.

Adding to Your Project

Once you have extracted the zip, add everything inside to your project.  The static mysql library will be linked into your application, and the headers and all the necessary bits to compile should just fall into place.

Forming the connection

You connect by creating an instance of MysqlConnection.  The best method for starting is

+ (MysqlConnection *)connectToHost:(NSString *)host
                              user:(NSString *)user
                          password:(NSString *)password
                            schema:(NSString *)schema
                             flags:(unsigned long)flags;

The best option for flags is MYSQL_DEFAULT_CONNECTION_FLAGS

If you are connecting to a MySQL server that will kick you if inactive, call the method

-[MysqlConnection startIdle]

to start a low impact periodic select that will run once every 60 seconds. Four additional methods add support for transactions

Performing Selects

Selects are pretty straight forward. Use MysqlFetch, and pass a SQL select command. You can then look at the results property to get an array of dictionaries. Each dictionary represents a single row. They key will be the name of each column, and the value will be the Objective-C type that matches the column. If you aren’t sure of the names of the fields, you can look at the fields an fieldNames properties for more details.

Example:
MysqlConnection *connection = [MysqlConnection connectToHost:@"serverName"
                                                        user:@"aUserName"
                                                    password:@"aPassword"
                                                      schema:@"myForumName"
                                                       flags:MYSQL_DEFAULT_CONNECTION_FLAGS];
MysqlFetch *userFetch = [MysqlFetch fetchWithCommand:@"select U_Number,U_Username from w3t_Users"
                                        onConnection:connection];
QLog(@"There are %d members",[userFetch.results count]);
for (NSDictionary *userRow in userFetch.results) {
  NSNumber *userNumber = [userRow objectForKey:@"U_Number"];
  NSString *userName = [userRow objectForKey:U_Username"];
  NSLog("%@ %@",userNumber,userName);
}

Performing Deletes

Deletes, inserts, and updates are very similar. To perform a delete:

MysqlDelete *deleteCommand = [MysqlDelete deleteWithConnection:connection];
delete.tableName=@"w3t_Users";
delete.qualifier=[NSDictionary dictionaryWithObject:@"3" andKey:@"U_Number"];
[deleteCommand execute];

You can then look at the affectedRows property to find out how many rows were deleted.

Performing Inserts

Inserts allow you to insert NSString, NSNumber, NSData, and NSNull. All other classes are converted using their -description method. The insert code uses bindings instead of composing a SQL string, so you don’t need to worry about escaping special characters, or filtering user input.

MysqlInsert *insertCommand = [MysqlInsert insertWithConnection:connection];
insertCommand.table =@"w3t_Users";
NSData *picture = [NSData dataWithContentsOfFile:@"sample.png"];
NSString *password=@";'!#";
insertCommand.rowData=[NSDictionary dictionaryWithObjectsAndKeys:@"Karl Kraft",@"U_Username",
                                                          picture,@"U_UserImage"
                                                          password,@"UserPassword"
                                                          nil];
[insertCommand execute];

After the insert, you can get the auto increment rowid by using the rowid property on your MysqlInsert instance.

Performing Updates

Once you have mastered delete and insert, updates are a simple cross of the two. Specify a qualifier, like you would for deletion, but rowData like you would use for an insert. Only the specified fields in the rowData are modified. Again you can pass NSString, NSNumber, NSData, and NSNull, and the values are inserted using bindings so that you don’t need to provide odd escapes.

MysqlUpdate *updateCommand = [MysqlInsert insertWithConnection:connection];
updateCommand.table =@"w3t_Users";
updateCommand.qualifier=[NSDictionary dictionaryWithObject:@"3" andKey:@"U_Number"];
NSData *picture = [NSData dataWithContentsOfFile:@"sample.png"];
NSString *password=@";'!#";
updateCommand.rowData=[NSDictionary dictionaryWithObjectsAndKeys:@"Karl Kraft",@"U_Username",
                                                          picture,@"U_UserImage"
                                                          password,@"UserPassword"
                                                          nil];
[updateCommand execute];

Like delete you can query the affectedRows property to find out how many records were updated.

Catching exceptions

Any exceptions while performing the mysql commands are thrown as MysqlException or a subclass of MysqlException. Common reasons for exceptions being throw are:

• Unable to connect to the database, or wrong username / password
• Commit or rollback fails
• Unsupported field type in a MysqlFetch
• Unqualified delete or update commands
• Any underlying mysql error

MYSQL_LOGGING

As a final useful trick you can define MYSQL_LOGGING in the CFLAGS of your project, or in a common header file, and useful debugging information will be generated.