Amplify GraphQL Relational Schema Transformer
raw JSON →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.
Common errors
error Failed to connect to RDS. Please ensure the database credentials and connection string are correct and accessible. ↓
error GraphQL schema validation failed. Unknown directive "@connection". ↓
@hasOne, @hasMany, @belongsTo, and @manyToMany, to define relationships between models. Consult the Amplify GraphQL Transformer v2 documentation for updated syntax. error Error: Table 'my_database.my_table' not found or inaccessible during schema inference. ↓
SELECT privileges on the table and SHOW TABLES, SHOW COLUMNS (or equivalent metadata access) permissions on the database to allow schema inspection. error Function invocation failed: Lambda couldn't find your 'index.handler' file. Please check your 'entry.py' or 'index.js' file in your custom resolver. ↓
amplify push to ensure correct deployment artifacts. Warnings
breaking Migration from GraphQL Transformer v1 to v2 introduced significant breaking changes in how relational models and connections are defined. Older `@connection` directives were replaced by explicit `@hasOne`, `@hasMany`, `@belongsTo`, and `@manyToMany` directives. If you are upgrading an existing Amplify project, expect manual schema adjustments. ↓
gotcha Incorrect or incomplete database connection details (hostname, port, database name, username, password, VPC configuration) are a frequent cause of deployment failures. The transformer needs secure and correct access to inspect the schema and generate resolvers. ↓
gotcha Schema evolution, particularly renaming GraphQL types that map to relational tables, can lead to unexpected behavior or data access issues. Amplify has specific mechanisms like `@mapsTo` for DynamoDB-backed models, but similar care is needed for relational sources to maintain consistency. ↓
gotcha The generated Lambda resolvers often run on specific Python runtimes (e.g., Python 3.8, 3.9, 3.12). Recent Amplify updates have enforced newer Python versions (e.g., 3.8 -> 3.12 for searchable Lambda functions). If you have custom resolvers or rely on a specific runtime, ensure compatibility. ↓
gotcha Upgrades within parent Amplify packages (like `amplify-category-api`) are migrating AWS SDK dependencies from v2 to v3. Custom Lambda resolvers or other custom code interacting with AWS services might require updates to use the AWS SDK for JavaScript v3 if they were written for v2. ↓
Install
npm install graphql-relational-schema-transformer yarn add graphql-relational-schema-transformer pnpm add graphql-relational-schema-transformer Imports
- RelationalDBTransformer
import { RelationalDBTransformer } from 'graphql-relational-schema-transformer'; - RelationalDBDataSourceType
import { RelationalDBDataSourceType } from 'graphql-relational-schema-transformer'; - RelationalDBProvisionedSettings
import { RelationalDBProvisionedSettings } from 'graphql-relational-schema-transformer';
Quickstart
import { AmplifyGraphqlApi, AmplifyGraphqlDefinition } from '@aws-amplify/graphql-api-construct';
import { App, Stack } from 'aws-cdk-lib';
import { CfnParameter } from 'aws-cdk-lib';
const app = new App();
const stack = new Stack(app, 'MyAmplifyRelationalApiStack');
// Define your database connection details using CDK parameters or environment variables.
// In a real application, retrieve these securely (e.g., from AWS Secrets Manager).
const dbHost = new CfnParameter(stack, 'DbHost', { type: 'String', description: 'Database Hostname' }).valueAsString;
const dbName = new CfnParameter(stack, 'DbName', { type: 'String', description: 'Database Name' }).valueAsString;
const dbUser = new CfnParameter(stack, 'DbUser', { type: 'String', description: 'Database User' }).valueAsString;
const dbPassword = new CfnParameter(stack, 'DbPassword', { type: 'String', description: 'Database Password', noEcho: true }).valueAsString;
// A simplified GraphQL schema for a relational model.
// In a typical Amplify CLI workflow, this would be in `amplify/backend/api/<api-name>/schema.sql.graphql`
const relationalSchema = `
type Post @model @hasMany(references: "Author") {
id: ID!
title: String!
content: String
authorId: ID
author: Author @belongsTo(references: "Post")
}
type Author @model {
id: ID!
name: String!
email: String!
posts: [Post]
}
# Example of how to connect to an existing database table (e.g., in schema.sql.graphql)
# Note: The actual connection parameters are provided at deployment time,
# not directly in the GraphQL schema directives for relational sources.
`;
new AmplifyGraphqlApi(stack, 'MyRelationalApi', {
apiName: 'myRelationalApi',
definition: AmplifyGraphqlDefinition.fromString(relationalSchema, {
// These are example settings; actual implementation varies by database and security setup.
// The transformer would infer schema from the live database during 'amplify push'
// or when using `amplify import api` via Amplify CLI.
// For CDK, you might define the RDS data source and connect it.
// This part is highly dependent on how your RDS instance is managed and exposed.
database: {
engine: 'MYSQL',
vpcConfig: {
vpcId: 'vpc-xxxxxxxxxxxxx', // Replace with your VPC ID
securityGroupIds: ['sg-xxxxxxxxxxxxx'], // Replace with your Security Group ID
subnetIds: ['subnet-xxxxxxxxxxxxx', 'subnet-yyyyyyyyyyyyy'], // Replace with your Subnet IDs
},
clusterIdentifier: 'my-rds-cluster',
secretArn: 'arn:aws:secretsmanager:REGION:ACCOUNT:secret:rds-credentials-xxxxxx' // Example
}
})
});
app.synth();