CBLDatabase Class Reference

Detailed Description

A Couchbase Lite database.

Inheritance diagram for CBLDatabase:

Instance Methods
(instancetype)	- initWithName:error:
	Initializes a database object with a given name and the default database options. More...
(instancetype)	- initWithName:options:error:
	Initializes a Couchbase Lite database with a given name and database options. More...
(instancetype)	- NS_UNAVAILABLE
(BOOL)	- close:
	Closes a database. More...
(BOOL)	- changeEncryptionKey:error:
	Changes the database's encryption key, or removes encryption if the new key is nil. More...
(BOOL)	- deleteDatabase:
	Deletes a database. More...
(BOOL)	- inBatch:do:
	Runs a group of database operations in a batch. More...
(CBLDocument *)	- document
	Creates a new CBLDocument object with no properties and a new (random) UUID. More...
(CBLDocument *)	- documentWithID:
	Gets or creates a CBLDocument object with the given ID. More...
(CBLDocument *)	- objectForKeyedSubscript:
	Same as -documentWithID: More...
(BOOL)	- documentExists:
	Checks whether the document of the given ID exists in the database or not. More...
(NSEnumerator< CBLDocument * > *)	- allDocuments
	Enumerates all documents in the database, ordered by document ID. More...
(CBLQuery *)	- createQueryWhere:
	Compiles a database query, from any of several input formats. More...
(BOOL)	- createIndexOn:error:
	Creates a value index (type kCBLValueIndex) on a given document property. More...
(BOOL)	- createIndexOn:type:options:error:
	Creates an index on a given document property. More...
(BOOL)	- deleteIndexOn:type:error:
	Deletes an existing index. More...

Class Methods
(BOOL)	+ deleteDatabase:inDirectory:error:
	Deletes a database of the given name in the given directory. More...
(BOOL)	+ databaseExists:inDirectory:
	Checks whether a database of the given name exists in the given directory or not. More...

Properties
NSString *	name
	The database's name. More...
NSString *	path
	The database's path. More...
id< CBLConflictResolver >	conflictResolver
	The conflict resolver for this database. More...

Method Documentation

- (instancetype) initWithName:		(NSString *)	name
error:		(NSError **)	error

Initializes a database object with a given name and the default database options.

If the database does not yet exist, it will be created.

Parameters

name	The name of the database. May NOT contain capital letters!
error	On return, the error if any.

- (instancetype) initWithName:		(NSString *)	name
options:		(nullable CBLDatabaseOptions *)	options
error:		(NSError **)	error

Initializes a Couchbase Lite database with a given name and database options.

If the database does not yet exist, it will be created, unless the readOnly option is used.

Parameters

name	The name of the database. May NOT contain capital letters!
options	The database options, or nil for the default options.
error	On return, the error if any.

- (instancetype) NS_UNAVAILABLE

- (BOOL) close:

(NSError **)

error

Closes a database.

- (BOOL) changeEncryptionKey:		(nullable id)	key
error:		(NSError **)	error

Changes the database's encryption key, or removes encryption if the new key is nil.

Parameters

key	The encryption key in the form of an NSString (a password) or an NSData object exactly 32 bytes in length (a raw AES key.) If a string is given, it will be internally converted to a raw key using 64,000 rounds of PBKDF2 hashing. A nil value will decrypt the database.
error	If an error occurs, it will be stored here if this parameter is non-NULL.

Returns

YES if the database was successfully re-keyed, or NO on error.

- (BOOL) deleteDatabase:

(NSError **)

error

Deletes a database.

+ (BOOL) deleteDatabase:		(NSString *)	name
inDirectory:		(nullable NSString *)	directory
error:		(NSError **)	error

Deletes a database of the given name in the given directory.

+ (BOOL) databaseExists:		(NSString *)	name
inDirectory:		(nullable NSString *)	directory

Checks whether a database of the given name exists in the given directory or not.

- (BOOL) inBatch:		(NSError **)	error
do:		(void(^)())	block

Runs a group of database operations in a batch.

Use this when performing bulk write operations like multiple inserts/updates; it saves the overhead of multiple database commits, greatly improving performance.

Parameters

error	On return, the error if any.
block	The block of code to run.

Returns

YES on success, NO on error.

- (CBLDocument*) document

Creates a new CBLDocument object with no properties and a new (random) UUID.

The document will be saved to the database when you call -save: on it.

- (CBLDocument*) documentWithID:

(NSString *)

docID

Gets or creates a CBLDocument object with the given ID.

The existence of the CBLDocument in the database can be checked by checking its .exists. CBLDocuments are cached, so there will never be more than one instance in this CBLDatabase object at a time with the same documentID.

- (CBLDocument*) objectForKeyedSubscript:

(NSString *)

docID

Same as -documentWithID:

- (BOOL) documentExists:

(NSString *)

docID

Checks whether the document of the given ID exists in the database or not.

- (NSEnumerator<CBLDocument*>*) allDocuments

Enumerates all documents in the database, ordered by document ID.

- (CBLQuery*) createQueryWhere:

(nullable id)

where

Compiles a database query, from any of several input formats.

Once compiled, the query can be run many times with different parameter values. The rows will be sorted by ascending document ID, and no custom values are returned.

Parameters

where

The query specification. This can be an NSPredicate, or an NSString (interpreted as an NSPredicate format string), or nil to return all documents.

Returns

The CBLQuery.

- (BOOL) createIndexOn:		(NSArray *)	expressions
error:		(NSError **)	error

Creates a value index (type kCBLValueIndex) on a given document property.

This will speed up queries that test that property, at the expense of making database writes a little bit slower.

Parameters

expressions	Expressions to index, typically key-paths. Can be NSExpression objects, or NSStrings that are expression format strings.
error	If an error occurs, it will be stored here if this parameter is non-NULL.

Returns

True on success, false on failure.

- (BOOL) createIndexOn:		(NSArray *)	expressions
type:		(CBLIndexType)	type
options:		(nullable const CBLIndexOptions *)	options
error:		(NSError **)	error

Creates an index on a given document property.

This will speed up queries that test that property, at the expense of making database writes a little bit slower.

Parameters

expressions	Expressions to index, typically key-paths. Can be NSExpression objects, or NSStrings that are expression format strings.
type	Type of index to create (value, full-text or geospatial.)
options	Options affecting the index, or NULL for default settings.
error	If an error occurs, it will be stored here if this parameter is non-NULL.

Returns

True on success, false on failure.

- (BOOL) deleteIndexOn:		(NSArray *)	expressions
type:		(CBLIndexType)	type
error:		(NSError **)	error

Deletes an existing index.

Returns NO if the index did not exist.

Parameters

expressions	Expressions indexed (same parameter given to -createIndexOn:.)
type	Type of index.
error	If an error occurs, it will be stored here if this parameter is non-NULL.

Returns

True if the index existed and was deleted, false if it did not exist.

Property Documentation

- (NSString*) name

readnonatomicassign

The database's name.

- (NSString*) path

readnonatomicassign

The database's path.

If the database is closed or deleted, nil value will be returned.

- (id<CBLConflictResolver>) conflictResolver

readwritenonatomicassign

The conflict resolver for this database.

If nil, a default algorithm will be used, where the revision with more history wins. An individual document can override this for itself by setting its own property.

---

The documentation for this class was generated from the following file:

• CBLDatabase.h