iOS SQlite3 常用命令

使用的過程根據使用的函數大致分為如下幾個過程:

sqlite3_open()

sqlite3_prepare()

sqlite3_step()

sqlite3_column()

sqlite3_finalize()

sqlite3_close()

1.sqlite3_open()

打開數據庫,在操作數據庫之前,首先要打開數據庫。這個函數打開一個sqlite數據庫文件的連接并且返回一個數據庫連接對象。這個操作同時程序中的第一個調用的sqlite函數,同時也是其他sqlite api的先決條件。許多的sqlite接口函數都需要一個數據庫連接對象的指針作為它們的第一個參數。

相關函數

SQLITE_APIintsqlite3_open(

? const char*filename,? /* Database filename (UTF-8) */

? sqlite3**ppDb? ? ? ? ? /* OUT: SQLite db handle */

);

SQLITE_APIintsqlite3_open16(

? const void*filename,? /* Database filename (UTF-16) */

? sqlite3**ppDb? ? ? ? ? /* OUT: SQLite db handle */

);

SQLITE_APIintsqlite3_open_v2(

? const char*filename,? /* Database filename (UTF-8) */

? sqlite3**ppDb,? ? ? ? /* OUT: SQLite db handle */

? intflags,? ? ? ? ? ? ? /* Flags */

? const char*zVfs? ? ? ? /* Name of VFS module to use */

);

說明:假如這個要被打開的數據文件不存在,則一個同名的數據庫文件將被創建。如果使用sqlite3_open和sqlite3_open_v2的話,數據庫將采用UTF-8的編碼方式,sqlite3_open16采用UTF-16的編碼方式。

返回值:如果sqlite數據庫被成功打開(或創建),將會返回SQLITE_OK,否則將會返回錯誤碼。Sqlite3_errmsg()或者sqlite3_errmsg16可以用于獲得數據庫打開錯誤碼的英文描述,這兩個函數定義為:

const char *sqlite3_errmsg(sqlite3*);

const void *sqlite3_errmsg16(sqlite3*);

無論是否成功打開數據庫, 都應該使用 sqlite3_close() 關閉數據庫連接.

參數說明:

filename:需要被打開的數據庫文件的文件名,在sqlite3_open和sqlite3_open_v2中這個參數采用UTF-8編碼,而在sqlite3_open16中則采用UTF-16編碼。

ppDb:一個數據庫連接句柄被返回到這個參數,即使發生錯誤。唯一的一場是如果sqlite不能分配內存來存放sqlite對象,ppDb將會被返回一個NULL值。

flags:作為數據庫連接的額外控制的參數,可以是SQLITE_OPEN_READONLY,SQLITE_OPEN_READWRITE和SQLITE_OPEN_READWRITE|SQLITE_OPEN_CREATE中的一個,用于控制數據庫的打開方式,可以和SQLITE_OPEN_NOMUTEX,SQLITE_OPEN_FULLMUTEX,SQLITE_OPEN_SHAREDCACHE,以及SQLITE_OPEN_PRIVATECACHE結合使用,具體的詳細情況可以查閱文檔。

2.Sqlite3_prepare()

這個函數將sql文本轉換成一個準備語句(prepared statement)對象,同時返回這個對象的指針。這個接口需要一個數據庫連接指針以及一個要準備的包含SQL語句的文本。它實際上并不執行(evaluate)這個SQL語句,它僅僅為執行準備這個sql語句。

函數定義

????SQLITE_API

????int sqlite3_prepare(

????sqlite3 *db,??????????? /* Database handle */? /* 成功打開的數據庫句柄 */

????const char *zSql,?????? /* SQL statement, UTF-8 encoded */ /* UTF8編碼的 SQL 語句 */

????int nByte,????????????? /* Maximum length of zSql in bytes. */ ? /* 參數 sql 的字節數, 包含 '\0' */

????sqlite3_stmt **ppStmt,? /* OUT: Statement handle */ /* 輸出:預編譯語句句柄 */

????const char **pzTail???? /* OUT: Pointer to unused portion of zSql */ /* 輸出:指向 sql 語句中未使用的部分 */

);

