-
Notifications
You must be signed in to change notification settings - Fork 0
DBCDatabase+Advanced
#DBCDatabase Advanced Category Reference
[SQLitews]:http://www.sqlite.org
[SQLiteModule]:http://www.sqlite.org/c3ref/module.html
[MAS]:http://www.apple.com/mac/app-store/
[DBCDatabaseCR]:https://github.com/parfeon/DBConnect/wiki/DBCDatabase
[DBCDatabaseBasicExample]:https://github.com/parfeon/DBConnect/wiki/DBCDatabase#basicExample
[DBCDatabaseOpenMethod]:https://github.com/parfeon/DBConnect/wiki/DBCDatabase#m7
[DBCErrorCR]:https://github.com/parfeon/DBConnect/wiki/DBCError
[DBCDatabase+Aiases]:https://github.com/parfeon/DBConnect/wiki/DBCDatabase+Aiases
[ConstantsJournalingMode]:https://github.com/parfeon/DBConnect/wiki/Constants#DBCDatabaseJournalingMode
[ConstantsJournalingModeDelete]:https://github.com/parfeon/DBConnect/wiki/Constants#DBCDatabaseJournalingModeDelete
[ConstantsLockingMode]:https://github.com/parfeon/DBConnect/wiki/Constants#DBCDatabaseLockingMode
[ConstantsAutoVacuumMode]:https://github.com/parfeon/DBConnect/wiki/Constants#DBCDatabaseAutoVacuumMode
[ConstantsAutoVacuumNoneMode]:https://github.com/parfeon/DBConnect/wiki/Constants#DBCDatabaseAutoVacuumNone
[ConstantsAutoVacuumFullMode]:https://github.com/parfeon/DBConnect/wiki/Constants#DBCDatabaseAutoVacuumFull
[ConstantsAutoVacuumIncrementalMode]:https://github.com/parfeon/DBConnect/wiki/Constants#DBCDatabaseAutoVacuumIncremental
Overview
Basic purpose of this category, is to keep some advanced database tweaks away form user, who needs only basic features of wrapper. Also this keeps autocomplete avay from showing you methods, which you probably won't use at all.
There is one more category for [DBCDatabase][DBCDatabaseCR] [Aliases][DBCDatabase+Aiases], this category was created thematically on their purposes.
Advanced category adds specific aliases and methods to work with [sqlite][SQLitews] database.
##Tasks
###DBCDatabase instance initialization
- openWithFlags:error:
###Working with [sqlite][SQLitews] database file pages
- autoVacuumModeError:
- autoVacuumModeForDatabase:error:
- setAutoVacuumMode:error:
- setAutoVacuumMode:forDatabase:error:
- freeAllUnusedPagesError:
- freeAmountOfUnusedPages:error:
- freeAllUnusedPagesForDatabase:error:
- freeAmountOfUnusedPages:forDatabase:error:
- freeUnusedPagesError:
- freePagesCountInDatabase:error:
- pagesCountInDatabase:error:
- setPageSizeInDatabase:size:error:
- pageSizeInDatabase:error:
- setMaximumPageCountForDatabase:size:error:
- resetMaximumPageCountForDatabase:error:
- maximumPageCountForDatabase:error:
###[sqlite][SQLitews] database backup/restore
- restore:fromFile:database:error:
- restore:from:database:error:
- backup:toFile:database:error:
- backup:to:database:error:
###Transaction journaling control
- turnOffJournalingError:
- turnOffJournalingForDatabase:error:
- turnOnJournalingError:error:
- turnOnJournalingForDatabase:error:
- setJournalMode:error:
- journalModeError:
- setJournalMode:forDatabase:error:
- journalModeForDatabase:error:
- setJournalSizeLimitForDatabase:size:error:
- journalSizeLimitForDatabase:error:
###Database locking
- setLockingMode:error:
- lockingModeError:
- setLockingMode:forDatabase:error:
- lockingModeForDatabase:error:
- setOmitReadlockLike:error:
- omitReadlockError:
###Virtual tables (modules) registration
- registerModule:moduleName:userData:cleanupFunction:error:
###Function register/unregister
- registerScalarFunction:functionName:parametersCount:textValueRepresentation:userData:error:
- unRegisterScalarFunction:parametersCount:textValueRepresentation:error:
- registerAggregationFunction:finalizeFunction:functionName:parametersCount:textValueRepresentation:userData:error:
- unRegisterAggregationFunction:parametersCount:textValueRepresentation:error:
- registerCollationFunction:cleanupFunction:functionName:textValueRepresentation:userData:error:
- unRegisterCollationFunction:textValueRepresentation:error:
##Instance methods
Open [sqlite][SQLitews] database connection with specific options.
- (BOOL)openWithFlags:(int)flags error:(DBCError**)error
Parameters
flags
A series of bit-flags that can be used to control how the database file is open.
error
If an error occurs, upon return contains an [DBCError][DBCErrorCR] object that describes the problem. Pass NULL, if you do not want error information.
Return value
YES, if database connection was successfully opened, otherwise - NO.
Discussion
Parameter flags controls state of the opened file. These parameters in most cases consist from few bit-flags:
- SQLITE_OPEN_READONLY - open database file for read-only access.
- SQLITE_OPEN_READWRITE - open database file for read-write access. The file must already exist.
- SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE - default bit-flags to open database file for read-write access and file creation, if it doesn't exist.
- SQLITE_OPEN_NOMUTEX - open database connection with multithreaded support (if library was compiled with thread support, but we knew what it is not our case). This flag cannot be used in conjunction with SQLITE_OPEN_FULLMUTEX flag.
- SQLITE_OPEN_FULLMUTEX - open database connection in _serialized_ mode (if library was compiled with thread support, but we knew what it is not our case). This flag cannot be used in conjunction with SQLITE_OPEN_NO MUTEX flag.
- SQLITE_OPEN_SHAREDCACHE - enables shared cache for this database connection. This flag cannot be used in conjunction with SQLITE_OPEN_PRIVATECACHE flag.
- SQLITE_OPEN_PRIVATECACHE - disables shared cache for this database connection. This flag cannot be used in conjunction with SQLITE_OPEN_SHAREDCACHE flag.
How to use
In this example I'll show you how to implement [openError:][DBCDatabaseOpenMethod] method from inside (of course, you can see it in source codes)
DBCError *error = nil;
DBCDatabase *db = [DBCDatabase databaseWithPath:@":memory:"];
BOOL isOpened = [db openWithFlags:SQLITE_OPEN_READWRITE|SQLITE_OPEN_CREATE error:&error];
if(error != nil){
// Hmm, something went wrong, try to log out an error to find out something useful. Or you can set a flag
for DBCUseDebugLogger in DBCConfiguration.h, than DBConnect will log out all debug information.
NSLog(@"Occurred an error: %@", error);
}
See Also
[- openError:][DBCDatabaseOpenMethod]
This method allows you to retrieve current auto-vacuum mode for main database.
- (DBCDatabaseAutoVacuumMode)autoVacuumModeError:(DBCError**)error
Parameters
error
If an error occurs, upon return contains an [DBCError][DBCErrorCR] object that describes the problem. Pass NULL, if you do not want error information.
Return value
[auto-vacuum mode][ConstantsAutoVacuumMode] for main database.
Discussion
This method allows you to retrieve current auto-vacuum mode for main database and use result to find out how database will utilize free pages. When database initially created auto-vacuum mode set to [DBCDatabaseAutoVacuumNone][ConstantsAutoVacuumNoneMode].
By default value, set to DBCDatabaseAutoVacuumNone.
How to use
In this example, we will use results from one of [examples][DBCDatabaseBasicExample], shown earlier in [DBCDatabase Class Reference][DBCDatabaseCR].
DBCError *error = nil;
DBCDatabaseAutoVacuumMode avutoVacuumMode = [db autoVacuumModeError:&error];
if(error != nil){
// Hmm, something went wrong, try to log out an error to find out something useful. Or you can set a flag
for DBCUseDebugLogger in DBCConfiguration.h, than DBConnect will log out all debug information.
NSLog(@"Occurred an error: %@", error);
}
See Also
- autoVacuumModeForDatabase:error:
- setAutoVacuumMode:error:
- setAutoVacuumMode:forDatabase:error:
autoVacuumModeForDatabase:error:
This method allows you to retrieve current auto-vacuum mode for main database.
- (DBCDatabaseAutoVacuumMode)autoVacuumModeForDatabase:(NSString*)databaseName error:(DBCError**)error
Parameters
databaseName
Name of the database for which you want to retrieve auto-vacuum mode. If nil, than main database is used.
error
If an error occurs, upon return contains an [DBCError][DBCErrorCR] object that describes the problem. Pass NULL, if you do not want error information.
Return value
[auto-vacuum mode][ConstantsAutoVacuumMode] for specified database.
Discussion
This method allows you to retrieve current auto-vacuum mode for specified database and use the result to find out how database will utilize free pages. When database initially created auto-vacuum mode is set to [DBCDatabaseAutoVacuumNone][ConstantsAutoVacuumNoneMode].
By default value, set to DBCDatabaseAutoVacuumNone.
How to use
In this example, we will use results from one of [examples][DBCDatabaseBasicExample], shown earlier in [DBCDatabase Class Reference][DBCDatabaseCR].
DBCError *error = nil;
DBCDatabaseAutoVacuumMode avutoVacuumMode = [db autoVacuumModeForDatabase:@"main" error:&error];
if(error != nil){
// Hmm, something went wrong, try to log out an error to find out something useful. Or you can set a flag
for DBCUseDebugLogger in DBCConfiguration.h, than DBConnect will log out all debug information.
NSLog(@"Occurred an error: %@", error);
}
See Also
- autoVacuumModeError:
- setAutoVacuumMode:error:
- setAutoVacuumMode:forDatabase:error:
This method allows you to change current auto-vacuum mode for main database.
- (BOOL)setAutoVacuumMode:(DBCDatabaseAutoVacuumMode)mode error:(DBCError**)error
Parameters
mode
New [auto-vacuum mode][ConstantsAutoVacuumMode].
error
If an error occurs, upon return contains an [DBCError][DBCErrorCR] object that describes the problem. Pass NULL, if you do not want error information.
Return value
YES, if database auto-vacuum mode was successfully changed, otherwise - NO.
Discussion
This method allows you to change current auto-vacuum mode for main database and give database information about how it should utilize free pages. This method can't be executed on in-memory databases, because they can't be vacuumed at all.
You can change mode from [DBCDatabaseAutoVacuumFull][ConstantsAutoVacuumFullMode] to [DBCDatabaseAutoVacuumIncremental][ConstantsAutoVacuumIncrementalMode] or vise versa any time and pages which were prepared in [DBCDatabaseAutoVacuumIncremental][ConstantsAutoVacuumIncrementalMode] mode would be removed and when transferred into [DBCDatabaseAutoVacuumFull][ConstantsAutoVacuumFullMode].
Transfer from [DBCDatabaseAutoVacuumNone][ConstantsAutoVacuumNoneMode] to [DBCDatabaseAutoVacuumFull][ConstantsAutoVacuumFullMode] or [DBCDatabaseAutoVacuumIncremental][ConstantsAutoVacuumIncrementalMode] or vise versa is not so simple. Yes, it can be easily transferred to or from [DBCDatabaseAutoVacuumNone][ConstantsAutoVacuumNoneMode] right before database was initialized. After it was initialized it can be done only in conjunction with VACUUM (in case of using this PRAGMA ROWID will be reset). This method will handle all this stuff for you.
How to use
In this example, we will use results from one of [examples][DBCDatabaseBasicExample], shown earlier in [DBCDatabase Class Reference][DBCDatabaseCR]. In this example we will set full auto-vacuum mode:
DBCError *error = nil;
[db setAutoVacuumMode:DBCDatabaseAutoVacuumFull error:&error];
if(error != nil){
// Hmm, something went wrong, try to log out an error to find out something useful. Or you can set a flag
for DBCUseDebugLogger in DBCConfiguration.h, than DBConnect will log out all debug information.
NSLog(@"Occurred an error: %@", error);
}
See Also
- autoVacuumModeError:
- autoVacuumModeForDatabase:error:
- setAutoVacuumMode:forDatabase:error:
setAutoVacuumMode:forDatabase:error:
This method allows you to change current auto-vacuum mode for specified database.
- (BOOL)setAutoVacuumMode:(DBCDatabaseAutoVacuumMode)mode forDatabase:(NSString*)databaseName
error:(DBCError**)error
Parameters
mode
New [auto-vacuum mode][ConstantsAutoVacuumMode].
databaseName
The name of the database for which you want to change [auto-vacuum mode][ConstantsAutoVacuumMode]. If nil, than main database is used.
error
If an error occurs, upon return contains an [DBCError][DBCErrorCR] object that describes the problem. Pass NULL, if you do not want error information.
Return value
YES, if database auto-vacuum mode was successfully changed, otherwise - NO.
Discussion
This method allows you to change current auto-vacuum mode for specified database and gives database information about how it should utilize free pages. This method can't be executed on in-memory databases, because they can't be vacuumed at all.
You can change mode from [DBCDatabaseAutoVacuumFull][ConstantsAutoVacuumFullMode] to [DBCDatabaseAutoVacuumIncremental][ConstantsAutoVacuumIncrementalMode] or vise versa any time and pages which were prepared in [DBCDatabaseAutoVacuumIncremental][ConstantsAutoVacuumIncrementalMode] mode would be removed and when transferred into [DBCDatabaseAutoVacuumFull][ConstantsAutoVacuumFullMode].
Transfer from [DBCDatabaseAutoVacuumNone][ConstantsAutoVacuumNoneMode] to [DBCDatabaseAutoVacuumFull][ConstantsAutoVacuumFullMode] or [DBCDatabaseAutoVacuumIncremental][ConstantsAutoVacuumIncrementalMode] or vise versa is not so simple. Yes, it can be easily transferred to or from [DBCDatabaseAutoVacuumNone][ConstantsAutoVacuumNoneMode] right before database was initialized. After it was initialized it can be done only in conjunction with VACUUM (in case of using this PRAGMA ROWID will be reset). This method will handle all this stuff for you.
How to use
In this example, we will use results from one of [examples][DBCDatabaseBasicExample], shown earlier in [DBCDatabase Class Reference][DBCDatabaseCR]. In this example we will set incremental auto-vacuum mode:
DBCError *error = nil;
[db setAutoVacuumMode:DBCDatabaseAutoVacuumIncremental forDatabase:@"main" error:&error];
if(error != nil){
// Hmm, something went wrong, try to log out an error to find out something useful. Or you can set a flag
for DBCUseDebugLogger in DBCConfiguration.h, than DBConnect will log out all debug information.
NSLog(@"Occurred an error: %@", error);
}
See Also
- autoVacuumModeError:
- autoVacuumModeForDatabase:error:
- setAutoVacuumMode:error:
This method allows you to free up all free pages in main database which were prepared by auto-vacuum in [DBCDatabaseAutoVacuumIncremental][ConstantsAutoVacuumIncrementalMode] mode.
- (BOOL)freeAllUnusedPagesError:(DBCError**)error
Parameters
error
If an error occurs, upon return contains an [DBCError][DBCErrorCR] object that describes the problem. Pass NULL, if you do not want error information.
Return value
YES, if pages was successfully freed, otherwise - NO.
Discussion
This method allows you to remove all swapped pages in main database, which were prepared by auto-vacuum in [DBCDatabaseAutoVacuumIncremental][ConstantsAutoVacuumIncrementalMode] mode.
How to use
In this example, we will use results from one of [examples][DBCDatabaseBasicExample], shown earlier in [DBCDatabase Class Reference][DBCDatabaseCR]. In this example we will set incremental auto-vacuum mode:
DBCError *error = nil;
[db freeAllUnusedPagesError:&error];
if(error != nil){
// Hmm, something went wrong, try to log out an error to find out something useful. Or you can set a flag
for DBCUseDebugLogger in DBCConfiguration.h, than DBConnect will log out all debug information.
NSLog(@"Occurred an error: %@", error);
}
See Also
- freeAmountOfUnusedPages:error:
- freeAllUnusedPagesForDatabase:error:
- freeAmountOfUnusedPages:forDatabase:error:
freeAmountOfUnusedPages:error:
This method allows you to free up specific amount of free pages in main database which were prepared by auto-vacuum in [DBCDatabaseAutoVacuumIncremental][ConstantsAutoVacuumIncrementalMode] mode.
- (BOOL)freeAmountOfUnusedPages:(int)pagesCount error:(DBCError**)error
Parameters
pagesCount
How much pages should be freed.
error
If an error occurs, upon return contains an [DBCError][DBCErrorCR] object that describes the problem. Pass NULL, if you do not want error information.
Return value
YES, if pages was successfully freed, otherwise - NO.
Discussion
This method allows you to free up specific amount of swapped pages in main database, which were prepared by auto-vacuum in [DBCDatabaseAutoVacuumIncremental][ConstantsAutoVacuumIncrementalMode] mode.
How to use
In this example, we will use results from one of [examples][DBCDatabaseBasicExample], shown earlier in [DBCDatabase Class Reference][DBCDatabaseCR]. In this example we will set incremental auto-vacuum mode:
DBCError *error = nil;
int freePagesCount = [db freePagesCountInDatabase:@"main" error:&error];
int pagesCountToFree = (freePagesCount>0)?((int)(freePagesCount*0.5f)):-1;
[db freeAmountOfUnusedPages:pagesCountToFree error:&error];
if(error != nil){
// Hmm, something went wrong, try to log out an error to find out something useful. Or you can set a flag
for DBCUseDebugLogger in DBCConfiguration.h, than DBConnect will log out all debug information.
NSLog(@"Occurred an error: %@", error);
}
See Also
- freeAllUnusedPagesError:
- freeAllUnusedPagesForDatabase:error:
- freeAmountOfUnusedPages:forDatabase:error:
freeAllUnusedPagesForDatabase:error:
This method allows you to free up all free pages in specified database which was prepared by auto-vacuum in [DBCDatabaseAutoVacuumIncremental][ConstantsAutoVacuumIncrementalMode] mode.
- (BOOL)freeAllUnusedPagesForDatabase:(NSString*)databaseName error:(DBCError**)error
Parameters
databaseName
Name of the database for which you want to free up all swapped pages. If nil, than main database is used.
error
If an error occurs, upon return contains an [DBCError][DBCErrorCR] object that describes the problem. Pass NULL, if you do not want error information.
Return value
YES, if pages was successfully freed, otherwise - NO.
Discussion
This method allows you to remove all swapped pages in specified database, which were prepared by auto-vacuum in [DBCDatabaseAutoVacuumIncremental][ConstantsAutoVacuumIncrementalMode] mode.
How to use
In this example, we will use results from one of [examples][DBCDatabaseBasicExample], shown earlier in [DBCDatabase Class Reference][DBCDatabaseCR]. In this example we will set incremental auto-vacuum mode:
DBCError *error = nil;
[db freeAllUnusedPagesForDatabase:@"main" error:&error];
if(error != nil){
// Hmm, something went wrong, try to log out an error to find out something useful. Or you can set a flag
for DBCUseDebugLogger in DBCConfiguration.h, than DBConnect will log out all debug information.
NSLog(@"Occurred an error: %@", error);
}
See Also
- freeAllUnusedPagesError:
- freeAmountOfUnusedPages:error:
- freeAmountOfUnusedPages:forDatabase:error:
freeAmountOfUnusedPages:forDatabase:error:
This method allows you to free up specific amount of free pages in specified database which was prepared by auto-vacuum in [DBCDatabaseAutoVacuumIncremental][ConstantsAutoVacuumIncrementalMode] mode.
- (BOOL)freeAmountOfUnusedPages:(int)pagesCount forDatabase:(NSString*)databaseName error:(DBCError**)error
Parameters
pagesCount
How much pages should be freed.
databaseName
Name of the database for which you want to free up specific amount of swapped pages. If nil, than main database is used.
error
If an error occurs, upon return contains an [DBCError][DBCErrorCR] object that describes the problem. Pass NULL, if you do not want error information.
Return value
YES, if pages was successfully freed, otherwise - NO.
Discussion
This method allows you to free up specific amount of swapped pages in specified database, which were prepared by auto-vacuum in [DBCDatabaseAutoVacuumIncremental][ConstantsAutoVacuumIncrementalMode] mode.
How to use
In this example, we will use results from one of [examples][DBCDatabaseBasicExample], shown earlier in [DBCDatabase Class Reference][DBCDatabaseCR]. In this example we will set incremental auto-vacuum mode:
DBCError *error = nil;
int freePagesCount = [db freePagesCountInDatabase:@"main" error:&error];
int pagesCountToFree = (freePagesCount>0)?((int)(freePagesCount*0.5f)):-1;
[db freeAmountOfUnusedPages:pagesCountToFree forDatabase:@"main" error:&error];
if(error != nil){
// Hmm, something went wrong, try to log out an error to find out something useful. Or you can set a flag
for DBCUseDebugLogger in DBCConfiguration.h, than DBConnect will log out all debug information.
NSLog(@"Occurred an error: %@", error);
}
See Also
- freeAllUnusedPagesError:
- freeAmountOfUnusedPages:error:
- freeAllUnusedPagesForDatabase:error:
This method allows you to remove garbage data from [sqlite][SQLitews] database file and reduce it in size.
- (BOOL)freeUnusedPagesError:(DBCError**)error
Parameters
error
If an error occurs, upon return contains an [DBCError][DBCErrorCR] object that describes the problem. Pass NULL, if you do not want error information.
Return value
YES, if database was successfully vacuumed, otherwise - NO.
Discussion
After removing large amount of data from the table, maybe even dropping the whole table, there is garbage left in [sqlite][SQLitews] database file, so we need to cleanup it time after time. This macro helps us to remove garbage data from [sqlite][SQLitews] database file and defragment database structures and repack individual database pages.
This method can be performed only on main database (which was used to create connection) also it doesn't have any effect on in-memory database.
Under the hood this method will recreate database from the scratch with database settings, default for current database connection. For example if your database file uses some non-standard settings (for example page_size), make sure to set them with appropriate methods before freeing unused pages. Also this methods will rebuild indexes and all this operations require some time, so don't overuse this feature.
How to use
In this example, we will use results from one of [examples][DBCDatabaseBasicExample], shown earlier in [DBCDatabase Class Reference][DBCDatabaseCR].
I'll show you how to clean up free pages after dropping whole table with data in it, if the number of free pages is more than 70% of total pages number.
error = nil;
[db dropTable:@"test" inDatabase:nil error:&error];
if(error == nil){
int freePagesCount = [db freePagesCountInDatabase:@"main" error:&error];
int totalPagesCount = [db pagesCountInDatabase:@"main" error:&error];
if(freePagesCount >= (totalPagesCount-freePagesCount)*0.7){
[db freeUnusedPagesError:&error];
if(error != nil){
// Hmm, something went wrong, try to log out an error to find out something useful. Or you can set a flag
for DBCUseDebugLogger in DBCConfiguration.h, than DBConnect will log out all debug information.
NSLog(@"Occurred an error: %@", error);
}
}
} else {
// Hmm, something went wrong, try to log out an error to find out something useful. Or you can set a flag
for DBCUseDebugLogger in DBCConfiguration.h, than DBConnect will log out all debug information.
NSLog(@"Occurred an error: %@", error);
}
See Also
- freePagesCountInDatabase:error:
- pagesCountInDatabase:error:
- setPageSizeInDatabase:size:error:
- pageSizeInDatabase:error:
- setMaximumPageCountForDatabase:size:error:
- resetMaximumPageCountForDatabase:error:
- maximumPageCountForDatabase:error:
freePagesCountInDatabase:error:
This method allows you to retrieve, how many pages in specified database are currently marked as free and available.
- (int)freePagesCountInDatabase:(NSString*)databaseName error:(DBCError**)error
Parameters
databaseName
Name of the database for which you want to retrieve how much free pages is there. If nil, than main database is used.
error
If an error occurs, upon return contains an [DBCError][DBCErrorCR] object that describes the problem. Pass NULL, if you do not want error information.
Return value
How many pages in specified database are currently marked as free and available.
Discussion
This method can be used to determine when you need to call freeUnusedPagesError: to free up pages.
How to use
In this example, we will use results from one of [examples][DBCDatabaseBasicExample], shown earlier in [DBCDatabase Class Reference][DBCDatabaseCR].
I'll show you how to retrieve number of free pages.
error = nil;
[db dropTable:@"test" inDatabase:nil error:&error];
if(error == nil){
int freePagesCount = [db freePagesCountInDatabase:@"main" error:&error];
if(error != nil){
// Hmm, something went wrong, try to log out an error to find out something useful. Or you can set a flag
for DBCUseDebugLogger in DBCConfiguration.h, than DBConnect will log out all debug information.
NSLog(@"Occurred an error: %@", error);
}
} else {
// Hmm, something went wrong, try to log out an error to find out something useful. Or you can set a flag
for DBCUseDebugLogger in DBCConfiguration.h, than DBConnect will log out all debug information.
NSLog(@"Occurred an error: %@", error);
}
See Also
- freeUnusedPagesError:
- pagesCountInDatabase:error:
- setPageSizeInDatabase:size:error:
- pageSizeInDatabase:error:
- setMaximumPageCountForDatabase:size:error:
- resetMaximumPageCountForDatabase:error:
- maximumPageCountForDatabase:error:
This method allows you to retrieve how many pages are used by specified database.
- (int)pagesCountInDatabase:(NSString*)databaseName error:(DBCError**)error
Parameters
databaseName
Name of the database for which you want to retrieve how many pages it uses. If nil, than main database is used.
error
If an error occurs, upon return contains an [DBCError][DBCErrorCR] object that describes the problem. Pass NULL, if you do not want error information.
Return value
How many pages are used by database (including marked as free).
Discussion
This method can be used to determine when you need to call freeUnusedPagesError: to free up pages. Product for return values of pagesCountInDatabase:error: and pageSizeInDatabase:error: will give you info about how many space is used by the database.
How to use
In this example, we will use results from one of [examples][DBCDatabaseBasicExample], shown earlier in [DBCDatabase Class Reference][DBCDatabaseCR].
error = nil;
int totalPagesCount = [db pagesCountInDatabase:@"main" error:&error];
if(error != nil){
// Hmm, something went wrong, try to log out an error to find out something useful. Or you can set a flag
for DBCUseDebugLogger in DBCConfiguration.h, than DBConnect will log out all debug information.
NSLog(@"Occurred an error: %@", error);
}
See Also
- freeUnusedPagesError:
- freePagesCountInDatabase:error:
- setPageSizeInDatabase:size:error:
- pageSizeInDatabase:error:
- setMaximumPageCountForDatabase:size:error:
- resetMaximumPageCountForDatabase:error:
- maximumPageCountForDatabase:error:
setPageSizeInDatabase:size:error:
This method allows you to change page's size for specified database.
- (BOOL)setPageSizeInDatabase:(NSString*)databaseName size:(int)newPageSize error:(DBCError**)error
Parameters
databaseName
Name of the database for which you want to change page size. If nil, than main database is used.
newPageSize
New page size value in bytes. Size must be a power of two.
error
If an error occurs, upon return contains an [DBCError][DBCErrorCR] object that describes the problem. Pass NULL, if you do not want error information.
Return value
YES, if database page size was successfully changed, otherwise - NO.
Discussion
This method allows you to change page size of the database and to repack database from the scratch with new page size value. The bytes must be a power of two. Default allowed sizes are 512, 1024, 2048, 4096, 8192, 16384, and 32768 bytes.
Both this and pageSizeInDatabase:error: methods are heavily used in backup and restore methods.
How to use
In this example, we will use results from one of [examples][DBCDatabaseBasicExample], shown earlier in [DBCDatabase Class Reference][DBCDatabaseCR].
I'll show you how to set new page size for specific database.
error = nil;
[db setPageSizeInDatabase:@"main" size:4096 error:&error];
if(error != nil){
// Hmm, something went wrong, try to log out an error to find out something useful. Or you can set a flag
for DBCUseDebugLogger in DBCConfiguration.h, than DBConnect will log out all debug information.
NSLog(@"Occurred an error: %@", error);
}
See Also
- freeUnusedPagesError:
- freePagesCountInDatabase:error:
- pagesCountInDatabase:error:
- pageSizeInDatabase:error:
- setMaximumPageCountForDatabase:size:error:
- resetMaximumPageCountForDatabase:error:
- maximumPageCountForDatabase:error:
This method allows you to retrieve page's size for specified database.
- (int)pageSizeInDatabase:(NSString*)databaseName error:(DBCError**)error
Parameters
databaseName
Name of the database for which you want to retrieve page's size. If nil, than main database is used.
error
If an error occurs, upon return contains an [DBCError][DBCErrorCR] object that describes the problem. Pass NULL, if you do not want error information.
Return value
Specified database page size.
Discussion
This method allows you to retrieve page size for specified database. Product for returning values of pagesCountInDatabase:error: and pageSizeInDatabase:error: will give you info about how much space is used by the database.
Both this and setPageSizeInDatabase:size:error: methods are heavily used in backup and restore methods.
How to use
In this example, we will use results from one of [examples][DBCDatabaseBasicExample], shown earlier in [DBCDatabase Class Reference][DBCDatabaseCR].
Here I'll show you how to retrieve page size for specific database in bytes:
error = nil;
int databasePageSize [db pageSizeInDatabase:@"main" error:&error];
if(error != nil){
// Hmm, something went wrong, try to log out an error to find out something useful. Or you can set a flag
for DBCUseDebugLogger in DBCConfiguration.h, than DBConnect will log out all debug information.
NSLog(@"Occurred an error: %@", error);
}
See Also
- freeUnusedPagesError:
- freePagesCountInDatabase:error:
- pagesCountInDatabase:error:
- setPageSizeInDatabase:size:error:
- setMaximumPageCountForDatabase:size:error:
- resetMaximumPageCountForDatabase:error:
- maximumPageCountForDatabase:error:
setMaximumPageCountForDatabase:size:error:
This method allows you to set maximum database pages count.
- (BOOL)setMaximumPageCountForDatabase:(NSString*)databaseName size:(int)newPageCount error:(DBCError**)error
Parameters
databaseName
Name of the database for which you want to change maximum pages count. If nil, than main database is used.
newPageCount
New page count (only 32-bit signed int is allowed).
error
If an error occurs, upon return contains an [DBCError][DBCErrorCR] object that describes the problem. Pass NULL, if you do not want error information.
Return value
YES, if database maximum pages count was successfully changed, otherwise - NO.
Discussion
This method allows you to change maximum page size for specified database. If database will try to grow over this maximum, you'll get an out-of-space error.
How to use
In this example, we will use results from one of [examples][DBCDatabaseBasicExample], shown earlier in [DBCDatabase Class Reference][DBCDatabaseCR].
In this example we will set custom maximum pages count for database, which is equal to 1073741823 (maximum value):
error = nil;
[db setMaximumPageCountForDatabase:@"main" size:1073741823 error:&error];
if(error != nil){
// Hmm, something went wrong, try to log out an error to find out something useful. Or you can set a flag
for DBCUseDebugLogger in DBCConfiguration.h, than DBConnect will log out all debug information.
NSLog(@"Occurred an error: %@", error);
}
See Also
- freeUnusedPagesError:
- freePagesCountInDatabase:error:
- pagesCountInDatabase:error:
- setPageSizeInDatabase:size:error:
- pageSizeInDatabase:error:
- resetMaximumPageCountForDatabase:error:
- maximumPageCountForDatabase:error:
resetMaximumPageCountForDatabase:error:
This method allows you to reset maximum page count to default value.
- (BOOL)resetMaximumPageCountForDatabase:(NSString*)databaseName error:(DBCError**)error
Parameters
databaseName
Name of the database for which you want to reset to default maximum pages count. If nil, than main database is used.
error
If an error occurs, upon return contains an [DBCError][DBCErrorCR] object that describes the problem. Pass NULL, if you do not want error information.
Return value
YES, if database maximum pages count was successfully reset, otherwise - NO.
Discussion
This method simply resets for specified database maximum pages count to 1073741823 pages (this count of pages allows to store one terabyte in database).
How to use
In this example, we will use results from one of [examples][DBCDatabaseBasicExample], shown earlier in [DBCDatabase Class Reference][DBCDatabaseCR].
In this example we will set default maximum pages count value for database, which will be equal to 1073741823:
error = nil;
[db resetMaximumPageCountForDatabase:@"main" error:&error];
if(error != nil){
// Hmm, something went wrong, try to log out an error to find out something useful. Or you can set a flag
for DBCUseDebugLogger in DBCConfiguration.h, than DBConnect will log out all debug information.
NSLog(@"Occurred an error: %@", error);
}
See Also
- freeUnusedPagesError:
- freePagesCountInDatabase:error:
- pagesCountInDatabase:error:
- setPageSizeInDatabase:size:error:
- pageSizeInDatabase:error:
- setMaximumPageCountForDatabase:size:error:
- maximumPageCountForDatabase:error:
maximumPageCountForDatabase:error:
This method allows you to retrieve maximum pages count for specified database.
- (int)maximumPageCountForDatabase:(NSString*)databaseName error:(DBCError**)error
Parameters
databaseName
Name of the database for which you want to retrieve maximum pages count. If nil, than main database is used.
error
If an error occurs, upon return contains an [DBCError][DBCErrorCR] object that describes the problem. Pass NULL, if you do not want error information.
Return value
Specified database maximum pages count.
Discussion
This method allow you to retrieve maximum pages count for specified database.
How to use
In this example, we will use results from one of [examples][DBCDatabaseBasicExample], shown earlier in [DBCDatabase Class Reference][DBCDatabaseCR].
Here I'll show you how to retrieve maximum pages count for specific database:
error = nil;
int maximumPagesCount [db maximumPageCountForDatabase:@"main" error:&error];
if(error != nil){
// Hmm, something went wrong, try to log out an error to find out something useful. Or you can set a flag
for DBCUseDebugLogger in DBCConfiguration.h, than DBConnect will log out all debug information.
NSLog(@"Occurred an error: %@", error);
}
See Also
- freeUnusedPagesError:
- freePagesCountInDatabase:error:
- pagesCountInDatabase:error:
- setPageSizeInDatabase:size:error:
- pageSizeInDatabase:error:
- setMaximumPageCountForDatabase:size:error:
- resetMaximumPageCountForDatabase:error:
restore:fromFile:database:error:
This method allows you to restore destination database from current [sqlite][SQLitews] database connection with source database file and specified source database name.
- (BOOL)restore:(NSString*)dstDatabaseName fromFile:(NSString*)srcDatabaseFile
database:(NSString*)srcDatabaseName error:(DBCError**)error
Parameters
dstDatabaseName
Destination database name in current [sqlite][SQLitews] database connection for restoring. If nil, than main database is used.
srcDatabaseFile
Source database file from which database restore will be performed.
srcDatabaseName
Source database name, which will be used to restore destination database. If nil, than main database is used.
error
If an error occurs, upon return contains an [DBCError][DBCErrorCR] object that describes the problem. Pass NULL, if you do not want error information.
Return value
YES, if database was successfully restored, otherwise - NO.
Discussion
If page-size of the source and destination database are different, than before restoring, destination database page-size will be changed (if opened with read-write access).
How to use
In this example, we will use results from one of [examples][DBCDatabaseBasicExample], shown earlier in [DBCDatabase Class Reference][DBCDatabaseCR].
We will assume what we used backup:toFile:database:error: to backup file from [example][DBCDatabaseBasicExample] to file with name test_backup.sqlite
error = nil;
NSString *docDir = [NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES)
objectAtIndex:0];
NSString *backupFilepath = [docDir stringByAppendingPathComponent:@"test_backup.sqlite"];
DBCDatabase *restoredDB = [DBCDatabase databaseWithPath:@":memory:"];
if(error == nil){
BOOL restored = [restoredDB restore:@"main" fromFile:backupFilepath database:@"main" error:&error];
if(restored) NSLog(@"Woohoo, database was restored from file");
else if(error != nil){
// Hmm, something went wrong, try to log out an error to find out something useful. Or you can set a flag
for DBCUseDebugLogger in DBCConfiguration.h, than DBConnect will log out all debug information.
NSLog(@"Occurred an error: %@", error);
}
} else {
// Hmm, something went wrong, try to log out an error to find out something useful. Or you can set a flag
for DBCUseDebugLogger in DBCConfiguration.h, than DBConnect will log out all debug information.
NSLog(@"Occurred an error: %@", error);
}
See Also
- restore:from:database:error:
- backup:toFile:database:error:
- backup:to:database:error:
This method allows you to restore destination database from current connection with source database connection and specified source database name.
- (BOOL)restore:(NSString*)dstDatabaseName from:(sqlite3*)srcDatabaseConnection
database:(NSString*)srcDatabaseName error:(DBCError**)error
Parameters
dstDatabaseName
Destination database name in current [sqlite][SQLitews] database connection for restoring. If nil, than main database is used.
srcDatabaseConnection
Source [sqlite][SQLitews] database connection from which database restore will be performed.
srcDatabaseName
Source database name, which will be used to restore destination database. If nil, than main database is used.
error
If an error occurs, upon return contains an [DBCError][DBCErrorCR] object that describes the problem. Pass NULL, if you do not want error information.
Return value
YES, if database was successfully restored, otherwise - NO.
Discussion
If page-size of the source and destination database are different, than before restoring, destination database page-size will be changed (if opened with read-write access).
How to use
In this example, we will use results from one of [examples][DBCDatabaseBasicExample], shown earlier in [DBCDatabase Class Reference][DBCDatabaseCR].
In this example we will use our original database connection from this [example][DBCDatabaseBasicExample] as a source for restoring new database:
error = nil;
DBCDatabase *restoredDB = [DBCDatabase databaseWithPath:@":memory:"];
if(error == nil){
BOOL restored = [restoredDB restore:nil from:[db database] database:nil error:&error];
if(restored) NSLog(@"Woohoo, database was restored from another database connection");
else if(error != nil){
// Hmm, something went wrong, try to log out an error to find out something useful. Or you can set a flag
for DBCUseDebugLogger in DBCConfiguration.h, than DBConnect will log out all debug information.
NSLog(@"Occurred an error: %@", error);
}
} else {
// Hmm, something went wrong, try to log out an error to find out something useful. Or you can set a flag
for DBCUseDebugLogger in DBCConfiguration.h, than DBConnect will log out all debug information.
NSLog(@"Occurred an error: %@", error);
}
See Also
- restore:fromFile:database:error:
- backup:toFile:database:error:
- backup:to:database:error:
This method allows you to backup source database from current connection to destination database file and specified destination database name.
- (BOOL)backup:(NSString*)srcDatabaseName toFile:(NSString*)dstDatabaseFile
database:(NSString*)dstDatabaseName error:(DBCError**)error
Parameters
srcDatabaseName
Source database name in current [sqlite][SQLitews] database connection for backup. If nil, than main database is used.
dstDatabaseFile
Destination database file to which database backup will be performed.
dstDatabaseName
Destination database name, which will be used to backup source database. If nil, than main database is used.
error
If an error occurs, upon return contains an [DBCError][DBCErrorCR] object that describes the problem. Pass NULL, if you do not want error information.
Return value
YES, if database backup successfully completed, otherwise - NO.
Discussion
If page-size of the source and destination database are different, than before restoring, destination database page-size will be changed (if opened with read-write access).
If another thread or process writes to the source database, while backing up, then SQLite detects this and usually restarts backup process. If the backup process is restarted frequently enough it may never run to completion and backup:toFile:database:error: function may never return.
How to use
In this example, we will use results from one of [examples][DBCDatabaseBasicExample], shown earlier in [DBCDatabase Class Reference][DBCDatabaseCR].
Here I'll show you how to backup active database to file:
error = nil;
NSString *docDir = [NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES)
objectAtIndex:0];
NSString *backupFilepath = [docDir stringByAppendingPathComponent:@"test_backup.sqlite"];
[db backup:nil toFile:backupFilepath database:nil error:&error];
if(error != nil){
// Hmm, something went wrong, try to log out an error to find out something useful. Or you can set a flag
for DBCUseDebugLogger in DBCConfiguration.h, than DBConnect will log out all debug information.
NSLog(@"Occurred an error: %@", error);
}
See Also
- restore:fromFile:database:error:
- restore:from:database:error:
- backup:to:database:error:
This method allows you to backup source database from current connection to destination database connection and specified destination.
- (BOOL)backup:(NSString*)srcDatabaseName to:(sqlite3*)dstDatabase
database:(NSString*)dstDatabaseName error:(DBCError**)error
Parameters
srcDatabaseName
Source database name in current [sqlite][SQLitews] database connection for backup. If nil, than main database is used.
dstDatabase
Destination [sqlite][SQLitews] database connection to which database backup will be performed.
dstDatabaseName
Destination database name, which will be used to backup source database. If nil, than main database is used.
error
If an error occurs, upon return contains an [DBCError][DBCErrorCR] object that describes the problem. Pass NULL, if you do not want error information.
Return value
YES, if database backup successfully completed, otherwise - NO.
Discussion
If page-size of the source and destination database are different, than before restoring, destination database page-size will be changed (if opened with read-write access).
If another thread or process writes to the source database, while backing up, then SQLite detects this and usually restarts backup process. If the backup process is restarted frequently enough it may never run to completion and backup:to:database:error: function may never return.
How to use
In this example, we will use results from one of [examples][DBCDatabaseBasicExample], shown earlier in [DBCDatabase Class Reference][DBCDatabaseCR].
In this example we will backup database from current connection to database on another connection (it's almost the same as in restore:from:database:error: except what source is used current connection):
error = nil;
DBCDatabase *dbForBackup = [DBCDatabase databaseWithPath:@":memory:"];
if(error == nil){
[db backup:nil to:[dbForBackup database] database:nil error:&error];
if(error != nil){
// Hmm, something went wrong, try to log out an error to find out something useful. Or you can set a flag
for DBCUseDebugLogger in DBCConfiguration.h, than DBConnect will log out all debug information.
NSLog(@"Occurred an error: %@", error);
}
} else {
// Hmm, something went wrong, try to log out an error to find out something useful. Or you can set a flag
for DBCUseDebugLogger in DBCConfiguration.h, than DBConnect will log out all debug information.
NSLog(@"Occurred an error: %@", error);
}
See Also
- restore:fromFile:database:error:
- restore:from:database:error:
- backup:toFile:database:error:
This method allows you to turn off transaction journaling for database connection by default.
- (BOOL)turnOffJournalingError:(DBCError**)error
Parameters
error
If an error occurs, upon return contains an [DBCError][DBCErrorCR] object that describes the problem. Pass NULL, if you do not want error information.
Return value
YES, if transaction journaling successfully turned off, otherwise - NO.
Discussion
Journal files used by [SQLite][SQLitews] to roll back transactions or if unrecoverable error was encountered. Basically journal required for all SQL statements which change database structure or values.
All existing databases won't be modified. To turn off journaling for specific (existing) database use turnOffJournalingForDatabase:error: instead.
By default journaling turned on.
How to use
In this example, we will use results from one of [examples][DBCDatabaseBasicExample], shown earlier in [DBCDatabase Class Reference][DBCDatabaseCR].
In this example I'll show you how to disable transaction journaling by default for all newly attached databases:
error = nil;
[db turnOffJournalingError:&error];
if(error != nil){
// Hmm, something went wrong, try to log out an error to find out something useful. Or you can set a flag
for DBCUseDebugLogger in DBCConfiguration.h, than DBConnect will log out all debug information.
NSLog(@"Occurred an error: %@", error);
}
See Also
- turnOffJournalingForDatabase:error:
- turnOnJournalingError:error:
- turnOnJournalingForDatabase:error:
turnOffJournalingForDatabase:error:
This method allows you to turn off transaction journaling for specified database.
- (BOOL)turnOffJournalingForDatabase:(NSString*)databaseName error:(DBCError**)error
Parameters
databaseName
The name of database, for which you want to turn off transactions journaling. If nil, than main database is used.
error
If an error occurs, upon return contains an [DBCError][DBCErrorCR] object that describes the problem. Pass NULL, if you do not want error information.
Return value
YES, if transaction journaling successfully turned off, otherwise - NO.
Discussion
Journal files used by [SQLite][SQLitews] to roll back transactions or if unrecoverable error was encountered. Basically journal required for all SQL statements which change database structure or values.
This will affect only specific database and rest will be untouched. If you wish to turn off journaling by default for all newly attached databases use turnOffJournalingError: instead.
By default journaling turned on.
How to use
In this example, we will use results from one of [examples][DBCDatabaseBasicExample], shown earlier in [DBCDatabase Class Reference][DBCDatabaseCR].
In this example I'll show you how to disable transaction journaling for specific database:
error = nil;
[db turnOffJournalingForDatabase:@"main" error:&error];
if(error != nil){
// Hmm, something went wrong, try to log out an error to find out something useful. Or you can set a flag
for DBCUseDebugLogger in DBCConfiguration.h, than DBConnect will log out all debug information.
NSLog(@"Occurred an error: %@", error);
}
See Also
- turnOffJournalingError:
- turnOnJournalingError:error:
- turnOnJournalingForDatabase:error:
This method allows you to turn on transaction journaling for database connection by default.
- (BOOL)turnOnJournalingError:(DBCError**)error
Parameters
error
If an error occurs, upon return contains an [DBCError][DBCErrorCR] object that describes the problem. Pass NULL, if you do not want error information.
Return value
YES, if transaction journaling successfully turned on, otherwise - NO.
Discussion
Journal files used by [SQLite][SQLitews] to roll back transactions or if unrecoverable error was encountered. Basically journal required for all SQL statements which change database structure or values.
All existing databases won't be modified. To turn on journaling for specific (existing) database use turnOnJournalingForDatabase:error: instead.
By default journaling turned on.
How to use
In this example, we will use results from one of [examples][DBCDatabaseBasicExample], shown earlier in [DBCDatabase Class Reference][DBCDatabaseCR].
In this example I'll show you how to enabled transaction journaling by default for all newly attached databases:
error = nil;
[db turnOnJournalingError:&error];
if(error != nil){
// Hmm, something went wrong, try to log out an error to find out something useful. Or you can set a flag
for DBCUseDebugLogger in DBCConfiguration.h, than DBConnect will log out all debug information.
NSLog(@"Occurred an error: %@", error);
}
See Also
- turnOffJournalingError:
- turnOffJournalingForDatabase:error:
- turnOnJournalingForDatabase:error:
turnOnJournalingForDatabase:error:
This method allows you to turn on transaction journaling for specified database.
- (BOOL)turnOnJournalingForDatabase:(NSString*)databaseName error:(DBCError**)error
Parameters
databaseName
The name of database, for which you want to turn on transactions journaling. If nil, than main database is used.
error
If an error occurs, upon return contains an [DBCError][DBCErrorCR] object that describes the problem. Pass NULL, if you do not want error information.
Return value
YES, if transaction journaling successfully turned on, otherwise - NO.
Discussion
Journal files used by [SQLite][SQLitews] to roll back transactions or if unrecoverable error was encountered. Basically journal required for all SQL statements which change database structure or values.
This will affect only specific database and rest will be untouched. If you wish to turn on journaling by default for all newly attached databases use turnOnJournalingError: instead.
By default journaling turned on.
How to use
In this example, we will use results from one of [examples][DBCDatabaseBasicExample], shown earlier in [DBCDatabase Class Reference][DBCDatabaseCR].
In this example I'll show you how to enable transaction journaling for specific database:
error = nil;
[db turnOnJournalingForDatabase:@"main" error:&error];
if(error != nil){
// Hmm, something went wrong, try to log out an error to find out something useful. Or you can set a flag
for DBCUseDebugLogger in DBCConfiguration.h, than DBConnect will log out all debug information.
NSLog(@"Occurred an error: %@", error);
}
See Also
- turnOffJournalingError:
- turnOffJournalingForDatabase:error:
- turnOnJournalingError:error:
This method allows you to change transaction journaling mode for database connection by default.
- (BOOL)setJournalMode:(DBCDatabaseJournalingMode)journalMode error:(DBCError**)error
Parameters
journalMode
New transaction [journaling mode][ConstantsJournalingMode].
error
If an error occurs, upon return contains an [DBCError][DBCErrorCR] object that describes the problem. Pass NULL, if you do not want error information.
Return value
YES, if transaction journaling mode was successfully changed, otherwise - NO.
Discussion
Journal files used by [SQLite][SQLitews] to roll back transactions or if unrecoverable error was encountered. Basically journal required for all SQL statements which change database structure or values.
By default value set to DBCDatabaseJournalingModeDelete.
How to use
In this example, we will use results from one of [examples][DBCDatabaseBasicExample], shown earlier in [DBCDatabase Class Reference][DBCDatabaseCR].
In this example I'll show you how to set custom transaction journaling mode by default for all newly attached databases:
error = nil;
[db setJournalMode:DBCDatabaseJournalingModeOff error:&error];
if(error != nil){
// Hmm, something went wrong, try to log out an error to find out something useful. Or you can set a flag
for DBCUseDebugLogger in DBCConfiguration.h, than DBConnect will log out all debug information.
NSLog(@"Occurred an error: %@", error);
}
See Also
- journalModeError:
- setJournalMode:forDatabase:error:
- journalModeForDatabase:error:
This method allows you to retrieve default transaction journaling mode for database connection.
- (DBCDatabaseJournalingMode)journalModeError:(DBCError**)error
Parameters
error
If an error occurs, upon return contains an [DBCError][DBCErrorCR] object that describes the problem. Pass NULL, if you do not want error information.
Return value
Default transaction [journaling mode][ConstantsJournalingMode].
How to use
In this example, we will use results from one of [examples][DBCDatabaseBasicExample], shown earlier in [DBCDatabase Class Reference][DBCDatabaseCR].
In this example I'll show you how to retrieve default journaling mode:
error = nil;
DBCDatabaseJournalingMode journalingMode = [db journalModeError::&error];
if(error != nil){
// Hmm, something went wrong, try to log out an error to find out something useful. Or you can set a flag
for DBCUseDebugLogger in DBCConfiguration.h, than DBConnect will log out all debug information.
NSLog(@"Occurred an error: %@", error);
}
See Also
- setJournalMode:error:
- setJournalMode:forDatabase:error:
- journalModeForDatabase:error:
setJournalMode:forDatabase:error:
This method allows you to change transaction journaling mode for specific database.
- (BOOL)setJournalMode:(DBCDatabaseJournalingMode)journalMode forDatabase:(NSString*)databaseName
error:(DBCError**)error
Parameters
journalMode
New transaction [journaling mode][ConstantsJournalingMode].
databaseName
The name of database, for which you want to change transactions journaling mode. If nil, than main database is used.
error
If an error occurs, upon return contains an [DBCError][DBCErrorCR] object that describes the problem. Pass NULL, if you do not want error information.
Return value
YES, if transaction journaling mode was successfully changed, otherwise - NO.
Discussion
Journal files used by [SQLite][SQLitews] to roll back transactions or if unrecoverable error was encountered. Basically journal required for all SQL statements which change database structure or values.
By default value set to DBCDatabaseJournalingModeDelete.
How to use
In this example, we will use results from one of [examples][DBCDatabaseBasicExample], shown earlier in [DBCDatabase Class Reference][DBCDatabaseCR].
In this example I'll show you how to set custom transaction journaling mode for specific database:
error = nil;
[db setJournalMode:DBCDatabaseJournalingModeTruncate forDatabase:@"main" error:&error];
if(error != nil){
// Hmm, something went wrong, try to log out an error to find out something useful. Or you can set a flag
for DBCUseDebugLogger in DBCConfiguration.h, than DBConnect will log out all debug information.
NSLog(@"Occurred an error: %@", error);
}
See Also
- setJournalMode:error:
- journalModeError:
- journalModeForDatabase:error:
This method allows you to retrieve transaction journaling mode for specific database.
- (DBCDatabaseJournalingMode)journalModeForDatabase:(NSString*)databaseName error:(DBCError**)error
Parameters
databaseName
The name of database, for which you want to retrieve transactions journaling mode. If nil, than main database is used.
error
If an error occurs, upon return contains an [DBCError][DBCErrorCR] object that describes the problem. Pass NULL, if you do not want error information.
Return value
Transaction [journaling mode][ConstantsJournalingMode] for specified database.
How to use
In this example, we will use results from one of [examples][DBCDatabaseBasicExample], shown earlier in [DBCDatabase Class Reference][DBCDatabaseCR].
In this example I'll show you how to retrieve journaling mode for specific database:
error = nil;
DBCDatabaseJournalingMode journalingMode = [db journalModeForDatabase:@"main" error:&error];
if(error != nil){
// Hmm, something went wrong, try to log out an error to find out something useful. Or you can set a flag
for DBCUseDebugLogger in DBCConfiguration.h, than DBConnect will log out all debug information.
NSLog(@"Occurred an error: %@", error);
}
See Also
- setJournalMode:error:
- journalModeError:
- setJournalMode:forDatabase:error:
setJournalSizeLimitForDatabase:size:error:
This method allows you to set default journal size limit for specified database.
- (BOOL)setJournalSizeLimitForDatabase:(NSString*)databaseName size:(long long int)newJournalSizeLimit
error:(DBCError**)error
Parameters
databaseName
The name of database, for which you want to change transactions journal size. If nil, than main database is used.
newJournalSizeLimit
New journal size in bytes.
error
If an error occurs, upon return contains an [DBCError][DBCErrorCR] object that describes the problem. Pass NULL, if you do not want error information.
Return value
YES, if transaction journal size was successfully changed, otherwise - NO.
Discussion
Forces the partial deletion of large journal files that would otherwise be left in place. By default journaling mode set to [DBCDatabaseJournalingModeDelete][ConstantsJournalingModeDelete] and journal will be removed as soon as transaction will be completed. But if journaling mode set to one of persistent modes, than file will be kept and will grown all the time.
This value applied per database.
By default value set to -1.
How to use
In this example, we will use results from one of [examples][DBCDatabaseBasicExample], shown earlier in [DBCDatabase Class Reference][DBCDatabaseCR].
In this example we will change transaction journaling size to 4096 bytes for specific database:
error = nil;
[db setJournalSizeLimitForDatabase:@"main" size:4096 error:&error];
if(error != nil){
// Hmm, something went wrong, try to log out an error to find out something useful. Or you can set a flag
for DBCUseDebugLogger in DBCConfiguration.h, than DBConnect will log out all debug information.
NSLog(@"Occurred an error: %@", error);
}
See Also
- journalSizeLimitForDatabase:error:
journalSizeLimitForDatabase:error:
This method allows you to retrieve default journal size limit for specified database.
- (long long int)journalSizeLimitForDatabase:(NSString*)databaseName error:(DBCError**)error
Parameters
databaseName
The name of database, for which you want to retrieve transactions journal size. If nil, than main database is used.
error
If an error occurs, upon return contains an [DBCError][DBCErrorCR] object that describes the problem. Pass NULL, if you do not want error information.
Return value
Transaction journal size for specified database in bytes.
How to use
In this example, we will use results from one of [examples][DBCDatabaseBasicExample], shown earlier in [DBCDatabase Class Reference][DBCDatabaseCR].
Here I'll show how to retrieve journal size limit for specific database:
error = nil;
long long int journalSizeLimit = [db journalSizeLimitForDatabase:@"main" error:&error];
if(error != nil){
// Hmm, something went wrong, try to log out an error to find out something useful. Or you can set a flag
for DBCUseDebugLogger in DBCConfiguration.h, than DBConnect will log out all debug information.
NSLog(@"Occurred an error: %@", error);
}
See Also
- journalSizeLimitForDatabase:error:
This method allows you to set default database file locking mode.
- (BOOL)setLockingMode:(DBCDatabaseLockingMode)lockingMode error:(DBCError**)error
Parameters
lockingMode
New [locking mode][ConstantsLockingMode].
error
If an error occurs, upon return contains an [DBCError][DBCErrorCR] object that describes the problem. Pass NULL, if you do not want error information.
Return value
YES, if database file locking mode was successfully changed, otherwise - NO.
Discussion
All existing databases won't be modified. To change locking mode for specific (existing) database use setLockingMode:forDatabase:error: instead.
By default value set to DBCDatabaseLockingModeNormal.
How to use
In this example, we will use results from one of [examples][DBCDatabaseBasicExample], shown earlier in [DBCDatabase Class Reference][DBCDatabaseCR].
Here I'll show how to change database file [locking mode][ConstantsLockingMode] to normal which won't lock file until it should perform some queries on it. This mode will be set by default for all newly attached databases:
error = nil;
[db setLockingMode:DBCDatabaseLockingModeNormal error:&error];
if(error != nil){
// Hmm, something went wrong, try to log out an error to find out something useful. Or you can set a flag
for DBCUseDebugLogger in DBCConfiguration.h, than DBConnect will log out all debug information.
NSLog(@"Occurred an error: %@", error);
}
See Also
- lockingModeError:
- setLockingMode:forDatabase:error:
- lockingModeForDatabase:error:
- setOmitReadlockLike:error:
- omitReadlockError:
This method allows you to retrieve default database file locking mode.
- (DBCDatabaseLockingMode)lockingModeError:(DBCError**)error
Parameters
error
If an error occurs, upon return contains an [DBCError][DBCErrorCR] object that describes the problem. Pass NULL, if you do not want error information.
Return value
Default database file [locking mode][ConstantsLockingMode].
How to use
In this example, we will use results from one of [examples][DBCDatabaseBasicExample], shown earlier in [DBCDatabase Class Reference][DBCDatabaseCR].
Here I'll show you how to retrieve default [locking mode][ConstantsLockingMode]:
error = nil;
DBCDatabaseLockingMode lockingMode = [db lockingModeError:&error];
if(error != nil){
// Hmm, something went wrong, try to log out an error to find out something useful. Or you can set a flag
for DBCUseDebugLogger in DBCConfiguration.h, than DBConnect will log out all debug information.
NSLog(@"Occurred an error: %@", error);
}
See Also
- setLockingMode:error:
- setLockingMode:forDatabase:error:
- lockingModeForDatabase:error:
- setOmitReadlockLike:error:
- omitReadlockError:
setLockingMode:forDatabase:error:
This method allows you to change specified database locking mode.
- (BOOL)setLockingMode:(DBCDatabaseLockingMode)lockingMode forDatabase:(NSString*)databaseName
error:(DBCError**)error
Parameters
lockingMode
New [locking mode][ConstantsLockingMode].
databaseName
The name of database, for which you want to change locking mode. If nil, than main database is used.
error
If an error occurs, upon return contains an [DBCError][DBCErrorCR] object that describes the problem. Pass NULL, if you do not want error information.
Return value
YES, if database file locking mode was successfully changed, otherwise - NO.
Discussion
This will affect only specific database and rest will be untouched. If you wish to change locking mode by default for all newly attached databases use setLockingMode:error: instead.
By default value set to DBCDatabaseLockingModeNormal.
How to use
In this example, we will use results from one of [examples][DBCDatabaseBasicExample], shown earlier in [DBCDatabase Class Reference][DBCDatabaseCR].
Here I'll show how to change database file [locking mode][ConstantsLockingMode] to normal which won't lock file until it should perform some queries on it. This mode will be set for specific database:
error = nil;
[db setLockingMode:DBCDatabaseLockingModeNormal forDatabase:@"main" error:&error];
if(error != nil){
// Hmm, something went wrong, try to log out an error to find out something useful. Or you can set a flag
for DBCUseDebugLogger in DBCConfiguration.h, than DBConnect will log out all debug information.
NSLog(@"Occurred an error: %@", error);
}
See Also
- setLockingMode:error:
- lockingModeError:
- lockingModeForDatabase:error:
- setOmitReadlockLike:error:
- omitReadlockError:
This method allows you to retrieve locking mode for specified database.
- (DBCDatabaseLockingMode)lockingModeForDatabase:(NSString*)databaseName error:(DBCError**)error
Parameters
databaseName
The name of database, for which you want to retrieve locking mode. If nil, than main database is used.
error
If an error occurs, upon return contains an [DBCError][DBCErrorCR] object that describes the problem. Pass NULL, if you do not want error information.
Return value
Specified database file [locking mode][ConstantsLockingMode].
How to use
In this example, we will use results from one of [examples][DBCDatabaseBasicExample], shown earlier in [DBCDatabase Class Reference][DBCDatabaseCR].
Here I'll show you how to retrieve [locking mode][ConstantsLockingMode] for specific database:
error = nil;
DBCDatabaseLockingMode lockingMode = [db lockingModeForDatabase:@"main" error:&error];
if(error != nil){
// Hmm, something went wrong, try to log out an error to find out something useful. Or you can set a flag
for DBCUseDebugLogger in DBCConfiguration.h, than DBConnect will log out all debug information.
NSLog(@"Occurred an error: %@", error);
}
See Also
- setLockingMode:error:
- lockingModeError:
- setLockingMode:forDatabase:error:
- setOmitReadlockLike:error:
- omitReadlockError:
This method allows you to enable or disable database read locking for read-only access.
- (BOOL)setOmitReadlockLike:(BOOL)omit error:(DBCError**)error
Parameters
databaseName
New locking flag state.
error
If an error occurs, upon return contains an [DBCError][DBCErrorCR] object that describes the problem. Pass NULL, if you do not want error information.
Return value
YES, if database read lock was successfully changed, otherwise - NO.
Discussion
This method allows to increase performance by disabling database read locks for connections which was opened with read-only access. You should ensure what all processes will access in read-only mode before disabling read locks.
Specify YES, if you wish do disable read locks.
How to use
In this example, we will use results from one of [examples][DBCDatabaseBasicExample], shown earlier in [DBCDatabase Class Reference][DBCDatabaseCR].
In this example I'll show you how to disable file locking for read operations:
error = nil;
[db setOmitReadlockLike:YES error:&error];
if(error != nil){
// Hmm, something went wrong, try to log out an error to find out something useful. Or you can set a flag
for DBCUseDebugLogger in DBCConfiguration.h, than DBConnect will log out all debug information.
NSLog(@"Occurred an error: %@", error);
}
See Also
- setLockingMode:error:
- lockingModeError:
- setLockingMode:forDatabase:error:
- lockingModeForDatabase:error:
- omitReadlockError:
This method allows you to retrieve current state of read lock flag.
- (BOOL)omitReadlockError:(DBCError**)error
Parameters
error
If an error occurs, upon return contains an [DBCError][DBCErrorCR] object that describes the problem. Pass NULL, if you do not want error information.
Return value
YES, if database read lock is enabled, otherwise - NO.
Discussion
If YES than this means what read lock is disabled and connection which opened with read-only access will be able to retrieve data from file till other process performing requests on this database.
How to use
In this example, we will use results from one of [examples][DBCDatabaseBasicExample], shown earlier in [DBCDatabase Class Reference][DBCDatabaseCR].
Here I'll show you how to retrieve whether read lock was omitted or not:
error = nil;
BOOL omitLock = [db omitReadlockError:error:&error];
if(error != nil){
// Hmm, something went wrong, try to log out an error to find out something useful. Or you can set a flag
for DBCUseDebugLogger in DBCConfiguration.h, than DBConnect will log out all debug information.
NSLog(@"Occurred an error: %@", error);
}
See Also
- setLockingMode:error:
- lockingModeError:
- setLockingMode:forDatabase:error:
- lockingModeForDatabase:error:
- setOmitReadlockLike:error:
registerModule:moduleName:userData:cleanupFunction:error:
This method allows you to register virtual table (module).
- (BOOL)registerModule:(const sqlite3_module*)module moduleName:(NSString*)moduleName userData:(void*)userData
cleanupFunction:(void(*)(void*))cleanupFunction error:(DBCError**)error
Parameters
module
SQL [virtual table structure][SQLiteModule].
moduleName
New module name.
userData
User data passed to module.
cleanupFunction
Function used to cleanup all retained resources. Pass NULL if you don't want use it.
error
If an error occurs, upon return contains an [DBCError][DBCErrorCR] object that describes the problem. Pass NULL, if you do not want error information.
Return value
YES, if module was successfully registered, otherwise - NO.
Discussion
This method allows to register own virtual tables (modules) which you can later use in your SQL statements to perform some additional actions or define specific behavior.
I'm recommend you to read some tutorials about creation one of internal or external modules.
registerScalarFunction:functionName:parametersCount:textValueRepresentation:userData:error:
This method allows you to register user defined scalar function.
- (BOOL)registerScalarFunction:(void(*)(sqlite3_context*, int, sqlite3_value**))function
functionName:(NSString*)fnName parametersCount:(int)fnParametersCount
textValueRepresentation:(int)expectedTextValueRepresentation userData:(void*)fnUserData
error:(DBCError**)error
Parameters
function
User defined scalar C function pointer.
fnName
Scalar function name.
fnParametersCount
Number of parameters what should be provided when calling function from SQL statement. If value is negative then variable parameters count is assumed.
expectedTextValueRepresentation
Expected representation for text values passed into the function, and can be one of SQLITE_UTF8, SQLITE_UTF16, SQLITE_UTF16BE, SQLITE_UTF16LE, or SQLITE_ANY.
fnUserData
The pointer to user data which.
error
If an error occurs, upon return contains an [DBCError][DBCErrorCR] object that describes the problem. Pass NULL, if you do not want error information.
Return value
YES, if scalar function was successfully registered, otherwise - NO.
Discussion
Scalar function may take multiple parameters, but return only one: integer or string.
You can use few functions with same name, but they should have different fnParametersCount.
I'm recommend you to read some tutorials about creation one of internal or external modules.
See Also
- unRegisterScalarFunction:parametersCount:textValueRepresentation:error:
- registerAggregationFunction:finalizeFunction:functionName:parametersCount:textValueRepresentation:userData:error:
- unRegisterAggregationFunction:parametersCount:textValueRepresentation:error:
- registerCollationFunction:cleanupFunction:functionName:textValueRepresentation:userData:error:
- unRegisterCollationFunction:textValueRepresentation:error:
unRegisterScalarFunction:parametersCount:textValueRepresentation:error:
This method allows you to unregister user defined scalar function.
- (BOOL)unRegisterScalarFunction:(NSString*)fnName parametersCount:(int)fnParametersCount
textValueRepresentation:(int)expectedTextValueRepresentation error:(DBCError**)error
Parameters
fnName
Scalar function name, which was used during registration.
fnParametersCount
Number of parameters what should be provided when calling function from SQL statement. If value is negative then variable parameters count is assumed.
expectedTextValueRepresentation
Expected representation for text values passed into the function, and can be one of SQLITE_UTF8, SQLITE_UTF16, SQLITE_UTF16BE, SQLITE_UTF16LE, or SQLITE_ANY.
error
If an error occurs, upon return contains an [DBCError][DBCErrorCR] object that describes the problem. Pass NULL, if you do not want error information.
Return value
YES, if scalar function was successfully unregistered, otherwise - NO.
Discussion
After function was unregistered you can't use it in SQL statements.
See Also
- registerScalarFunction:functionName:parametersCount:textValueRepresentation:userData:error:
- registerAggregationFunction:finalizeFunction:functionName:parametersCount:textValueRepresentation:userData:error:
- unRegisterAggregationFunction:parametersCount:textValueRepresentation:error:
- registerCollationFunction:cleanupFunction:functionName:textValueRepresentation:userData:error:
- unRegisterCollationFunction:textValueRepresentation:error:
registerAggregationFunction:finalizeFunction:functionName:parametersCount:textValueRepresentation:userData:error:
This method allows you to register user defined aggregation function.
- (BOOL)registerAggregationFunction:(void(*)(sqlite3_context*, int, sqlite3_value**))stepFunction
finalizeFunction:(void(*)(sqlite3_context*))finalizeFunction functionName:(NSString*)fnName
parametersCount:(int)fnParametersCount
textValueRepresentation:(int)expectedTextValueRepresentation userData:(void*)fnUserData
error:(DBCError**)error
Parameters
stepFunction
User defined step C function pointer.
finalizeFunction
User defined finalize C function pointer.
fnName
Scalar function name.
fnParametersCount
Number of parameters what should be provided when calling function from SQL statement. If value is negative then variable parameters count is assumed.
expectedTextValueRepresentation
Expected representation for text values passed into the function, and can be one of SQLITE_UTF8, SQLITE_UTF16, SQLITE_UTF16BE, SQLITE_UTF16LE, or SQLITE_ANY.
fnUserData
The pointer to user data which.
error
If an error occurs, upon return contains an [DBCError][DBCErrorCR] object that describes the problem. Pass NULL, if you do not want error information.
Return value
YES, if aggregation function was successfully registered, otherwise - NO.
Discussion
Aggregate functions are used to collapse values from a grouping of rows into a single result value.
You can use few functions with same name, but they should have different fnParametersCount.
I'm recommend you to read some tutorials about creation one of internal or external modules.
See Also
- registerScalarFunction:functionName:parametersCount:textValueRepresentation:userData:error:
- unRegisterScalarFunction:parametersCount:textValueRepresentation:error:
- unRegisterAggregationFunction:parametersCount:textValueRepresentation:error:
- registerCollationFunction:cleanupFunction:functionName:textValueRepresentation:userData:error:
- unRegisterCollationFunction:textValueRepresentation:error:
unRegisterAggregationFunction:parametersCount:textValueRepresentation:error:
This method allows you to unregister user defined aggregation function.
- (BOOL)unRegisterAggregationFunction:(NSString*)fnName parametersCount:(int)fnParametersCount
textValueRepresentation:(int)expectedTextValueRepresentation
error:(DBCError**)error
Parameters
fnName
Collation function name, which was used during registration.
fnParametersCount
Number of parameters what should be provided when calling function from SQL statement. If value is negative then variable parameters count is assumed.
expectedTextValueRepresentation
Expected representation for text values passed into the function, and can be one of SQLITE_UTF8, SQLITE_UTF16, SQLITE_UTF16BE, SQLITE_UTF16LE, or SQLITE_ANY.
error
If an error occurs, upon return contains an [DBCError][DBCErrorCR] object that describes the problem. Pass NULL, if you do not want error information.
Return value
YES, if aggregation function was successfully registered, otherwise - NO.
Discussion
After function was unregistered you can't use it in SQL statements.
You can use few functions with same name, but they should have different fnParametersCount.
See Also
- registerScalarFunction:functionName:parametersCount:textValueRepresentation:userData:error:
- unRegisterScalarFunction:parametersCount:textValueRepresentation:error:
- registerAggregationFunction:finalizeFunction:functionName:parametersCount:textValueRepresentation:userData:error:
- registerCollationFunction:cleanupFunction:functionName:textValueRepresentation:userData:error:
- unRegisterCollationFunction:textValueRepresentation:error:
registerCollationFunction:cleanupFunction:functionName:textValueRepresentation:userData:error:
This method allows you to register user defined collation function.
- (BOOL)registerCollationFunction:(int(*)(void*, int, const void*, int, const void*))function
cleanupFunction:(void(*)(void*))cleanupFunction functionName:(NSString*)fnName
textValueRepresentation:(int)expectedTextValueRepresentation userData:(void*)fnUserData
error:(DBCError**)error
Parameters
function
User defined collation C function pointer.
cleanupFunction
Function used to cleanup all retained resources. Pass NULL if you don't want use it.
fnName
Scalar function name.
fnParametersCount
Number of parameters what should be provided when calling function from SQL statement. If value is negative then variable parameters count is assumed.
expectedTextValueRepresentation
Expected representation for text values passed into the function, and can be one of SQLITE_UTF8, SQLITE_UTF16, SQLITE_UTF16BE, SQLITE_UTF16LE, or SQLITE_ANY.
fnUserData
The pointer to user data which.
error
If an error occurs, upon return contains an [DBCError][DBCErrorCR] object that describes the problem. Pass NULL, if you do not want error information.
Return value
YES, if collation function was successfully registered, otherwise - NO.
Discussion
Collations are used to sort text values.
You can use few functions with same name, but they should have different fnParametersCount.
I'm recommend you to read some tutorials about creation one of internal or external modules.
See Also
- registerScalarFunction:functionName:parametersCount:textValueRepresentation:userData:error:
- unRegisterScalarFunction:parametersCount:textValueRepresentation:error:
- registerAggregationFunction:finalizeFunction:functionName:parametersCount:textValueRepresentation:userData:error:
- unRegisterAggregationFunction:parametersCount:textValueRepresentation:error:
- unRegisterCollationFunction:textValueRepresentation:error:
unRegisterCollationFunction:textValueRepresentation:error:
This method allows you to unregister user defined collation function.
- (BOOL)unRegisterCollationFunction:(NSString*)fnName
textValueRepresentation:(int)expectedTextValueRepresentation
error:(DBCError**)error
Parameters
fnName
Collation function name, which was used during registration.
expectedTextValueRepresentation
Expected representation for text values passed into the function, and can be one of SQLITE_UTF8, SQLITE_UTF16, SQLITE_UTF16BE, SQLITE_UTF16LE, or SQLITE_ANY.
error
If an error occurs, upon return contains an [DBCError][DBCErrorCR] object that describes the problem. Pass NULL, if you do not want error information.
Return value
YES, if collation function was successfully unregistered, otherwise - NO.
Discussion
After function was unregistered you can't use it in SQL statements.
See Also
- registerScalarFunction:functionName:parametersCount:textValueRepresentation:userData:error:
- unRegisterScalarFunction:parametersCount:textValueRepresentation:error:
- registerAggregationFunction:finalizeFunction:functionName:parametersCount:textValueRepresentation:userData:error:
- unRegisterAggregationFunction:parametersCount:textValueRepresentation:error:
- registerCollationFunction:cleanupFunction:functionName:textValueRepresentation:userData:error: