3 ** This file is the interface to a very simple database library used for
4 ** testing. The interface is similar to that of the LSM. The main virtue
5 ** of this library is that the same API may be used to access a key-value
6 ** store implemented by LSM, SQLite or another database system. Which
7 ** makes it easy to use for correctness and performance tests.
19 typedef struct TestDb TestDb
;
22 ** Open a new database connection. The first argument is the name of the
23 ** database library to use. e.g. something like:
28 ** See function tdb_system_name() for a list of available database systems.
30 ** The second argument is the name of the database to open (e.g. a filename).
32 ** If the third parameter is non-zero, then any existing database by the
33 ** name of zDb is removed before opening a new one. If it is zero, then an
34 ** existing database may be opened.
36 int tdb_open(const char *zLibrary
, const char *zDb
, int bClear
, TestDb
**ppDb
);
39 ** Close a database handle.
41 int tdb_close(TestDb
*pDb
);
44 ** Write a new key/value into the database.
46 int tdb_write(TestDb
*pDb
, void *pKey
, int nKey
, void *pVal
, int nVal
);
49 ** Delete a key from the database.
51 int tdb_delete(TestDb
*pDb
, void *pKey
, int nKey
);
54 ** Delete a range of keys from the database.
56 int tdb_delete_range(TestDb
*, void *pKey1
, int nKey1
, void *pKey2
, int nKey2
);
59 ** Query the database for key (pKey/nKey). If no entry is found, set *ppVal
60 ** to 0 and *pnVal to -1 before returning. Otherwise, set *ppVal and *pnVal
61 ** to a pointer to and size of the value associated with (pKey/nKey).
63 int tdb_fetch(TestDb
*pDb
, void *pKey
, int nKey
, void **ppVal
, int *pnVal
);
66 ** Open and close nested transactions. Currently, these functions only
67 ** work for SQLite3 and LSM systems. Use the tdb_transaction_support()
68 ** function to determine if a given TestDb handle supports these methods.
70 ** These functions and the iLevel parameter follow the same conventions as
71 ** the SQLite 4 transaction interface. Note that this is slightly different
72 ** from the way LSM does things. As follows:
75 ** A successful call to tdb_begin() with (iLevel>1) guarantees that
76 ** there are at least (iLevel-1) write transactions open. If iLevel==1,
77 ** then it guarantees that at least a read-transaction is open. Calling
78 ** tdb_begin() with iLevel==0 is a no-op.
81 ** A successful call to tdb_commit() with (iLevel>1) guarantees that
82 ** there are at most (iLevel-1) write transactions open. If iLevel==1,
83 ** then it guarantees that there are no write transactions open (although
84 ** a read-transaction may remain open). Calling tdb_commit() with
85 ** iLevel==0 ensures that all transactions, read or write, have been
86 ** closed and committed.
89 ** This call is similar to tdb_commit(), except that instead of committing
90 ** transactions, it reverts them. For example, calling tdb_rollback() with
91 ** iLevel==2 ensures that there is at most one write transaction open, and
92 ** restores the database to the state that it was in when that transaction
95 ** In other words, tdb_commit() just closes transactions - tdb_rollback()
96 ** closes transactions and then restores the database to the state it
97 ** was in before those transactions were even opened.
99 int tdb_begin(TestDb
*pDb
, int iLevel
);
100 int tdb_commit(TestDb
*pDb
, int iLevel
);
101 int tdb_rollback(TestDb
*pDb
, int iLevel
);
104 ** Return true if transactions are supported, or false otherwise.
106 int tdb_transaction_support(TestDb
*pDb
);
109 ** Return the name of the database library (as passed to tdb_open()) used
110 ** by the handled passed as the first argument.
112 const char *tdb_library_name(TestDb
*pDb
);
115 ** Scan a range of database keys. Invoke the callback function for each
119 TestDb
*pDb
, /* Database handle */
120 void *pCtx
, /* Context pointer to pass to xCallback */
121 int bReverse
, /* True to scan in reverse order */
122 void *pKey1
, int nKey1
, /* Start of search */
123 void *pKey2
, int nKey2
, /* End of search */
124 void (*xCallback
)(void *pCtx
, void *pKey
, int nKey
, void *pVal
, int nVal
)
127 const char *tdb_system_name(int i
);
128 const char *tdb_default_db(const char *zSys
);
130 int tdb_lsm_open(const char *zCfg
, const char *zDb
, int bClear
, TestDb
**ppDb
);
133 ** If the TestDb handle passed as an argument is a wrapper around an LSM
134 ** database, return the LSM handle. Otherwise, if the argument is some other
135 ** database system, return NULL.
137 lsm_db
*tdb_lsm(TestDb
*pDb
);
140 ** Return true if the db passed as an argument is a multi-threaded LSM
143 int tdb_lsm_multithread(TestDb
*pDb
);
146 ** Return a pointer to the lsm_env object used by all lsm database
147 ** connections initialized as a copy of the object returned by
148 ** lsm_default_env(). It may be modified (e.g. to override functions)
149 ** if the caller can guarantee that it is not already in use.
151 lsm_env
*tdb_lsm_env(void);
154 ** The following functions only work with LSM database handles. It is
155 ** illegal to call them with any other type of database handle specified
158 void tdb_lsm_enable_log(TestDb
*pDb
, int bEnable
);
159 void tdb_lsm_application_crash(TestDb
*pDb
);
160 void tdb_lsm_prepare_system_crash(TestDb
*pDb
);
161 void tdb_lsm_system_crash(TestDb
*pDb
);
162 void tdb_lsm_prepare_sync_crash(TestDb
*pDb
, int iSync
);
165 void tdb_lsm_safety(TestDb
*pDb
, int eMode
);
166 void tdb_lsm_config_work_hook(TestDb
*pDb
, void (*)(lsm_db
*, void *), void *);
167 void tdb_lsm_write_hook(TestDb
*, void(*)(void*,int,lsm_i64
,int,int), void*);
168 int tdb_lsm_config_str(TestDb
*pDb
, const char *zStr
);
171 } /* End of the 'extern "C"' block */