YapDatabaseConnection

A database connection maintains a strong reference to its parent.

This is to enforce the following core architecture rule: A database instance cannot be deallocated if a corresponding connection is stil alive.

The optional name property assists in debugging. It is only used internally for log statements.

Each database connection maintains an independent cache of deserialized objects. This reduces disk IO and the overhead of the deserialization process. You can optionally configure the cache size, or disable it completely.

The cache is properly kept in sync with the atomic snapshot architecture of the database system.

You can configure the objectCache at any time, including within readBlocks or readWriteBlocks. To disable the object cache entirely, set objectCacheEnabled to NO. To use an inifinite cache size, set the objectCacheLimit to zero.

By default the objectCache is enabled and has a limit of 250.

New connections will inherit the default values set by the parent database via -[YapDatabase connectionDefaults]. Thus the default values for new connection instances are configurable.

Also see the wiki for a bit more info: https://github.com/yapstudios/YapDatabase/wiki/Cache

Each database connection maintains an independent cache of deserialized objects. This reduces disk IO and the overhead of the deserialization process. You can optionally configure the cache size, or disable it completely.

The cache is properly kept in sync with the atomic snapshot architecture of the database system.

You can configure the objectCache at any time, including within readBlocks or readWriteBlocks. To disable the object cache entirely, set objectCacheEnabled to NO. To use an inifinite cache size, set the objectCacheLimit to zero.

By default the objectCache is enabled and has a limit of 250.

New connections will inherit the default values set by the parent database via -[YapDatabase connectionDefaults]. Thus the default values for new connection instances are configurable.

Also see the wiki for a bit more info: https://github.com/yapstudios/YapDatabase/wiki/Cache

Each database connection maintains an independent cache of deserialized metadata. This reduces disk IO and the overhead of the deserialization process. You can optionally configure the cache size, or disable it completely.

The cache is properly kept in sync with the atomic snapshot architecture of the database system.

You can configure the metadataCache at any time, including within readBlocks or readWriteBlocks. To disable the metadata cache entirely, set metadataCacheEnabled to NO. To use an inifinite cache size, set the metadataCacheLimit to zero.

By default the metadataCache is enabled and has a limit of 250.

New connections will inherit the default values set by the parent database via -[YapDatabase connectionDefaults]. Thus the default values for new connection instances are configurable.

Also see the wiki for a bit more info: https://github.com/yapstudios/YapDatabase/wiki/Cache

Each database connection maintains an independent cache of deserialized metadata. This reduces disk IO and the overhead of the deserialization process. You can optionally configure the cache size, or disable it completely.

The cache is properly kept in sync with the atomic snapshot architecture of the database system.

You can configure the metadataCache at any time, including within readBlocks or readWriteBlocks. To disable the metadata cache entirely, set metadataCacheEnabled to NO. To use an inifinite cache size, set the metadataCacheLimit to zero.

By default the metadataCache is enabled and has a limit of 250.

New connections will inherit the default values set by the parent database via -[YapDatabase connectionDefaults]. Thus the default values for new connection instances are configurable.

Also see the wiki for a bit more info: https://github.com/yapstudios/YapDatabase/wiki/Cache

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

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 readwrite transaction that makes modifications to the database. Due 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.

You may also query YapDatabase.snapshot to determine the most up-to-date snapshot among all connections.

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 connection2 started its transaction when the database was in snapshot 1. Thus, for the duration of its transaction, the database remains in that state.

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 number of pending/active transactions for the connection. That is, the number of queued read-only & read-write transactions that are currently queued to be performed on this connection.

Note that if a transaction is currently in progress (active), it’s still considered pending since it hasn’t completed yet.

This is a generalized way to estimate the load on a connection, and can be used for load balancing, such as done by YapDatabaseConnectionPool.

Read-only access to the database.

The given block can run concurrently with sibling connections, regardless of whether the sibling connections are executing read-only or read-write transactions.

The only time this method ever blocks is if another thread is currently using this connection instance to execute a readBlock or readWriteBlock. Recall that you may create multiple connections for concurrent access.

This method is synchronous.

Read-write access to the database.

Only a single read-write block can execute among all sibling connections. Thus this method may block if another sibling connection is currently executing a read-write block.

Read-only access to the database.

