169 lines
7.0 KiB
C
169 lines
7.0 KiB
C
/*
|
|
** 2017 April 07
|
|
**
|
|
** The author disclaims copyright to this source code. In place of
|
|
** a legal notice, here is a blessing:
|
|
**
|
|
** May you do good and not evil.
|
|
** May you find forgiveness for yourself and forgive others.
|
|
** May you share freely, never taking more than you give.
|
|
**
|
|
*************************************************************************
|
|
*/
|
|
#if !defined(SQLITEEXPERT_H)
|
|
#define SQLITEEXPERT_H 1
|
|
#include "sqlite3.h"
|
|
|
|
typedef struct sqlite3expert sqlite3expert;
|
|
|
|
/*
|
|
** Create a new sqlite3expert object.
|
|
**
|
|
** If successful, a pointer to the new object is returned and (*pzErr) set
|
|
** to NULL. Or, if an error occurs, NULL is returned and (*pzErr) set to
|
|
** an English-language error message. In this case it is the responsibility
|
|
** of the caller to eventually free the error message buffer using
|
|
** sqlite3_free().
|
|
*/
|
|
sqlite3expert *sqlite3_expert_new(sqlite3 *db, char **pzErr);
|
|
|
|
/*
|
|
** Configure an sqlite3expert object.
|
|
**
|
|
** EXPERT_CONFIG_SAMPLE:
|
|
** By default, sqlite3_expert_analyze() generates sqlite_stat1 data for
|
|
** each candidate index. This involves scanning and sorting the entire
|
|
** contents of each user database table once for each candidate index
|
|
** associated with the table. For large databases, this can be
|
|
** prohibitively slow. This option allows the sqlite3expert object to
|
|
** be configured so that sqlite_stat1 data is instead generated based on a
|
|
** subset of each table, or so that no sqlite_stat1 data is used at all.
|
|
**
|
|
** A single integer argument is passed to this option. If the value is less
|
|
** than or equal to zero, then no sqlite_stat1 data is generated or used by
|
|
** the analysis - indexes are recommended based on the database schema only.
|
|
** Or, if the value is 100 or greater, complete sqlite_stat1 data is
|
|
** generated for each candidate index (this is the default). Finally, if the
|
|
** value falls between 0 and 100, then it represents the percentage of user
|
|
** table rows that should be considered when generating sqlite_stat1 data.
|
|
**
|
|
** Examples:
|
|
**
|
|
** // Do not generate any sqlite_stat1 data
|
|
** sqlite3_expert_config(pExpert, EXPERT_CONFIG_SAMPLE, 0);
|
|
**
|
|
** // Generate sqlite_stat1 data based on 10% of the rows in each table.
|
|
** sqlite3_expert_config(pExpert, EXPERT_CONFIG_SAMPLE, 10);
|
|
*/
|
|
int sqlite3_expert_config(sqlite3expert *p, int op, ...);
|
|
|
|
#define EXPERT_CONFIG_SAMPLE 1 /* int */
|
|
|
|
/*
|
|
** Specify zero or more SQL statements to be included in the analysis.
|
|
**
|
|
** Buffer zSql must contain zero or more complete SQL statements. This
|
|
** function parses all statements contained in the buffer and adds them
|
|
** to the internal list of statements to analyze. If successful, SQLITE_OK
|
|
** is returned and (*pzErr) set to NULL. Or, if an error occurs - for example
|
|
** due to a error in the SQL - an SQLite error code is returned and (*pzErr)
|
|
** may be set to point to an English language error message. In this case
|
|
** the caller is responsible for eventually freeing the error message buffer
|
|
** using sqlite3_free().
|
|
**
|
|
** If an error does occur while processing one of the statements in the
|
|
** buffer passed as the second argument, none of the statements in the
|
|
** buffer are added to the analysis.
|
|
**
|
|
** This function must be called before sqlite3_expert_analyze(). If a call
|
|
** to this function is made on an sqlite3expert object that has already
|
|
** been passed to sqlite3_expert_analyze() SQLITE_MISUSE is returned
|
|
** immediately and no statements are added to the analysis.
|
|
*/
|
|
int sqlite3_expert_sql(
|
|
sqlite3expert *p, /* From a successful sqlite3_expert_new() */
|
|
const char *zSql, /* SQL statement(s) to add */
|
|
char **pzErr /* OUT: Error message (if any) */
|
|
);
|
|
|
|
|
|
/*
|
|
** This function is called after the sqlite3expert object has been configured
|
|
** with all SQL statements using sqlite3_expert_sql() to actually perform
|
|
** the analysis. Once this function has been called, it is not possible to
|
|
** add further SQL statements to the analysis.
|
|
**
|
|
** If successful, SQLITE_OK is returned and (*pzErr) is set to NULL. Or, if
|
|
** an error occurs, an SQLite error code is returned and (*pzErr) set to
|
|
** point to a buffer containing an English language error message. In this
|
|
** case it is the responsibility of the caller to eventually free the buffer
|
|
** using sqlite3_free().
|
|
**
|
|
** If an error does occur within this function, the sqlite3expert object
|
|
** is no longer useful for any purpose. At that point it is no longer
|
|
** possible to add further SQL statements to the object or to re-attempt
|
|
** the analysis. The sqlite3expert object must still be freed using a call
|
|
** sqlite3_expert_destroy().
|
|
*/
|
|
int sqlite3_expert_analyze(sqlite3expert *p, char **pzErr);
|
|
|
|
/*
|
|
** Return the total number of statements loaded using sqlite3_expert_sql().
|
|
** The total number of SQL statements may be different from the total number
|
|
** to calls to sqlite3_expert_sql().
|
|
*/
|
|
int sqlite3_expert_count(sqlite3expert*);
|
|
|
|
/*
|
|
** Return a component of the report.
|
|
**
|
|
** This function is called after sqlite3_expert_analyze() to extract the
|
|
** results of the analysis. Each call to this function returns either a
|
|
** NULL pointer or a pointer to a buffer containing a nul-terminated string.
|
|
** The value passed as the third argument must be one of the EXPERT_REPORT_*
|
|
** #define constants defined below.
|
|
**
|
|
** For some EXPERT_REPORT_* parameters, the buffer returned contains
|
|
** information relating to a specific SQL statement. In these cases that
|
|
** SQL statement is identified by the value passed as the second argument.
|
|
** SQL statements are numbered from 0 in the order in which they are parsed.
|
|
** If an out-of-range value (less than zero or equal to or greater than the
|
|
** value returned by sqlite3_expert_count()) is passed as the second argument
|
|
** along with such an EXPERT_REPORT_* parameter, NULL is always returned.
|
|
**
|
|
** EXPERT_REPORT_SQL:
|
|
** Return the text of SQL statement iStmt.
|
|
**
|
|
** EXPERT_REPORT_INDEXES:
|
|
** Return a buffer containing the CREATE INDEX statements for all recommended
|
|
** indexes for statement iStmt. If there are no new recommeded indexes, NULL
|
|
** is returned.
|
|
**
|
|
** EXPERT_REPORT_PLAN:
|
|
** Return a buffer containing the EXPLAIN QUERY PLAN output for SQL query
|
|
** iStmt after the proposed indexes have been added to the database schema.
|
|
**
|
|
** EXPERT_REPORT_CANDIDATES:
|
|
** Return a pointer to a buffer containing the CREATE INDEX statements
|
|
** for all indexes that were tested (for all SQL statements). The iStmt
|
|
** parameter is ignored for EXPERT_REPORT_CANDIDATES calls.
|
|
*/
|
|
const char *sqlite3_expert_report(sqlite3expert*, int iStmt, int eReport);
|
|
|
|
/*
|
|
** Values for the third argument passed to sqlite3_expert_report().
|
|
*/
|
|
#define EXPERT_REPORT_SQL 1
|
|
#define EXPERT_REPORT_INDEXES 2
|
|
#define EXPERT_REPORT_PLAN 3
|
|
#define EXPERT_REPORT_CANDIDATES 4
|
|
|
|
/*
|
|
** Free an (sqlite3expert*) handle and all associated resources. There
|
|
** should be one call to this function for each successful call to
|
|
** sqlite3-expert_new().
|
|
*/
|
|
void sqlite3_expert_destroy(sqlite3expert*);
|
|
|
|
#endif /* !defined(SQLITEEXPERT_H) */
|