SQLITE_API int sqlite3_prepare_v2(

? ????sqlite3 *db,? ? ? ? ? ? /* Database handle */

????? const char *zSql,? ? ? /* SQL statement, UTF-8 encoded */

????? int nByte,? ? ? ? ? ? ? /* Maximum length of zSql in bytes. */

? ????sqlite3_stmt **ppStmt,? /* OUT: Statement handle */

????? const char **pzTail? ? /* OUT: Pointer to unused portion of zSql */

);

SQLITE_API int sqlite3_prepare16(

? ????sqlite3 *db,? ? ? ? ? ? /* Database handle */

? ????const void *zSql,? ? ? /* SQL statement, UTF-16 encoded */

????? int nByte,? ? ? ? ? ? ? /* Maximum length of zSql in bytes. */

????? sqlite3_stmt **ppStmt,? /* OUT: Statement handle */

????? const void **pzTail? ? /* OUT: Pointer to unused portion of zSql */

);

SQLITE_API int sqlite3_prepare16_v2(

????? sqlite3 *db,? ? ? ? ? ? /* Database handle */

? ????const void *zSql,? ? ? /* SQL statement, UTF-16 encoded */

????? int nByte,? ? ? ? ? ? ? /* Maximum length of zSql in bytes. */

????? sqlite3_stmt **ppStmt,? /* OUT: Statement handle */

? ????const void **pzTail? ? /* OUT: Pointer to unused portion of zSql */

);

這里只對sqlite3_prepare 的參數做下介紹:

db:數據指針。

zSql:sql語句,使用UTF-8編碼。

nByte:如果nByte小于0,則函數取出zSql中從開始到第一個0終止符的內容;如果nByte不是負的,那么它就是這個函數能從zSql中讀取的字節數的最大值。如果nBytes非負,zSql在第一次遇見’/000/或’u000’的時候終止.如果用戶知道被傳入的 sql 語句是以 '\0' 結尾的, 那么有一個更好的做法是:把nbytes的值設為該字符串的長度(包含'\0'), 這樣可以避免 SQLite 復制該字符串的一份拷貝, 以提高程序的效率。

pzTail:上面提到zSql在遇見終止符或者是達到設定的nByte之后結束,假如zSql還有剩余的內容,那么這些剩余的內容被存放到pZTail中,不包括終止符。如果 pszTail 不為 NULL, 則 *pszTail 指向 sql 中第一個被傳入的 SQL 語句的結尾. 該函數只編譯 sql 的第一個語句, 所以 *pszTail 指向的內容則是未被編譯的。

ppStmt:能夠使用sqlite3_step()執行的編譯好的準備語句的指針,如果錯誤發生,它被置為NULL,如假如輸入的文本不包括sql語句。調用過程必須負責在編譯好的sql語句完成使用后使用sqlite3_finalize()刪除它。

說明:如果執行成功,則返回SQLITE_OK,否則返回一個錯誤碼。推薦在現在任何的程序中都使用sqlite3_prepare_v2這個函數,sqlite3_prepare只是用于前向兼容。

準備語句(prepared statement)對象? ?typedef struct sqlite3_stmt sqlite3_stmt;??準備語句(prepared statement)對象一個代表一個簡單SQL語句對象的實例,這個對象通常被稱為“準備語句”或者“編譯好的SQL語句”或者就直接稱為“語句”。

語句對象的生命周期經歷這樣的過程:

????1.使用sqlite3_prepare_v2或相關的函數創建這個對象。

? ? 2.使用sqlite3_bind_*()給宿主參數(host parameters)綁定值。

????3.通過調用sqlite3_step一次或多次來執行這個sql。

????4.使用sqlite3——reset()重置這個語句,然后回到第2步,這個過程做0次或多次。

????5.使用sqlite3_finalize()銷毀這個

在sqlite中并沒有定義sqlite3_stmt這個結構的具體內容,它只是一個抽象類型,在使用過程中一般以它的指針進行操作,而sqlite3_stmt類型的指針在實際上是一個指向Vdbe的結構體得指針。

3.sqlite3_step()

