{"id":16099,"library":"kysely-data-api","title":"Kysely Data API","description":"Kysely Data API is a specialized library that extends the `kysely` type-safe SQL query builder to provide seamless integration with the AWS RDS Data API. This enables serverless applications, particularly those built on AWS Lambda, to interact with Amazon RDS databases (both MySQL and PostgreSQL) without requiring traditional, long-lived database connections. The current stable version is 2.0.0, indicating a mature and actively developed project, though a specific release cadence is not publicly defined. Its key differentiator lies in abstracting the complexities of the RDS Data API into a familiar `kysely` dialect, allowing developers to leverage `kysely`'s powerful type-safe query building capabilities within a serverless, event-driven architecture, simplifying database interactions and resource management.","status":"active","version":"2.0.0","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/serverless-stack/kysely-data-api","tags":["javascript","typescript"],"install":[{"cmd":"npm install kysely-data-api","lang":"bash","label":"npm"},{"cmd":"yarn add kysely-data-api","lang":"bash","label":"yarn"},{"cmd":"pnpm add kysely-data-api","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for interacting with the AWS RDS Data API.","package":"@aws-sdk/client-rds-data","optional":false},{"reason":"The core query builder that this library extends.","package":"kysely","optional":false}],"imports":[{"note":"This library is primarily designed for ESM consumption, especially within TypeScript projects. CommonJS `require` should be avoided.","wrong":"const DataApiDialect = require('kysely-data-api').DataApiDialect;","symbol":"DataApiDialect","correct":"import { DataApiDialect } from 'kysely-data-api';"},{"note":"Kysely is a peer dependency and its main class is a named export.","wrong":"import Kysely from 'kysely';","symbol":"Kysely","correct":"import { Kysely } from 'kysely';"},{"note":"This class comes from the AWS SDK peer dependency and is essential for configuring the data API driver.","wrong":"import * as RDSDataService from '@aws-sdk/client-rds-data';","symbol":"RDSDataService","correct":"import { RDSDataService } from '@aws-sdk/client-rds-data';"}],"quickstart":{"code":"import { Kysely } from 'kysely';\nimport { DataApiDialect } from 'kysely-data-api';\nimport { RDSDataService } from '@aws-sdk/client-rds-data';\n\n// Define your database schema interface (replace with your actual schema)\ninterface Database {\n  person: {\n    id: number;\n    first_name: string;\n    last_name: string;\n  };\n  // Add other tables here\n}\n\nasync function initializeDb() {\n  const dataApi = new DataApiDialect({\n    mode: 'mysql', // or 'postgres'\n    driver: {\n      client: new RDSDataService({ region: process.env.AWS_REGION ?? 'us-east-1' }),\n      database: process.env.DB_NAME ?? 'my_database',\n      secretArn: process.env.DB_SECRET_ARN ?? '<arn of secret containing credentials>',\n      resourceArn: process.env.DB_RESOURCE_ARN ?? '<arn of database>',\n    },\n  });\n\n  const db = new Kysely<Database>({ dialect: dataApi });\n\n  try {\n    const results = await db.selectFrom('person').selectAll().execute();\n    console.log('Query results:', results);\n  } catch (error) {\n    console.error('Database query failed:', error);\n  } finally {\n    // In serverless environments, explicit connection closing is often not needed\n    // as the Lambda invocation ends, but for local testing, consider:\n    // await db.destroy(); \n  }\n}\n\ninitializeDb();","lang":"typescript","description":"Demonstrates how to initialize `Kysely` with `DataApiDialect` for AWS RDS Data API, configuring it with essential ARN values and performing a simple select query."},"warnings":[{"fix":"Consult the official migration guide (if available) or the latest README for `kysely-data-api` for specific changes to the API and configuration.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"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`.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"The `secretArn` and `resourceArn` are mandatory for configuring the `DataApiDialect`. Incorrect or missing ARNs will lead to authentication or connection failures.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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`.","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.","error":"AccessDeniedException: User is not authorized to perform rds-data:ExecuteStatement on resource: arn:aws:rds:..."},{"fix":"Ensure that the `secretArn` field is correctly populated with the ARN of your AWS Secrets Manager secret containing database credentials.","cause":"The `secretArn` property was not provided or was empty in the `DataApiDialect` driver configuration.","error":"ValidationException: Missing required parameter: secretArn"},{"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.","cause":"The `resourceArn` provided does not correspond to an existing RDS database cluster that has the Data API enabled, or the ARN is incorrect.","error":"BadRequestException: There is no data-api enabled DB cluster with this ARN: arn:aws:rds:..."}],"ecosystem":"npm"}