{"id":15029060,"url":"https://github.com/datastax/nodejs-driver","last_synced_at":"2025-04-23T00:04:34.077Z","repository":{"id":20429921,"uuid":"23706552","full_name":"datastax/nodejs-driver","owner":"datastax","description":"DataStax Node.js Driver for Apache Cassandra","archived":false,"fork":false,"pushed_at":"2025-03-11T14:08:01.000Z","size":6542,"stargazers_count":1253,"open_issues_count":17,"forks_count":205,"subscribers_count":63,"default_branch":"master","last_synced_at":"2025-04-01T20:15:16.620Z","etag":null,"topics":["cassandra","client","database","datastax","datastax-driver","driver","javascript","nodejs","nosql"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/datastax.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-09-05T14:46:37.000Z","updated_at":"2025-03-28T10:44:31.000Z","dependencies_parsed_at":"2024-05-02T21:49:09.230Z","dependency_job_id":"3308d224-342f-47cc-8e4f-3b39360464b7","html_url":"https://github.com/datastax/nodejs-driver","commit_stats":{"total_commits":1313,"total_committers":70,"mean_commits":"18.757142857142856","dds":0.5247524752475248,"last_synced_commit":"f767bcc6dad71939a3314f71eac8d43607e9c8aa"},"previous_names":[],"tags_count":52,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datastax%2Fnodejs-driver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datastax%2Fnodejs-driver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datastax%2Fnodejs-driver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datastax%2Fnodejs-driver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/datastax","download_url":"https://codeload.github.com/datastax/nodejs-driver/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247927403,"owners_count":21019526,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cassandra","client","database","datastax","datastax-driver","driver","javascript","nodejs","nosql"],"created_at":"2024-09-24T20:09:39.912Z","updated_at":"2025-04-08T21:10:14.928Z","avatar_url":"https://github.com/datastax.png","language":"JavaScript","readme":"# DataStax Node.js Driver for Apache Cassandra®\n\nA modern, [feature-rich](#features) and highly tunable Node.js client library for Apache Cassandra and [DSE][dse] using\nexclusively Cassandra's binary protocol and Cassandra Query Language.\n\n## Installation\n\n```bash\n$ npm install cassandra-driver\n```\n\n[![Build Status](https://api.travis-ci.com/datastax/nodejs-driver.svg?branch=master)](https://travis-ci.org/datastax/nodejs-driver)\n[![Build status](https://ci.appveyor.com/api/projects/status/m21t2tfdpmkjex1l/branch/master?svg=true)](https://ci.appveyor.com/project/datastax/nodejs-driver/branch/master)\n\n\n## Features\n\n- Simple, Prepared, and [Batch][batch] statements\n- Asynchronous IO, parallel execution, request pipelining\n- [Connection pooling][pooling]\n- Auto node discovery\n- Automatic reconnection\n- Configurable [load balancing][load-balancing] and [retry policies][retry]\n- Works with any cluster size\n- Built-in [object mapper][doc-mapper]\n- Both [promise and callback-based API][doc-promise-callback]\n- [Row streaming and pipes](#row-streaming-and-pipes)\n- Built-in TypeScript support\n\n## Documentation\n\n- [Documentation index][doc-index]\n- [CQL types to JavaScript types][doc-datatypes]\n- [API docs][doc-api]\n- [FAQ][faq]\n\n## Getting Help\n\nYou can use the [project mailing list][mailinglist] or create a ticket on the [Jira issue tracker][jira].\n\n## Basic usage\n\n```javascript\nconst cassandra = require('cassandra-driver');\n\nconst client = new cassandra.Client({\n  contactPoints: ['h1', 'h2'],\n  localDataCenter: 'datacenter1',\n  keyspace: 'ks1'\n});\n\nconst query = 'SELECT name, email FROM users WHERE key = ?';\n\nclient.execute(query, [ 'someone' ])\n  .then(result =\u003e console.log('User with email %s', result.rows[0].email));\n```\n\nThe driver supports both [promises and callbacks][doc-promise-callback] for the asynchronous methods,\nyou can choose the approach that suits your needs.\n\nNote that in order to have concise code examples in this documentation, we will use the promise-based API of the \ndriver along with the `await` keyword.\n\nIf you are using [DataStax Astra][astra] you can configure your client by setting the secure bundle and the\n user credentials:\n\n```javascript\nconst client = new cassandra.Client({\n  cloud: { secureConnectBundle: 'path/to/secure-connect-DATABASE_NAME.zip' },\n  credentials: { username: 'user_name', password: 'p@ssword1' }\n});\n```\n\n### Prepare your queries\n\nUsing prepared statements provides multiple benefits.\n\nPrepared statements are parsed and prepared on the Cassandra nodes and are ready for future execution.\nAlso, when preparing, the driver retrieves information about the parameter types which\n **allows an accurate mapping between a JavaScript type and a Cassandra type**.\n\nThe driver will prepare the query once on each host and execute the statement with the bound parameters.\n\n```javascript\n// Use query markers (?) and parameters\nconst query = 'UPDATE users SET birth = ? WHERE key=?'; \nconst params = [ new Date(1942, 10, 1), 'jimi-hendrix' ];\n\n// Set the prepare flag in the query options\nawait client.execute(query, params, { prepare: true });\nconsole.log('Row updated on the cluster');\n```\n\n### Row streaming and pipes\n\nWhen using `#eachRow()` and `#stream()` methods, the driver parses each row as soon as it is received,\n yielding rows without buffering them.\n\n```javascript\n// Reducing a large result\nclient.eachRow(\n  'SELECT time, val FROM temperature WHERE station_id=',\n  ['abc'],\n  (n, row) =\u003e {\n    // The callback will be invoked per each row as soon as they are received\n    minTemperature = Math.min(row.val, minTemperature); \n  },\n  err =\u003e { \n    // This function will be invoked when all rows where consumed or an error was encountered  \n  }\n);\n```\n\nThe `#stream()` method works in the same way but instead of callback it returns a [Readable Streams2][streams2] object\n in `objectMode` that emits instances of `Row`.\n\nIt can be **piped** downstream and provides automatic pause/resume logic (it buffers when not read).\n\n```javascript\nclient.stream('SELECT time, val FROM temperature WHERE station_id=', [ 'abc' ])\n  .on('readable', function () {\n    // 'readable' is emitted as soon a row is received and parsed\n    let row;\n    while (row = this.read()) {\n      console.log('time %s and value %s', row.time, row.val);\n    }\n  })\n  .on('end', function () {\n    // Stream ended, there aren't any more rows\n  })\n  .on('error', function (err) {\n    // Something went wrong: err is a response error from Cassandra\n  });\n```\n\n### User defined types\n\n[User defined types (UDT)][cql-udt] are represented as JavaScript objects.\n\nFor example:\nConsider the following UDT and table\n\n```cql\nCREATE TYPE address (\n  street text,\n  city text,\n  state text,\n  zip int,\n  phones set\u003ctext\u003e\n);\nCREATE TABLE users (\n  name text PRIMARY KEY,\n  email text,\n  address frozen\u003caddress\u003e\n);\n```\n\nYou can retrieve the user address details as a regular JavaScript object.\n\n```javascript\nconst query = 'SELECT name, address FROM users WHERE key = ?';\nconst result = await client.execute(query, [ key ], { prepare: true });\nconst row = result.first();\nconst address = row.address;\nconsole.log('User lives in %s, %s - %s', address.street, address.city, address.state);\n```\n\nRead more information  about using [UDTs with the Node.js Driver][doc-udt].\n\n### Paging\n\nAll driver methods use a default `fetchSize` of 5000 rows, retrieving only first page of results up to a\nmaximum of 5000 rows to shield an application against accidentally retrieving large result sets in a single response.\n\n`stream()` method automatically fetches the following page once the current one was read. You can also use `eachRow()` \nmethod to retrieve the following pages by using `autoPage` flag. See [paging documentation for more \ninformation][doc-paging].\n\n### Batch multiple statements\n\nYou can execute multiple statements in a batch to update/insert several rows atomically even in different column families.\n\n```javascript\nconst queries = [\n  {\n    query: 'UPDATE user_profiles SET email=? WHERE key=?',\n    params: [ emailAddress, 'hendrix' ]\n  }, {\n    query: 'INSERT INTO user_track (key, text, date) VALUES (?, ?, ?)',\n    params: [ 'hendrix', 'Changed email', new Date() ]\n  }\n];\n\nawait client.batch(queries, { prepare: true });\nconsole.log('Data updated on cluster');\n```\n\n## Object Mapper\n\nThe driver provides a built-in [object mapper][doc-mapper] that lets you interact with your data like you \nwould interact with a set of documents.\n\nRetrieving objects from the database:\n\n```javascript\nconst videos = await videoMapper.find({ userId });\nfor (let video of videos) {\n  console.log(video.name);\n}\n```\n\nUpdating an object from the database:\n\n```javascript\nawait videoMapper.update({ id, userId, name, addedDate, description });\n```\n\nYou can read more information about [getting started with the Mapper in our\ndocumentation][doc-mapper-start].\n\n----\n\n## Data types\n\nThere are few data types defined in the ECMAScript specification, this usually represents a problem when you are trying\n to deal with data types that come from other systems in JavaScript.\n\nThe driver supports all the CQL data types in Apache Cassandra (3.0 and below) even for types with no built-in\nJavaScript representation, like decimal, varint and bigint. Check the documentation on working with\n [numerical values][doc-numerical], [uuids][doc-uuid] and [collections][doc-collections].\n\n## Logging\n\nInstances of `Client()` are `EventEmitter` and emit `log` events:\n\n```javascript\nclient.on('log', (level, loggerName, message, furtherInfo) =\u003e {\n  console.log(`${level} - ${loggerName}:  ${message}`);\n});\n```\n\nThe `level` being passed to the listener can be `verbose`, `info`, `warning` or `error`. Visit the [logging\ndocumentation][doc-logging] for more information. \n\n## Compatibility\n\nThe driver supports all versions of Node.js, Cassandra, and DSE that are not EOL at the time of release.  Only LTS eligible branches (i.e. even numbered releases) are supported for Node.js.  See the [project documentation] for more information about the Node.js release cycle.\n\nThe current version of the driver offers support consistent with this policy for the following:\n\n- Apache Cassandra versions 3.0 and above.\n- DataStax Enterprise versions 5.1 and 6.8.\n- Node.js versions 18.x, 20.x, and 22.x.\n\nNote: DataStax products do not support big-endian systems.\n\n## Credits\n\nThis driver is based on the original work of [Jorge Bay][jorgebay] on [node-cassandra-cql][old-driver] and adds a series of advanced features that are common across all other [DataStax drivers][drivers] for Apache Cassandra.\n\nThe development effort to provide an up to date, high performance, fully featured Node.js Driver for Apache Cassandra will continue on this project, while [node-cassandra-cql][old-driver] will be discontinued.\n\n## License\n\n© DataStax, Inc.\n\nLicensed under the Apache License, Version 2.0 (the \"License\"); you may not use this file except in compliance with the License. You may obtain a copy of the License at\n\nhttp://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software distributed under the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.\n\n[cassandra]: https://cassandra.apache.org/\n[doc-api]: https://docs.datastax.com/en/developer/nodejs-driver/latest/api/\n[doc-index]: https://docs.datastax.com/en/developer/nodejs-driver/latest/\n[doc-datatypes]: https://docs.datastax.com/en/developer/nodejs-driver/latest/features/datatypes/\n[doc-numerical]: https://docs.datastax.com/en/developer/nodejs-driver/latest/features/datatypes/numerical/\n[doc-uuid]: https://docs.datastax.com/en/developer/nodejs-driver/latest/features/datatypes/uuids/\n[doc-collections]: https://docs.datastax.com/en/developer/nodejs-driver/latest/features/datatypes/collections/\n[doc-udt]: https://docs.datastax.com/en/developer/nodejs-driver/latest/features/datatypes/udts/\n[doc-promise-callback]: https://docs.datastax.com/en/developer/nodejs-driver/latest/features/promise-callback/\n[doc-mapper]: https://docs.datastax.com/en/developer/nodejs-driver/latest/features/mapper/\n[doc-mapper-start]: https://docs.datastax.com/en/developer/nodejs-driver/latest/features/mapper/getting-started/\n[doc-logging]: https://docs.datastax.com/en/developer/nodejs-driver/latest/features/logging/\n[faq]: https://docs.datastax.com/en/developer/nodejs-driver/latest/faq/\n[load-balancing]: https://docs.datastax.com/en/developer/nodejs-driver/latest/features/tuning-policies/#load-balancing-policy\n[retry]: https://docs.datastax.com/en/developer/nodejs-driver/latest/features/tuning-policies/#retry-policy\n[pooling]: https://docs.datastax.com/en/developer/nodejs-driver/latest/features/connection-pooling/\n[batch]: https://docs.datastax.com/en/developer/nodejs-driver/latest/features/batch/\n[old-driver]: https://github.com/jorgebay/node-cassandra-cql\n[project documentation]: https://github.com/nodejs/release#release-schedule\n[jorgebay]: https://github.com/jorgebay\n[drivers]: https://github.com/datastax\n[mailinglist]: https://groups.google.com/a/lists.datastax.com/forum/#!forum/nodejs-driver-user\n[jira]: https://datastax-oss.atlassian.net/projects/NODEJS/issues\n[streams2]: https://nodejs.org/api/stream.html#stream_class_stream_readable\n[cql-udt]: https://cassandra.apache.org/doc/latest/cql/types.html#udts\n[dse]: https://www.datastax.com/products/datastax-enterprise\n[astra]: https://www.datastax.com/products/datastax-astra\n","funding_links":[],"categories":["Libraries and Clients","Packages"],"sub_categories":["Libraries"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatastax%2Fnodejs-driver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdatastax%2Fnodejs-driver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatastax%2Fnodejs-driver/lists"}