FMDatabaseQueue Class Reference

Inherits from NSObject
Declared in FMDatabaseQueue.h

Overview

To perform queries and updates on multiple threads, you’ll want to use FMDatabaseQueue.

Using a single instance of FMDatabase from multiple threads at once is a bad idea. It has always been OK to make a FMDatabase object per thread. Just don’t share a single instance across threads, and definitely not across multiple threads at the same time.

Instead, use FMDatabaseQueue. Here’s how to use it:

First, make your queue.

FMDatabaseQueue *queue = [FMDatabaseQueue databaseQueueWithPath:aPath];

Then use it like so:

[queue inDatabase:^(FMDatabase *db) {
    [db executeUpdate:@"INSERT INTO myTable VALUES (?)", [NSNumber numberWithInt:1]];
    [db executeUpdate:@"INSERT INTO myTable VALUES (?)", [NSNumber numberWithInt:2]];
    [db executeUpdate:@"INSERT INTO myTable VALUES (?)", [NSNumber numberWithInt:3]];

    FMResultSet *rs = [db executeQuery:@"select * from foo"];
    while ([rs next]) {
        //…
    }
}];

An easy way to wrap things up in a transaction can be done like this:

[queue inTransaction:^(FMDatabase *db, BOOL *rollback) {
    [db executeUpdate:@"INSERT INTO myTable VALUES (?)", [NSNumber numberWithInt:1]];
    [db executeUpdate:@"INSERT INTO myTable VALUES (?)", [NSNumber numberWithInt:2]];
    [db executeUpdate:@"INSERT INTO myTable VALUES (?)", [NSNumber numberWithInt:3]];

    if (whoopsSomethingWrongHappened) {
        *rollback = YES;
        return;
    }
    // etc…
    [db executeUpdate:@"INSERT INTO myTable VALUES (?)", [NSNumber numberWithInt:4]];
}];

FMDatabaseQueue will run the blocks on a serialized queue (hence the name of the class). So if you call FMDatabaseQueue’s methods from multiple threads at the same time, they will be executed in the order they are received. This way queries and updates won’t step on each other’s toes, and every one is happy.

See also

Warning: Do not instantiate a single FMDatabase object and use it across multiple threads. Use FMDatabaseQueue instead.

Warning: The calls to FMDatabaseQueue’s methods are blocking. So even though you are passing along blocks, they will not be run on another thread.

Other Methods

  path

Path of database

@property (atomic, retain) NSString *path

Discussion

Path of database

Declared In

FMDatabaseQueue.h

  openFlags

Open flags

@property (atomic, readonly) int openFlags

Discussion

Open flags

Declared In

FMDatabaseQueue.h

Initialization, opening, and closing of queue

+ databaseQueueWithPath:

Create queue using path.

+ (instancetype)databaseQueueWithPath:(NSString *)aPath

Parameters

aPath

The file path of the database.

Return Value

The FMDatabaseQueue object. nil on error.

Discussion

Create queue using path.

Declared In

FMDatabaseQueue.h

+ databaseQueueWithPath:flags:

Create queue using path and specified flags.

+ (instancetype)databaseQueueWithPath:(NSString *)aPath flags:(int)openFlags

Parameters

aPath

The file path of the database.

openFlags

Flags passed to the openWithFlags method of the database

Return Value

The FMDatabaseQueue object. nil on error.

Discussion

Create queue using path and specified flags.

Declared In

FMDatabaseQueue.h

– initWithPath:

Create queue using path.

- (instancetype)initWithPath:(NSString *)aPath

Parameters

aPath

The file path of the database.

Return Value

The FMDatabaseQueue object. nil on error.

Discussion

Create queue using path.

Declared In

FMDatabaseQueue.h

– initWithPath:flags:

Create queue using path and specified flags.

- (instancetype)initWithPath:(NSString *)aPath flags:(int)openFlags

Parameters

aPath

The file path of the database.

openFlags

Flags passed to the openWithFlags method of the database

Return Value

The FMDatabaseQueue object. nil on error.

Discussion

Create queue using path and specified flags.

Declared In

FMDatabaseQueue.h

– initWithPath:flags:vfs:

Create queue using path and specified flags.

- (instancetype)initWithPath:(NSString *)aPath flags:(int)openFlags vfs:(NSString *)vfsName

Parameters

aPath

The file path of the database.

openFlags

Flags passed to the openWithFlags method of the database

vfsName

The name of a custom virtual file system

Return Value

The FMDatabaseQueue object. nil on error.

Discussion

Create queue using path and specified flags.

Declared In

FMDatabaseQueue.h

+ databaseClass

Returns the Class of ‘FMDatabase’ subclass, that will be used to instantiate database object.

+ (Class)databaseClass

Return Value

The Class of ‘FMDatabase’ subclass, that will be used to instantiate database object.

Discussion

Returns the Class of ‘FMDatabase’ subclass, that will be used to instantiate database object.

Subclasses can override this method to return specified Class of ‘FMDatabase’ subclass.

Declared In

FMDatabaseQueue.h

– close

Close database used by queue.

- (void)close

Discussion

Close database used by queue.

Declared In

FMDatabaseQueue.h

Dispatching database operations to queue

– inDatabase:

Synchronously perform database operations on queue.

- (void)inDatabase:(void ( ^ ) ( FMDatabase *db ))block

Parameters

block

The code to be run on the queue of FMDatabaseQueue

Discussion

Synchronously perform database operations on queue.

Declared In

FMDatabaseQueue.h

– inTransaction:

Synchronously perform database operations on queue, using transactions.

- (void)inTransaction:(void ( ^ ) ( FMDatabase *db , BOOL *rollback ))block

Parameters

block

The code to be run on the queue of FMDatabaseQueue

Discussion

Synchronously perform database operations on queue, using transactions.

Declared In

FMDatabaseQueue.h

– inDeferredTransaction:

Synchronously perform database operations on queue, using deferred transactions.

- (void)inDeferredTransaction:(void ( ^ ) ( FMDatabase *db , BOOL *rollback ))block

Parameters

block

The code to be run on the queue of FMDatabaseQueue

Discussion

Synchronously perform database operations on queue, using deferred transactions.

Declared In

FMDatabaseQueue.h

– inSavePoint:

Synchronously perform database operations using save point.

- (NSError *)inSavePoint:(void ( ^ ) ( FMDatabase *db , BOOL *rollback ))block

Parameters

block

The code to be run on the queue of FMDatabaseQueue

Discussion

Synchronously perform database operations using save point.

Declared In

FMDatabaseQueue.h