How to use anynines' service bindings

Service Creation

A PaaS system like anynines allows you to create services and bind them to your application. You can list the available service plan offerings by using the cf marketplace subcommand:

 $> cf marketplace
 Getting services from marketplace in org anynines / space test as jweber@anynines.com... 
 OK service plans description

 elasticsearch Pluto-free Elasticsearch search service
 mongodb 100, Venus-20, Mercury-5 MongoDB NoSQL database
 mysql Mercury-5, Pluto-free, Venus-20 MySQL database
 postgresql Mercury-5, Venus-20, Pluto-free PostgreSQL database (vFabric)
 rabbitmq 100, Venus-2 RabbitMQ message queue
 redis 100, Venus-2 Redis key-value store
 swift free Swift service 

Create a service instance by using the create-service subcommand demonstrated below:

$> cf create-service SERVICE PLAN SERVICE_INSTANCE_NAME

e.g.:

$> cf create-service postgresql Pluto-free postgresql_service_a

This will create a PostgreSQL service instance named “postgresql_service_a” using the Pluto-free plan.

For pricing information on our services please have a look at our pricing page.

Service Bindings

A service binding enables your application to access your service by providing access credentials and server address data within your app’s environment. A service can be bound to multiple applications if they need to share a common service. In addition you can bind multiple services to one application, e.g. a SQL database and a message queue like RabbitMQ.

You can use the bind-service subcommand to create service bindings for your application:

$> cf bind-service APP_NAME SERVICE_INSTANCE_NAME

If you have an application called “my_application” you could bind our previously created service like this:

$> cf bind-service my_application postgresql_service_a

You should restart your app instances after binding a service using the restart subcommand:

$> cf restart my_application

The PaaS system will add an environment variable called VCAP_SERVICES to your application’s containers. This environment variable can be accessed from your application to read credentials and use them to initialize connections to your service instances. The VCAP_SERVICES string is encoded as json.

The following VCAP_SERVICES variable shows an example of the structure:

 VCAP_SERVICES={
 "postgresql-9.1":
 [
 {
 "name":"postgresql_service_a",
 "label":"postgresql-9.1",
 "tags":[],
 "plan":"Pluto-free",
 "credentials":
 {"name":"db_name",
 "host":"10.12.0.9",
 "hostname":"10.12.0.9",
 "port":5433,
 "user":"userX",
 "username":"userX",
 "password":"passwordX",
 "uri":"postgres://userX:passwordX@10.12.0.9:5433/db_name"
 }
 }
 ]
 } 

Since every service needs another set of credential values, the credentials sub-hash structure depends on the bound service type. Please have a look at our article on how to list environment variables for your applications to retrieve the VCAP_SERVICES environment variable.

Ruby Code Snippet

The following code snippet shows how you can access the credentials in Ruby.

 
require 'json'
require 'ostruct'

vcap_services_string = ENV['VCAP_SERVICES']
vs_hash = JSON.parse(vcap_services_string)

# since we can bind multiple service instances of the same service the structure located under "postgresql-9.1" is an array
# we will select the first array member here
credentials_hash = vs_hash["postgresql-9.1"].first['credentials']
credentials = OpenStruct.new(credentials_hash)

# Now you can access the credentials object like a plain ruby object
credentials.name # => "db_name"
credentials.host # => "10.12.0.9"
credentials.hostname # => "10.12.0.9"
credentials.port # => 5433
credentials.user # => "userX"
credentials.username # => "userX"
credentials.password # => "passwordX"
credentials.uri # => "postgres://userX:passwordX@10.12.0.9:5433/db_name"

# Those values can be used to initialize your ORM
# ORM intialization here

We encourage our users to create according snippets for their language of choice and share them with us and our community.

If you have additional questions or code snippets please feel free to use our comment function to add them to this article.

Happy binding.