YapDatabase

The default database file URL.

• macOS : ~/Library/Application Support/{Bundle Identifier}/yapdb.sqlite
• iOS : {App Sandbox}/Application Support/yapdb.sqlite

The default serializer & deserializer use NSCoding (NSKeyedArchiver & NSKeyedUnarchiver). This is suitable for Objective-C, but not for Swift.

For Swift: It’s likely you’ll prefer to use the Codable protocol. To do so, you simply register your Codable class for the corresponding collection:

 database.registerCodableSerialization(String.self, forCollection: "foo")
 database.registerCodableSerialization(MyCodableClass.self, forCollection: "bar")

For Objective-C: Any objects that support the NSCoding protocol can be used. Most of Apple’s primary data types support NSCoding out of the box. And it’s easy to add NSCoding support to your own custom objects.

The default serializer & deserializer use NSCoding (NSKeyedArchiver & NSKeyedUnarchiver). This is suitable for Objective-C, but not for Swift.

For Swift: It’s likely you’ll prefer to use the Codable protocol. To do so, you simply register your Codable class for the corresponding collection:

 database.registerCodableSerialization(String.self, forCollection: "foo")
 database.registerCodableSerialization(MyCodableClass.self, forCollection: "bar")

For Objective-C: Any objects that support the NSCoding protocol can be used. Most of Apple’s primary data types support NSCoding out of the box. And it’s easy to add NSCoding support to your own custom objects.

Objective-C only:

Property lists ONLY support the following types:

• NSData
• NSString
• NSArray
• NSDictionary
• NSDate
• NSNumber

Although limited in functionality, property lists are highly optimized and are used extensively by Apple.

Property lists may make a good fit when your existing code already uses them, such as replacing NSUserDefaults with a database.

For Swift: - see: -[YapDatabase registerSerializer:forCollection:]

Objective-C only:

Property lists ONLY support the following types:

• NSData
• NSString
• NSArray
• NSDictionary
• NSDate
• NSNumber

Although limited in functionality, property lists are highly optimized and are used extensively by Apple.

Property lists may make a good fit when your existing code already uses them, such as replacing NSUserDefaults with a database.

For Swift: - see: -[YapDatabase registerDeserializer:forCollection:]

Objective-C only:

A FASTER serializer & deserializer than the default, if serializing ONLY a NSDate object. You may want to use timestampSerializer & timestampDeserializer if your metadata is simply an NSDate.

For Swift: - see: -[YapDatabase registerSerializer:forCollection:]

Objective-C only:

A FASTER serializer & deserializer than the default, if serializing ONLY a NSDate object. You may want to use timestampSerializer & timestampDeserializer if your metadata is simply an NSDate.

For Swift: - see: -[YapDatabase registerDeserializer:forCollection:]

Allows you to configure a handler for log messages emitted from the framework.

A custom log handler allows you to integrate framework-emitted log messages into your desired logging system.

If you don’t configure your own log handler, then a default handler is used, which:

• only logs errors & warnings
• uses os_log

Opens or creates a sqlite database with the default file URL.

Opens or creates a sqlite database with the given file URL. The defaults options are used.

Swift example:

 let documenstDir = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask)[0]
 let databaseURL = baseDir.appendingPathComponent("yapdb.sqlite")
 let database = YapDatabase(url: databaseURL)

Opens or creates a sqlite database with the given URL and options.

This is typically used to configure encryption options for the databse.

Returns that location of the database file.

Keep in mind that sqlite actually creates 3 different files on disk:

• databaseName
• databaseName-wal
• databaseName-shm

Returns that location of the database file.

Keep in mind that sqlite actually creates 3 different files on disk:

• databaseName
• databaseName-wal
• databaseName-shm

Returns that location of the database file.

Keep in mind that sqlite actually creates 3 different files on disk:

• databaseName
• databaseName-wal
• databaseName-shm

The options that were specified when the database was created.

The snapshot number is the internal synchronization state primitive for the database.

