node-sqlite3 直译中文API文档

最新推荐文章于 2024-06-24 22:22:01 发布

bug星君

最新推荐文章于 2024-06-24 22:22:01 发布

阅读量1.8k

点赞数 1

分类专栏： sqlite 文章标签：数据库 sqlite sql

原文链接：https://github.com/TryGhost/node-sqlite3/wiki/API#preparesql--param---callback

版权

sqlite 专栏收录该内容

1 篇文章 0 订阅

订阅专栏

new sqlite3.Database(filename [, mode] [, callback])

描述：

返回新的数据库对象并自动打开数据库。没有单独的方法来打开数据库。

参数：

filename：
有效值为文件名，":memory:"表示匿名内存数据库，空字符串表示匿名磁盘数据库。匿名数据库不会持久化，当关闭数据库句柄时，其内容将丢失。
mode（可选）：
可选一个或多个，值可为：sqlite3.OPEN_READWRITE, sqlite3.OPEN_CREATE, sqlite3.OPEN_FULLMUTEX, sqlite3.OPEN_URI, sqlite3.OPEN_SHAREDCACHE, sqlite3.OPEN_PRIVATECACHE.
默认值为OPEN_READWRITE | OPEN_CREATE | OPEN_FULLMUTEX
callback (可选):
如果提供了该函数，则将在成功打开数据库或发生错误时调用该函数。第一个参数是一个错误对象。当它为空时，表示打开成功。如果没有提供回调，并且发生了错误，则会在数据库对象上发出错误事件，其中error对象是唯一的参数。如果打开成功，则触发一个不带参数的打开事件，而不管是否提供了回调。

sqlite3.verbose()

描述：

将执行模式设置为verbose以产生较长的堆栈跟踪。这是无法重置的。有关详细信息，请参阅有关调试的wiki页面。

Database

close([callback])

描述：

关闭数据库

参数：

callback(可选):
如果提供，该函数将在数据库成功关闭或发生错误时调用。第一个参数是一个错误对象。当它为null时，关闭成功。如果没有提供回调，并且发生了错误，则会在数据库对象上发出错误事件，其中error对象是唯一的参数。如果关闭成功，则触发一个不带参数的close事件，而不管是否提供了回调。

configure(option, value)

描述：

为数据库设置一个配置选项。有效的选项是:

Tracing & profiling
trace:提供一个回调函数作为值。在SQL语句执行时调用，并呈现语句文本。
profile:配置文件:提供一个函数回调。每次执行SQL语句时调用。
busyTimeout: 提供一个整数作为值。设置忙时超时。

run(sql [, param, …] [, callback])

描述：

使用指定的参数运行SQL查询，然后调用回调。它不检索任何结果数据。函数返回调用它的Database对象以允许函数链接

参数：

sql:
要运行的SQL查询。如果SQL查询无效，并且将回调传递给函数，则使用包含来自SQLite的错误消息的错误对象调用该函数。如果没有传递回调而准备失败，则会在底层Statement对象上触发一个错误事件。
param, …(可选):
当SQL语句包含占位符时，您可以将它们传递到这里。它们将在语句执行之前绑定到该语句。有三种方式传递绑定形参:直接在函数的实参中传递，作为数组传递，以及作为命名形参的对象传递。这将自动清除输入RE: issue #57。参数不能用于列名或表名。

如果你想保持回调作为第3个参数，你应该设置param为“[]”(空数组)根据问题#116

// 直接在函数参数中
db.run("UPDATE tbl SET name = ? WHERE id = ?", "bar", 2);

// 为一个数组
db.run("UPDATE tbl SET name = ? WHERE id = ?", [ "bar", 2 ]);

// 为具有命名参数的对象
db.run("UPDATE tbl SET name = $name WHERE id = $id", {
  $id: 2,
  $name: "bar"
});

命名参数可以用: name、 @name和 $name作为前缀。我们建议使用$name，因为JavaScript允许使用美元符号作为变量名而不必转义。还可以在?占位符。这些对应于数组中的位置。注意，占位符索引在SQLite中从1开始。node-sqlite3将数组映射为以1开头的数组，这样您就不必指定一个空值作为第一个数组元素(索引为0)。注意，在本例中，第一个索引是1:

