Using Instaclustr from Heroku

Our Heroku add-on is now in general release and provides the simplest method to get started with Cassandra from Heroku. Find it in the Heroku Elements marketplace and see our documentation on the Heroku devcenter: https://devcenter.heroku.com/articles/instaclustr

However, for more advanced use cases (such as connecting from both Heroku and another environment) it may be useful to connect from Heroku to a cluster provisioned through the standard Instaclustr environment. The process for doing that is described below.

The tutorial describes the steps required to extend the Heroku python tutorial app to query a Cassandra cluster provisioned by Instaclustr. If you are interested in using a different language, the Instaclustr configuration steps will be the same for all languages. The basic connection settings and driver API reference for other languages can be found on the cluster Connection Details page on the Instaclustr dashboard.

1. Complete the Heroku “Getting Started with Python on Heroku” tutorial. If you are already familiar with Heroku or just impatient to get going with Cassandra, you only need to complete till the “Push local changes” step to follow this tutorial.
2. Provision a new cluster on Instaclustr by logging into the dashboard and choosing “Create Cluster”.
   1. Choose the same AWS region as your Heroku app. You can verify this by running:
      
      heroku info

      1	heroku info

      
      The heroku us region corresponds to AWS US East (Northern Virginia) data centre, the heroku eu region is AWS EU West (Ireland).
   2. For Heroku, we highly recommend enabling password authentication/authorization and client to cluster encryption(due to the fact that Heroku apps have dynamic IPs so it is necessary to open the firewall to all source addresses). At the present time these options are only available for production level Instaclustr node sizes (not developer nodes).
   3. All other settings can be left at default.
3. Once your cluster finishes provisioning, configure the firewall to allow connections from Heroku:
   1. Navigate to the Settings page for the cluster.
   2. Change the value of allowed addresses in the Firewall rules section to “0.0.0.0/0” and click Save Cluster Settings. This will allow any source IP to connect to the cluster.
4. Download the SSL certificate for your newly created cluster
   1. Navigate to the Connection Details page for your cluster.
   2. Click on the “Download Cluster CA X.509 Certificates” button. This will download a zip file with the Certificate Authority certificate for your cluster in a variety of formats.
   3. Unzip the downloaded zip file and copy the cluster-ca-certificate.pem file to your python-getting-started folder.
5. Add the Cassandra driver to your python virtual environment
   1. Edit requirements.txt in your python-getting-started folder to add the line “cassandra-driver==3.11.0” at the end.
   2. Install cassandra-driver to your env:
      
      pip install -r requirements.txt --allow-all-external

      1	pip install -r requirements.txt --allow-all-external

6. Edit the file hello/views.py to include the required code to connect to Cassandra and retrieve some data from a table. Replace the existing contents of the file with the following:
   
   from django.http import HttpResponse from cassandra.cluster import Cluster from cassandra.policies import DCAwareRoundRobinPolicy from cassandra.auth import PlainTextAuthProvider # Create your views here. def index(request): cluster = Cluster( contact_points=[ "<CLUSTER_IP_ADDRESS>" # US_EAST_1 (Amazon Web Services (VPC)) ], load_balancing_policy=DCAwareRoundRobinPolicy(local_dc='US_EAST_1'), # your local data centre port=9042, ssl_options={ 'ca_certs': 'cluster-ca-certificate.pem' }, auth_provider = PlainTextAuthProvider(username='<USER_NAME>', password='<PASSWORD>')) session = cluster.connect() html = 'Connected to cluster %s<br>' % cluster.metadata.cluster_name for host in cluster.metadata.all_hosts(): html += 'Datacenter: %s; Host: %s; Rack: %s<br>' % (host.datacenter, host.address, host.rack) html += "<br>Keyspaces:<br>" rows = session.execute("select keyspace_name from system_schema.keyspaces;") for row in rows: html += row[0] + "<br>" cluster.shutdown() return HttpResponse(html) def db(request): greeting = Greeting() greeting.save() greetings = Greeting.objects.all() return render(request, 'db.html', {'greetings': greetings})

   1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35

   from django.http import HttpResponse from cassandra.cluster import Cluster from cassandra.policies import DCAwareRoundRobinPolicy from cassandra.auth import PlainTextAuthProvider # Create your views here.   def index(request):   cluster = Cluster(        contact_points=[            "<CLUSTER_IP_ADDRESS>" # US_EAST_1 (Amazon Web Services (VPC))        ],       load_balancing_policy=DCAwareRoundRobinPolicy(local_dc='US_EAST_1'),                                                   # your local data centre                port=9042,          ssl_options={            'ca_certs': 'cluster-ca-certificate.pem'        },        auth_provider = PlainTextAuthProvider(username='<USER_NAME>',                password='<PASSWORD>'))   session = cluster.connect()   html = 'Connected to cluster %s<br>' % cluster.metadata.cluster_name     for host in cluster.metadata.all_hosts():     html += 'Datacenter: %s; Host: %s; Rack: %s<br>' % (host.datacenter, host.address, host.rack)     html += "<br>Keyspaces:<br>"     rows = session.execute("select keyspace_name from system_schema.keyspaces;")   for row in rows:        html += row[0] + "<br>"   cluster.shutdown()   return HttpResponse(html) def db(request):   greeting = Greeting()   greeting.save()   greetings = Greeting.objects.all()   return render(request, 'db.html', {'greetings': greetings})

   
   Note: the “connection_points”, “local_dc”, “username” and “password” values in the call to Cluster() will need to be updated with the appropriate value for your cluster. This can be copied from the Connection Setting page for your cluster.
7. Test the changes from your local computer:
   1. Start the application locally by running:
      
      heroku local web

      1	heroku local web

   2. Browse to https://localhost:5000 and you should see the result from connecting to your Cassandra cluster
8. Upload the changes to Heroku and run the application:
   1. Add changed and new files to git change set:
      
      git add cluster-ca-certificate.pem git add requirements.txt git add hello/views.py

      1 2 3

      git add cluster-ca-certificate.pem git add requirements.txt git add hello/views.py

   2. Commit changes to git:
      
      git commit -m "Cassandra!"

      1	git commit -m "Cassandra!"

   3. Push your changes to heroku:
      
      git push heroku master

      1	git push heroku master

   4. Open the application running on Heroku and see the results:
      
      heroku open

      1	heroku open

This is, of course, a basic tutorial and production ready apps are likely to require the use of additional Cassandra driver features such as retry policies and async execution. However, those considerations are not Heroku specific and can be designed using the general driver documentation and other sources of information.