Was this page helpful?
Caution
You're viewing documentation for an unstable version of ScyllaDB Node.js Driver. Switch to the latest stable version.
Client¶
Client(options)
Represents a database client that maintains multiple connections to the cluster nodes, providing methods to execute CQL statements.
The Client uses policies to decide which nodes to connect to, which node
to use per each query execution, when it should retry failed or timed-out executions and how reconnection to down
nodes should be made.
Constructor¶
new Client(options)
Creates a new instance of Client.
Parameters:
| Name | Type | Description |
|---|---|---|
options |
The options for this instance. |
Source
Examples
Creating a new client instance
const client = new Client({
contactPoints: ['10.0.1.101', '10.0.1.102'],
});Executing a query
const result = await client.connect();
console.log(`Connected to ${client.hosts.length} nodes in the cluster: ${client.hosts.keys().join(', ')}`);Executing a query
const result = await client.execute('SELECT key FROM system.local');
const row = result.first();
console.log(row['key']);Extends¶
- events.EventEmitter
Members¶
(package) connected
Source
(package) connecting
Source
hosts
Gets an associative array of cluster hosts.
Source
(package) isShuttingDown
Source
keyspace
Gets the name of the active keyspace.
Source
metadata
Gets the schema and cluster metadata information. TODO: This field is currently not supported
Source
metrics
The ClientMetrics instance used to expose measurements of its internal behavior and of the server as seen from the driver side.
By default, a DefaultMetrics instance is used. TODO: This field is currently not supported
Source
(package) options
Source
(package) rustClient
Source
(package) rustOptions
Source
Methods¶
batch(queries, options, callback)
Executes batch of queries on an available connection to a host.
It returns a Promise when a callback is not provided.
Parameters:
| Name | Type | Description |
|---|---|---|
queries |
The queries to execute as an Array of strings or as an array of object containing the query and params. |
|
options |
The query options. |
|
callback |
Executes callback(err, result) when the batch was executed |
Source
connect(callback)
Attempts to connect to one of the contactPoints and discovers the rest the nodes of the cluster.
When the Client is already connected, it resolves immediately.
It returns a Promise when a callback is not provided.
Parameters:
| Name | Type | Description |
|---|---|---|
callback |
The optional callback that is invoked when the pool is connected or it failed to connect. |
Source
Example
Usage example
await client.connect();(package) createOptions()
Manually create final execution options, applying client and default setting.
Creating those options requires a native call, but they can be reused without any additional native calls, which improves performance for queries with the same QueryOptions.
Source
eachRow(query, params, options, rowCallback, callback)
Executes the query and calls rowCallback for each row as soon as they are received. Calls the final
callback after all rows have been sent, or when there is an error.
The query can be prepared (recommended) or not depending on the prepare flag.
Parameters:
| Name | Type | Description |
|---|---|---|
query |
The query to execute |
|
params |
Array of parameter values or an associative array (object) containing parameter names as keys and its value. |
|
options |
The query options. |
|
rowCallback |
Executes |
|
callback |
Executes When dealing with paged results, ResultSet#nextPage() method can be used
to retrieve the following page. In that case, |
Source
Examples
Using per-row callback and arrow functions
client.eachRow(query, params, { prepare: true }, (n, row) => console.log(n, row), err => console.error(err));Overloads
client.eachRow(query, rowCallback);
client.eachRow(query, params, rowCallback);
client.eachRow(query, params, options, rowCallback);
client.eachRow(query, params, rowCallback, callback);
client.eachRow(query, params, options, rowCallback, callback);execute(query, params, options, callback)
Executes a query on an available connection.
The query can be prepared (recommended) or not depending on the prepare flag.
Some execution failures can be handled transparently by the driver, according to the
RetryPolicy or the
SpeculativeExecutionPolicy used.
It returns a Promise when a callback is not provided.
Parameters:
| Name | Type | Description |
|---|---|---|
query |
The query to execute. |
|
params |
Array of parameter values or an associative array (object) containing parameter names as keys and its value. |
|
options |
The query options for the execution. |
|
callback |
Executes callback(err, result) when execution completed. When not defined, the method will return a promise. |
- See:
-
- ExecutionProfile to reuse a set of options across different query executions.
Source
Examples
Promise-based API, using async/await
const query = 'SELECT name, email FROM users WHERE id = ?';
const result = await client.execute(query, [ id ], { prepare: true });
const row = result.first();
console.log('%s: %s', row['name'], row['email']);Callback-based API
const query = 'SELECT name, email FROM users WHERE id = ?';
client.execute(query, [ id ], { prepare: true }, function (err, result) {
assert.ifError(err);
const row = result.first();
console.log('%s: %s', row['name'], row['email']);
});executeGraph()
Source
Deprecated
Not supported by the driver. Usage will throw an error.
getReplicas()
Gets the host that are replicas of a given token.
Source
getState()
Source
Deprecated
This is not planned feature for the driver. Currently this remains in place, but returns Client state with no information. This endpoint may be removed at any point.
Returns:
A dummy ClientState instance.
(async, package) prepareStatement()
Manually prepare query into prepared statement.
Source
(async, package) rustyExecute(pageState)
Wrapper for executing queries by rust driver. When called with a pageState argument (including null), executes a single-page query. When called without pageState, executes an unpaged query.
Parameters:
| Name | Type | Description |
|---|---|---|
pageState |
When provided (including null), enables paged execution. When unprovided (undefined), executes an unpaged query. |
Source
shutdown(callback)
The only effect of calling shutdown is rejecting any following queries to the database.
It returns a Promise when a callback is not provided.
Parameters:
| Name | Type | Description |
|---|---|---|
callback |
Optional callback to be invoked when finished closing all connections. |
Source
Deprecated
Explicit connection shutdown is deprecated and may be removed in the future. Drop this client to close the connection to the database.
stream(query, params, options, callback)
Executes the query and pushes the rows to the result stream as soon as they received.
The stream is a ReadableStream object that emits rows. It can be piped downstream and provides automatic pause/resume logic (it buffers when not read).
The query can be prepared (recommended) or not depending on QueryOptions.prepare flag. Retries on multiple hosts if needed.
Parameters:
| Name | Type | Description |
|---|---|---|
query |
The query to prepare and execute. |
|
params |
Array of parameter values or an associative array (object) containing parameter names as keys and its value |
|
options |
The query options. |
|
callback |
executes callback(err) after all rows have been received or if there is an error |
Source
Events¶
hostAdd
Emitted when a new host is added to the cluster.
- Host The host being added.
Source
hostDown
Emitted when a host in the cluster changed status from up to down.
- host The host that changed the status.
Source
hostRemove
Emitted when a host is removed from the cluster
- Host The host being removed.
Source
hostUp
Emitted when a host in the cluster changed status from down to up.
- host The host that changed the status.
Source