db.run('UPDATE tbl SET name = ?5 WHERE id = ?', {
  1: 2,
  5: 'bar'
})

这将第一个占位符( $id )绑定到 2，索引为 5 的占位符绑定到"bar"。虽然这在SQLite和node-sqlite3中是有效的，但不建议混合使用不同的占位符类型。
如果使用数组或对象绑定形参，则它必须是绑定实参列表中的第一个值。如果在它之前有其他对象，则会抛出错误。数组或对象后面的附加绑定参数将被忽略。

callback(可选):
如果给定了callback，则在语句准备或执行的任何步骤中发生错误时，或在查询运行后调用它。如果发生错误，第一个(也是唯一的)参数将是一个包含错误消息的错误对象。如果执行成功，第一个参数为null。函数的上下文(函数中的this对象)是语句对象。注意，不可能再次运行该语句，因为它在第一次运行后会自动完成。任何后续再次运行该语句的尝试都将失败。

如果执行成功，this 对象将包含两个属性lastID和changes，分别包含最后插入的行ID的值和受此查询影响的行数。注意:

你必须使用旧版的**function () { … }**样式的回调函数，而不是lambda函数，否则 this.lastID 和 this.changes 将undefined
lastID仅在查询是一个成功完成的 INSERT 语句时包含有效信息，changes仅在查询是一个成功完成的UPDATE或DELETE语句时包含有效信息。在所有其他情况下，这些属性的内容是不准确的，不应该使用。.run()函数是唯一设置这两个值的查询方法;所有其他查询方法，如.all()或.get()，都不会检索这些值。

get(sql [, param, …] [, callback])

描述：

使用指定的参数运行SQL查询，然后使用所有结果行调用回调。函数返回Database对象以允许函数链接。参数与 Database#run函数相同，不同之处在于:

回调函数的签名是function(err, row){}。如果结果集为空，则第二个参数undefined，否则它是一个包含第一行值的对象。属性名与结果集的列名对应。不可能通过列索引访问它们;唯一支持的方式是通过列名。

all(sql [, param, …] [, callback])

描述：

使用指定的参数运行SQL查询，然后使用所有结果行调用回调。函数返回Database对象以允许函数链接。参数与Database#run函数相同，不同之处在于:

回调函数的签名是function(err, rows){}。rows 是一个数组。如果结果集为空，则它将是一个空数组，否则它将为每个结果行提供一个对象，该对象依次包含该行的值，如Database#get函数。

注意，它首先检索所有结果行并将它们存储在内存中。对于可能具有较大结果集的查询，使用Database#each函数检索所有行，或使用Database#prepare后跟多个Statement#get调用检索先前未知数量的行。

each(sql [, param, …] [, callback] [, complete])

描述：

使用指定的参数运行SQL查询，并对每个结果行调用一次回调。函数返回Database对象以允许函数链接。参数与Database#run函数相同，不同之处在于:

回调函数的签名是function(err, row){}。如果结果集成功但为空，则永远不会调用回调函数。在所有其他情况下，对检索到的每一行调用一次回调。调用的顺序与结果集中的行顺序完全一致。

在调用所有行回调之后，如果存在，则将调用完成回调。第一个参数是一个错误对象，第二个参数是检索的行数。如果你只指定一个函数，它将被视为行回调，如果你指定了两个，第一个(==倒数第二个)函数将是行回调，最后一个函数将是完成回调。

如果您知道查询只返回非常有限的行数，那么使用Database#all一次性检索所有行可能会更方便。

目前没有办法中止执行。

exec(sql [, callback])

描述：

运行提供的字符串中的所有SQL查询。未检索任何结果行。该函数返回Database对象以允许函数链接。如果查询失败，则不会执行任何后续语句（如果希望执行所有语句或不执行任何语句，请将其包装在事务中）。当所有语句都已成功执行时，或发生错误时，将调用回调函数，第一个参数为null或错误对象。当未提供回调且发生错误时，将在数据库对象上发出error 事件。

注意:这个函数只执行第一个NULL字节以内的语句。