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 #if __OBJC2__
  27
  28 #import <Foundation/Foundation.h>
  29 #import <sqlite3.h>
  30
  31 @class SFSQLiteStatement;
  32
  33 typedef SInt64 SFSQLiteRowID;
  34 @class SFSQLite;
  35
  36 NSArray *SFSQLiteJournalSuffixes(void);
  37
  38 typedef NS_ENUM(NSInteger, SFSQLiteSynchronousMode) {
  39     SFSQLiteSynchronousModeOff = 0,
  40     SFSQLiteSynchronousModeNormal = 1, // default
  41     SFSQLiteSynchronousModeFull = 2
  42 };
  43
  44 @protocol SFSQLiteDelegate <NSObject>
  45 @property (nonatomic, readonly) SInt32 userVersion;
  46
  47 - (BOOL)migrateDatabase:(SFSQLite *)db fromVersion:(SInt32)version;
  48 @end
  49
  50 // Wrapper around the SQLite API. Typically subclassed to add table accessor methods.
  51 @interface SFSQLite : NSObject {
  52 @private
  53     id<SFSQLiteDelegate> _delegate;
  54     NSString* _path;
  55     NSString* _schema;
  56     NSString* _schemaVersion;
  57     NSMutableDictionary* _statementsBySQL;
  58     NSString* _objectClassPrefix;
  59     SFSQLiteSynchronousMode _synchronousMode;
  60     SInt32 _userVersion;
  61     sqlite3* _db;
  62     NSUInteger _openCount;
  63     NSDateFormatter* _dateFormatter;
  64 #if DEBUG
  65     NSMutableDictionary* _unitTestOverrides;
  66 #endif
  67     BOOL _hasMigrated;
  68     BOOL _shouldVacuum;
  69     BOOL _corrupt;
  70     BOOL _traced;
  71 }
  72
  73 - (instancetype)initWithPath:(NSString *)path schema:(NSString *)schema;
  74
  75 @property (nonatomic, readonly, strong) NSString   *path;
  76 @property (nonatomic, readonly, strong) NSString   *schema;
  77 @property (nonatomic, readonly, strong) NSString   *schemaVersion;
  78 @property (nonatomic, strong)           NSString   *objectClassPrefix;
  79 @property (nonatomic, assign)           SInt32     userVersion;
  80 @property (nonatomic, assign)           SFSQLiteSynchronousMode synchronousMode;
  81 @property (nonatomic, readonly)         BOOL       isOpen;
  82 @property (nonatomic, readonly)         BOOL       hasMigrated;
  83 @property (nonatomic, assign)           BOOL       shouldVacuum; // vacuum the db on open (default:YES)
  84 @property (nonatomic, assign)           BOOL       traced;
  85
  86 @property (nonatomic, strong) id<SFSQLiteDelegate> delegate;
  87
  88 #if DEBUG
  89 @property (nonatomic, strong) NSDictionary* unitTestOverrides;
  90 #endif
  91
  92 // Open/close the underlying database file read/write. Initially, the database is closed.
  93 - (void)open;
  94 - (BOOL)openWithError:(NSError **)error;
  95 - (void)close;
  96
  97 // Remove the database file.
  98 - (void)remove;
  99
 100 // Database exclusive transaction operations.
 101 - (void)begin;
 102 - (void)end;
 103 - (void)rollback;
 104
 105 // Database maintenance.
 106 - (void)analyze;
 107 - (void)vacuum;
 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 - (BOOL)executeSQL:(NSString *)format, ... NS_FORMAT_FUNCTION(1, 2);
 117 - (BOOL)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
 153
 154 #endif