{"id":14443,"library":"aws-cdk-aws-neptune-alpha","title":"AWS CDK AWS Neptune (Alpha)","description":"The `aws-cdk-aws-neptune-alpha` library is the AWS Cloud Development Kit (CDK) Construct Library for AWS Neptune. It provides higher-level constructs (L2 and L3) for provisioning Amazon Neptune database clusters and instances using Python. As an 'alpha' module, its APIs are experimental and subject to non-backward compatible changes or removal in future versions, not adhering to semantic versioning. It is actively developed and released frequently as part of the broader AWS CDK project, with the current version being 2.250.0a0.","status":"active","version":"2.250.0a0","language":"en","source_language":"en","source_url":"https://github.com/aws/aws-cdk.git","tags":["aws","cdk","neptune","graphdb","database","alpha","iac"],"install":[{"cmd":"pip install aws-cdk-aws-neptune-alpha","lang":"bash","label":"Install library"}],"dependencies":[{"reason":"Core AWS CDK library, essential for all CDK applications and construct libraries. Alpha modules may have specific version constraints.","package":"aws-cdk-lib","optional":false},{"reason":"Core building blocks of the AWS CDK construct programming model.","package":"constructs","optional":false}],"imports":[{"note":"Standard import alias for Neptune alpha constructs.","symbol":"aws_neptune_alpha","correct":"import aws_cdk.aws_neptune_alpha as neptune"},{"note":"Required for defining VPCs, which Neptune clusters depend on.","symbol":"aws_ec2","correct":"import aws_cdk.aws_ec2 as ec2"},{"note":"Standard import for the core AWS CDK library.","symbol":"cdk","correct":"import aws_cdk as cdk"}],"quickstart":{"code":"import aws_cdk as cdk\nfrom aws_cdk import (Stack,\n                     aws_ec2 as ec2,\n                     aws_neptune_alpha as neptune)\n\nclass NeptuneStack(Stack):\n    def __init__(self, scope: cdk.App, construct_id: str, **kwargs) -> None:\n        super().__init__(scope, construct_id, **kwargs)\n\n        # Create a VPC for the Neptune cluster\n        vpc = ec2.Vpc(self, \"Vpc\",\n                      max_azs=2,  # Use 2 Availability Zones\n                      nat_gateways=1)\n\n        # Create a Neptune Database Cluster\n        # Note: instanceType requires an 'alpha' prefix for some versions/runtimes\n        cluster = neptune.DatabaseCluster(self, \"NeptuneDatabase\",\n                                          vpc=vpc,\n                                          instance_type=neptune.InstanceType.R5_LARGE,\n                                          engine_version=neptune.EngineVersion.V1_2_0_0)\n\n        # Add a default security group rule to allow connections\n        cluster.connections.allow_default_port_from_any_ipv4(\"Allow connections from anywhere\")\n\n        # Output the cluster endpoint\n        cdk.CfnOutput(self, \"NeptuneClusterEndpoint\",\n                      value=cluster.cluster_endpoint.socket_address,\n                      description=\"The endpoint address of the Neptune Cluster\")\n\napp = cdk.App()\nNeptuneStack(app, \"NeptuneAlphaQuickstartStack\")\napp.synth()","lang":"python","description":"This quickstart deploys a basic AWS Neptune Database Cluster within a new VPC. It defines a `Vpc`, then instantiates `neptune.DatabaseCluster` with a specified instance type and engine version, and finally adds a security group rule to allow connections. The cluster's endpoint is exported as a CloudFormation output."},"warnings":[{"fix":"Refer to the release notes on the AWS CDK GitHub repository or official documentation before upgrading. Be prepared to update your code to match new API signatures or construct names.","message":"This module is in 'alpha' status. Its APIs are experimental and subject to non-backward compatible changes or removal in any future version. It does not adhere to semantic versioning, and breaking changes will be announced in release notes, requiring source code updates when upgrading.","severity":"breaking","affected_versions":"2.x.x-alpha.x"},{"fix":"Always pass a `vpc` property to the `DatabaseCluster` construct. Ensure the VPC has available private subnets and NAT Gateways for outbound internet access if required for engine updates or external services.","message":"Neptune clusters *must* be launched within a VPC. Attempting to deploy a DatabaseCluster without specifying a valid VPC will result in CloudFormation deployment failures.","severity":"gotcha","affected_versions":"All"},{"fix":"If a new engine version or instance type is released and not yet available in the enum, you can use `neptune.EngineVersion.of('your-new-version')` or `neptune.InstanceType.of('db.r6g.large')` to specify it as a string. Always check the official AWS Neptune documentation for the latest supported versions and instance types.","message":"The `EngineVersion` enum and available `InstanceType` options within the CDK construct might not automatically reflect the very latest versions or instance types supported by AWS Neptune. Using an unsupported version will lead to deployment errors.","severity":"gotcha","affected_versions":"All"},{"fix":"Enable `iam_authentication=True` on your `DatabaseCluster` and use `cluster.grant_connect(iam_role)` to grant connection permissions to specific IAM roles or users. Ensure your application's IAM role has the necessary `neptune-db:connect` permissions.","message":"Configuring IAM database authentication for Neptune requires careful setup of IAM policies and granting connect permissions to specific roles or users. Misconfigured IAM can lead to connection errors.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Run `pip install aws-cdk-aws-neptune-alpha` in your virtual environment. Ensure your `requirements.txt` includes this package and you've run `pip install -r requirements.txt`.","cause":"The `aws-cdk-aws-neptune-alpha` package has not been installed or is not accessible in the current Python environment.","error":"ModuleNotFoundError: No module named 'aws_cdk.aws_neptune_alpha'"},{"fix":"Consult the release notes or the latest API documentation for the `aws-cdk-aws-neptune-alpha` version you are using. Update your code to reflect the current API. Consider pinning your `aws-cdk-aws-neptune-alpha` version if stability is critical.","cause":"You are using an older (or newer) version of the `aws-cdk-aws-neptune-alpha` library, and an API method, property, or construct has been renamed, removed, or changed due to its alpha status.","error":"AttributeError: 'DatabaseCluster' object has no attribute 'old_api_method'"},{"fix":"Verify the selected `neptune.InstanceType` and `neptune.EngineVersion` against the official AWS Neptune documentation for your chosen AWS region. Ensure your VPC has sufficient available AZs that support the instance type.","cause":"The combination of the chosen `InstanceType`, `EngineVersion`, and potentially `vpc.availability_zones` is not supported by AWS Neptune in the region you are deploying to, or the specified engine version is outdated/invalid.","error":"CloudFormation deployment failed: The requested DBInstanceClass is not available for the specified EngineVersion and Availability Zone."},{"fix":"Attach an IAM policy to the deploying user/role that grants permissions like `neptune:CreateDBCluster`, `neptune:DeleteDBCluster`, `neptune:ModifyDBCluster`, `neptune:CreateDBInstance`, `ec2:CreateSecurityGroup`, etc., or use the `AdministratorAccess` managed policy for development environments.","cause":"The IAM user or role attempting to deploy the CDK stack lacks the necessary permissions to create or manage Neptune resources.","error":"User: arn:aws:iam::ACCOUNT_ID:user/IAM_USER is not authorized to perform: neptune:CreateDBCluster on resource: arn:aws:neptune:REGION:ACCOUNT_ID:db-cluster/DB_CLUSTER_ID"}],"ecosystem":"pypi"}