Kysely Data API

Common errors

• AccessDeniedException: User is not authorized to perform rds-data:ExecuteStatement on resource: arn:aws:rds:...

  cause The AWS credentials used (e.g., Lambda execution role) lack the necessary IAM permissions to interact with the RDS Data API or the specific database resource.
  fix Review and update the IAM policy attached to your AWS role or user, ensuring it includes `rds-data:ExecuteStatement` (and other `rds-data:*` actions as needed) on the `resourceArn` and `secretArn`.

• ValidationException: Missing required parameter: secretArn

  cause The `secretArn` property was not provided or was empty in the `DataApiDialect` driver configuration.
  fix Ensure that the `secretArn` field is correctly populated with the ARN of your AWS Secrets Manager secret containing database credentials.

• BadRequestException: There is no data-api enabled DB cluster with this ARN: arn:aws:rds:...

  cause The `resourceArn` provided does not correspond to an existing RDS database cluster that has the Data API enabled, or the ARN is incorrect.
  fix Verify that the `resourceArn` is accurate and points to an RDS cluster that specifically has the Data API feature turned on in its configuration.

Warnings

• breaking Version 2.0.0 is a major release and likely contains breaking changes from 1.x versions. Always review the release notes when upgrading between major versions, especially concerning dialect configuration or specific driver options.
  Fix: Consult the official migration guide (if available) or the latest README for `kysely-data-api` for specific changes to the API and configuration.
• gotcha Proper IAM permissions are crucial for the RDS Data API. The AWS Lambda execution role or credentials used by `RDSDataService` must have `rds-data:*` permissions on the specified `resourceArn` and `secretArn`.
  Fix: Verify that the associated IAM role/user has the necessary `rds-data:ExecuteStatement`, `rds-data:BatchExecuteStatement`, etc., permissions and access to both the database cluster resource and the Secrets Manager secret.
• gotcha The `secretArn` and `resourceArn` are mandatory for configuring the `DataApiDialect`. Incorrect or missing ARNs will lead to authentication or connection failures.
  Fix: Ensure that the `secretArn` (pointing to a Secrets Manager secret containing database credentials) and `resourceArn` (pointing to your RDS database cluster or instance) are correctly provided in the driver configuration. These are often passed via environment variables in serverless contexts.
• gotcha Compatibility with `kysely` versions is important. While peer dependency specifies `^0.27.4`, newer `kysely` versions might introduce changes that require `kysely-data-api` updates.
  Fix: Always install `kysely-data-api` alongside a compatible `kysely` version as specified in its `peerDependencies`. Update both packages together after checking for compatibility notes.

Install

• npm install kysely-data-api npm
• yarn add kysely-data-api yarn
• pnpm add kysely-data-api pnpm

Imports

• DataApiDialect
  wrong:

  const DataApiDialect = require('kysely-data-api').DataApiDialect;

  correct:

  import { DataApiDialect } from 'kysely-data-api';

  This library is primarily designed for ESM consumption, especially within TypeScript projects. CommonJS `require` should be avoided.
• Kysely
  wrong:

  import Kysely from 'kysely';

  correct:

  import { Kysely } from 'kysely';

  Kysely is a peer dependency and its main class is a named export.
• RDSDataService
  wrong:

  import * as RDSDataService from '@aws-sdk/client-rds-data';

  correct:

  import { RDSDataService } from '@aws-sdk/client-rds-data';

  This class comes from the AWS SDK peer dependency and is essential for configuring the data API driver.

Quickstart

Demonstrates how to initialize `Kysely` with `DataApiDialect` for AWS RDS Data API, configuring it with essential ARN values and performing a simple select query.

import { Kysely } from 'kysely';
import { DataApiDialect } from 'kysely-data-api';
import { RDSDataService } from '@aws-sdk/client-rds-data';

// Define your database schema interface (replace with your actual schema)
interface Database {
  person: {
    id: number;
    first_name: string;
    last_name: string;
  };
  // Add other tables here
}

async function initializeDb() {
  const dataApi = new DataApiDialect({
    mode: 'mysql', // or 'postgres'
    driver: {
      client: new RDSDataService({ region: process.env.AWS_REGION ?? 'us-east-1' }),
      database: process.env.DB_NAME ?? 'my_database',
      secretArn: process.env.DB_SECRET_ARN ?? '<arn of secret containing credentials>',
      resourceArn: process.env.DB_RESOURCE_ARN ?? '<arn of database>',
    },
  });

  const db = new Kysely<Database>({ dialect: dataApi });

  try {
    const results = await db.selectFrom('person').selectAll().execute();
    console.log('Query results:', results);
  } catch (error) {
    console.error('Database query failed:', error);
  } finally {
    // In serverless environments, explicit connection closing is often not needed
    // as the Lambda invocation ends, but for local testing, consider:
    // await db.destroy(); 
  }
}

initializeDb();