Analytics/SQLite/SFSQLite.h

   1 /*
   2  * Copyright (c) 2017 Apple Inc. All Rights Reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. Please obtain a copy of the License at
  10  * http://www.opensource.apple.com/apsl/ and read it before using this
  11  * file.
  12  *
  13  * The Original Code and all software distributed under the License are
  14  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  15  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  16  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  17  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  18  * Please see the License for the specific language governing rights and
  19  * limitations under the License.
  20  *
  21  * @APPLE_LICENSE_HEADER_END@
  22  */
  23
  24 // Header exposed for unit testing only
  25
  26 #import <Foundation/Foundation.h>
  27 #import <sqlite3.h>
  28
  29 @class SFSQLiteStatement;
  30
  31 typedef SInt64 SFSQLiteRowID;
  32 @class SFSQLite;
  33
  34 NSArray *SFSQLiteJournalSuffixes(void);
  35
  36 typedef NS_ENUM(NSInteger, SFSQLiteSynchronousMode) {
  37     SFSQLiteSynchronousModeOff = 0,
  38     SFSQLiteSynchronousModeNormal = 1, // default
  39     SFSQLiteSynchronousModeFull = 2
  40 };
  41
  42 @protocol SFSQLiteDelegate
  43 @property (nonatomic, readonly) SInt32 userVersion;
  44
  45 - (BOOL)migrateDatabase:(SFSQLite *)db fromVersion:(SInt32)version;
  46 @end
  47
  48 // Wrapper around the SQLite API. Typically subclassed to add table accessor methods.
  49 @interface SFSQLite : NSObject {
  50     id<SFSQLiteDelegate> _delegate;
  51     NSString* _path;
  52     NSString* _schema;
  53     NSString* _schemaVersion;
  54     NSMutableDictionary* _statementsBySQL;
  55     NSString* _objectClassPrefix;
  56     SFSQLiteSynchronousMode _synchronousMode;
  57     SInt32 _userVersion;
  58     sqlite3* _db;
  59     NSUInteger _openCount;
  60     NSDateFormatter* _dateFormatter;
  61 #if DEBUG
  62     NSMutableDictionary* _unitTestOverrides;
  63 #endif
  64     BOOL _hasMigrated;
  65     BOOL _shouldVacuum;
  66     BOOL _corrupt;
  67     BOOL _traced;
  68 }
  69
  70 - (instancetype)initWithPath:(NSString *)path schema:(NSString *)schema;
  71
  72 @property (nonatomic, readonly, strong) NSString   *path;
  73 @property (nonatomic, readonly, strong) NSString   *schema;
  74 @property (nonatomic, readonly, strong) NSString   *schemaVersion;
  75 @property (nonatomic, strong)           NSString   *objectClassPrefix;
  76 @property (nonatomic, assign)           SInt32     userVersion;
  77 @property (nonatomic, assign)           SFSQLiteSynchronousMode synchronousMode;
  78 @property (nonatomic, readonly)         BOOL       isOpen;
  79 @property (nonatomic, readonly)         BOOL       hasMigrated;
  80 @property (nonatomic, assign)           BOOL       shouldVacuum; // vacuum the db on open (default:YES)
  81 @property (nonatomic, assign)           BOOL       traced;
  82
  83 @property (nonatomic, strong) id<SFSQLiteDelegate> delegate;
  84
  85 #if DEBUG
  86 @property (nonatomic, strong) NSDictionary* unitTestOverrides;
  87 #endif
  88
  89 // Open/close the underlying database file read/write. Initially, the database is closed.
  90 - (void)open;
  91 - (BOOL)openWithError:(NSError **)error;
  92 - (void)close;
  93
  94 // Remove the database file.
  95 - (void)remove;
  96
  97 // Database exclusive transaction operations.
  98 - (void)begin;
  99 - (void)end;
 100 - (void)rollback;
 101
 102 // Database maintenance.
 103 - (void)analyze;
 104 - (void)vacuum;
 105
 106 // Raise an exception. Including any database error in the description and removing the databse if it's corrupt.
 107 - (void)raise:(NSString *)format, ... NS_FORMAT_FUNCTION(1, 2);
 108
 109 // The rowID assigned to the last record inserted into the database.
 110 - (SFSQLiteRowID)lastInsertRowID;
 111
 112 // returns the number of rows modified, inserted or deleted by the most recently completed INSERT, UPDATE or DELETE statement on the database connection
 113 - (int)changes;
 114
 115 // Execute one-or-more queries. Use prepared statements for anything performance critical.
 116 - (void)executeSQL:(NSString *)format, ... NS_FORMAT_FUNCTION(1, 2);
 117 - (void)executeSQL:(NSString *)format arguments:(va_list)args NS_FORMAT_FUNCTION(1, 0);
 118
 119 // Prepared statement pool accessors. Statements must be reset after they're used.
 120 - (SFSQLiteStatement *)statementForSQL:(NSString *)SQL;
 121 - (void)removeAllStatements;
 122
 123 // Accessors for all the tables created in the database.
 124 - (NSArray *)allTableNames;
 125 - (void)dropAllTables;
 126
 127 // Generic key/value properties set in the database.
 128 - (NSString *)propertyForKey:(NSString *)key;
 129 - (void)setProperty:(NSString *)value forKey:(NSString *)key;
 130 - (NSDate *)datePropertyForKey:(NSString *)key;
 131 - (void)setDateProperty:(NSDate *)value forKey:(NSString *)key;
 132 - (void)removePropertyForKey:(NSString *)key;
 133
 134 // Date the cache was created.
 135 - (NSDate *)creationDate;
 136
 137 // Convience calls that generate and execute statements.
 138 - (NSArray *)selectAllFrom:(NSString *)tableName where:(NSString *)whereSQL bindings:(NSArray *)bindings;
 139 - (NSArray *)select:(NSArray *)columns from:(NSString *)tableName;
 140 - (NSArray *)select:(NSArray *)columns from:(NSString *)tableName where:(NSString *)whereSQL bindings:(NSArray *)bindings;
 141 - (void)select:(NSArray *)columns from:(NSString *)tableName where:(NSString *)whereSQL bindings:(NSArray *)bindings orderBy:(NSArray *)orderBy limit:(NSNumber *)limit block:(void (^)(NSDictionary *resultDictionary, BOOL *stop))block;
 142 - (void)selectFrom:(NSString *)tableName where:(NSString *)whereSQL bindings:(NSArray *)bindings orderBy:(NSArray *)orderBy limit:(NSNumber *)limit block:(void (^)(NSDictionary *resultDictionary, BOOL *stop))block;
 143 - (NSUInteger)selectCountFrom:(NSString *)tableName  where:(NSString *)whereSQL bindings:(NSArray *)bindings;
 144 - (SFSQLiteRowID)insertOrReplaceInto:(NSString *)tableName values:(NSDictionary *)valuesByColumnName;
 145 - (void)deleteFrom:(NSString *)tableName where:(NSString *)whereSQL bindings:(NSArray *)bindings;
 146 - (void)update:(NSString *)tableName set:(NSString *)setSQL where:(NSString *)whereSQL bindings:(NSArray *)whereBindings limit:(NSNumber *)limit;
 147 - (void)deleteFrom:(NSString *)tableName matchingValues:(NSDictionary *)valuesByColumnName;
 148 - (NSSet<NSString*> *)columnNamesForTable:(NSString*)tableName;
 149
 150 - (SInt32)dbUserVersion;
 151
 152 @end