250 lines
9.6 KiB
C
250 lines
9.6 KiB
C
|
/*
|
||
|
|
** 2022-08-27
|
||
|
|
**
|
||
|
|
** 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.
|
||
|
|
**
|
||
|
|
*************************************************************************
|
||
|
|
**
|
||
|
|
** This file contains the public interface to the "recover" extension -
|
||
|
|
** an SQLite extension designed to recover data from corrupted database
|
||
|
|
** files.
|
||
|
|
*/
|
||
|
|
|
||
|
|
/*
|
||
|
|
** OVERVIEW:
|
||
|
|
**
|
||
|
|
** To use the API to recover data from a corrupted database, an
|
||
|
|
** application:
|
||
|
|
**
|
||
|
|
** 1) Creates an sqlite3_recover handle by calling either
|
||
|
|
** sqlite3_recover_init() or sqlite3_recover_init_sql().
|
||
|
|
**
|
||
|
|
** 2) Configures the new handle using one or more calls to
|
||
|
|
** sqlite3_recover_config().
|
||
|
|
**
|
||
|
|
** 3) Executes the recovery by repeatedly calling sqlite3_recover_step() on
|
||
|
|
** the handle until it returns something other than SQLITE_OK. If it
|
||
|
|
** returns SQLITE_DONE, then the recovery operation completed without
|
||
|
|
** error. If it returns some other non-SQLITE_OK value, then an error
|
||
|
|
** has occurred.
|
||
|
|
**
|
||
|
|
** 4) Retrieves any error code and English language error message using the
|
||
|
|
** sqlite3_recover_errcode() and sqlite3_recover_errmsg() APIs,
|
||
|
|
** respectively.
|
||
|
|
**
|
||
|
|
** 5) Destroys the sqlite3_recover handle and frees all resources
|
||
|
|
** using sqlite3_recover_finish().
|
||
|
|
**
|
||
|
|
** The application may abandon the recovery operation at any point
|
||
|
|
** before it is finished by passing the sqlite3_recover handle to
|
||
|
|
** sqlite3_recover_finish(). This is not an error, but the final state
|
||
|
|
** of the output database, or the results of running the partial script
|
||
|
|
** delivered to the SQL callback, are undefined.
|
||
|
|
*/
|
||
|
|
|
||
|
|
#ifndef _SQLITE_RECOVER_H
|
||
|
|
#define _SQLITE_RECOVER_H
|
||
|
|
|
||
|
|
#include "sqlite3.h"
|
||
|
|
|
||
|
|
#ifdef __cplusplus
|
||
|
|
extern "C" {
|
||
|
|
#endif
|
||
|
|
|
||
|
|
/*
|
||
|
|
** An instance of the sqlite3_recover object represents a recovery
|
||
|
|
** operation in progress.
|
||
|
|
**
|
||
|
|
** Constructors:
|
||
|
|
**
|
||
|
|
** sqlite3_recover_init()
|
||
|
|
** sqlite3_recover_init_sql()
|
||
|
|
**
|
||
|
|
** Destructor:
|
||
|
|
**
|
||
|
|
** sqlite3_recover_finish()
|
||
|
|
**
|
||
|
|
** Methods:
|
||
|
|
**
|
||
|
|
** sqlite3_recover_config()
|
||
|
|
** sqlite3_recover_errcode()
|
||
|
|
** sqlite3_recover_errmsg()
|
||
|
|
** sqlite3_recover_run()
|
||
|
|
** sqlite3_recover_step()
|
||
|
|
*/
|
||
|
|
typedef struct sqlite3_recover sqlite3_recover;
|
||
|
|
|
||
|
|
/*
|
||
|
|
** These two APIs attempt to create and return a new sqlite3_recover object.
|
||
|
|
** In both cases the first two arguments identify the (possibly
|
||
|
|
** corrupt) database to recover data from. The first argument is an open
|
||
|
|
** database handle and the second the name of a database attached to that
|
||
|
|
** handle (i.e. "main", "temp" or the name of an attached database).
|
||
|
|
**
|
||
|
|
** If sqlite3_recover_init() is used to create the new sqlite3_recover
|
||
|
|
** handle, then data is recovered into a new database, identified by
|
||
|
|
** string parameter zUri. zUri may be an absolute or relative file path,
|
||
|
|
** or may be an SQLite URI. If the identified database file already exists,
|
||
|
|
** it is overwritten.
|
||
|
|
**
|
||
|
|
** If sqlite3_recover_init_sql() is invoked, then any recovered data will
|
||
|
|
** be returned to the user as a series of SQL statements. Executing these
|
||
|
|
** SQL statements results in the same database as would have been created
|
||
|
|
** had sqlite3_recover_init() been used. For each SQL statement in the
|
||
|
|
** output, the callback function passed as the third argument (xSql) is
|
||
|
|
** invoked once. The first parameter is a passed a copy of the fourth argument
|
||
|
|
** to this function (pCtx) as its first parameter, and a pointer to a
|
||
|
|
** nul-terminated buffer containing the SQL statement formated as UTF-8 as
|
||
|
|
** the second. If the xSql callback returns any value other than SQLITE_OK,
|
||
|
|
** then processing is immediately abandoned and the value returned used as
|
||
|
|
** the recover handle error code (see below).
|
||
|
|
**
|
||
|
|
** If an out-of-memory error occurs, NULL may be returned instead of
|
||
|
|
** a valid handle. In all other cases, it is the responsibility of the
|
||
|
|
** application to avoid resource leaks by ensuring that
|
||
|
|
** sqlite3_recover_finish() is called on all allocated handles.
|
||
|
|
*/
|
||
|
|
sqlite3_recover *sqlite3_recover_init(
|
||
|
|
sqlite3* db,
|
||
|
|
const char *zDb,
|
||
|
|
const char *zUri
|
||
|
|
);
|
||
|
|
sqlite3_recover *sqlite3_recover_init_sql(
|
||
|
|
sqlite3* db,
|
||
|
|
const char *zDb,
|
||
|
|
int (*xSql)(void*, const char*),
|
||
|
|
void *pCtx
|
||
|
|
);
|
||
|
|
|
||
|
|
/*
|
||
|
|
** Configure an sqlite3_recover object that has just been created using
|
||
|
|
** sqlite3_recover_init() or sqlite3_recover_init_sql(). This function
|
||
|
|
** may only be called before the first call to sqlite3_recover_step()
|
||
|
|
** or sqlite3_recover_run() on the object.
|
||
|
|
**
|
||
|
|
** The second argument passed to this function must be one of the
|
||
|
|
** SQLITE_RECOVER_* symbols defined below. Valid values for the third argument
|
||
|
|
** depend on the specific SQLITE_RECOVER_* symbol in use.
|
||
|
|
**
|
||
|
|
** SQLITE_OK is returned if the configuration operation was successful,
|
||
|
|
** or an SQLite error code otherwise.
|
||
|
|
*/
|
||
|
|
int sqlite3_recover_config(sqlite3_recover*, int op, void *pArg);
|
||
|
|
|
||
|
|
/*
|
||
|
|
** SQLITE_RECOVER_LOST_AND_FOUND:
|
||
|
|
** The pArg argument points to a string buffer containing the name
|
||
|
|
** of a "lost-and-found" table in the output database, or NULL. If
|
||
|
|
** the argument is non-NULL and the database contains seemingly
|
||
|
|
** valid pages that cannot be associated with any table in the
|
||
|
|
** recovered part of the schema, data is extracted from these
|
||
|
|
** pages to add to the lost-and-found table.
|
||
|
|
**
|
||
|
|
** SQLITE_RECOVER_FREELIST_CORRUPT:
|
||
|
|
** The pArg value must actually be a pointer to a value of type
|
||
|
|
** int containing value 0 or 1 cast as a (void*). If this option is set
|
||
|
|
** (argument is 1) and a lost-and-found table has been configured using
|
||
|
|
** SQLITE_RECOVER_LOST_AND_FOUND, then is assumed that the freelist is
|
||
|
|
** corrupt and an attempt is made to recover records from pages that
|
||
|
|
** appear to be linked into the freelist. Otherwise, pages on the freelist
|
||
|
|
** are ignored. Setting this option can recover more data from the
|
||
|
|
** database, but often ends up "recovering" deleted records. The default
|
||
|
|
** value is 0 (clear).
|
||
|
|
**
|
||
|
|
** SQLITE_RECOVER_ROWIDS:
|
||
|
|
** The pArg value must actually be a pointer to a value of type
|
||
|
|
** int containing value 0 or 1 cast as a (void*). If this option is set
|
||
|
|
** (argument is 1), then an attempt is made to recover rowid values
|
||
|
|
** that are not also INTEGER PRIMARY KEY values. If this option is
|
||
|
|
** clear, then new rowids are assigned to all recovered rows. The
|
||
|
|
** default value is 1 (set).
|
||
|
|
**
|
||
|
|
** SQLITE_RECOVER_SLOWINDEXES:
|
||
|
|
** The pArg value must actually be a pointer to a value of type
|
||
|
|
** int containing value 0 or 1 cast as a (void*). If this option is clear
|
||
|
|
** (argument is 0), then when creating an output database, the recover
|
||
|
|
** module creates and populates non-UNIQUE indexes right at the end of the
|
||
|
|
** recovery operation - after all recoverable data has been inserted
|
||
|
|
** into the new database. This is faster overall, but means that the
|
||
|
|
** final call to sqlite3_recover_step() for a recovery operation may
|
||
|
|
** be need to create a large number of indexes, which may be very slow.
|
||
|
|
**
|
||
|
|
** Or, if this option is set (argument is 1), then non-UNIQUE indexes
|
||
|
|
** are created in the output database before it is populated with
|
||
|
|
** recovered data. This is slower overall, but avoids the slow call
|
||
|
|
** to sqlite3_recover_step() at the end of the recovery operation.
|
||
|
|
**
|
||
|
|
** The default option value is 0.
|
||
|
|
*/
|
||
|
|
#define SQLITE_RECOVER_LOST_AND_FOUND 1
|
||
|
|
#define SQLITE_RECOVER_FREELIST_CORRUPT 2
|
||
|
|
#define SQLITE_RECOVER_ROWIDS 3
|
||
|
|
#define SQLITE_RECOVER_SLOWINDEXES 4
|
||
|
|
|
||
|
|
/*
|
||
|
|
** Perform a unit of work towards the recovery operation. This function
|
||
|
|
** must normally be called multiple times to complete database recovery.
|
||
|
|
**
|
||
|
|
** If no error occurs but the recovery operation is not completed, this
|
||
|
|
** function returns SQLITE_OK. If recovery has been completed successfully
|
||
|
|
** then SQLITE_DONE is returned. If an error has occurred, then an SQLite
|
||
|
|
** error code (e.g. SQLITE_IOERR or SQLITE_NOMEM) is returned. It is not
|
||
|
|
** considered an error if some or all of the data cannot be recovered
|
||
|
|
** due to database corruption.
|
||
|
|
**
|
||
|
|
** Once sqlite3_recover_step() has returned a value other than SQLITE_OK,
|
||
|
|
** all further such calls on the same recover handle are no-ops that return
|
||
|
|
** the same non-SQLITE_OK value.
|
||
|
|
*/
|
||
|
|
int sqlite3_recover_step(sqlite3_recover*);
|
||
|
|
|
||
|
|
/*
|
||
|
|
** Run the recovery operation to completion. Return SQLITE_OK if successful,
|
||
|
|
** or an SQLite error code otherwise. Calling this function is the same
|
||
|
|
** as executing:
|
||
|
|
**
|
||
|
|
** while( SQLITE_OK==sqlite3_recover_step(p) );
|
||
|
|
** return sqlite3_recover_errcode(p);
|
||
|
|
*/
|
||
|
|
int sqlite3_recover_run(sqlite3_recover*);
|
||
|
|
|
||
|
|
/*
|
||
|
|
** If an error has been encountered during a prior call to
|
||
|
|
** sqlite3_recover_step(), then this function attempts to return a
|
||
|
|
** pointer to a buffer containing an English language explanation of
|
||
|
|
** the error. If no error message is available, or if an out-of memory
|
||
|
|
** error occurs while attempting to allocate a buffer in which to format
|
||
|
|
** the error message, NULL is returned.
|
||
|
|
**
|
||
|
|
** The returned buffer remains valid until the sqlite3_recover handle is
|
||
|
|
** destroyed using sqlite3_recover_finish().
|
||
|
|
*/
|
||
|
|
const char *sqlite3_recover_errmsg(sqlite3_recover*);
|
||
|
|
|
||
|
|
/*
|
||
|
|
** If this function is called on an sqlite3_recover handle after
|
||
|
|
** an error occurs, an SQLite error code is returned. Otherwise, SQLITE_OK.
|
||
|
|
*/
|
||
|
|
int sqlite3_recover_errcode(sqlite3_recover*);
|
||
|
|
|
||
|
|
/*
|
||
|
|
** Clean up a recovery object created by a call to sqlite3_recover_init().
|
||
|
|
** The results of using a recovery object with any API after it has been
|
||
|
|
** passed to this function are undefined.
|
||
|
|
**
|
||
|
|
** This function returns the same value as sqlite3_recover_errcode().
|
||
|
|
*/
|
||
|
|
int sqlite3_recover_finish(sqlite3_recover*);
|
||
|
|
|
||
|
|
|
||
|
|
#ifdef __cplusplus
|
||
|
|
} /* end of the 'extern "C"' block */
|
||
|
|
#endif
|
||
|
|
|
||
|
|
#endif /* ifndef _SQLITE_RECOVER_H */
|