It’s generally only useful for database internals, but it can sometimes come in handy for general debugging of your app.

The snapshot is a simple 64-bit number that gets incremented upon every read-write transaction that makes modifications to the database. Thanks to the concurrent architecture of YapDatabase, there may be multiple concurrent connections that are inspecting the database at similar times, yet they are looking at slightly different snapshots of the database.

The snapshot number may thus be inspected to determine (in a general fashion) what state the connection is in compared with other connections.

• YapDatabase.snapshot => most up-to-date snapshot among all connections
• YapDatabaseConnection.snapshot => snapshot of individual connection

Example:

 let database = YapDatabase(url: url)
 let _ = database.snapshot // returns zero

 let connection1 = database.newConnection()
 let connection2 = database.newConnection()

 let _ = connection1.snapshot // returns zero
 let _ = connection2.snapshot // returns zero

 connection1.readWrite {(transaction) in
    transaction.setObject(objectA, forKey:keyA, inCollection:nil)
 }

 let _ = database.snapshot;    // returns 1
 let _ = connection1.snapshot; // returns 1
 let _ = connection2.snapshot; // returns 1

 connection1.asyncReadWrite({ (transaction) in
    transaction.setObject(objectB, forKey:keyB, inCollection:nil)
    Thread.sleep(forTimeInterval: 1.0) // sleep for 1 second

    let _ = connection1.snapshot // returns 1 (we know it will turn into 2 once the transaction completes)

 }, completionBlock: {

     connection1.snapshot; // returns 2
 })

 connection2.asyncRead {(transaction) in
    Thread.sleep(forTimeInterval: 5.0) // sleep for 5 seconds

    let _ = connection2.snapshot // returns 1. Understand why? See below.
 }

It’s because when connection2 started its transaction, the database was in snapshot 1. (Both connection1 & connection2 started an ASYNC transaction at the same time.) Thus, for the duration of its transaction, the database remains in that state for connection2.

However, once connection2 completes its transaction, it will automatically update itself to snapshot 2.

In general, the snapshot is primarily for internal use. However, it may come in handy for some tricky edge-case bugs. (i.e. why doesn’t my connection see that other commit ?)

Returns the version of sqlite being used.

E.g.: SELECT sqlite_version();

Allows you to configure the default values for new connections.

When you create a connection via [YapDatabase newConnection], that new connection will inherit its initial configuration via these connectionDefaults. Of course, the connection may then override these default configuration values, and configure itself as needed.

Changing the connectionDefault values only affects future connections that will be created. It does not affect connections that have already been created.

Registers a default serializer (object => data), which will be used in cases where another serializer isn’t configured for the collection.

Registers a default deserializer (data => object), which will be used in cases where another deserializer isn’t configured for the collection.

Registers a default PreSanitizer, which will be used in cases where another PreSanitizer isn’t configured for the collection.

Registeres a default PostSanitizer, which will be used in cases where another PostSanitizer isn’t configured for the collection.

Registers a serializer (object => data) to be used for all objects & metadata in the given collection.

Registers a deserializer (data => object) to be used for all objects & metadata in the given collection.

Registers a PreSanitizer to be used for all objects & metadata in the given collection.

Registers a PostSanitizer to be used for all objects & metadata in the given collection.

Registers a configuration group (for both objects & metadata) for an array of collections.

This is equivalent to looping over the array, and invoking each individual registration method. (But faster.)

Registers a serializer (object => data) to be used for all objects in the given collection.

@note: Passing nil for the collection is the equivalent of passing the empty string.

Registers a deserializer (data => object) to be used for all objects in the given collection.

@note: Passing nil for the collection is the equivalent of passing the empty string.

Registers a PreSanitizer to be used for all objects in the given collection.

Registers a PostSanitizer to be used for all objects in the given collection.s

Registers a serializer (object => data) to be used for all metadata in the given collection.

Registers a deserializer (data => object) to be used for all metadata in the given collection.

