1 /* 2 ** 2017 April 07 3 ** 4 ** The author disclaims copyright to this source code. In place of 5 ** a legal notice, here is a blessing: 6 ** 7 ** May you do good and not evil. 8 ** May you find forgiveness for yourself and forgive others. 9 ** May you share freely, never taking more than you give. 10 ** 11 ************************************************************************* 12 */ 13 14 15 #include "sqlite3.h" 16 17 typedef struct sqlite3expert sqlite3expert; 18 19 /* 20 ** Create a new sqlite3expert object. 21 ** 22 ** If successful, a pointer to the new object is returned and (*pzErr) set 23 ** to NULL. Or, if an error occurs, NULL is returned and (*pzErr) set to 24 ** an English-language error message. In this case it is the responsibility 25 ** of the caller to eventually free the error message buffer using 26 ** sqlite3_free(). 27 */ 28 sqlite3expert *sqlite3_expert_new(sqlite3 *db, char **pzErr); 29 30 /* 31 ** Specify zero or more SQL statements to be included in the analysis. 32 ** 33 ** Buffer zSql must contain zero or more complete SQL statements. This 34 ** function parses all statements contained in the buffer and adds them 35 ** to the internal list of statements to analyze. If successful, SQLITE_OK 36 ** is returned and (*pzErr) set to NULL. Or, if an error occurs - for example 37 ** due to a error in the SQL - an SQLite error code is returned and (*pzErr) 38 ** may be set to point to an English language error message. In this case 39 ** the caller is responsible for eventually freeing the error message buffer 40 ** using sqlite3_free(). 41 ** 42 ** If an error does occur while processing one of the statements in the 43 ** buffer passed as the second argument, none of the statements in the 44 ** buffer are added to the analysis. 45 ** 46 ** This function must be called before sqlite3_expert_analyze(). If a call 47 ** to this function is made on an sqlite3expert object that has already 48 ** been passed to sqlite3_expert_analyze() SQLITE_MISUSE is returned 49 ** immediately and no statements are added to the analysis. 50 */ 51 int sqlite3_expert_sql( 52 sqlite3expert *p, /* From a successful sqlite3_expert_new() */ 53 const char *zSql, /* SQL statement(s) to add */ 54 char **pzErr /* OUT: Error message (if any) */ 55 ); 56 57 /* 58 ** This function is called after the sqlite3expert object has been configured 59 ** with all SQL statements using sqlite3_expert_sql() to actually perform 60 ** the analysis. Once this function has been called, it is not possible to 61 ** add further SQL statements to the analysis. 62 ** 63 ** If successful, SQLITE_OK is returned and (*pzErr) is set to NULL. Or, if 64 ** an error occurs, an SQLite error code is returned and (*pzErr) set to 65 ** point to a buffer containing an English language error message. In this 66 ** case it is the responsibility of the caller to eventually free the buffer 67 ** using sqlite3_free(). 68 ** 69 ** If an error does occur within this function, the sqlite3expert object 70 ** is no longer useful for any purpose. At that point it is no longer 71 ** possible to add further SQL statements to the object or to re-attempt 72 ** the analysis. The sqlite3expert object must still be freed using a call 73 ** sqlite3_expert_destroy(). 74 */ 75 int sqlite3_expert_analyze(sqlite3expert *p, char **pzErr); 76 77 /* 78 ** Return the total number of statements loaded using sqlite3_expert_sql(). 79 ** The total number of SQL statements may be different from the total number 80 ** to calls to sqlite3_expert_sql(). 81 */ 82 int sqlite3_expert_count(sqlite3expert*); 83 84 /* 85 ** Return a component of the report. 86 ** 87 ** This function is called after sqlite3_expert_analyze() to extract the 88 ** results of the analysis. Each call to this function returns either a 89 ** NULL pointer or a pointer to a buffer containing a nul-terminated string. 90 ** The value passed as the third argument must be one of the EXPERT_REPORT_* 91 ** #define constants defined below. 92 ** 93 ** For some EXPERT_REPORT_* parameters, the buffer returned contains 94 ** information relating to a specific SQL statement. In these cases that 95 ** SQL statement is identified by the value passed as the second argument. 96 ** SQL statements are numbered from 0 in the order in which they are parsed. 97 ** If an out-of-range value (less than zero or equal to or greater than the 98 ** value returned by sqlite3_expert_count()) is passed as the second argument 99 ** along with such an EXPERT_REPORT_* parameter, NULL is always returned. 100 ** 101 ** EXPERT_REPORT_SQL: 102 ** Return the text of SQL statement iStmt. 103 ** 104 ** EXPERT_REPORT_INDEXES: 105 ** Return a buffer containing the CREATE INDEX statements for all recommended 106 ** indexes for statement iStmt. If there are no new recommeded indexes, NULL 107 ** is returned. 108 ** 109 ** EXPERT_REPORT_PLAN: 110 ** Return a buffer containing the EXPLAIN QUERY PLAN output for SQL query 111 ** iStmt after the proposed indexes have been added to the database schema. 112 ** 113 ** EXPERT_REPORT_CANDIDATES: 114 ** Return a pointer to a buffer containing the CREATE INDEX statements 115 ** for all indexes that were tested (for all SQL statements). The iStmt 116 ** parameter is ignored for EXPERT_REPORT_CANDIDATES calls. 117 */ 118 const char *sqlite3_expert_report(sqlite3expert*, int iStmt, int eReport); 119 120 /* 121 ** Values for the third argument passed to sqlite3_expert_report(). 122 */ 123 #define EXPERT_REPORT_SQL 1 124 #define EXPERT_REPORT_INDEXES 2 125 #define EXPERT_REPORT_PLAN 3 126 #define EXPERT_REPORT_CANDIDATES 4 127 128 /* 129 ** Free an (sqlite3expert*) handle and all associated resources. There 130 ** should be one call to this function for each successful call to 131 ** sqlite3-expert_new(). 132 */ 133 void sqlite3_expert_destroy(sqlite3expert*); 134 135 136