這個過程用于執行有前面sqlite3_prepare創建的準備語句。這個語句執行到結果的第一行可用的位置。繼續前進到結果的第二行的話,只需再次調用sqlite3_setp()。繼續調用sqlite3_setp()知道這個語句完成,那些不返回結果的語句(如:INSERT,UPDATE,或DELETE),sqlite3_step()只執行一次就返回

函數定義 :int sqlite3_step(sqlite3_stmt*);

返回值:函數的返回值基于創建sqlite3_stmt參數所使用的函數,假如是使用老版本的接口sqlite3_prepare()和sqlite3_prepare16(),返回值會是?SQLITE_BUSY,?SQLITE_DONE,?SQLITE_ROW,?SQLITE_ERROR 或?SQLITE_MISUSE,而v2版本的接口sqlite3_prepare_v2()和sqlite3_prepare16_v2()則會同時返回這些結果碼和擴展結果碼。

對所有V3.6.23.1以及其前面的所有版本,需要在sqlite3_step()之后調用sqlite3_reset(),在后續的sqlite3_ step之前。如果調用sqlite3_reset重置準備語句失敗,將會導致sqlite3_ step返回SQLITE_MISUSE,但是在V3. 6.23.1以后,sqlite3_step()將會自動調用sqlite3_reset。

說明:

??????? 當一條語句被 sqlite3_prepare() 或其相關的函數預編譯后, sqlite3_step() 必須被調用一次或多次來評估該預編譯語句.

???????該函數的詳細行為依賴于由 sqlite3_prepare()(或其相關的函數) 產生的是一條怎樣的預編譯語句.

??????? 函數將返回一個以下的結果來標識其執行結果:

? ? ????SQLITE_BUSY:忙碌. 數據庫引擎無法鎖定數據去完成其工作. 但可以多次嘗試.

??????? SQLITE_DONE:完成. sql 語句已經被成功地執行. 在調用 sqlite_reset() 之前, 當前預編譯的語句不應該被sqlite3_step() 再次調用.

??????? SQLITE_ROW:查詢時產生了結果. 此時可以通過相關的"數據訪問函數(column access functions)"來取得數據. sqlite3_step() 的再一次調用將取得下一條查詢結果.

??????? SQLITE_ERROR:發生了錯誤. 此時可以通過 sqlite3_errmmsg() 取得相關的錯誤信息. sqlite3_step() 不能被再次調用.

??????? SQLITE_MISUSE:不正確的庫的使用. 該函數使用不當.

4.int sqlite3_reset(sqlite3_stmt *pStmt)

sqlite3_reset用于重置一個準備語句對象到它的初始狀態,然后準備被重新執行。所有sql語句變量使用sqlite3_bind*綁定值,使用sqlite3_clear_bindings重設這些綁定。Sqlite3_reset接口重置準備語句到它代碼開始的時候。sqlite3_reset并不改變在準備語句上的任何綁定值,那么這里猜測,可能是語句在被執行的過程中發生了其他的改變,然后這個語句將它重置到綁定值的時候的那個狀態。

它的返回值相對有些特殊。返回SQLITE_BUSY表示暫時無法執行操作,SQLITE_DONE表示操作執行完畢,SQLITE_ROW表示執行完畢并且有返回(執行select語句時)。當返回值為SQLITE_ROW時,我們需要對查詢結果進行處理,SQLITE3提供sqlite3_column_*系列函數。

const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol);

其中參數iCol為列的序號,從0開始。如果返回值有多行,則可以再次調用sqlite3_step函數,然后由sqlite3_column_*函數取得返回值。使用上述這些函數基本上可以完成對SQLITE3數據庫的操作了(不過這里只針對text數據類型做了說明)。

5.? sqlite3_column()

這個過程從執行sqlite3_step()執行一個準備語句得到的結果集的當前行中返回一個列。每次sqlite3_step得到一個結果集的列停下后,這個過程就可以被多次調用去查詢這個行的各列的值。對列操作是有多個函數,均以sqlite3_column為前綴

????const void *sqlite3_column_blob(sqlite3_stmt*, int iCol);

????int sqlite3_column_bytes(sqlite3_stmt*, int iCol);

????int sqlite3_column_bytes16(sqlite3_stmt*, int iCol);

