FMDatabasePool

@interface FMDatabasePool : NSObject

Pool of FMDatabase objects.

See also

Warning

Before using FMDatabasePool , please consider using FMDatabaseQueue instead.

If you really really really know what you’re doing and FMDatabasePool is what you really really need (ie, you’re using a read only database), OK you can use it. But just be careful not to deadlock!

For an example on deadlocking, search for: ONLY_USE_THE_POOL_IF_YOU_ARE_DOING_READS_OTHERWISE_YOULL_DEADLOCK_USE_FMDATABASEQUEUE_INSTEAD in the main.m file.

  • Database path

    Declaration

    Objective-C

    @property (copy, nullable) NSString *path;

    Swift

    var path: String? { get set }

  • Delegate object

    Declaration

    Objective-C

    @property (nullable) id delegate;

    Swift

    unowned(unsafe) var delegate: AnyObject? { get set }

  • Maximum number of databases to create

    Declaration

    Objective-C

    @property NSUInteger maximumNumberOfDatabasesToCreate;

    Swift

    var maximumNumberOfDatabasesToCreate: UInt { get set }

  • Open flags

    Declaration

    Objective-C

    @property (readonly) int openFlags;

    Swift

    var openFlags: Int32 { get }

  • Custom virtual file system name

    Declaration

    Objective-C

    @property (copy, nullable) NSString *vfsName;

    Swift

    var vfsName: String? { get set }