The given block can run concurrently with sibling connections, regardless of whether the sibling connections are executing read-only or read-write transactions.

This method is asynchronous.

Read-only access to the database.

The given block can run concurrently with sibling connections, regardless of whether the sibling connections are executing read-only or read-write transactions.

This method is asynchronous.

An optional completion block may be used. The completionBlock will be invoked on the main thread (dispatch_get_main_queue()).

Read-only access to the database.

The given block can run concurrently with sibling connections, regardless of whether the sibling connections are executing read-only or read-write transactions.

This method is asynchronous.

An optional completion block may be used. Additionally the dispatch_queue to invoke the completion block may also be specified. If NULL, dispatch_get_main_queue() is automatically used.

Read-write access to the database.

Only a single read-write block can execute among all sibling connections. Thus this method may block if another sibling connection is currently executing a read-write block.

This method is asynchronous.

Read-write access to the database.

Only a single read-write block can execute among all sibling connections. Thus the execution of the block may be delayed if another sibling connection is currently executing a read-write block.

This method is asynchronous.

An optional completion block may be used. The completionBlock will be invoked on the main thread (dispatch_get_main_queue()).

Read-write access to the database.

Only a single read-write block can execute among all sibling connections. Thus the execution of the block may be delayed if another sibling connection is currently executing a read-write block.

This method is asynchronous.

An optional completion block may be used. Additionally the dispatch_queue to invoke the completion block may also be specified. If NULL, dispatch_get_main_queue() is automatically used.

It’s sometimes useful to find out when all previously queued transactions on a connection have completed. For example, you may have multiple methods (perhaps scattered across multiple classes) that may queue asyncReadWriteTransaction’s on a particular databaseConnection. And you’d like to know when all the queued readWriteTransactions have completed.

One way to accomplish this is simply to queue an asyncReadTransaction on the databaseConnection. Since all transactions on a databaseConnection are queued onto a serial dispatch queue, you’ll know that once your asyncReadTransaction is running, all previously scheduled transactions have completed.

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

Invoke this method to start a long-lived read-only transaction. This allows you to effectively create a stable state for the connection. This is most often used for connections that service the main thread for UI data.

For a complete discussion, please see the wiki page: https://github.com/yapstudios/YapDatabase/wiki/LongLivedReadTransactions

Invoke this method to start a long-lived read-only transaction. This allows you to effectively create a stable state for the connection. This is most often used for connections that service the main thread for UI data.

For a complete discussion, please see the wiki page: https://github.com/yapstudios/YapDatabase/wiki/LongLivedReadTransactions

Returns YES if beginLongLivedReadTransaction has been called, and the transaction is still active.

A long-lived read-only transaction is most often setup on a connection that is designed to be read-only. But sometimes we forget, and a read-write transaction gets added that uses the read-only connection. This will implicitly end the long-lived read-only transaction. Oops.

This is a bug waiting to happen. And when it does happen, it will be one of those bugs that’s nearly impossible to reproduce. So its better to have an early warning system to help you fix the bug before it occurs.

For a complete discussion, please see the wiki page: https://github.com/yapstudios/YapDatabase/wiki/LongLivedReadTransactions

