AWS Aurora Serverless Data API Client

2.1.4 · active · verified Tue Apr 21

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.

Common errors

Warnings

Install

Imports

Quickstart

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.

import DataAPIClient from 'data-api-client';

// In a real application, these should be loaded from environment variables or a secure configuration service.
// For demonstration, using fallback values.
const config = {
  secretArn: process.env.DB_SECRET_ARN ?? 'arn:aws:secretsmanager:REGION:ACCOUNT_ID:secret:DB_CREDENTIALS-XXXXX',
  resourceArn: process.env.DB_RESOURCE_ARN ?? 'arn:aws:rds:REGION:ACCOUNT_ID:cluster:DB_CLUSTER_ID',
  database: process.env.DB_NAME ?? 'your_database',
  // Optional: configure automatic retry behavior for Aurora Serverless scale-to-zero wake-ups
  retryOptions: {
    maxRetries: 5,
    retryDelay: (retryCount) => Math.pow(2, retryCount) * 100 // Example: exponential backoff
  }
};

const db = DataAPIClient(config);

async function manageUsers() {
  try {
    // Insert a new user, demonstrating automatic type handling for objects (JSONB in PostgreSQL)
    const insertResult = await db.query(
      `INSERT INTO users (name, email, settings) VALUES (:name, :email, :settings) RETURNING id, name, settings;`,
      {
        name: 'John Doe',
        email: 'john.doe@example.com',
        settings: { theme: 'dark', notifications: true } // Auto-casts to JSONB in PostgreSQL since v2.1.2
      }
    );
    console.log('Inserted user:', insertResult.records[0]);

    // Fetch all users
    const users = await db.query(`SELECT id, name, email, settings FROM users;`);
    console.log('All users:', users.records);

    // Update a user's name
    const userId = insertResult.records[0].id;
    const updateResult = await db.query(
      `UPDATE users SET name = :newName WHERE id = :userId RETURNING id, name;`,
      { newName: 'Jane Doe', userId }
    );
    console.log('Updated user:', updateResult.records[0]);

  } catch (error) {
    console.error('Database operation failed:', error);
    throw error;
  }
}

manageUsers();

view raw JSON →