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