????double sqlite3_column_double(sqlite3_stmt*, int iCol);

????int sqlite3_column_int(sqlite3_stmt*, int iCol);

????sqlite3_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol);

????const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol);

????const void *sqlite3_column_text16(sqlite3_stmt*, int iCol);

????int sqlite3_column_type(sqlite3_stmt*, int iCol);

????int sqlite3_column_numeric_type(sqlite3_stmt*, int iCol);

????sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol);

說明

第一個參數為從sqlite3_prepare返回來的prepared statement對象的指針,第二參數指定這一行中的想要被返回的列的索引。最左邊的一列的索引號是0,行的列數可以使用sqlite3_colum_count()獲得。

(1) 得到數據行中某個列的數據

????sqlite3_column_xxx(sqlite3_stmt*, int iCol);

????在sqlite3_step返回SQLITE_ROW后,使用它得到第iCol列的數據。

????其中的xxx代表:

????blob:指向保存數據內存的指針。

????bytes, bytes16: 得到該blob類型數據的大小,或者text轉換為UTF8/UTF16的字符串長度。

????double, int, int64: 數值。

????text,text16:字符串指針。

????type:該列的數據類型(SQLITE_INTEGER,SQLITE_FLOAT,SQLITE_TEXT,SQLITE_BLOB,SQLITE_NULL)

注意:如果對該列使用了不同與該列本身類型適合的數據讀取方法,得到的數值將是轉換過的結果。

(2)?得到數據行中某個列的數據的類型

????int sqlite3_column_type(sqlite3_stmt*, int iCol);

????返回值:SQLITE_INTEGER,SQLITE_FLOAT,SQLITE_TEXT,SQLITE_BLOB,SQLITE_NULL。

????使用的方法和sqlite3_column_xxx()函數類似。

(3)

????int sqlite3_column_count(sqlite3_stmt *pStmt);?功能:獲取列數? 如果過程沒有返回值,如update,將返回0。

????const char *sqlite3_column_name(sqlite3_stmt*,int);?功能:獲取列名 。

????const char *sqlite3_column_decltype(sqlite3_stmt *, int i);?功能:返回列數據類型。

????得到當前行中包含的數據個數? int sqlite3_data_count(sqlite3_stmt *pStmt); 如果sqlite3_step返回SQLITE_ROW,可以得到列數,否則為零。

6.sqlite3_finalize

int sqlite3_finalize(sqlite3_stmt *pStmt);這個過程銷毀前面被sqlite3_prepare創建的準備語句,每個準備語句都必須使用這個函數去銷毀以防止內存泄露。在空指針上調用這個函數沒有什么影響,同時可以準備語句的生命周期的任一時刻調用這個函數:在語句被執行前,一次或多次調用sqlite_reset之后,或者在sqlite3_step任何調用之后不管語句是否完成執行。

示例:

??? sqlite3_finalize(pStmt);

??? pStmt = NULL;

7.sqlite3_close

這個過程關閉前面使用sqlite3_open打開的數據庫連接,任何與這個連接相關的準備語句必須在調用這個關閉函數之前被釋放

int sqlite3_close(

????sqlite3* pDB??? /* 由 sqlite3_open 或基相關的函數打開的 SQLite 對象句柄 */

);

說明:

該函數用來析構 sqlite3 對象. 返回 SQLITE_OK 表示對象被成功析構, 以及所有相關的資源被成功回收應用程序必須在關閉之前 "完成(finalize)" 所有的 "預編譯語句(prepared statements)", 并且關閉所有的 "二進制句柄綁定(BLOB handle)", 如果在關閉時還有未完成的預編譯語句或二進制句柄, 那么函數返回 SQLITE_BUSY(5).

示例:

if(pDB != NULL)

{

????sqlite3_close(pDB);

????pDB = NULL;

? }

8.int sqlite3_exec

int sqlite3_exe(

????sqlite3* pDB,??????? /* sqlite3句柄 */

????const char* sql,??? /* 被執行的 SQL 語句 */

????int (*callback)(void*,int,char**,char**),? /* 執行/查詢回調函數 */

????void* pvoid,??? /* 傳遞給回調函數的第一個參數 */

????char**errmsg??? /* 錯誤輸出信息 */

);

