| 1 |
/* |
| 2 |
** 2022-08-27 |
| 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 |
** This file contains the public interface to the "recover" extension - |
| 14 |
** an SQLite extension designed to recover data from corrupted database |
| 15 |
** files. |
| 16 |
*/ |
| 17 |
|
| 18 |
/* |
| 19 |
** OVERVIEW: |
| 20 |
** |
| 21 |
** To use the API to recover data from a corrupted database, an |
| 22 |
** application: |
| 23 |
** |
| 24 |
** 1) Creates an sqlite3_recover handle by calling either |
| 25 |
** sqlite3_recover_init() or sqlite3_recover_init_sql(). |
| 26 |
** |
| 27 |
** 2) Configures the new handle using one or more calls to |
| 28 |
** sqlite3_recover_config(). |
| 29 |
** |
| 30 |
** 3) Executes the recovery by repeatedly calling sqlite3_recover_step() on |
| 31 |
** the handle until it returns something other than SQLITE_OK. If it |
| 32 |
** returns SQLITE_DONE, then the recovery operation completed without |
| 33 |
** error. If it returns some other non-SQLITE_OK value, then an error |
| 34 |
** has occurred. |
| 35 |
** |
| 36 |
** 4) Retrieves any error code and English language error message using the |
| 37 |
** sqlite3_recover_errcode() and sqlite3_recover_errmsg() APIs, |
| 38 |
** respectively. |
| 39 |
** |
| 40 |
** 5) Destroys the sqlite3_recover handle and frees all resources |
| 41 |
** using sqlite3_recover_finish(). |
| 42 |
** |
| 43 |
** The application may abandon the recovery operation at any point |
| 44 |
** before it is finished by passing the sqlite3_recover handle to |
| 45 |
** sqlite3_recover_finish(). This is not an error, but the final state |
| 46 |
** of the output database, or the results of running the partial script |
| 47 |
** delivered to the SQL callback, are undefined. |
| 48 |
*/ |
| 49 |
|
| 50 |
#ifndef _SQLITE_RECOVER_H |
| 51 |
#define _SQLITE_RECOVER_H |
| 52 |
|
| 53 |
#include "sqlite3.h" |
| 54 |
|
| 55 |
#ifdef __cplusplus |
| 56 |
extern "C" { |
| 57 |
#endif |
| 58 |
|
| 59 |
/* |
| 60 |
** An instance of the sqlite3_recover object represents a recovery |
| 61 |
** operation in progress. |
| 62 |
** |
| 63 |
** Constructors: |
| 64 |
** |
| 65 |
** sqlite3_recover_init() |
| 66 |
** sqlite3_recover_init_sql() |
| 67 |
** |
| 68 |
** Destructor: |
| 69 |
** |
| 70 |
** sqlite3_recover_finish() |
| 71 |
** |
| 72 |
** Methods: |
| 73 |
** |
| 74 |
** sqlite3_recover_config() |
| 75 |
** sqlite3_recover_errcode() |
| 76 |
** sqlite3_recover_errmsg() |
| 77 |
** sqlite3_recover_run() |
| 78 |
** sqlite3_recover_step() |
| 79 |
*/ |
| 80 |
typedef struct sqlite3_recover sqlite3_recover; |
| 81 |
|
| 82 |
/* |
| 83 |
** These two APIs attempt to create and return a new sqlite3_recover object. |
| 84 |
** In both cases the first two arguments identify the (possibly |
| 85 |
** corrupt) database to recover data from. The first argument is an open |
| 86 |
** database handle and the second the name of a database attached to that |
| 87 |
** handle (i.e. "main", "temp" or the name of an attached database). |
| 88 |
** |
| 89 |
** If sqlite3_recover_init() is used to create the new sqlite3_recover |
| 90 |
** handle, then data is recovered into a new database, identified by |
| 91 |
** string parameter zUri. zUri may be an absolute or relative file path, |
| 92 |
** or may be an SQLite URI. If the identified database file already exists, |
| 93 |
** it is overwritten. |
| 94 |
** |
| 95 |
** If sqlite3_recover_init_sql() is invoked, then any recovered data will |
| 96 |
** be returned to the user as a series of SQL statements. Executing these |
| 97 |
** SQL statements results in the same database as would have been created |
| 98 |
** had sqlite3_recover_init() been used. For each SQL statement in the |
| 99 |
** output, the callback function passed as the third argument (xSql) is |
| 100 |
** invoked once. The first parameter is a passed a copy of the fourth argument |
| 101 |
** to this function (pCtx) as its first parameter, and a pointer to a |
| 102 |
** nul-terminated buffer containing the SQL statement formated as UTF-8 as |
| 103 |
** the second. If the xSql callback returns any value other than SQLITE_OK, |
| 104 |
** then processing is immediately abandoned and the value returned used as |
| 105 |
** the recover handle error code (see below). |
| 106 |
** |
| 107 |
** If an out-of-memory error occurs, NULL may be returned instead of |
| 108 |
** a valid handle. In all other cases, it is the responsibility of the |
| 109 |
** application to avoid resource leaks by ensuring that |
| 110 |
** sqlite3_recover_finish() is called on all allocated handles. |
| 111 |
*/ |
| 112 |
sqlite3_recover *sqlite3_recover_init( |
| 113 |
sqlite3* db, |
| 114 |
const char *zDb, |
| 115 |
const char *zUri |
| 116 |
); |
| 117 |
sqlite3_recover *sqlite3_recover_init_sql( |
| 118 |
sqlite3* db, |
| 119 |
const char *zDb, |
| 120 |
int (*xSql)(void*, const char*), |
| 121 |
void *pCtx |
| 122 |
); |
| 123 |
|
| 124 |
/* |
| 125 |
** Configure an sqlite3_recover object that has just been created using |
| 126 |
** sqlite3_recover_init() or sqlite3_recover_init_sql(). This function |
| 127 |
** may only be called before the first call to sqlite3_recover_step() |
| 128 |
** or sqlite3_recover_run() on the object. |
| 129 |
** |
| 130 |
** The second argument passed to this function must be one of the |
| 131 |
** SQLITE_RECOVER_* symbols defined below. Valid values for the third argument |
| 132 |
** depend on the specific SQLITE_RECOVER_* symbol in use. |
| 133 |
** |
| 134 |
** SQLITE_OK is returned if the configuration operation was successful, |
| 135 |
** or an SQLite error code otherwise. |
| 136 |
*/ |
| 137 |
int sqlite3_recover_config(sqlite3_recover*, int op, void *pArg); |
| 138 |
|
| 139 |
/* |
| 140 |
** SQLITE_RECOVER_LOST_AND_FOUND: |
| 141 |
** The pArg argument points to a string buffer containing the name |
| 142 |
** of a "lost-and-found" table in the output database, or NULL. If |
| 143 |
** the argument is non-NULL and the database contains seemingly |
| 144 |
** valid pages that cannot be associated with any table in the |
| 145 |
** recovered part of the schema, data is extracted from these |
| 146 |
** pages to add to the lost-and-found table. |
| 147 |
** |
| 148 |
** SQLITE_RECOVER_FREELIST_CORRUPT: |
| 149 |
** The pArg value must actually be a pointer to a value of type |
| 150 |
** int containing value 0 or 1 cast as a (void*). If this option is set |
| 151 |
** (argument is 1) and a lost-and-found table has been configured using |
| 152 |
** SQLITE_RECOVER_LOST_AND_FOUND, then is assumed that the freelist is |
| 153 |
** corrupt and an attempt is made to recover records from pages that |
| 154 |
** appear to be linked into the freelist. Otherwise, pages on the freelist |
| 155 |
** are ignored. Setting this option can recover more data from the |
| 156 |
** database, but often ends up "recovering" deleted records. The default |
| 157 |
** value is 0 (clear). |
| 158 |
** |
| 159 |
** SQLITE_RECOVER_ROWIDS: |
| 160 |
** The pArg value must actually be a pointer to a value of type |
| 161 |
** int containing value 0 or 1 cast as a (void*). If this option is set |
| 162 |
** (argument is 1), then an attempt is made to recover rowid values |
| 163 |
** that are not also INTEGER PRIMARY KEY values. If this option is |
| 164 |
** clear, then new rowids are assigned to all recovered rows. The |
| 165 |
** default value is 1 (set). |
| 166 |
** |
| 167 |
** SQLITE_RECOVER_SLOWINDEXES: |
| 168 |
** The pArg value must actually be a pointer to a value of type |
| 169 |
** int containing value 0 or 1 cast as a (void*). If this option is clear |
| 170 |
** (argument is 0), then when creating an output database, the recover |
| 171 |
** module creates and populates non-UNIQUE indexes right at the end of the |
| 172 |
** recovery operation - after all recoverable data has been inserted |
| 173 |
** into the new database. This is faster overall, but means that the |
| 174 |
** final call to sqlite3_recover_step() for a recovery operation may |
| 175 |
** be need to create a large number of indexes, which may be very slow. |
| 176 |
** |
| 177 |
** Or, if this option is set (argument is 1), then non-UNIQUE indexes |
| 178 |
** are created in the output database before it is populated with |
| 179 |
** recovered data. This is slower overall, but avoids the slow call |
| 180 |
** to sqlite3_recover_step() at the end of the recovery operation. |
| 181 |
** |
| 182 |
** The default option value is 0. |
| 183 |
*/ |
| 184 |
#define SQLITE_RECOVER_LOST_AND_FOUND 1 |
| 185 |
#define SQLITE_RECOVER_FREELIST_CORRUPT 2 |
| 186 |
#define SQLITE_RECOVER_ROWIDS 3 |
| 187 |
#define SQLITE_RECOVER_SLOWINDEXES 4 |
| 188 |
|
| 189 |
/* |
| 190 |
** Perform a unit of work towards the recovery operation. This function |
| 191 |
** must normally be called multiple times to complete database recovery. |
| 192 |
** |
| 193 |
** If no error occurs but the recovery operation is not completed, this |
| 194 |
** function returns SQLITE_OK. If recovery has been completed successfully |
| 195 |
** then SQLITE_DONE is returned. If an error has occurred, then an SQLite |
| 196 |
** error code (e.g. SQLITE_IOERR or SQLITE_NOMEM) is returned. It is not |
| 197 |
** considered an error if some or all of the data cannot be recovered |
| 198 |
** due to database corruption. |
| 199 |
** |
| 200 |
** Once sqlite3_recover_step() has returned a value other than SQLITE_OK, |
| 201 |
** all further such calls on the same recover handle are no-ops that return |
| 202 |
** the same non-SQLITE_OK value. |
| 203 |
*/ |
| 204 |
int sqlite3_recover_step(sqlite3_recover*); |
| 205 |
|
| 206 |
/* |
| 207 |
** Run the recovery operation to completion. Return SQLITE_OK if successful, |
| 208 |
** or an SQLite error code otherwise. Calling this function is the same |
| 209 |
** as executing: |
| 210 |
** |
| 211 |
** while( SQLITE_OK==sqlite3_recover_step(p) ); |
| 212 |
** return sqlite3_recover_errcode(p); |
| 213 |
*/ |
| 214 |
int sqlite3_recover_run(sqlite3_recover*); |
| 215 |
|
| 216 |
/* |
| 217 |
** If an error has been encountered during a prior call to |
| 218 |
** sqlite3_recover_step(), then this function attempts to return a |
| 219 |
** pointer to a buffer containing an English language explanation of |
| 220 |
** the error. If no error message is available, or if an out-of memory |
| 221 |
** error occurs while attempting to allocate a buffer in which to format |
| 222 |
** the error message, NULL is returned. |
| 223 |
** |
| 224 |
** The returned buffer remains valid until the sqlite3_recover handle is |
| 225 |
** destroyed using sqlite3_recover_finish(). |
| 226 |
*/ |
| 227 |
const char *sqlite3_recover_errmsg(sqlite3_recover*); |
| 228 |
|
| 229 |
/* |
| 230 |
** If this function is called on an sqlite3_recover handle after |
| 231 |
** an error occurs, an SQLite error code is returned. Otherwise, SQLITE_OK. |
| 232 |
*/ |
| 233 |
int sqlite3_recover_errcode(sqlite3_recover*); |
| 234 |
|
| 235 |
/* |
| 236 |
** Clean up a recovery object created by a call to sqlite3_recover_init(). |
| 237 |
** The results of using a recovery object with any API after it has been |
| 238 |
** passed to this function are undefined. |
| 239 |
** |
| 240 |
** This function returns the same value as sqlite3_recover_errcode(). |
| 241 |
*/ |
| 242 |
int sqlite3_recover_finish(sqlite3_recover*); |
| 243 |
|
| 244 |
|
| 245 |
#ifdef __cplusplus |
| 246 |
} /* end of the 'extern "C"' block */ |
| 247 |
#endif |
| 248 |
|
| 249 |
#endif /* ifndef _SQLITE_RECOVER_H */ |