# APICloud db組件
db 模塊封裝了手機常用數據庫 sqlite 的增刪改查語句，可實現數據的本地存儲，極大的簡化了數據持久化問題，本模塊已支持同步接口。
# 異步接口
# openDatabase
打開數據庫，若數據庫不存在則創建數據庫。
數據庫打開后即使當前頁面關閉了，數據庫也不會關閉，除非手動調用 closeDatabase()方法關閉，所以一旦打開在其它頁面就可以直接使用。
若數據庫放在 widget 目錄下，那么需要先把數據庫拷貝到 fs:// 對應目錄下面再使用
openDatabase({params}, callback(ret, err))
## params
name：
* 類型：字符串
* 描述：數據庫名稱
path：
* 類型：字符串
* 描述：（可選項）數據庫所在路徑，不傳時使用默認創建的路徑。支持 fs://、widget://等協議（如fs://user.db）
* 默認值：自動創建的路徑
## callback(ret, err)
ret：
* 類型：JSON 對象
* 內部字段：
~~~
{
status: true //布爾類型；操作成功狀態值，true|false
}
~~~
err：
* 類型：JSON 對象
* 內部字段：
~~~
{
code: '', //數字類型；錯誤碼，詳情參考-----附錄之‘錯誤碼對照表’。本參數暫僅支持iOS平臺
msg: '' //字符串類型；錯誤信息
}
~~~
## 示例代碼
~~~
var db = api.require('db');
db.openDatabase({
name: 'test'
}, function(ret, err) {
if (ret.status) {
alert(JSON.stringify(ret));
} else {
alert(JSON.stringify(err));
}
});
~~~
## 可用性
iOS系統，Android系統，PC 模擬器
可提供的1.0.0及更高版本
# closeDatabase
關閉數據庫
closeDatabase({params}, callback(ret, err))
## params
name：
* 類型：字符串
* 描述：數據庫名稱
## callback(ret, err)
ret：
* 類型：JSON 對象
* 內部字段：
~~~
{
status: true //布爾類型；操作成功狀態值，true|false
}
~~~
err：
* 類型：JSON 對象
* 內部字段：
~~~
{
code: '', //數字類型；錯誤碼，詳情參考-----附錄之‘錯誤碼對照表’。本參數暫僅支持iOS平臺
msg: '' //字符串類型；錯誤描述
}
~~~
## 示例代碼
~~~
var db = api.require('db');
db.closeDatabase({
name: 'test'
}, function(ret, err) {
if (ret.status) {
alert(JSON.stringify(ret));
} else {
alert(JSON.stringify(err));
}
});
~~~
## 可用性
iOS系統，Android系統，PC 模擬器
可提供的1.0.0及更高版本
# transaction
執行事務操作語句
transaction({params}, callback(ret, err))
## params
name：
* 類型：字符串
* 描述：數據庫名稱
operation：
* 類型：字符串
* 描述：事務操作類型，取值范圍如下：
* begin //開始事務
* commit //提交事務
* rollback //回滾操作
## callback(ret, err)
ret：
* 類型：JSON 對象
* 內部字段：
~~~
{
status: true //布爾類型；操作成功狀態值，true|false
}
~~~
err：
* 類型：JSON 對象
* 內部字段：
~~~
{
code: '', //數字類型；錯誤碼，詳情參考-----附錄之‘錯誤碼對照表’。本參數暫僅支持iOS平臺
msg: '' //字符串類型；錯誤描述
}
~~~
## 示例代碼
~~~
var db = api.require('db');
db.transaction({
name: 'test',
operation: 'begin'
}, function(ret, err) {
if (ret.status) {
alert(JSON.stringify(ret));
} else {
alert(JSON.stringify(err));
}
});
~~~
## 可用性
iOS系統，Android系統，PC 模擬器
可提供的1.0.0及更高版本
# executeSql
執行 sql
executeSql({params}, callback(ret, err))
## params
name：
* 類型：字符串
* 描述：數據庫名稱
sql：
* 類型：字符串
* 描述：sql 語句
## callback(ret, err)
ret：
* 類型：JSON 對象
* 內部字段：
~~~
{
status: true //布爾類型；操作成功狀態值，true|false
}
~~~
err：
* 類型：JSON 對象
* 內部字段：
~~~
{
code: '', //數字類型；錯誤碼，詳情參考-----附錄之‘錯誤碼對照表’。本參數暫僅支持iOS平臺
msg: '' //字符串類型；錯誤描述
}
~~~
## 示例代碼
~~~
var db = api.require('db');
db.executeSql({
name: 'test',
sql: 'CREATE TABLE Persons(Id_P int, LastName varchar(255), FirstName varchar(255), Address varchar(255), City varchar(255))'
}, function(ret, err) {
if (ret.status) {
alert(JSON.stringify(ret));
} else {
alert(JSON.stringify(err));
}
});
~~~
## 可用性
iOS系統，Android系統，PC模擬器
可提供的1.0.0及更高版本
# selectSql
查詢sql
selectSql({params}, callback(ret, err))
## params
name：
* 類型：字符串
* 描述：數據庫名稱
sql：
* 類型：字符串
* 描述：sql語句
## callback(ret, err)
ret：
* 類型：JSON 對象
* 內部字段：
~~~
{
status: true, //布爾類型；操作成功狀態值，true|false
data: [] //數組類型；查詢結果數據
}
~~~
err：
* 類型：JSON 對象
* 內部字段：
~~~
{
code: '', //數字類型；錯誤碼，詳情參考-----附錄之‘錯誤碼對照表’。本參數暫僅支持iOS平臺
msg: '' //字符串類型；錯誤描述
}
~~~
## 示例代碼
~~~
var db = api.require('db');
db.selectSql({
name: 'test',
sql: 'SELECT * FROM Persons'
}, function(ret, err) {
if (ret.status) {
alert(JSON.stringify(ret));
} else {
alert(JSON.stringify(err));
}
});
~~~
## 可用性
iOS系統，Android系統，PC 模擬器
可提供的1.0.0及更高版本
# 同步接口
# openDatabaseSync
打開數據庫，若數據庫不存在則創建數據庫（同步接口）。
數據庫打開后即使當前頁面關閉了，數據庫也不會關閉，除非手動調用 closeDatabase()方法關閉，所以一旦打開在其它頁面就可以直接使用。
若數據庫放在 widget 目錄下，那么需要先把數據庫拷貝到 fs:// 對應目錄下面再使用
openDatabaseSync({params})
## params
name：
* 類型：字符串
* 描述：數據庫名稱
path：
* 類型：字符串
* 描述：（可選項）數據庫所在路徑，不傳時使用默認創建的路徑。支持 fs://、widget://等協議（如fs://user.db）
* 默認值：自動創建的路徑
## return
ret：
* 類型：JSON 對象
* 內部字段：
~~~
{
status: true, //布爾類型；操作成功狀態值，true|false
code: '', //數字類型；錯誤碼，詳情參考-----附錄之‘錯誤碼對照表’。，僅當 status 為 false 時有值。本參數暫僅支持iOS平臺
msg: '' //字符串類型；錯誤描述，僅當 status 為 false 時有值
}
~~~
## 示例代碼
~~~
var db = api.require('db');
var ret = db.openDatabaseSync({
name: 'test'
});
alert(JSON.stringify(ret));
~~~
## 可用性
iOS系統，Android系統
可提供的1.0.0及更高版本
# closeDatabaseSync
關閉數據庫（同步接口）
closeDatabaseSync({params})
## params
name：
* 類型：字符串
* 描述：數據庫名稱
## return
ret：
* 類型：JSON 對象
* 內部字段：
~~~
{
status: true, //布爾類型；操作成功狀態值，true|false
code: '', //數字類型；錯誤碼，詳情參考-----附錄之‘錯誤碼對照表’。，僅當 status 為 false 時有值。本參數暫僅支持iOS平臺
msg: '' //字符串類型；錯誤描述，僅當 status 為 false 時有值
}
~~~
## 示例代碼
~~~
var db = api.require('db');
var ret = db.closeDatabaseSync({
name: 'test'
});
alert(JSON.stringify(ret));
~~~
## 可用性
iOS系統，Android系統
可提供的1.0.0及更高版本
# transactionSync
執行事務操作語句（同步接口）
transactionSync({params})
## params
name：
* 類型：字符串
* 描述：數據庫名稱
operation：
* 類型：字符串
* 描述：事務操作類型，取值范圍如下：
* begin //開始事務
* commit //提交事務
* rollback //回滾操作
## return
ret：
* 類型：JSON 對象
* 內部字段：
~~~
{
status: true, //布爾類型；操作成功狀態值，true|false
code: '', //數字類型；錯誤碼，詳情參考-----附錄之‘錯誤碼對照表’。，僅當 status 為 false 時有值。本參數暫僅支持iOS平臺
msg: '' //字符串類型；錯誤描述，僅當 status 為 false 時有值
}
~~~
## 示例代碼
~~~
var db = api.require('db');
var ret = db.transactionSync({
name: 'test',
operation: 'begin'
});
alert(JSON.stringify(ret));
~~~
## 可用性
iOS系統，Android系統
可提供的1.0.0及更高版本
# executeSqlSync
執行 sql（同步接口）
executeSqlSync({params})
## params
name：
* 類型：字符串
* 描述：數據庫名稱
sql：
* 類型：字符串
* 描述：sql 語句
## return
ret：
* 類型：JSON 對象
* 內部字段：
~~~
{
status: true, //布爾類型；操作成功狀態值，true|false
code: '', //數字類型；錯誤碼，詳情參考-----附錄之‘錯誤碼對照表’。，僅當 status 為 false 時有值。本參數暫僅支持iOS平臺
msg: '' //字符串類型；錯誤描述，僅當 status 為 false 時有值
}
~~~
## 示例代碼
~~~
var db = api.require('db');
var ret = db.executeSqlSync({
name: 'test',
sql: 'CREATE TABLE Persons(Id_P int, LastName varchar(255), FirstName varchar(255), Address varchar(255), City varchar(255))'
});
alert(JSON.stringify(ret));
~~~
## 可用性
iOS系統，Android系統
可提供的1.0.0及更高版本
# selectSqlSync
查詢 sql（同步接口）
selectSqlSync({params})
## params
name：
* 類型：字符串
* 描述：數據庫名稱
sql：
* 類型：字符串
* 描述：sql語句
## return
ret：
* 類型：JSON 對象
* 內部字段：
~~~
{
status: true, //布爾類型；操作成功狀態值，true|false
data: [], //數組類型；查詢結果數據
code: '', //數字類型；錯誤碼，詳情參考-----附錄之‘錯誤碼對照表’。，僅當 status 為 false 時有值。本參數暫僅支持iOS平臺
msg: '' //字符串類型；錯誤描述，僅當 status 為 false 時有值
}
~~~
## 示例代碼
~~~
var db = api.require('db');
var ret = db.selectSqlSync({
name: 'test',
sql: 'SELECT * FROM Persons'
});
alert(JSON.stringify(ret));
~~~
## 可用性
iOS系統，Android系統
可提供的1.0.0及更高版本
# 附錄
# 錯誤碼對照表
* 0：SQLITE_OK /*?Successful result?*/
* 1：SQLITE_ERROR /*?SQL error or missing database?*/
* 2：SQLITE_INTERNAL /*?Internal logic error in SQLite?*/
* 3：SQLITE_PERM /*?Access permission denied?*/
* 4：SQLITE_ABORT /*?Callback routine requested an abort?*/
* 5：SQLITE_BUSY /*?The database file is locked?*/
* 6：SQLITE_LOCKED /*?A table in the database is locked?*/
* 7：SQLITE_NOMEM /*?A malloc() failed?*/
* 8：SQLITE_READONLY /*?Attempt to write a readonly database?*/
* 9：SQLITE_INTERRUPT /*?Operation terminated by sqlite3_interrupt()*/
* 10：SQLITE_IOERR /*?Some kind of disk I/O error occurred?*/
* 11：SQLITE_CORRUPT /*?The database disk image is malformed?*/
* 12：SQLITE_NOTFOUND /*?Unknown opcode in sqlite3_file_control()?*/
* 13：SQLITE_FULL /*?Insertion failed because database is full?*/
* 14：SQLITE_CANTOPEN /*?Unable to open the database file?*/
* 15：SQLITE_PROTOCOL /*?Database lock protocol error?*/
* 16：SQLITE_EMPTY /*?Database is empty?*/
* 17：SQLITE_SCHEMA /*?The database schema changed?*/
* 18：SQLITE_TOOBIG /*?String or BLOB exceeds size limit?*/
* 19：SQLITE_CONSTRAINT /*?Abort due to constraint violation?*/
* 20：SQLITE_MISMATCH /*?Data type mismatch?*/
* 21：SQLITE_MISUSE /*?Library used incorrectly?*/
* 22：SQLITE_NOLFS /*?Uses OS features not supported on host?*/
* 23：SQLITE_AUTH /*?Authorization denied?*/
* 24：SQLITE_FORMAT /*?Auxiliary database format error?*/
* 25：SQLITE_RANGE /*?2nd parameter to sqlite3_bind out of range?*/
* 26：SQLITE_NOTADB /*?File opened that is not a database file?*/
* 27：SQLITE_NOTICE /*?Notifications from sqlite3_log()?*/
* 28：SQLITE_WARNING /*?Warnings from sqlite3_log()?*/
* 100：SQLITE_ROW /*?sqlite3_step() has another row ready?*/
* 101：SQLITE_DONE /*?sqlite3_step() has finished executing?*/
