Node.js 6.11.0 or later VoltDB 7.5 or later
Run NPM to install all the dependencies for the driver itself. The example application does not automatically install its dependencies, so do npm install in both the directory where the node.js driver is installed and the example/voter/voter folder as well.
npm install
The VoltDB is a high throughput, ACID compliant database that works best when using an asynchronous client. This wire driver runs in asynchronous mode only.
Please see the documentation for administering and using VoltDB on the VoltDB community page
The example uses the voter example server included in the VoltDB distribution. It is found in VOLTDB_HOME/examples/voter.
1. Start the server
./run.sh server
2. In a second terminal, run the sample
cd ./examples/voter/voter
node ./app.js
3. Open a browser and connect to localhost:3000 and watch the voting results.
The example include detailed comments about how the application runs in the app.js and volt.js files.
You may want to set the number of VoltDB sites per host to something interesting in VOLTDB_HOME/examples/voter/deployment.xml. The
sites per host value is equivalent to the number of cores that VoltDB will use for the server when you are running a single instance on localhost.
This provides the interface for connecting to the VoltDB server, managing event processing and executing stored procedures.
- configurationArray: A collection of configurations for connecting to and managing all of the nodes within the VoltDB cluster.
Creates an instance of the client and sets internal properties, but does not perform the actual connection operation.
- callback: A handler that gets the success and failure statuses for each of the servers specified in the
configurationArrayin theVoltClient
Attempts to connect to each of the VoltDB server configurations passed into the constructor. The callback will be invoked for each connection. Connections may fail and the callback will receive error information. See the Callbacks section for callback parameter information.
- query: An instance of a
VoltQueryobject. - readCallback: callback that receives the results of a query.
- writeCallback: callback that is invoked when the client driver is able to write again to the driver.
This function manages all queries to the VoltDB server. This includes whether it is safe to allow for more writes, encoding of query parameters and management of the outgoing query queue.
Calling this function in a loop is generally discouraged since it can lead to blocking socket reads. The VoltDB server will drop a connection if data lingers on the socket for too long. The writeCallback handler is mechanism for avoiding that particular problem is it will get invoked each time the driver is able to issue another query.
See the Callbacks section for callback parameter information.
Create a VoltConfiguration object for each server within a VoltDB cluster. Pass this configuration into the VoltClient(configurationArray) constructor.
- VoltConfiguration.host: The server name
- VoltConfiguration.port: The server port (optional)
- VoltConfiguration.username: Username if not using the default. (optional)
- VoltConfiguration.password: Password if not using the default. (optional)
- VoltConfiguration.service: Service if not using the default. (optional)
- VoltConfiguration.queryTimeout: How long a query should be allowed to be pending before the driver issues an error message. (optional)
- VoltConfiguration.queryTimeoutInterval: The interval for checking for queries that have timed out. Also cleans out the queue of processed queries. (optional)
- VoltConfiguration.flushInterval: How long to wait before flushing the query queue. (optional)
- VoltConfiguration.messageQueueSize: Maximum number of messages to place in the driver's internal message queue before writing them to the outgoing socket. The default value is set to 10 and it is not recommended to create queue much larger as the gains become less significant as the queue grows. (optional)
- VoltConfiguration.maxConsecutiveWrites: The driver will only allow this number of writes to the outgoing queue and socket before requiring a read operation. This is necessary to ensure that read operations are not blocked. The default value is 5000 queries. If you find that connections between the client and server are being dropped by the server, then lower this value to ensure more frequent reads. (optional)
Defines a template for a query, which includes the name of the procedure and the parameter types that can be passed to the query.
- name: The name of the stored procedure.
- types: An array of types specified as a set of strings.
Example
var resultsProc = new VoltProcedure('Results');
var initProc = new VoltProcedure('Initialize', ['int', 'string']);
var voteProc = new VoltProcedure('Vote', ['long', 'int', 'long']);
A complete list of types is specified in the Data Types section
Returns an instance of a VoltQuery.
VoltQuery is necessary for query invocation, but the application developer does very little with it. A VoltQuery is produced by the VoltProcedure.getQuery() function. That object is then passed to the VoltClient.callProcedurefunction.
Called only by the VoltProcedure object.
All callbacks take follow the same structure: (errorCode, eventCode, result)
- errorCode: Will be set to null if successful or a numeric value if an error occurred. See Error Codes for details on each error code.
Example 1: Using status codes
client.callProcedure(query, displayResults(errorCode, eventCode, results) {
if(errorCode == VoltConstants.STATUS_CODES.SUCCESS) {
// Success!
} else {
// Error handling
}
});
Example 2: No status codes
client.callProcedure(query, displayResults(errorCode, eventCode, results) {
if(errorCode) {
// Error Handling
} else {
// Success!
}
});
- SESSION_EVENT.CONNECTION: A successful connection to the volt server
- SESSION_EVENT.CONNECTION_ERROR: Could not connect, see both the status code and the event handler's message parameter.
- SESSION_EVENT.QUERY_RESPONSE: Query executed and returned.
- SESSION_EVENT.QUERY_ALLOWED: Indicates that the application may execute another query Note that this prevents your application from flooding the database and the application's code from blocking.
- SESSION_EVENT.QUERY_RESPONSE_ERROR:The query was successfully dispatched but theVoltDB server either had a critical fault or dropped the connection.
- SESSION_EVENT.QUERY_DISPATCH_ERROR: The client could not dispatch the query.
- SESSION_EVENT.FATAL_ERROR: A critical error occurred that was above and beyond all other error conditions.
- STATUS_CODES.SUCCESS: Operation succeeded. Note that the value of this constant is null.
- STATUS_CODES.USER_ABORT: The user's stored procedure intentionally threw an exception of type
UserAbortException. - STATUS_CODES.GRACEFUL_FAILURE: Query had an error that rolled back the transaction.
- STATUS_CODES.UNEXPECTED_FAILURE: Query had an error, rolled back the transaction and caused additional errors.
- STATUS_CODES.CONNECTION_LOST: The connection to VoltDB was lost before the query returned. This is not issued by the server, but is issued by the client.
- STATUS_CODES.SERVER_UNAVAILABLE: Attempted to use an invalid connection.
- STATUS_CODES.CONNECTION_TIMEOUT: The server stopped replying.
- STATUS_CODES.QUERY_TIMEOUT: The server issues a message saying that the query took too long to execute.
- STATUS_CODES.QUERY_TOOK_TOO_LONG: Driver issued message indicating that the server has taken too long to respond.
These data types are not JavaScript data types. The driver uses these type specifiers to encode a JavaScript type into a VoltDB type.
- null: Use
null - byte: Use a number, not a string
- tinyint: Use a number, not a string
- short: Use a number, not a string
- smallint: Use a number, not a string
- int: Use a number, not a string
- integer: Use a number, not a string
- long: Use a number, not a string
- bigint: Use a number, not a string
- double: Use a number, not a string
- float: Use a number, not a string
- string: Use a string
- date: Use a number, not a string
- timestamp: Use a number, not a string
- decimal: Use a number, not a string
- varbinary: Use a
Buffer