說明:

該函數用來執行若干條 SQL 語句.

該函數包裹了先前版本的 sqlite3_prepare(), sqlte3_step() 和 sqlite3_finalize() 函數, 這樣, 用戶就可以執行簡單的代碼執行多條 SQL 語句.

sqlite3_exec()接口執行多條以";"分隔的SQL語句. 如果回調函數不為 NULL, 則它對每一個行查詢結果都會調用該回調函數. 如果沒有回調函數被指定, sqlite3_exec() 只是簡單地忽略查詢結果.

當在執行該SQL語句發生錯誤時, 執行將發生中斷, 并且后面的語句也全部被忽略. 如果 errmsg 參數不為空任何錯誤信息將會被寫進由 sqlite3_malloc() 得到的的內存空間中, 即 errmsg 指向的內存. 為了避免內存泄漏, 應用程序應該在不需要該錯誤信息后立即調用 sqlite3_free() 釋放該內存空間. 如果 errmsg 參數不為 NULL, 并且沒有錯誤發生, errmsg 被設置為 NULL.

如果回調函數返回非零, sqlite3_exec() 立即中斷查詢, 并且不再執行后續的 SQL 語句, 也不再調用回調函數, sqlite3_exec() 將返回 SQLITE_ABORT 結束執行.

示例:

sqlite3_exec(pDB, to_utf8("delete from tablename where id=123;"), NULL, NULL, NULL);

sqlite3_exec(pDB, to_utf8("create table if not exists tablename (id integer primary key,name text);"), NULL, NULL, NULL);

sqlite3_exec(pDB, to_utf8("insert into tablename (name) values ('女孩不哭');"), NULL, NULL, NULL);

if(sqlite3_exec(pDB, to_utf8("select * from tablename;"), sqlite_callback, NULL, &pszErrMsg) != SQLITE_OK)

{

????...

????sqlite3_free(pszErrMsg);

????pszErrMsg = NULL;

}

參閱:在 sqlite3 中使用回調函數(http://www.cnblogs.com/nbsofer/archive/2012/05/29/2523807.html)

9.int sqlite3_errcode

int sqlite3_errcode(

????sqlite3* pDB??? /* SQLite3 數據庫句柄 */

);

說明:

該函數返回最近一次調用 sqlite3_ API時產生的錯誤碼.

示例:

int errcode = sqlite3_errcode(pDB);

10.const char *sqlite3_errmsg

const char *sqlite3_errmsg(

????sqlite3* pDB??? /* SQLite3 數據庫句柄 */

);

說明:

該函數返回與pDB數據庫指針相關的錯誤信息, 由英語書寫.

用戶不必考慮內存的釋放, 其由SQLite內部管理, 它也將會在下產次調用函數時被覆蓋.

示例:

printf("%s\n", sqlite3_errmsg(pDB));

11.int sqlite3_key

int sqlite3_key(

????sqlite3 *db,?????????????????? /* Database to be rekeyed */????

????const void *pKey, int nKey???? /* The key */

);

功能:為加密的數據庫指定密碼,改函數在sqlite3_open之后調用

12.int sqlite3_rekey

int sqlite3_rekey(

????sqlite3 *db,?????????????????? /* Database to be rekeyed */

????const void *pKey, int nKey???? /* The new key */

);

功能:重設數據庫密碼,如果pKey = 0 或者 nKey = 0,這數據庫不加密

13.int sqlite3_get_table

int sqlite3_get_table(

????sqlite3*,?????????????? /* An open database */

????const char *sql,?????? /* SQL to be executed */

????char ***resultp,?????? /* Result written to a char *[]? that this points to */

????int *nrow,???????????? /* Number of result rows written here */

????int *ncolumn,????????? /* Number of result columns written here */

????char **errmsg????????? /* Error msg written here */

);

功能:查詢表.

參數1(IN):數據庫句柄.

參數2(IN):sql語句,以\0結尾.

參數3(OUT):查詢結果.

參數4(OUT):返回行數(多少條數據).

參數5(OUT):返回列數(多少字段).

參數6(OUT):返回錯誤信息.

返回值:SQLITE_OK成功,房子失敗見錯誤信息.

14.void sqlite3_free_table(char **result);

void sqlite3_free_table(char **result);

功能:釋放通過sqlite3_get_table查詢保存的結果數據.

參數1(IN):要釋放的數據指針.

15.int sqlite3_create_function

int sqlite3_create_function(

????sqlite3 *,

????const char *zFunctionName,

????int nArg,

????int eTextRep,

????void*,

????void (*xFunc)(sqlite3_context*,int,sqlite3_value**),

????void (*xStep)(sqlite3_context*,int,sqlite3_value**),

????void (*xFinal)(sqlite3_context*)

);

功能:

const void *sqlite3_value_blob(sqlite3_value*);

int sqlite3_value_bytes(sqlite3_value*);

int sqlite3_value_bytes16(sqlite3_value*);

double sqlite3_value_double(sqlite3_value*);

int sqlite3_value_int(sqlite3_value*);

sqlite_int64 sqlite3_value_int64(sqlite3_value*);

const unsigned char *sqlite3_value_text(sqlite3_value*);

const void *sqlite3_value_text16(sqlite3_value*);

const void *sqlite3_value_text16le(sqlite3_value*);

const void *sqlite3_value_text16be(sqlite3_value*);

int sqlite3_value_type(sqlite3_value*);

int sqlite3_value_numeric_type(sqlite3_value*);

功能:類似sqlite3_column_*函數

其他:

const char *sqlite3_libversion(void);

int sqlite3_libversion_number(void);

功能:獲取版本號

sqlite_int64 sqlite3_last_insert_rowid(sqlite3*);

功能:獲取最后插入的行標示.

int sqlite3_changes(sqlite3*);

功能:獲取最近執行的sqlite3_exec影響的行數.

int sqlite3_total_changes(sqlite3*);

功能:獲取自從數據庫打開后有改動的函數

void sqlite3_interrupt(sqlite3*);

功能:打斷或停止數據庫當前操作.

int sqlite3_complete(const char *sql);

功能:判斷語句是否以分號(;)結尾

int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*);