Initialization

  • Create pool using path.

    Declaration

    Objective-C

    + (nonnull instancetype)databasePoolWithPath:(NSString *_Nullable)aPath;

    Parameters

    aPath

    The file path of the database.

    Return Value

    The FMDatabasePool object. nil on error.

  • Create pool using file URL.

    Declaration

    Objective-C

    + (nonnull instancetype)databasePoolWithURL:(NSURL *_Nullable)url;

    Parameters

    url

    The file NSURL of the database.

    Return Value

    The FMDatabasePool object. nil on error.

  • Create pool using path and specified flags

    Declaration

    Objective-C

    + (nonnull instancetype)databasePoolWithPath:(NSString *_Nullable)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 FMDatabasePool object. nil on error.

  • Create pool using file URL and specified flags

    Declaration

    Objective-C

    + (nonnull instancetype)databasePoolWithURL:(NSURL *_Nullable)url
                                      flags:(int)openFlags;

    Parameters

    url

    The file NSURL of the database.
    openFlags

    Flags passed to the openWithFlags method of the database.

    Return Value

    The FMDatabasePool object. nil on error.

  • Create pool using path.

    Declaration

    Objective-C

    - (nonnull instancetype)initWithPath:(NSString *_Nullable)aPath;

    Swift

    init(path aPath: String?)

    Parameters

    aPath

    The file path of the database.

    Return Value

    The FMDatabasePool object. nil on error.

  • Create pool using file URL.

    Declaration

    Objective-C

    - (nonnull instancetype)initWithURL:(NSURL *_Nullable)url;

    Swift

    init(url: URL?)

    Parameters

    url

    The file `NSURL of the database.

    Return Value

    The FMDatabasePool object. nil on error.

  • Create pool using path and specified flags.

    Declaration

    Objective-C

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

    Swift

    init(path aPath: String?, flags openFlags: Int32)

    Parameters

    aPath

    The file path of the database.
    openFlags

    Flags passed to the openWithFlags method of the database

    Return Value

    The FMDatabasePool object. nil on error.

  • Create pool using file URL and specified flags.

    Declaration

    Objective-C

    - (nonnull instancetype)initWithURL:(NSURL *_Nullable)url flags:(int)openFlags;

    Swift

    init(url: URL?, flags openFlags: Int32)

    Parameters

    url

    The file NSURL of the database.
    openFlags

    Flags passed to the openWithFlags method of the database

    Return Value

    The FMDatabasePool object. nil on error.

  • Create pool using path and specified flags.

    Declaration

    Objective-C

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

    Swift

    init(path aPath: String?, flags openFlags: Int32, vfs vfsName: String?)

    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 FMDatabasePool object. nil on error.

  • Create pool using file URL and specified flags.

    Declaration

    Objective-C

    - (nonnull instancetype)initWithURL:(NSURL *_Nullable)url
                              flags:(int)openFlags
                                vfs:(NSString *_Nullable)vfsName;

    Swift

    init(url: URL?, flags openFlags: Int32, vfs vfsName: String?)

    Parameters

    url

    The file NSURL 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 FMDatabasePool object. nil on error.

  • 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.

    Declaration

    Objective-C

    + (nonnull Class)databaseClass;

    Swift

    class func databaseClass() -> AnyClass

    Return Value

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

Keeping track of checked in/out databases

  • Number of checked-in databases in pool

    Declaration

    Objective-C

    @property (nonatomic, readonly) NSUInteger countOfCheckedInDatabases;

    Swift

    var countOfCheckedInDatabases: UInt { get }

  • Number of checked-out databases in pool

    Declaration

    Objective-C

    @property (nonatomic, readonly) NSUInteger countOfCheckedOutDatabases;

    Swift

    var countOfCheckedOutDatabases: UInt { get }

  • Total number of databases in pool

    Declaration

    Objective-C

    @property (nonatomic, readonly) NSUInteger countOfOpenDatabases;

    Swift

    var countOfOpenDatabases: UInt { get }

  • Release all databases in pool

    Declaration

    Objective-C

    - (void)releaseAllDatabases;

    Swift

    func releaseAllDatabases()

Perform database operations in pool

  • Synchronously perform database operations in pool.

    Declaration

    Objective-C

    - (void)inDatabase:(nonnull void (^)(FMDatabase *_Nonnull))block;

    Swift

    func inDatabase(_ block: (FMDatabase) -> Void)

    Parameters

    block

    The code to be run on the FMDatabasePool pool.

  • Synchronously perform database operations in pool using transaction.

    Warning

    Unlike SQLite’s BEGIN TRANSACTION, this method currently performs an exclusive transaction, not a deferred transaction. This behavior is likely to change in future versions of FMDB, whereby this method will likely eventually adopt standard SQLite behavior and perform deferred transactions. If you really need exclusive tranaction, it is recommended that you use inExclusiveTransaction, instead, not only to make your intent explicit, but also to future-proof your code.

    Declaration

    Objective-C

    - (void)inTransaction:(nonnull void (^)(FMDatabase *_Nonnull,
                                        BOOL *_Nonnull))block;

    Swift

    func inTransaction(_ block: (FMDatabase, UnsafeMutablePointer<ObjCBool>) -> Void)

    Parameters

    block

    The code to be run on the FMDatabasePool pool.

  • Synchronously perform database operations in pool using exclusive transaction.

    Declaration

    Objective-C

    - (void)inExclusiveTransaction:(nonnull void (^)(FMDatabase *_Nonnull,
                                                 BOOL *_Nonnull))block;

    Swift

    func inExclusiveTransaction(_ block: (FMDatabase, UnsafeMutablePointer<ObjCBool>) -> Void)

    Parameters

    block

    The code to be run on the FMDatabasePool pool.

  • Synchronously perform database operations in pool using deferred transaction.

    Declaration

    Objective-C

    - (void)inDeferredTransaction:(nonnull void (^)(FMDatabase *_Nonnull,
                                                BOOL *_Nonnull))block;

    Swift

    func inDeferredTransaction(_ block: (FMDatabase, UnsafeMutablePointer<ObjCBool>) -> Void)

    Parameters

    block

    The code to be run on the FMDatabasePool pool.

  • Synchronously perform database operations on queue, using immediate transactions.

    Declaration

    Objective-C

    - (void)inImmediateTransaction:(nonnull void (^)(FMDatabase *_Nonnull,
                                                 BOOL *_Nonnull))block;

    Swift

    func inImmediateTransaction(_ block: (FMDatabase, UnsafeMutablePointer<ObjCBool>) -> Void)

    Parameters

    block

    The code to be run on the queue of FMDatabaseQueue

  • Synchronously perform database operations in pool using save point.

    Warning

    You can not nest these, since calling it will pull another database out of the pool and you’ll get a deadlock. If you need to nest, use startSavePointWithName:error: instead.

    Declaration

    Objective-C

    - (NSError *_Nullable)inSavePoint:(nonnull void (^)(FMDatabase *_Nonnull,
                                                    BOOL *_Nonnull))block;

    Swift

    func inSavePoint(_ block: (FMDatabase, UnsafeMutablePointer<ObjCBool>) -> Void) -> Error?

    Parameters

    block

    The code to be run on the FMDatabasePool pool.

    Return Value

    NSError object if error; nil if successful.