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 _corrupt;
  69     BOOL _traced;
  70 }
  71
  72 - (instancetype)initWithPath:(NSString *)path schema:(NSString *)schema;
  73
  74 @property (nonatomic, readonly, strong) NSString   *path;
  75 @property (nonatomic, readonly, strong) NSString   *schema;
  76 @property (nonatomic, readonly, strong) NSString   *schemaVersion;
  77 @property (nonatomic, strong)           NSString   *objectClassPrefix;
  78 @property (nonatomic, assign)           SInt32     userVersion;
  79 @property (nonatomic, assign)           SFSQLiteSynchronousMode synchronousMode;
  80 @property (nonatomic, readonly)         BOOL       isOpen;
  81 @property (nonatomic, readonly)         BOOL       hasMigrated;
  82 @property (nonatomic, assign)           BOOL       traced;
  83
  84 @property (nonatomic, strong) id<SFSQLiteDelegate> delegate;
  85
  86 #if DEBUG
  87 @property (nonatomic, strong) NSDictionary* unitTestOverrides;
  88 #endif
  89
  90 // Open/close the underlying database file read/write. Initially, the database is closed.
  91 - (void)open;
  92 - (BOOL)openWithError:(NSError **)error;
  93 - (void)close;
  94
  95 // Remove the database file.
  96 - (void)remove;
  97
  98 // Database exclusive transaction operations.
  99 - (void)begin;
 100 - (void)end;
 101 - (void)rollback;
 102
 103 // Database maintenance.
 104 - (void)analyze;
 105 - (void)vacuum;
 106
 107 // The rowID assigned to the last record inserted into the database.
 108 - (SFSQLiteRowID)lastInsertRowID;
 109
 110 // returns the number of rows modified, inserted or deleted by the most recently completed INSERT, UPDATE or DELETE statement on the database connection
 111 - (int)changes;
 112
 113 // Execute one-or-more queries. Use prepared statements for anything performance critical.
 114 - (BOOL)executeSQL:(NSString *)format, ... NS_FORMAT_FUNCTION(1, 2);
 115 - (BOOL)executeSQL:(NSString *)format arguments:(va_list)args NS_FORMAT_FUNCTION(1, 0);
 116
 117 // Prepared statement pool accessors. Statements must be reset after they're used.
 118 - (SFSQLiteStatement *)statementForSQL:(NSString *)SQL;
 119 - (void)removeAllStatements;
 120
 121 // Accessors for all the tables created in the database.
 122 - (NSArray *)allTableNames;
 123 - (void)dropAllTables;
 124
 125 // Generic key/value properties set in the database.
 126 - (NSString *)propertyForKey:(NSString *)key;
 127 - (void)setProperty:(NSString *)value forKey:(NSString *)key;
 128 - (NSDate *)datePropertyForKey:(NSString *)key;
 129 - (void)setDateProperty:(NSDate *)value forKey:(NSString *)key;
 130 - (void)removePropertyForKey:(NSString *)key;
 131
 132 // Date the cache was created.
 133 - (NSDate *)creationDate;
 134
 135 // Convience calls that generate and execute statements.
 136 - (NSArray *)selectAllFrom:(NSString *)tableName where:(NSString *)whereSQL bindings:(NSArray *)bindings;
 137 - (NSArray *)select:(NSArray *)columns from:(NSString *)tableName;
 138 - (NSArray *)select:(NSArray *)columns from:(NSString *)tableName where:(NSString *)whereSQL bindings:(NSArray *)bindings;
 139 - (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;
 140 - (void)selectFrom:(NSString *)tableName where:(NSString *)whereSQL bindings:(NSArray *)bindings orderBy:(NSArray *)orderBy limit:(NSNumber *)limit block:(void (^)(NSDictionary *resultDictionary, BOOL *stop))block;
 141 - (NSUInteger)selectCountFrom:(NSString *)tableName  where:(NSString *)whereSQL bindings:(NSArray *)bindings;
 142 - (SFSQLiteRowID)insertOrReplaceInto:(NSString *)tableName values:(NSDictionary *)valuesByColumnName;
 143 - (void)deleteFrom:(NSString *)tableName where:(NSString *)whereSQL bindings:(NSArray *)bindings;
 144 - (void)update:(NSString *)tableName set:(NSString *)setSQL where:(NSString *)whereSQL bindings:(NSArray *)whereBindings limit:(NSNumber *)limit;
 145 - (void)deleteFrom:(NSString *)tableName matchingValues:(NSDictionary *)valuesByColumnName;
 146 - (NSSet<NSString*> *)columnNamesForTable:(NSString*)tableName;
 147
 148 - (SInt32)dbUserVersion;
 149
 150 @end
 151
 152 #endif