功能:設置查詢忙碌時的回調處理

說明:缺省的回調函數為空,如果回調函數為空,表鎖定后sqlite3_exec()執行會直接返回SQLITE_BUSY

int sqlite3_busy_timeout(sqlite3*, int ms);

功能:設置查詢超時時間(毫秒)

char *sqlite3_mprintf(const char*,...);

char *sqlite3_vmprintf(const char*, va_list);

char *sqlite3_snprintf(int,char*,const char*, ...);

功能:格式化字符,需要用%q來代替%s.(主要是不用對分號'進行轉義)

void *sqlite3_malloc(int);

void *sqlite3_realloc(void*, int);

void sqlite3_free(void*);

功能:內存函數

int sqlite3_set_authorizer(

????sqlite3*,

????int (*xAuth)(void*,int,const char*,const char*,const char*,const char*),

????void *pUserData

);

功能:設置數據庫授權

void *sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*);

void *sqlite3_profile(sqlite3*,

void(*xProfile)(void*,const char*,sqlite_uint64), void*);

void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);

功能:設置執行回調函數,sqlite3_exec(),sqlite3_step() ,sqlite3_get_table()時會調用

void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*);

功能:設置事務回調函數

int sqlite3_errcode(sqlite3 *db);

const char *sqlite3_errmsg(sqlite3*);

功能:獲取錯誤碼和錯誤消息

int sqlite3_bind_parameter_count(sqlite3_stmt*);

功能:返回需要綁定的參數數目(sql語句中問號?數量)

const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int);

功能:獲取綁定參數名字,?參數返回NULL

int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName);

功能:獲取綁定參數索引

int sqlite3_clear_bindings(sqlite3_stmt*);

功能:清除綁定的參數

最后編輯于
?著作權歸作者所有,轉載或內容合作請聯系作者
平臺聲明:文章內容(如有圖片或視頻亦包括在內)由作者上傳并發布,文章內容僅代表作者本人觀點,簡書系信息發布平臺,僅提供信息存儲服務。

推薦閱讀更多精彩內容