{"id":21448948,"url":"https://github.com/proddata/node-cratedb","last_synced_at":"2026-03-05T23:13:34.484Z","repository":{"id":263141653,"uuid":"882990762","full_name":"proddata/node-cratedb","owner":"proddata","description":"A lightweight Node.js client for CrateDB.","archived":false,"fork":false,"pushed_at":"2026-02-24T13:37:58.000Z","size":517,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-24T18:35:40.397Z","etag":null,"topics":["crate","cratedb","crateio","database","sql"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/proddata.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-11-04T07:21:37.000Z","updated_at":"2026-02-24T13:38:02.000Z","dependencies_parsed_at":"2025-02-15T14:27:17.620Z","dependency_job_id":"0553b5d0-4fe2-46cc-8f0e-038e88afcab3","html_url":"https://github.com/proddata/node-cratedb","commit_stats":null,"previous_names":["proddata/node-cratedb"],"tags_count":19,"template":false,"template_full_name":null,"purl":"pkg:github/proddata/node-cratedb","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/proddata%2Fnode-cratedb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/proddata%2Fnode-cratedb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/proddata%2Fnode-cratedb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/proddata%2Fnode-cratedb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/proddata","download_url":"https://codeload.github.com/proddata/node-cratedb/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/proddata%2Fnode-cratedb/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30154480,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-05T22:39:40.138Z","status":"ssl_error","status_checked_at":"2026-03-05T22:39:24.771Z","response_time":93,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["crate","cratedb","crateio","database","sql"],"created_at":"2024-11-23T03:17:37.607Z","updated_at":"2026-03-05T23:13:34.452Z","avatar_url":"https://github.com/proddata.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![npm version](https://img.shields.io/npm/v/@proddata/node-cratedb.svg)](https://www.npmjs.com/package/@proddata/node-cratedb)\n[![Build Status](https://github.com/proddata/node-cratedb/actions/workflows/test.yml/badge.svg)](https://github.com/proddata/node-cratedb/actions)\n\n# CrateDB HTTP API Client for Node.js\n\nThis library is a Node.js client derived from `node-crate` for interacting with CrateDB via its **HTTP endpoint**. Unlike libraries such as `node-postgres`, which use the PostgreSQL wire protocol, this client communicates with CrateDB's native HTTP API.\n\n\u003e [!CAUTION]\n\u003e While it provides basic functionality to interact with CrateDB, it is **not** production-ready and lacks the robustness of established libraries.\n\u003e For production use, consider mature libraries like [`node-postgres`](https://node-postgres.com/) which leverage CrateDB's PostgreSQL compatibility.\n\n## Installation\n\nTo install `node-cratedb` using npm:\n\n```bash\nnpm install @proddata/node-cratedb\n```\n\nTo use the `CrateDBClient`:\n\n1. Import the `CrateDBClient` class.\n2. Instantiate it with your configuration options.\n3. Call any of the CRUD and DDL methods provided.\n\nImport and instantiate CrateDBClient:\n\n**ESM (ECMAScript Modules)**\n\n```javascript\nimport { CrateDBClient } from '@proddata/node-cratedb';\n\nconst client = new CrateDBClient();\n```\n\n**CommonJS (CJS)**\n\n```javascript\nconst { CrateDBClient } = require('@proddata/node-cratedb');\n\nconst client = new CrateDBClient();\n```\n\nFor a remote CrateDB Instance:\n\n```javascript\nimport { CrateDBClient } from '@proddata/node-cratedb';\n\nconst client = new CrateDBClient({\n  user: 'database-user',\n  password: 'secretpassword!!',\n  host: 'my.database-server.com',\n  port: 4200,\n  ssl: true, // Use HTTPS\n  keepAlive: true, // Enable persistent connections\n  maxConnections: 20, // Limit to 10 concurrent sockets\n  defaultSchema: 'my_schema', // Default schema for queries\n});\n```\n\nYou can also use JWT-based authentication. When a jwt is provided, it overrides the basic authentication credentials:\n\n```javascript\nimport { CrateDBClient } from '@proddata/node-cratedb';\n\nconst client = new CrateDBClient({\n  host: 'my.database-server.com',\n  jwt: 'your.jwt.token.here', // Use JWT for Bearer authentication\n  ssl: true,\n});\n```\n\n### Configuration\n\nThe `CrateDBClient` can be configured with either environment variables or directly with an options object. Below are the configuration options, along with their default values.\n\n#### Configuration Options\n\n| Option                 | Type                    | Default Value                                         | Description                                                  |\n| ---------------------- | ----------------------- | ----------------------------------------------------- | ------------------------------------------------------------ |\n| `user`                 | `string`                | `'crate'` or `process.env.CRATEDB_USER`               | Database user.                                               |\n| `password`             | `string` or `null`      | `''` or `process.env.CRATEDB_PASSWORD`                | Database password.                                           |\n| `jwt`                  | `string \\| null`        | `null`                                                | JWT token for Bearer authentication.                         |\n| `host`                 | `string`                | `'localhost'` or `process.env.CRATEDB_HOST`           | Database host.                                               |\n| `port`                 | `number`                | `4200` or `process.env.CRATEDB_PORT`                  | Database port.                                               |\n| `defaultSchema`        | `string`                | `null` or `process.env.CRATEDB_DEFAULT_SCHEMA`        | Default schema for queries.                                  |\n| `connectionString`     | `string`                | `null`                                                | Connection string, e.g., `https://user:password@host:port/`. |\n| `ssl`                  | `object` or `null`      | `null`                                                | SSL configuration;                                           |\n| `keepAlive`            | `boolean`               | `true`                                                | Enables HTTP keep-alive for persistent connections.          |\n| `maxConnections`       | `number`                | `20`                                                  | Limits the maximum number of concurrent connections.         |\n| `deserialization`      | `DeserializationConfig` | `{ long: 'number', timestamp: 'date', date: 'date' }` | Controls deserialization behaviour                           |\n| `rowMode`              | `'array' \\| 'object'`   | `'array'`                                             | Controls the format of returned rows.                        |\n| `enableCompression`    | `boolean`               | `true`                                                | Enables GZIP compression for large requests.                 |\n| `compressionThreshold` | `number`                | `1024`                                                | Minimum size in bytes before compression is applied.         |\n\n#### Environment Variables\n\nAlternatively, you can set these variables in your environment:\n\n```bash\nexport CRATEDB_USER=crate\nexport CRATEDB_PASSWORD=secretpassword\nexport CRATEDB_HOST=my.database-server.com\nexport CRATEDB_PORT=4200\nexport CRATEDB_DEFAULT_SCHEMA=doc\n```\n\n#### RequestCompression\n\nThe client supports GZIP compression for requests and response to improve network efficiency.\nRequest compression is enabled by default, response compression is disabled.\n\n```typescript\nconst client = new CrateDBClient({\n  compression: {\n    request: 'gzip',\n    response: 'none',\n  },\n});\n```\n\n---\n\n## Usage\n\n### General Operations\n\n#### execute(sql, args?, config?)\n\nExecute a SQL query with optional parameters and configuration.\n\n```typescript\n// Basic query\nawait client.execute('SELECT * FROM my_table';);\n// Parameterized query\nawait client.execute('SELECT FROM my_table WHERE id = ?', [123]);\n// Query with row mode configuration\nawait client.execute('SELECT FROM my_table', undefined, { rowMode: 'object' });\n```\n\nThe `rowMode` configuration determines how rows are returned:\n\n- `'array'` (default): Returns rows as arrays of values\n- `'object'`: Returns rows as objects with column names as keys\n\nExample responses:\n\n```typescript\n// Basic query\nconst result = await client.execute('SELECT * FROM my_table');\nconsole.log(result.rows); // [[1, 'Alice', 30], [2, 'Bob', 25]]\n\n// Query with row mode configuration\nconst result = await client.execute('SELECT * FROM my_table', undefined, { rowMode: 'object' });\nconsole.log(result.rows); // [{id: 1, name: 'Alice', age: 30}, {id: 2, name: 'Bob', age: 25}]\n```\n\n#### executeMany(sql, bulk_args)\n\nExecute a raw bulk SQL query.\n\n```js\nawait client.execute('INSERT INTO my_table VALUES(?);', [['Hello'], ['World']]);\n```\n\n#### streamQuery(sql, batchSize)\n\nThe `streamQuery` method in CrateDBClient wraps the Cursor functionality\nfor convenient query streaming. This method automatically manages the cursor's\nlifecycle.\n\nStreams query results row by row using an async generator. The `batchSize`\ndetermines the number of rows fetched per request (default is `100`).\n\n```js\nfor await (const row of client.streamQuery('SELECT * FROM my_table ORDER BY id', 5)) {\n  console.log(row); // Process each row individually\n}\n```\n\n### CRUD Operations\n\n#### insert(tableName, obj, primaryKeys = null)\n\nInsert a new row into a specified table with optional primary key conflict resolution.\n\n- **`tableName`**: The name of the table to insert the row into.\n- **`obj`**: An object representing the row to insert.\n- **`primaryKeys`**: (Optional) An array of column names to use as primary keys for conflict resolution.\n\nIf `primaryKeys` are provided, the method will handle conflicts by updating the non-primary key fields of conflicting rows. If no `primaryKeys` are provided, conflicting rows will be skipped.\n\n```javascript\n// Insert a row with primary key conflict resolution\nawait client.insert('my_table', { id: 1, column1: 'value1', column2: 'value2' }, ['id']);\n\n// Insert a row without conflict resolution\nawait client.insert('my_table', { id: 1, column1: 'value1', column2: 'value2' });\n```\n\n#### insertMany(tableName, objectArray, primaryKeys = null)\n\nInsert multiple rows into a table with optional primary key conflict resolution.\n\n- **`tableName`**: The name of the table to insert rows into.\n- **`objectArray`**: An array of objects representing rows to insert.\n- **`primaryKeys`**: (Optional) An array of column names to use as primary keys for conflict resolution.\n\nIf `primaryKeys` are provided, the method will handle conflicts by updating the non-primary key fields of conflicting rows. If no `primaryKeys` are provided, conflicting rows will be skipped.\n\n```javascript\nconst bulkData = [\n  { id: 1, name: 'Earth', kind: 'Planet', description: 'A beautiful place.' },\n  { id: 2, name: 'Mars', kind: 'Planet', description: 'The red planet.' },\n  { id: 1, name: 'Earth Updated', kind: 'Planet', description: 'Updated description.' }, // Conflict on id\n];\n\nawait client.insertMany('my_table', bulkData, ['id']);\n// Conflicting row with `id: 1` will be updated instead of skipped.\n\nawait client.insertMany('my_table', bulkData);\n// Conflicting rows will be skipped as no `primaryKeys` are provided.\n```\n\n#### getPrimaryKeys(tableName)\n\nGet the primary key columns for a specified table. Convenient for when you need to know the primary keys of a table before inserting.\n\n```js\n// Get primary keys for a table in the default schema\nconst primaryKeys = await client.getPrimaryKeys('my_table');\nconsole.log(primaryKeys); // ['id']\n// Get primary keys for a schema-qualified table\nconst keys = await client.getPrimaryKeys('my_schema.orders');\nconsole.log(keys); // ['order_id', 'customer_id']\n```\n\n#### drop(tableName)\n\nDrop a specified table.\n\n```js\nawait client.drop('my_table');\n```\n\n#### refresh(tableName)\n\nRefresh a specified table.\n\n```js\nawait client.refresh('my_table');\n```\n\n#### createTable(tableName, schema, options?)\n\nCreates a new table with the specified name, schema, and options.\n\n```typescript\n// Basic table creation\nawait client.createTable('users', {\n  id: { type: 'INTEGER', primaryKey: true },\n  name: { type: 'TEXT', notNull: true },\n  age: { type: 'INTEGER' },\n  created_at: { type: 'TIMESTAMP', defaultValue: 'CURRENT_TIMESTAMP' },\n  metadata: {\n    type: 'object',\n    mode: 'strict',\n    properties: {\n      email: { type: 'TEXT' },\n      address: {\n        type: 'object',\n        mode: 'dynamic',\n        properties: {\n          city: { type: 'TEXT' },\n        },\n      },\n    },\n  },\n});\n\n// Advanced table creation with options\nawait client.createTable(\n  'metrics',\n  {\n    timestamp: { type: 'TIMESTAMP', primaryKey: true },\n    week: { type: 'TIMESTAMP', defaultValue: \"date_trunc('week', timestamp)\" },\n    sensor_id: { type: 'TEXT' },\n    value: { type: 'DOUBLE' },\n    location: {\n      type: 'object',\n      mode: 'strict',\n      properties: {\n        lat: { type: 'DOUBLE' },\n        lon: { type: 'DOUBLE' },\n      },\n    },\n  },\n  {\n    numberOfShards: 6,\n    numberOfReplicas: '2',\n    clusteredBy: 'sensor_id',\n    partitionedBy: ['week'],\n  }\n);\n```\n\n##### Parameters\n\n- `tableName`: string - Name of the table to create\n- `schema`: Record\u003cstring, ColumnDefinition\u003e - Object defining the table columns\n  - Regular columns:\n    - `type`: string - SQL type of the column\n    - `primaryKey?`: boolean - Whether this column is part of primary key\n    - `notNull?`: boolean - Whether this column can contain NULL values\n    - `defaultValue?`: unknown - Default value for the column\n    - `generatedAlways?`: string - SQL expression for generated column\n    - `stored?`: boolean - Whether generated column should be stored\n  - Object columns:\n    - `type`: 'object' - Specifies an object column\n    - `mode?`: 'strict' | 'dynamic' | 'ignored' - Object mode (default: no mode)\n    - `properties?`: Record\u003cstring, ColumnDefinition\u003e - Optional nested column definitions\n- `options?`: TableOptions - Additional table configuration\n  - `clusteredBy?`: string - Column to use for clustering\n  - `partitionedBy?`: string[] - Columns to use for partitioning\n  - `numberOfShards?`: number - Number of shards (default: 6)\n  - `numberOfReplicas?`: string | number - Number of replicas (default: '1')\n\n### Cursor Operations\n\n#### createCursor(sql)\n\nCreate a cursor to fetch large datasets efficiently.\n\n```js\nconst cursor = client.createCursor('SELECT * FROM my_table ORDER BY id');\nawait cursor.open();\n\nconsole.log(await cursor.fetchone()); // Fetch one record\nconsole.log(await cursor.fetchmany(5)); // Fetch 5 records\nconsole.log(await cursor.fetchall()); // Fetch all remaining records\n\nawait cursor.close(); // Close the cursor and commit the transaction\n```\n\n#### iterate(batchSize)\n\nCreates an async generator that fetches query results in chunks of size\nbatchSize (default is 100).\n\n```js\nconst cursor = client.createCursor('SELECT * FROM my_table ORDER BY id');\nawait cursor.open();\n\nfor await (const row of cursor.iterate(5)) {\n  console.log(row); // Process each row individually\n}\n\nawait cursor.close();\n```\n\n## Serialization and Deserialization\n\nThe client handles serialization and deserialization of various data types,\nincluding `BigInt`, `Date`, and timestamps, ensuring precision and compatibility\nbetween JavaScript and CrateDB.\n\n- **Serialization**\n\n  - Data types such as `BigInt`, `Date`, `Set`, and `Map` are serialized into\n    compatible JSON representations without loss of precision.\n\n- **Deserialization**\n  - The client supports configurable deserialization for specific CrateDB data\n    types, including `LONG`, `DATE`, `TIMESTAMP`, and `TIMESTAMPTZ`.\n  - By default, when type information is available in the result set, values are\n    automatically converted to the appropriate JavaScript types.\n  - Integer values exceeding `Number.MAX_SAFE_INTEGER` are converted to\n    `BigInt`, even when explicit type information is unavailable.\n\nDeserialization behavior can be controlled through the client configuration:\n\n```typescript\nexport type DeserializationConfig = {\n  long: 'bigint' | 'number';\n  timestamp: 'date' | 'number';\n  date: 'date' | 'number';\n};\n```\n\n## Duration Metrics\n\nThe client collects several duration metrics for each request to help diagnose performance:\n\n- **encoding**: Time spent compressing the request payload. If compression is disabled or the payload is below the threshold, this value is `0`.\n- **request**: Time elapsed from sending the request until the response is received.\n- **deserialization**: Time taken to parse and deserialize the response.\n- **total**: Overall time from initiating the request until the response is fully processed.\n- **client**: Client-side processing time, computed as `total - cratedb`, which represents the overhead outside of CrateDB execution.\n\nThese metrics are available via the `durations` property in the response object returned by methods such as `execute` and `executeMany`.\n\n## License\n\nMIT License. Feel free to use and modify this library as per the terms of the license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fproddata%2Fnode-cratedb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fproddata%2Fnode-cratedb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fproddata%2Fnode-cratedb/lists"}