Build a friend recommendation engine for games with Amazon Neptune

Introduction

Background and setup

Provision a database

Plan your data model

Add authentication to your application

Deploy your application

Test your application

Clean up and next steps

Provision a database

In this module, you provision an Amazon Neptune instance and test connecting to your instance in your application code.

Time to Complete Module: 30 Minutes

Amazon Neptune is a fully managed graph database provided by AWS. It provides a highly-available service with easy scaling mechanisms, automatic failovers, and regular backups.

In the following steps, you first provision an Amazon Neptune instance. Then, you configure your Neptune instance so that it is accessible from your Cloud9 development environment. Finally, you test this connection by connecting with your application code.

  • Step 1. Provision an Amazon Neptune database

    Step 1. Provision an Amazon Neptune database

    Go to the Amazon Neptune section in the AWS Management Console and choose Launch Amazon Neptune.

    (Click to enlarge)

    In the Engine options section, for Version, choose Neptune 1.2.1.0.R3.

    (Click to enlarge)

    In the Settings section, for DB cluster identifier, name your database recommendations.

    (Click to enlarge)

    In the Templates section, choose Development and Testing.

    (Click to enlarge)

    In the DB instance size section, choose Burstable classes and choose the smallest instance size. A burstable instance class is the most cost-effective for development, where you generally don't need high capacity all the time. (Note: Amazon Neptune does not qualify for the AWS Free Tier, so you will incur a small charge for your instance.)

    (Click to enlarge)

    In the Availability & durability section, for Multi-AZ-deployment, choose No. ( Note: In production, you may want to enable this option so that your database is available in the event of a failure.)

    (Click to enlarge)

    In the Connectivity section, keep the default settings.

    Expand the Additional configuration section. In the Database options section, for DB instance identifier, name your database instance recommendations. Leave all other default settings.

    Choose Create database.

    (Click to enlarge)

    Success! You've created your Amazon Neptune database! You should see a status of creating for your recommendations database.

    (Click to enlarge)

  • Step 2. Create a security group for your AWS Lambda function

    Step 2. Create a security group for your AWS Lamba function

    While your database is provisioning, you can create a security group for your Lambda function. AWS Lambda is a serverless computing service from AWS where you upload code that is executed when certain events happen. You don't need to worry about server provisioning or management -- your code execution is handled entirely for you. You learn more about AWS Lambda in a future module.

    For now, you need to create a security group for your Lambda function so that it can access your Amazon Neptune database. To get started, navigate to the Security Groups tab in the EC2 section of the AWS Management Console.

    Choose Create Security Group to create a new security group.

    (Click to enlarge)

    On the Create Security Group page, name your security group recommendations-lambda. It should be in your default VPC, which is the same VPC where you launched your Neptune database.

    Choose Create security group.

    (Click to enlarge)

    In the list of security groups, find your recommendations-lambda security group. Copy the value of the Group ID (starts with sg-).

    In your Cloud9 terminal, run the following command, substituting your Group ID value for for <securityGroupId>:

    echo "export SECURITY_GROUP_ID=<securityGroupId>" >> env.sh && source env.sh

  • Step 3. Configure access to your Neptune instance

    Step 3. Configure access to your Neptune instance

    Now you need to configure your Neptune database so that both your Cloud9 development environment and your AWS Lambda function can access it.

    Amazon Neptune instances must be provisioned in a virtual private cloud (VPC) in a private subnet. They cannnot receive a public IP address and cannot be accessed from the public internet. To access your Neptune instance, you need to configure access from some compute resource -- like an Amazon EC2 instance or Lambda function -- that has access inside your VPC.

    To configure this access, go to Databases in the Neptune section of the AWS Management Console and choose the recommendations instance with a Writer role (under Cluster).

    (Click to enlarge)

    In the Neptune database instance details, the Connectivity & security section shows the security groups configured for your database. Choose the security group name to open it.

    (Click to enlarge)

    In the lower section, choose the Inbound rules tab to see the allowed inbound rules for your security group. Then, choose Edit inbound rules.

    (Click to enlarge)

    The inbound rules state what network traffic is allowed into your Neptune instance and on which ports. By default, the Neptune wizard configured an inbound rule. Edit this existing rule to allow access from your Cloud9 instance:

    1. For Type, choose Custom TCP.
    2. For Port range, type 8182.
    3. For Source, choose Custom, and type aws-cloud9-User-Recommendations. Select the security group for your Cloud9 instance.
    4. For Description, type AWS Cloud9.

    Next, choose Add Rule and add a rule allowing access for your Lambda function:

    1. For Type, choose Custom TCP.
    2. For Port Range, type 8182.
    3. For Source, choose Custom, and type recommendations-lambda. Select your Lambda security group.
    4. For Description, type AWS Lambda.

    You should now have two rules in your security group. Choose Save rules.

    (Click to enlarge)

    You have now given your Cloud9 development environment and Lambda function access to your Amazon Neptune database.

  • Step 4. Test the connection to your Neptune database

    Step 4. Test the connection to your Neptune database

    Now that you have enabled access to your Neptune database from your Cloud9 instance, you should test the connection to ensure you can connect to your database.

    Return to the details page for your Neptune instance. In the Connectivity & security box, you should see an Endpoint for your database.

    Copy the value of the Endpoint. Then, in your Cloud9 terminal, run the following command (make sure to replace <yourEndpoint> with the Endpoint value you copied):

    echo "export NEPTUNE_ENDPOINT=<yourEndpoint>" >> env.sh

    (Click to enlarge)

    Load these environment variables into your session by running the following command:

    source env.sh

    There is a file in the scripts/ directory called testDatabase.js. This file initiates a connection to your Neptune database to make sure your connection setup is correct.

    The contents of the file are as follows:

    const gremlin = require('gremlin');
const DriverRemoteConnection = gremlin.driver.DriverRemoteConnection;
const Graph = gremlin.structure.Graph;

const connection = new DriverRemoteConnection(`wss://${process.env.NEPTUNE_ENDPOINT}:8182/gremlin`,{});

const graph = new Graph();
const g = graph.traversal().withRemote(connection);

g.V().count().next().
    then(data => {
        console.log(data);
        connection.close();
    }).catch(error => {
        console.log('ERROR', error);
        connection.close();
    });

    The library you are using to connect to the database is called Gremlin. It uses the Gremlin query language to query and traverse your Neptune database. You learn more about Gremlin queries in the following modules.

    The first few lines of code import the needed libraries. Then, it creates a connection to your database using the Neptune endpoint property you set in your terminal. Finally, it connects to the database and runs a count() request to query the number of vertices in your graph.

    You can execute the script with the following command:

    node scripts/testDatabase.js

    You should see the following output: 

    { value: 0, done: false }

    Success! You can connect to your database. The script prints out the results, and it shows that there are 0 vertices in your graph.

Conclusion

In this module, you provisioned an Amazon Neptune database instance for your application. Then, you updated the security group settings to allow access to your database from your Cloud9 development environment and a Lambda function. Finally, you ran a test script to ensure you could connect to your database instance.

In the next module, you learn about the Neptune graph data model. You learn key concepts and terms for a graph database. Then, you load some data into your database and run some queries that are needed in your application.

Next: Plan your data model