Compose Database-as-a-Service Help and Documentation

Everything you need to know about Compose, Hosted or Enterprise, is here in our help system. Whether you run one database for your businesses' sole application or six different databases to support an entire corporation, we've got the information you need.

RabbitMQ Playground

Introduction

Picture your database and application environment. As business demands change, so does your environment - what started as a single DBMS may have morphed into several members communicating information between one another. As you build an inter-communicating network, you'll witness a sharp spike in complexity ensuring that messages are being delivered and received reliably and securely.

Imagine we took a post-office and placed it at the heart of your environment. Just like an actual post-office, RabbitMQ brokers, receives and sends various forms of communication from location to location. It can acknowledge, queue, and reject messages and message attempts. It will generate long-lived HTTP connections, protected by SSL. You can apply TTL values on your messages and configure vhosts to control access from user groups, queues, and exchanges.

Falling down the 'Rabbit' hole, we need to understand some basic conceptual terms. Within RabbitMQ messaging, there are three entities.

  • The Producers: Applications that generate messages.
  • The Consumers: Applications that receive messages.
  • The Broker: The entity that processes, routes, and queues messages.

The underlying fabric of a RabbitMQ exchange cluster is the core messaging protocol, the Advanced Message Queuing Protocol (AMQP). AMQP offers a supportive connective interface and four different exchange types: direct, fanout, topic, and headers. For more information on specific headers, we recommend exploring the RabbitMQ tutorial on AMQP Concepts.

Let's follow the Rabbit into a simple connectivity example to get some data beating into the heart of your new deployment. We'll whip up a quick Go application, then explore how the data will appear within the administrative panel.

Make a Connection

To follow along, you'll require a standard unix command-line interface with Go installed. Our example is written using OS x, so substitute brew for apt-get when appropriate.

Begin by installing Go.

brew install go --cross-compile-common

Next, we'll need to create and configure a working directory then pull in the AMQP package.

cd ~ && mkdir compose-go-demo && cd compose-go-demo && export GOPATH=$HOME/compose-go-demo
go get github.com/streadway/amqp

We're ready for a small piece of sample code... but before we get into that, we'll need to spin up a RabbitMQ deployment. If you don't have a Compose account, you can get one going here. If you've already got an account, but a RabbitMQ instance, click here to deploy one.

The first thing we'll need to do is create a user. Click on "Browser", then select your vhost. Your initial vhost will take the name of you provided your deployment with.

Select your vhost... then we'll need to add a user and configure their permissions.

Permissions within RabbitMQ require 3 regular expressions: configuration, read, and write. Configure allows a user to create, modify, and delete resources. Write operations allow messages to be injected into a specific resource, with Read allowing the retrieval of messages. We'd suggest checking out the official documents on access control as you start to spec out your cluster.

For our example, we'll give master privileges to our user by including .* as each of the three required expressions.

set_permissions -p RabbitMQDemo compose .* .* .*

Now that we have our user set-up, we have the option to add your development machine IP to the white list. To do this, head to the 'Security' tab. If no IP addresses are whitelisted, a deployment is accessible by anyone. Next, we will return to 'Overview' and isolate one of our connection strings and create a simple messaging application.

Each connection string is associated with one of the haproxy instances in your cluster. Compose enables 'portal management' by default, which creates a single access point to facilitate your HTTP connections into your deployment. Either string can be used to reach this access point.

amqps://[username]:[password]@aws-us-east-1-portal.8.dblayer.com:10437/RabbitMQDemo

Depending on which language you're going to be using to build your application, you'll need an appropriate library for both AMQP and encryption. We'll show you the Go send message script in its entirety. The script will send a health-check message to the RabbitMQ exchange server. We've defined what the name of the queue should be (Health Check) and the content of the health check ("Are you still there?! Phew, good"). Follow the comments to get a sense for what we've built.

package main

//Libraries required to enable a TLS connection, utilize AMQP, and access core Go function.
import (
	"fmt"
	"log"
	"github.com/streadway/amqp"
	"crypto/tls"
	"crypto/x509"
	"io/ioutil"
)

// A function to provide articulate errors - good to practice!
func failOnError(err error, msg string) {
	if err != nil {
		log.Fatalf("%s: %s", msg, err)
		panic(fmt.Sprintf("%s: %s", msg, err))
	}
}

//Establish a connection using secure means. Compose will not allow standard amqp connections - only amqps. Remove the 'InsecureSkipVerify' option in production, as we're only doing it here for quick-example purposes.
func main() {
	cfg := &tls.Config{InsecureSkipVerify : true}
	conn, err := amqp.DialTLS("amqps://[username]:[password]@aws-us-east-1-portal.8.dblayer.com:10437/RabbitMQDemo", cfg)
	failOnError(err, "Failed to connect to RabbitMQ")
	defer conn.Close()

	ch, err := conn.Channel()
	failOnError(err, "Failed to open a channel")
	defer ch.Close()
  
  // Define the name of the queue, and queuing options. We are naming this queue 'Health Check'.
	q, err := ch.QueueDeclare(
		"Health Check", // name
		false,   // durable
		false,   // delete when unused
		false,   // exclusive
		false,   // no-wait
		nil,     // arguments
	)
	failOnError(err, "Failed to declare a queue")

  // Our message, with limited options. We've specified content type and some basic information.
	body := "Are you still there?! Phew, good"
	err = ch.Publish(
		"",     // exchange
		q.Name, // routing key
		false,  // mandatory
		false,  // immediate
		amqp.Publishing{
			ContentType: "text/plain",
			Body:        []byte(body),
		})
	log.Printf(" [x] Sent %s", body)
	failOnError(err, "Failed to publish a message")
}

First, we imported the packages we'll need to connect securely. We defined an error function, then implemented a messaging protocol to send messages to RabbitMQ. Please note, for this demo we're circumventing the security check - you'll want to create your own certificate when applying RabbitMQ in production.

Once you've got your message-sending application ready to roll, save it -- we've named it send.go. We then use go run to compile and run the file once.

$ go run send.go                                                                                                                               
2015/10/23 13:14:44  [x] Are you still there?! Phew, good

Success! We've sent a message to the RabbitMQ message broker after defining a queue name and the message content. Let's access our Web UI, provided underneath the connection string:

Login using the user we created earlier: you'll see that our message was recorded and organized within the Web UI.

The overview provides a real-time demonstration of how many messages are heading towards your exchange. Checkout each menu option to see how each your "default" AMQP exchange has taken place. Send a few more sample messages, provide a new queue name -- play around, break things, explore and see what happens!

Walking through and playing with this example, you should now have a feel for how RabbitMQ might work within an actual application. Whether you're keeping user-scoreboards up to date, sending configuration directives from back-end-to-back-end, sending push notifications, or enabling typical text communication, RabbitMQ will work asynchronously to broker messages and help you decouple your environment into functional server groups.

Hopefully you've enjoyed your first foray into RabbitMQ, happy creating!

RabbitMQ Playground