Using services with your app

Overview

Tsuru provide ways you to use external services, with that you can have a database, a storage and a lot of other services.

Using

The service workflow can be resumed to two steps:

  1. Create a service instance
  2. Bind the service instance to the app

To start you have to list all services provided by tsuru:

$ tsuru service-list
+----------------+-----------+
| Services       | Instances |
+----------------+-----------+
| elastic-search |           |
| mysql          |           |
+----------------+-----------+

The output from service-list above says that there are two available services: “elastic-search” and “mysql”, and no instances. To create our MySQL instance, we should run the command service-instance-add:

$ tsuru service-instance-add mysql db_instance
Service successfully added.

Now, if we run service-list again, we will see our new service instance in the list:

$ tsuru service-list
+----------------+---------------+
| Services       | Instances     |
+----------------+---------------+
| elastic-search |               |
| mysql          | db_instance   |
+----------------+---------------+

To bind the service instance to the application, we use the command service-instance-bind:

$ tsuru service-instance-bind mysql db_instance -a myapp
Instance blogsql is now bound to the app myapp.

The following environment variables are now available for use in your app:

- MYSQL_PORT
- MYSQL_PASSWORD
- MYSQL_USER
- MYSQL_HOST
- MYSQL_DATABASE_NAME

For more details, please check the documentation for the service, using service-doc command.

As you can see from bind output, we use environment variables to connect to the MySQL server. Next step is update your app to use these variables to connect in the database.

After update it and deploy the new version your app will be able to communicate with service.

More tools

To see more information about a service you should use service-info <service_name>:

$ tsuru service-info mysql
Info for "mysql"

Instances
+-------------+---------+-------+
| Instances   | Plan    | Apps  |
+-------------+---------+-------+
| db_instance | default | myapp |
+-----------------------+-------+

Plans
+---------+------------+
| Name    | Description|
+---------+------------+
| medium  | 2G Memory  |
| default | 1G Memory  |
+---------+------------+

After create a new service instance, sometimes it takes a while to be done. To see the state of a service instance you should use service-instance-status <service_name> <service_instance>:

$ tsuru service-instance-status mysql db_instance
Service instance "db_instance" is pending

After service-instance-status command return up to instance, you are free to use it with your app.