Registry / database / kysely-data-api

kysely-data-api

JSON →
library2.0.0jsnpmunverified

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.

npm install kysely-data-api
INSTALL
IMPORT
SIG · KYSELY-DATA-API
K
kysely-data-api
databasejavascriptv2.0.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

DataApiDialect
import { DataApiDialect } from 'kysely-data-api';
const DataApiDialect = require('kysely-data-api').DataApiDialect;
This library is primarily designed for ESM consumption, especially within TypeScript projects. CommonJS `require` should be avoided.
Kysely
import { Kysely } from 'kysely';
import Kysely from 'kysely';
Kysely is a peer dependency and its main class is a named export.
RDSDataService
import { RDSDataService } from '@aws-sdk/client-rds-data';
import * as 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.

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();
Debug
Known issues
breakingVersion 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.
affects: >=2.0.0
gotchaProper 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.
affects: >=1.0.0
gotchaThe `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.
affects: >=1.0.0
gotchaCompatibility 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.
affects: >=1.0.0
Errors
Common errors & fixes
AccessDeniedException: User is not authorized to perform rds-data:ExecuteStatement on resource: arn:aws:rds:...
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
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:...
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.
Upgrade
Version history
2.0.0latest on npm
Audit
Dependencies
@aws-sdk/client-rds-datarequiredRequired for interacting with the AWS RDS Data API.
kyselyrequiredThe core query builder that this library extends.
Agent activity
6 hits · last 30 days
node
6
Resources