輕量級資料庫sqlite的介面說明

標籤：

原文地址：http://www.cnblogs.com/kfqcome/archive/2011/06/27/2136999.html

一．使用流程

要使用sqlite，需要從sqlite官網下載到三個檔案，分別為sqlite3.lib，sqlite3.dll，sqlite3.h，然後再在自己的工程中配置好標頭檔和庫檔案，同時將dll檔案放到目前的目錄下，就完成配置可以使用sqlite了。

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

• sqlite3_open()
• sqlite3_prepare()
• sqlite3_step()
• sqlite3_column()
• sqlite3_finalize()
• sqlite3_close()

這幾個過程是概念上的說法，而不完全是程式啟動並執行過程，如sqlite3_column()表示的是對查詢獲得一行裡面的資料的列的各個操作統稱，實際上在sqlite中並不存在這個函數。

1．  sqlite3_open()：開啟資料庫

在操作資料庫之前，首先要開啟資料庫。這個函數開啟一個sqlite資料庫檔案的串連並且返回一個資料庫連接對象。這個操作同時程式中的第一個調用的sqlite函數，同時也是其他sqlite api的先決條件。許多的sqlite介面函數都需要一個資料庫連接對象的指標作為它們的第一個參數。

函數定義

int sqlite3_open(

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

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

);

int sqlite3_open16(

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

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

);

int sqlite3_open_v2(

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

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

  int flags,              /* 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*);

        

參數說明：

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語句

函數定義（僅列出UTF-8的）

int sqlite3_prepare(

  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 */

);

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 */

);

 

參數：

db：資料指標

zSql：sql語句，使用UTF-8編碼

nByte：如果nByte小於0，則函數取出zSql中從開始到第一個0終止符的內容；如果nByte不是負的，那麼它就是這個函數能從zSql中讀取的位元組數的最大值。如果nBytes非負，zSql在第一次遇見’/000/或’u000’的時候終止

pzTail：上面提到zSql在遇見終止符或者是達到設定的nByte之後結束，假如zSql還有剩餘的內容，那麼這些剩餘的內容被存放到pZTail中，不包括終止符

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

 

說明

如果執行成功，則返回SQLITE_OK，否則返回一個錯誤碼。推薦在現在任何的程式中都使用sqlite3_prepare_v2這個函數，sqlite3_prepare只是用於前向相容

 

備忘

<1>準備語句（prepared statement）對象

typedef struct sqlite3_stmt sqlite3_stmt;

        

準備語句（prepared statement）對象一個代表一個簡單SQL語句對象的執行個體，這個對象通常被稱為“準備語句”或者“編譯好的SQL語句”或者就直接稱為“語句”。

         語句對象的生命週期經曆這樣的過程：

l  使用sqlite3_prepare_v2或相關的函數建立這個對象

l  使用sqlite3_bind_*()給宿主參數（host parameters）綁定值

l  通過調用sqlite3_step一次或多次來執行這個sql

l  使用sqlite3——reset()重設這個語句，然後回到第2步，這個過程做0次或多次

l  使用sqlite3_finalize()銷毀這個對象

 

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

<2>宿主參數(host parameters)

在傳給sqlite3_prepare_v2()的sql的語句文本或者它的變數中，滿足如下模板的文字將被替換成一個參數：

l  ?

l  ?NNN，NNN代表數字

l  :VVV，VVV代表字元

l  @VVV

l  $VVV

在上面這些模板中，NNN代表一個數字，VVV代表一個字母數字標記符（例如:222表示名稱為222的標記符），sql語句中的參數（變數）通過上面的幾個模板來指定，如

“select ? from ? “這個語句中指定了兩個參數，sqlite語句中的第一個參數的索引值是1，這就知道這個語句中的兩個參數的索引分別為1和2，使用”?”的話會被自動給予索引值，而使用”?NNN”則可以自己指定參數的索引值，它表示這個參數的索引值為NNN。”:VVV”表示一個名為”VVV”的參數，它也有一個索引值，被自動指定。

可以使用sqlite3_bind_*()來給這些參數綁定值

 

 

 

3．  sqlite3_setp()

這個過程用於執行有前面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。

int sqlite3_reset(sqlite3_stmt *pStmt);

sqlite3_reset用於重設一個準備語句對象到它的初始狀態，然後準備被重新執行。所有sql語句變數使用sqlite3_bind*綁定值，使用sqlite3_clear_bindings重設這些綁定。Sqlite3_reset介面重設準備語句到它代碼開始的時候。sqlite3_reset並不改變在準備語句上的任何綁定值，那麼這裡猜測，可能是語句在被執行的過程中發生了其他的改變，然後這個語句將它重設到綁定值的時候的那個狀態。

 

4．  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);

sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol);

說明

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

這些過程會根據情況去轉換數值的類型，sqlite內部使用sqlite3_snprintf()去自動進行這個轉換，下面是關於轉換的細節表：

內部類型	請求的類型	轉換
NULL	INTEGER	結果是0
NULL	FLOAT	結果是0.0
NULL	TEXT	結果是NULL
NULL	BLOB	結果是NULL
INTEGER	FLOAT	從整形轉換到浮點型
INTEGER	TEXT	整形的ASCII碼顯示
INTEGER	BLOB	同上
FLOAT	INTEGER	浮點型轉換到整形
FLOAT	TEXT	浮點型的ASCII顯示
FLOAT	BLOB	同上
TEXT	INTEGER	使用atoi()
TEXT	FLOAT	使用atof()
TEXT	BLOB	沒有轉換
BLOB	INTEGER	先到TEXT，然後使用atoi
BLOB	FLOAT	先到TEXT，然後使用atof
BLOB	TEXT	如果需要的話添加0終止符

 

註：BLOB資料類型是指二進位的資料區塊，比如要在資料庫中存放一張圖片，這張圖片就會以二進位形式存放，在sqlite中對應的資料類型就是BLOB

 

int sqlite3_column_bytes(sqlite3_stmt*, int iCol)int sqlite3_column_bytes16(sqlite3_stmt*, int iCol)兩個函數返回對應列的內容的位元組數，這個位元組數不包括後面類型轉換過程中加上的0終止符。

下面是幾個最安全和最簡單的使用原則

• 先sqlite3_column_text() ，然後 sqlite3_column_bytes()
• 先sqlite3_column_blob()，然後sqlite3_column_bytes()
• 先sqlite3_column_text16()，然後sqlite3_column_bytes16()

 

 

5．  sqlite3_finalize

    int sqlite3_finalize(sqlite3_stmt *pStmt);

這個過程銷毀前面被sqlite3_prepare建立的準備語句，每個準備語句都必須使用這個函數去銷毀以防止記憶體泄露。

在null 指標上調用這個函數沒有什麼影響，同時可以準備語句的生命週期的任一時刻調用這個函數：在語句被執行前，一次或多次調用sqlite_reset之後，或者在sqlite3_step任何調用之後不管語句是否完成執行

 

6．  sqlite3_close

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

輕量級資料庫sqlite的介面說明