{"id":16000,"library":"data-api-client","title":"AWS Aurora Serverless Data API Client","description":"The Data API Client is a lightweight wrapper designed to simplify interactions with the Amazon Aurora Serverless Data API. It abstracts away the complexity of field values by automatically annotating native JavaScript types for input parameters and converting annotated response data back to native JavaScript types. Key features include streamlined transaction management, built-in automatic retry logic specifically optimized for Aurora Serverless scale-to-zero clusters, and compatibility layers for `pg` (node-postgres) and `mysql2/promise` drivers, enabling seamless integration with popular ORMs like Drizzle ORM and Kysely. The current stable version is 2.1.4, with active development marked by frequent minor releases addressing bug fixes, performance improvements, and new features. Version 2.0 introduced a significant migration to AWS SDK v3, full TypeScript support, and enhanced PostgreSQL data type handling, further differentiating it by offering a DocumentClient-like experience for Aurora.","status":"active","version":"2.1.4","language":"javascript","source_language":"en","source_url":"https://github.com/jeremydaly/data-api-client","tags":["javascript","serverless","data-api","aurora","aws","typescript"],"install":[{"cmd":"npm install data-api-client","lang":"bash","label":"npm"},{"cmd":"yarn add data-api-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add data-api-client","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required peer dependency for interacting with the AWS RDS Data API. This library builds on top of the official AWS SDK v3 client.","package":"@aws-sdk/client-rds-data","optional":false}],"imports":[{"note":"The main client is a default export. Since v2.0.0, the library is ESM-first, so direct `require` without `.default` or proper module interop will fail.","wrong":"const DataAPIClient = require('data-api-client');","symbol":"DataAPIClient","correct":"import DataAPIClient from 'data-api-client';"},{"note":"This is a named export from a specific compatibility layer path, introduced in v2.1.0 for `pg` driver compatibility.","wrong":"import DataAPIClient from 'data-api-client/compat/pg';","symbol":"createPgCompatClient","correct":"import { createPgCompatClient } from 'data-api-client/compat/pg';"},{"note":"This is a named export from a specific compatibility layer path, introduced in v2.1.0 for `mysql2` driver compatibility.","wrong":"import { createClient } from 'data-api-client/compat/mysql2';","symbol":"createMysql2CompatClient","correct":"import { createMysql2CompatClient } from 'data-api-client/compat/mysql2';"}],"quickstart":{"code":"import DataAPIClient from 'data-api-client';\n\n// In a real application, these should be loaded from environment variables or a secure configuration service.\n// For demonstration, using fallback values.\nconst config = {\n  secretArn: process.env.DB_SECRET_ARN ?? 'arn:aws:secretsmanager:REGION:ACCOUNT_ID:secret:DB_CREDENTIALS-XXXXX',\n  resourceArn: process.env.DB_RESOURCE_ARN ?? 'arn:aws:rds:REGION:ACCOUNT_ID:cluster:DB_CLUSTER_ID',\n  database: process.env.DB_NAME ?? 'your_database',\n  // Optional: configure automatic retry behavior for Aurora Serverless scale-to-zero wake-ups\n  retryOptions: {\n    maxRetries: 5,\n    retryDelay: (retryCount) => Math.pow(2, retryCount) * 100 // Example: exponential backoff\n  }\n};\n\nconst db = DataAPIClient(config);\n\nasync function manageUsers() {\n  try {\n    // Insert a new user, demonstrating automatic type handling for objects (JSONB in PostgreSQL)\n    const insertResult = await db.query(\n      `INSERT INTO users (name, email, settings) VALUES (:name, :email, :settings) RETURNING id, name, settings;`,\n      {\n        name: 'John Doe',\n        email: 'john.doe@example.com',\n        settings: { theme: 'dark', notifications: true } // Auto-casts to JSONB in PostgreSQL since v2.1.2\n      }\n    );\n    console.log('Inserted user:', insertResult.records[0]);\n\n    // Fetch all users\n    const users = await db.query(`SELECT id, name, email, settings FROM users;`);\n    console.log('All users:', users.records);\n\n    // Update a user's name\n    const userId = insertResult.records[0].id;\n    const updateResult = await db.query(\n      `UPDATE users SET name = :newName WHERE id = :userId RETURNING id, name;`,\n      { newName: 'Jane Doe', userId }\n    );\n    console.log('Updated user:', updateResult.records[0]);\n\n  } catch (error) {\n    console.error('Database operation failed:', error);\n    throw error;\n  }\n}\n\nmanageUsers();","lang":"typescript","description":"This quickstart demonstrates how to initialize the `data-api-client` with necessary AWS ARN configurations, perform basic CRUD operations (insert, select, update), and showcase automatic JSONB type casting for PostgreSQL. It also illustrates how to use named parameters and configures the built-in automatic retry logic for Aurora Serverless."},"warnings":[{"fix":"Update your project's `@aws-sdk/client-rds-data` dependency to `^3.0.0` or higher. Ensure your build system supports ESM for optimal tree-shaking and compatibility.","message":"Version 2.0.0 introduced a major breaking change by migrating from AWS SDK v2 to AWS SDK v3. This reduces bundle sizes and improves Lambda cold starts but requires users to ensure their environment is compatible with AWS SDK v3 and that `@aws-sdk/client-rds-data` is at `^3.0.0`.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Upgrade `data-api-client` to version 2.1.3 or higher. This version replaces the external `pg-escape` with an internal implementation, eliminating the problematic file dependencies.","message":"Prior to v2.1.3, deployments to AWS Lambda or other bundled environments could encounter `ENOENT: no such file or directory, open '/var/task/reserved.txt'` errors. This was caused by an external `pg-escape` dependency that included runtime file dependencies not properly handled during bundling.","severity":"gotcha","affected_versions":"<2.1.3"},{"fix":"Upgrade `data-api-client` to version 2.1.4 or higher. This version includes a fix that executes each parameter set individually via `ExecuteStatementCommand` when a `RETURNING` clause is detected in a batch query, avoiding the error.","message":"PostgreSQL batch queries using a `RETURNING` clause would fail with a 'Too many update results' error in versions prior to 2.1.4. The `BatchExecuteStatementCommand` from the RDS Data API does not correctly handle `RETURNING` clauses when multiple parameter sets are provided.","severity":"gotcha","affected_versions":"<2.1.4"},{"fix":"Upgrade `data-api-client` to version 2.1.4 or higher. This version includes a fix for `JSONB typeName` parsing, ensuring automatic JSON parsing is consistently applied.","message":"Before v2.1.2, automatic JSON parsing for PostgreSQL JSONB columns was inconsistent, specifically when the Aurora Data API returned `typeName: 'jsonb'`, which was not correctly matched for automatic deserialization.","severity":"gotcha","affected_versions":"<2.1.4"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Upgrade `data-api-client` to version 2.1.3 or newer. This version internally implements the necessary functionality, removing the problematic external dependency.","cause":"A runtime file dependency from the `pg-escape` library was not bundled correctly in AWS Lambda or similar environments.","error":"ENOENT: no such file or directory, open '/var/task/reserved.txt'"},{"fix":"For CommonJS, use `const DataAPIClient = require('data-api-client').default;`. For modern projects, prefer ESM `import DataAPIClient from 'data-api-client';` and ensure your environment supports ESM.","cause":"Incorrect import statement when using CommonJS or specific module interop configurations, trying to `require` a default ESM export directly without accessing the `.default` property.","error":"TypeError: (0 , data_api_client__WEBPACK_IMPORTED_MODULE_0__.default) is not a function"},{"fix":"Upgrade `data-api-client` to version 2.1.4 or newer. This version detects such scenarios and executes statements individually to ensure correct `RETURNING` behavior.","cause":"The AWS RDS Data API's `BatchExecuteStatementCommand` does not correctly process `RETURNING` clauses when multiple parameter sets are provided for PostgreSQL.","error":"Too many update results (or similar errors related to batch queries with RETURNING clauses on PostgreSQL)"}],"ecosystem":"npm"}