Registers a PreSanitizer to be used for all metadata in the given collection.

Registers a PostSanitizer to be used for all metadata in the given collection.

Allows you to opt-in to various performance improvements, which is generally dependent on the object types you’re storing in each collection.

The Object-Policy is documented on the wiki here: https://github.com/yapstudios/YapDatabase/wiki/Object-Policy

Allows you to opt-in to various performance improvements, which is generally dependent on the object types you’re storing in each collection.

The Object-Policy is documented on the wiki here: https://github.com/yapstudios/YapDatabase/wiki/Object-Policy

Creates and returns a new connection to the database. It is through this connection that you will access the database.

You can create multiple connections to the database. Each invocation of this method creates and returns a new connection.

Multiple connections can simultaneously read from the database. Multiple connections can simultaneously read from the database while another connection is modifying the database. For example, the main thread could be reading from the database via connection A, while a background thread is writing to the database via connection B.

However, only a single connection may be writing to the database at any one time.

A connection is thread-safe, and operates by serializing access to itself. Thus you can share a single connection between multiple threads. But for conncurrent access between multiple threads you must use multiple connections.

You should avoid creating more connections than you need. Creating a new connection everytime you need to access the database is a recipe for foolishness.

Creates and returns a new connection to the database. It is through this connection that you will access the database.

You can create multiple connections to the database. Each invocation of this method creates and returns a new connection.

Multiple connections can simultaneously read from the database. Multiple connections can simultaneously read from the database while another connection is modifying the database. For example, the main thread could be reading from the database via connection A, while a background thread is writing to the database via connection B.

However, only a single connection may be writing to the database at any one time.

A connection is thread-safe, and operates by serializing access to itself. Thus you can share a single connection between multiple threads. But for conncurrent access between multiple threads you must use multiple connections.

You should avoid creating more connections than you need. Creating a new connection everytime you need to access the database is a recipe for foolishness.

Registers the extension with the database using the given name. After registration everything works automatically using just the extension name.

The registration process is equivalent to a (synchronous) readwrite transaction. It involves persisting various information about the extension to the database, as well as possibly populating the extension by enumerating existing rows in the database.

@return YES if the extension was properly registered. NO if an error occurred, such as the extensionName is already registered.

Registers the extension with the database using the given name. After registration everything works automatically using just the extension name.

The registration process is equivalent to a (synchronous) readwrite transaction. It involves persisting various information about the extension to the database, as well as possibly populating the extension by enumerating existing rows in the database.

Asynchronoulsy starts the extension registration process. After registration everything works automatically using just the extension name.

The registration process is equivalent to an asyncReadwrite transaction. It involves persisting various information about the extension to the database, as well as possibly populating the extension by enumerating existing rows in the database.

Asynchronoulsy starts the extension registration process. After registration everything works automatically using just the extension name.

The registration process is equivalent to an asyncReadwrite transaction. It involves persisting various information about the extension to the database, as well as possibly populating the extension by enumerating existing rows in the database.

Asynchronoulsy starts the extension registration process. After registration everything works automatically using just the extension name.

The registration process is equivalent to an asyncReadwrite transaction. It involves persisting various information about the extension to the database, as well as possibly populating the extension by enumerating existing rows in the database.

Asynchronoulsy starts the extension registration process. After registration everything works automatically using just the extension name.

The registration process is equivalent to an asyncReadwrite transaction. It involves persisting various information about the extension to the database, as well as possibly populating the extension by enumerating existing rows in the database.

This method unregisters an extension with the given name. The associated underlying tables will be dropped from the database.

The unregistration process is equivalent to a (synchronous) readwrite transaction. It involves deleting various information about the extension from the database, as well as possibly dropping related tables the extension may have been using.

Note 1: You don’t need to re-register an extension in order to unregister it. For example, you’ve previously registered an extension (in previous app launches), but you no longer need the extension. You don’t have to bother creating and registering the unneeded extension, just so you can unregister it and have the associated tables dropped. The database persists information about registered extensions, including the associated class of an extension. So you can simply pass the name of the extension, and the database system will use the associated class to drop the appropriate tables.

