The `graphql-relational-schema-transformer` package is a foundational component within the AWS Amplify ecosystem, designed to facilitate the creation of GraphQL APIs from existing relational databases for use with AWS AppSync. As of version 2.21.34, it plays a crucial role in enabling developers to connect their AppSync GraphQL APIs to data sources like Amazon RDS (MySQL, PostgreSQL) and Aurora Serverless. This transformer inspects relational database schemas and automatically generates corresponding GraphQL types, along with the necessary AppSync resolvers and underlying AWS Lambda functions, to perform CRUD (Create, Read, Update, Delete) operations. While direct programmatic interaction with this specific package name might be less common for end-users, it underpins the functionality exposed through higher-level tools like the Amplify CLI's `amplify import api` command and the `@aws-amplify/graphql-api-construct` for AWS CDK deployments. It integrates with GraphQL Transformer v2's directive system, allowing the definition of relational models using `@model`, `@hasOne`, `@hasMany`, `@belongsTo`, and `@manyToMany` directives. This package is actively maintained as part of the broader AWS Amplify API category, with frequent updates often bundled within `@aws-amplify/amplify-category-api` releases.
npm install graphql-relational-schema-transformerVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to define a simple GraphQL schema with relational directives (`@model`, `@hasMany`, `@belongsTo`) and deploy it using the `@aws-amplify/graphql-api-construct` for AWS CDK, which internally leverages transformers like `graphql-relational-schema-transformer`. It also illustrates how to specify database connection parameters for an existing relational database.
Review the AWS Amplify documentation for GraphQL Transformer v1 to v2 migration guides. Manually update your `schema.graphql` or `schema.sql.graphql` to use the new relational directives.
Ensure all database connection parameters are correct and securely stored (e.g., in AWS Systems Manager Parameter Store or Secrets Manager). Verify VPC, security group, and network ACL configurations allow AppSync/Lambda to reach your RDS instance, especially if it's in a private subnet.
Plan schema changes carefully. For relational models, consider using a database migration tool to manage actual table renames. If a GraphQL type name changes, ensure any generated code or manual mappings account for the underlying relational table name, potentially using custom resolver overrides.
Regularly update your Amplify CLI and dependencies. If deploying custom Lambda functions, ensure their runtime environments are compatible with the latest Amplify-generated Lambda runtimes or specify a compatible version explicitly.
When `amplify push` generates new resolvers, check the deployed Lambda code for SDK version. If you have custom Lambda functions, review the AWS SDK v3 migration guide to update your code if necessary. Leverage the AWS SDK v3's modular design for smaller bundles.
Verify database hostname, port, username, and password. Ensure the database is publicly accessible or that your VPC, security groups, and NACLs allow inbound traffic from the Amplify deployment environment (e.g., Lambda functions' VPCs) to the RDS instance.
Update your GraphQL schema to use the new relational directives introduced in GraphQL Transformer v2, such as `@hasOne`, `@hasMany`, `@belongsTo`, and `@manyToMany`, to define relationships between models. Consult the Amplify GraphQL Transformer v2 documentation for updated syntax.
Confirm the table name spelling and case sensitivity. Grant the database user `SELECT` privileges on the table and `SHOW TABLES`, `SHOW COLUMNS` (or equivalent metadata access) permissions on the database to allow schema inspection.
Check the CloudWatch logs for the specific Lambda function for detailed errors. Verify the configured Lambda runtime version (e.g., Python 3.12) and ensure your custom resolver code (if any) or the generated code is compatible and correctly packaged for that runtime. Re-run `amplify push` to ensure correct deployment artifacts.