A promise based client library for rqlite, the lightweight, distribubted database built on SQLite, that will work in the browser and in NodeJS. This package is designed to provide a javascript interface that communicates with rqlite API endpoints. Please note that there is no code in this package for writing SQL queries. There are other Javascript SQL generator libraries such as sequel which can be used to create the SQLite query strings. You are welcome to use one of those libraries or write your own SQL queries directly in your code.
The data API will allow you to access the basic CRUD operations of rqlite such as SELECT, INSERT, UPDATE, DELETE, CREATE TABLE and DROP TABLE. To begin using the data API methods you will first want to use the connect function in lib/api/data/client which returns a promise. When the connection is successful the promise will resolve with an data API object.
The follow methods are available on the data API object including their function signatures.
- api.select(sql, options) -
SELECTbased SQL statments - api.insert(sql, options) -
INSERTbased SQL statments - api.update(sql, options) -
UPDATEbased SQL statments - api.delete(sql, options) -
DELETEbased SQL statments - api.table.create(sql, options) -
CREATE TABLEbased SQL statments - api.table.drop(sql, options) -
DROP TABLEbased SQL statments
The code sample shows how would connect to a rqlite server and create a table.
import connect from 'rqlite-js/lib/api/data/client'
import {getError, toPlainJs} from 'rqlite-js/lib/api/results'
try {
const api = await connect('http://localhost:4001')
try {
// You can create your own raw SQL query or use another SQL generator library of your liking.
const sql = 'CREATE TABLE foo (id integer not null primary key, name text)'
const res = await api.table.create(sql)
// We are given back the entire response object if anything is needed, otherwise
// the response body has our rqlite data.
const results = res.body.results
// Check the results for an error to make sure we the SQL query did
// not generate an error while executing.
const error = getError(results)
if (error) {
console.error('rqlite results contained an error.', error)
return
}
// We are successful and have results to use from our SQL query.
console.log('Checkout the rqlite results.', results)
console.log('Checkout the rqlite results as plain Js object for app use.', toPlainJs(results))
} catch (err) {
console.error('The HTTP client got an HTTP error, there must be something else going on.', err)
}
} catch (err) {
console.error('The rqlite-js connect function threw an error.', err)
}The code sample shows how would connect to a rqlite server insert a row then select the row.
import connect from 'rqlite-js/lib/api/data/client'
import {getError, toPlainJs} from 'rqlite-js/lib/api/results'
const api = await connect('http://localhost:4001')
// Insert a row into the table foo we create above in the CREATE TABLE example.
// The values for sql can be a string or an array if you want to execute multiple
// SQL queries on the server.
const sql = 'INSERT INTO foo(name) VALUES(\"fiona\")'
const resInsert = await api.insert(sql)
if (getError(resInsert.body.results)) {
console.error('rqlite results contained an error.', error)
return
}
const id = resInsert.body.results[0].last_insert_id
const sql = `SELECT name FROM foo WHERE id="${id}"`
const res = await api.select(sql)
const results = res.body.results
const error = getError(results)
if (error) {
console.error('rqlite results contained an error.', error)
return
}
console.log('The value for the name field which should equal fiona', results[0].values[0])
console.log('rqlite results are great, but I just want to work with the data', toPlainJs(results))The code sample shows how would connect to a rqlite and run multiple insert queries within a transaction transactions.
import connect from 'rqlite-js/lib/api/data/client'
import {getError, toPlainJs} from 'rqlite-js/lib/api/results'
const api = await connect('http://localhost:4001')
// Insert a row into the table foo we create above in the CREATE TABLE example.
// The values for sql can be a string or an array if you want to execute multiple
// SQL queries on the server.
const sql = [
'INSERT INTO foo(name) VALUES(\"fiona\")',
'INSERT INTO bar(name) VALUES(\"test\")'
]
const res = await api.insert(sql, {transaction: true})
const results = res.body.results
if (getError(results)) {
console.error('rqlite results contained an error.', error)
return
}
console.log('The id for the first insert is in index 0 last_insert_id', results[0].last_insert_id)
console.log('The id for the second insert is in index 1 last_insert_id', results[1].last_insert_id)The code sample shows how would connect to a rqlite and run multiple select queries with strong consistency.
import connect from 'rqlite-js/lib/api/data/client'
import {getError, toPlainJs} from 'rqlite-js/lib/api/results'
const api = await connect('http://localhost:4001')
const sql = [
'SELECT name FROM foo WHERE id="1"',
'SELECT id FROM bar WHERE name="test"'
]
const res = await api.select(sql, {level: 'strong'})
const results = res.body.results
if (getError(results)) {
console.error('rqlite results contained an error.', error)
return
}
console.log('The results for the first select are in index 0', results[0])
console.log('The results for the second select are in index 1', results[1])The code sample shows how would pass a default httpOptions to all HTTP requests for agentkeepalive and set a different timeout. Keepalive is something to be used in NodeJS, on the serverside only, since it is on by default in the browsers. This will speed up requests on the server by re-using HTTP connections. See Agent keepalive for more details https://www.npmjs.com/package/agentkeepalive.
import connect from 'rqlite-js/lib/api/data/client'
import {getError, toPlainJs} from 'rqlite-js/lib/api/results'
import Agent from 'agentkeepalive'
const keepaliveAgent = new Agent({
maxSockets: 100,
maxFreeSockets: 10,
timeout: 60000,
freeSocketKeepAliveTimeout: 30000
})
const options = {
url: 'http://localhost:4001',
// httpOptions will now be applied to all HTTP requests, but can
// still be overridden per request inside of connect.
httpOptions: {
agent: keepaliveAgent,
timeout: {
deadline: 60000
}
}
}
const api = await connect(options)
// This is the same INSERT quert from above, but now it is sent over an HTTP connection
// that remains open for the next request.
const sql = 'INSERT INTO foo(name) VALUES(\"fiona\")'
const resInsert = await api.insert(sql)
if (getError(resInsert.body.results)) {
console.error('rqlite results contained an error.', error)
return
}
const id = resInsert.body.results[0].last_insert_id
const sql = `SELECT name FROM foo WHERE id="${id}"`
// Override the options and turn off keepalive for just this request and change
// the timeout to 10 seconds.
const selectOptions = {
httpOptions: {
agent: undefined,
timeout: {
deadline: 10000
}
}
}
const res = await api.select(sql, selectOptions)
const results = res.body.results
const error = getError(results)
if (error) {
console.error('rqlite results contained an error.', error)
return
}
console.log('The value for the name field which should equal fiona', results[0].values[0])
console.log('rqlite results are great, but I just want to work with the data', toPlainJs(results))Authentication can be passed either inline in the URL or via the httpOptions auth property and object of the form {user, pass}.
import connect from 'rqlite-js/lib/api/data/client'
import {getError, toPlainJs} from 'rqlite-js/lib/api/results'
const user = 'rqliteUsername'
const pass = 'rqlitePassword'
// Notice how we just added the username and password to the URL
const url = `http://${user}:${pass}@localhost:4001`
// This object is equivalent to the url above.
/*
const options = {
url: 'http://localhost:4001',
httpOptions: {
auth: {user, pass}
}
}
*/
const api = await connect(url)
// You can create your own raw SQL query or use another SQL generator library of your liking.
const sql = 'CREATE TABLE foo (id integer not null primary key, name text)'
const res = await api.table.create(sql)
// We are given back the entire response object if anything is needed, otherwise
// the response body has our rqlite data.
const results = res.body.results
// Check the results for an error to make sure we the SQL query did
// not generate an error while executing.
const error = getError(results)
if (error) {
console.error('rqlite results contained an error.', error)
return
}
// We are successful and have results to use from our SQL query.
console.log('Checkout the rqlite results.', results)
console.log('Checkout the rqlite results as plain Js object for app use.', toPlainJs(results))Please see the docs/test/README.md for more information.