Note 2: In fact, you don’t even have to worry about unregistering extensions that you no longer need. That database system will automatically handle it for you. That is, upon completion of the first readWrite transaction (that makes changes), the database system will check to see if there are any orphaned extensions. That is, previously registered extensions that are no longer in use (and are now out-of-date because they didn’t process the recent change(s) to the db). And it will automatically unregister these orhpaned extensions for you.

Asynchronoulsy starts the extension unregistration process.

The unregistration process is equivalent to an asyncReadwrite transaction. It involves deleting various information about the extension from the database, as well as possibly dropping related tables the extension may have been using.

Asynchronoulsy starts the extension unregistration process.

The unregistration process is equivalent to an asyncReadwrite transaction. It involves deleting various information about the extension from the database, as well as possibly dropping related tables the extension may have been using.

Returns the registered extension with the given name. The returned object will be a subclass of YapDatabaseExtension.

Returns all currently registered extensions as a dictionary. The key is the registed name (NSString), and the value is the extension (YapDatabaseExtension subclass).

Allows you to fetch the registered extension names from the last time the database was run. Typically this means from the last time the app was run.

This may be used to assist in various tasks, such as cleanup or upgrade tasks.

If you need this information, you should fetch it early on because YapDatabase only maintains this information until it sees you are done registering all your initial extensions. That is, after one initializes the database they then immediately register any needed initial extensions before they begin to use the database. Once a readWriteTransaction modifies the database, YapDatabase will take this opportunity to look for orphaned extensions. These are extensions that were registered at the end of the last database session, but which are no longer registered. YapDatabase will automatically cleanup these orphaned extensions, and also clear the previouslyRegisteredExtensionNames information at this point.

It’s sometimes useful to find out when all async registerExtension/unregisterExtension requests have completed.

One way to accomplish this is simply to queue an asyncReadWriteTransaction on any databaseConnection. Since all async register/unregister extension requests are immediately dispatch_async’d through the internal serial writeQueue, you’ll know that once your asyncReadWriteTransaction is running, all previously scheduled register/unregister requests have completed.

Although the above technique works, the ‘flushExtensionRequestsWithCompletionQueue::’ is a more efficient way to accomplish this task. (And a more elegant & readable way too.)

As recommended in the Performance Primer ( https://github.com/yapstudios/YapDatabase/wiki/Performance-Primer )

You should consider connections to be relatively heavy weight objects.

OK, truth be told they’re not really that heavy weight. I’m just trying to scare you. Because in terms of performance, you get a lot of bang for your buck if you recycle your connections.

However, experience has shown how easy it is to neglect this information. Perhaps because it’s just so darn easy to create a connection that it becomes easy to forgot that connections aren’t free.

Whatever the reason, the connection pool was designed to alleviate some of the overhead. The most expensive component of a connection is the internal sqlite database connection. The connection pool keeps these internal sqlite database connections around in a pool to help recycle them.

So when a connection gets deallocated, it returns the sqlite database connection to the pool. And when a new connection gets created, it can recycle a sqlite database connection from the pool.

This property sets a maximum limit on the number of items that will get stored in the pool at any one time.

The default value is 5.

See also connectionPoolLifetime, which allows you to set a maximum lifetime of connections sitting around in the pool.

The connection pool can automatically drop stale connections. That is, if an item stays in the pool for too long (without another connection coming along and removing it from the pool to be recycled) then the connection can optionally be removed and dropped.

This is called the connection lifetime.

That is, after an item is added to the connection pool to be recycled, a timer will be started. If the connection is still in the pool when the timer goes off, then the connection will automatically be removed and dropped.

The default value is 90 seconds.

To disable the timer, set the lifetime to zero (or any non-positive value). When disabled, open connections will remain in the pool indefinitely.