In debug mode (#if DEBUG), these exceptions are turned ON by default. In non-debug mode (#if !DEBUG), these exceptions are turned OFF by default.

A long-lived read-only transaction is most often setup on a connection that is designed to be read-only. But sometimes we forget, and a read-write transaction gets added that uses the read-only connection. This will implicitly end the long-lived read-only transaction. Oops.

This is a bug waiting to happen. And when it does happen, it will be one of those bugs that’s nearly impossible to reproduce. So its better to have an early warning system to help you fix the bug before it occurs.

For a complete discussion, please see the wiki page: https://github.com/yapstudios/YapDatabase/wiki/LongLivedReadTransactions

In debug mode (#if DEBUG), these exceptions are turned ON by default. In non-debug mode (#if !DEBUG), these exceptions are turned OFF by default.

A YapDatabaseModifiedNotification is posted for every readwrite transaction that makes changes to the database.

Given one or more notifications, these methods allow you to easily query to see if a change affects a given collection, key, or combinary.

This is most often used in conjunction with longLivedReadTransactions.

For more information on longLivedReadTransaction, see the following wiki article: https://github.com/yapstudios/YapDatabase/wiki/LongLivedReadTransactions

Undocumented

Undocumented

Undocumented

Undocumented

Undocumented

Undocumented

Undocumented

Undocumented

Returns YES if [transaction removeAllObjectsInCollection:] was invoked on the collection, or if [transaction removeAllObjectsInAllCollections] was invoked during any of the commits represented by the given notifications.

If this was the case then YapDatabase may not have tracked every single key within the collection. And thus a key that was removed via clearing the collection may not show up while enumerating changedKeys.

This method is designed to be used in conjunction with the enumerateChangedKeys…. methods (below). The hasChange… methods (above) already take this into account.

Returns YES if [transaction removeAllObjectsInAllCollections] was invoked during any of the commits represented by the given notifications.

If this was the case then YapDatabase may not have tracked every single key within every single collection. And thus a key that was removed via clearing the database may not show up while enumerating changedKeys.

This method is designed to be used in conjunction with the enumerateChangedKeys…. methods (below). The hasChange… methods (above) already take this into account.

Allows you to enumerate all the changed keys in the given collection, for the given commits.

Keep in mind that if [transaction removeAllObjectsInCollection:] was invoked on the given collection or [transaction removeAllObjectsInAllCollections] was invoked during any of the commits represented by the given notifications, then the key may not be included in the enumeration. You must use didClearCollection:inNotifications: or didClearAllCollectionsInNotifications: if you need to handle that case.

Allows you to enumerate all the changed collection/key tuples for the given commits.

Keep in mind that if [transaction removeAllObjectsInCollection:] was invoked on the given collection or [transaction removeAllObjectsInAllCollections] was invoked during any of the commits represented by the given notifications, then the collection/key tuple may not be included in the enumeration. You must use didClearCollection:inNotifications: or didClearAllCollectionsInNotifications: if you need to handle that case.

Creates or fetches the extension with the given name. If this connection has not yet initialized the proper extension connection, it is done automatically.

One must register an extension with the database before it can be accessed from within connections or transactions. After registration everything works automatically using just the registered extension name.

Shorthand for -[YapDatabaseConnection extension:]

This method may be used to flush the internal caches used by the connection, as well as flushing pre-compiled sqlite statements. Depending upon how often you use the database connection, you may want to be more or less aggressive on how much stuff you flush.

• YapDatabaseConnectionFlushMemoryFlags_None
  No-op. Doesn’t flush anything.

• YapDatabaseConnectionFlushMemoryFlags_Caches
  Flushes all caches, including the object cache and metadata cache.

• YapDatabaseConnectionFlushMemoryFlags_Statements
  Flushes all pre-compiled sqlite statements.

• YapDatabaseConnectionFlushMemoryFlags_Internal
  Flushes internal memory used by sqlite instance via sqlite_db_release_memory. Generally this means cached database pages.

• YapDatabaseConnectionFlushMemoryFlags_All
  Full flush of everything (caches, statements, internal)

When a UIApplicationDidReceiveMemoryWarningNotification is received, the code automatically invokes flushMemoryWithFlags and passes the set flags.

The default value is YapDatabaseConnectionFlushMemoryFlags_All.

Returns the current synchronous configuration via PRAGMA synchronous;. Allows you to verify that sqlite accepted your synchronous configuration request.

Returns the current page_size configuration via PRAGMA page_size;. Allows you to verify that sqlite accepted your page_size configuration request.

Returns the currently memory mapped I/O configureation via PRAGMA mmap_size;. Allows you to verify that sqlite accepted your mmap_size configuration request.

Memory mapping may be disabled by sqlite’s compile-time options. Or it may restrict the mmap_size to something smaller than requested.

Upgrade Notice:

The auto_vacuum=FULL was not properly set until YapDatabase v2.5. And thus if you have an app that was using YapDatabase prior to this version, then the existing database file will continue to operate in auto_vacuum=NONE mode. This means the existing database file won’t be properly truncated as you delete information from the db. That is, the data will be removed, but the pages will be moved to the freelist, and the file itself will remain the same size on disk. (I.e. the file size can grow, but not shrink.) To correct this problem, you should run the vacuum operation at least once. After it is run, the auto_vacuum=FULL mode will be set, and the database file size will automatically shrink in the future (as you delete data).

@returns Result from PRAGMA auto_vacuum; command, as a readable string:

• NONE
• FULL
• INCREMENTAL
• UNKNOWN (future proofing)

If the return value is NONE, then you should run the vacuum operation at some point in order to properly reconfigure the database.

Concerning Method Invocation:

You can invoke this method as a standalone method on the connection:

NSString *value = [databaseConnection pragmaAutoVacuum]

Or you can invoke this method within a transaction:

[databaseConnection asyncReadWithBlock:^(YapDatabaseReadTransaction *transaction){ NSString *value = [databaseConnection pragmaAutoVacuum]; }];

Performs a VACUUM on the sqlite database.

This method operates as a synchronous ReadWrite transaction. That is, it behaves in a similar fashion, and you may treat it as if it is a ReadWrite transaction.

For more infomation on the VACUUM operation, see the sqlite docs: http://sqlite.org/lang_vacuum.html

Remember that YapDatabase operates in WAL mode, with auto_vacuum=FULL set.

Performs a VACUUM on the sqlite database.

This method operates as an asynchronous readWrite transaction. That is, it behaves in a similar fashion, and you may treat it as if it is a ReadWrite transaction.

For more infomation on the VACUUM operation, see the sqlite docs: http://sqlite.org/lang_vacuum.html

Remember that YapDatabase operates in WAL mode, with auto_vacuum=FULL set.

An optional completion block may be used. The completionBlock will be invoked on the main thread (dispatch_get_main_queue()).

Performs a VACUUM on the sqlite database.

This method operates as an asynchronous readWrite transaction. That is, it behaves in a similar fashion, and you may treat it as if it is a ReadWrite transaction.

For more infomation on the VACUUM operation, see the sqlite docs: http://sqlite.org/lang_vacuum.html

Remember that YapDatabase operates in WAL mode, with auto_vacuum=FULL set.

An optional completion block may be used. Additionally the dispatch_queue to invoke the completion block may also be specified. If NULL, dispatch_get_main_queue() is automatically used.

This method backs up the database by exporting all the tables to another sqlite database.

This method operates as a synchronous ReadWrite transaction. That is, it behaves in a similar fashion, and you may treat it as if it is a ReadWrite transaction.

The database will be backed up as it exists at the moment this transaction operates. That is, it will backup everything in the sqlite file, as well as everything in the WAL file.

For more information on the BACKUP operation, see the sqlite docs: https://www.sqlite.org/c3ref/backup_finish.html

As stated in the sqlite docs, it is your responsibilty to ensure that nothing else is currently using the backupDatabase.

This method backs up the database by exporting all the tables to another sqlite database.

This method operates as an asynchronous readWrite transaction. That is, it behaves in a similar fashion, and you may treat it as if it is a ReadWrite transaction.

The database will be backed up as it exists at the moment this transaction operates. That is, it will backup everything in the sqlite file, as well as everything in the WAL file.

An optional completion block may be used. The completionBlock will be invoked on the main thread (dispatch_get_main_queue()).

For more information on the BACKUP operation, see the sqlite docs: https://www.sqlite.org/c3ref/backup_finish.html

As stated in the sqlite docs, it is your responsibilty to ensure that nothing else is currently using the backupDatabase.

@return A NSProgress instance that may be used to track the backup progress. The progress in cancellable, meaning that invoking [progress cancel] will abort the backup operation.

This method backs up the database by exporting all the tables to another sqlite database.

This method operates as an asynchronous readWrite transaction. That is, it behaves in a similar fashion, and you may treat it as if it is a ReadWrite transaction.

The database will be backed up as it exists at the moment this transaction operates. That is, it will backup everything in the sqlite file, as well as everything in the WAL file.

An optional completion block may be used. Additionally the dispatch_queue to invoke the completion block may also be specified. If NULL, dispatch_get_main_queue() is automatically used.

For more information on the BACKUP operation, see the sqlite docs: https://www.sqlite.org/c3ref/backup_finish.html

As stated in the sqlite docs, it is your responsibilty to ensure that nothing else is currently using the backupDatabase.

@return A NSProgress instance that may be used to track the backup progress. The progress in cancellable, meaning that invoking [progress cancel] will abort the backup operation.