Stackato includes a number of data services which can be bound to the applications you deploy. These include several databases (PostgreSQL, MySQL, MongoDB, Redis), the RabbitMQ messaging service, a persistent file system service and Memcached.
The data services your application requires need to be specified at the time your app is pushed to the Stackato server. This can be done in a number of ways:
If you would like to use an external database system, see Using External Database Services.
The stackato.yml file can hold a lot of application specific details that tell the Stackato Client what to do without having to enter them when you run stackato push. For complete details for the stackato.yml file, please see Configuration With stackato.yml.
A simple example:
name: cirrus
framework:
type: perl
mem: 64M
instances: 2
services:
cirrusdb: mysql
This tells the Stackato Client to request a MySQL database called cirrusdb. Possible service types are:
To access the data services once they've been created, see Accessing Configured Database Services.
If you do not specify services in the stackato.yml file, you will be prompted to create one during the push process. Should you want to set up a database service, enter "y" when asked, and follow the prompts:
$ stackato push
...
Would you like to bind any services to 'cirrus' ? [yN]: y
The following system services are available
1. mongodb
2. mysql
3. postgresql
4. redis
5. <None of the above>
Please select one you wish to provision: 2
Specify the name of the service [mysql-18cab]: cirrusdb
Creating Service: OK
Binding Service: OK
...
In order to ensure the correct services are configured each time the app is pushed, your services should be listed in the stackato.yml file.
It is possible to create services and bind them to an app after they are pushed to the Stackato server. There are two ways to do this:
This combines all parameters into a single command. service is the type of service you want to create (mysql, redis, postgresql, mongodb). name is the name you want to assign to the service. app is the name of the application the service is to be bound to.
$ stackato create-service mysql ordersdb myapp
Creating Service: OK
Binding Service: OK
Stopping Application [myapp]: OK
Staging Application [myapp]: OK
Starting Application [myapp]: OK
$ stackato apps
+-------------+---+-------------+---------------------------+----------------+
| Application | # | Health | URLS | Services |
+-------------+---+-------------+---------------------------+----------------+
| myapp | 1 | RUNNING | myapp.stackato-xxxx.local | ordersdb |
+-------------+---+-------------+---------------------------+----------------+
create-service <service> <name>
These two commands do the same thing as if all three parameters were passed using create-service, but it allows the flexibility of creating and perhaps configuring the service before binding it.
service is the type of service you want to create (mysql, redis, postgresql, mongodb). name is the name you want to assign to the service. servicename is the name assigned during the create-service command. app is the name of the application the service is to be bound to.
$ stackato create-service mysql customerdb
Creating Service: OK
$ stackato bind-service customerdb myapp
Binding Service: OK
Stopping Application [myapp]: OK
Staging Application [myapp]: OK
Starting Application [myapp]: OK
$ stackato apps
+-------------+---+---------+---------------------------+-----------------------+
| Application | # | Health | URLS | Services |
+-------------+---+---------+---------------------------+-----------------------+
| myapp | 1 | RUNNING | myapp.stackato-xxxx.local | ordersdb, customerdb |
+-------------+---+---------+---------------------------+-----------------------+
For further information on the commands for manging services, please see the stackato services command reference.
Note
To remotely check the settings and credentials of any Stackato service, use the stackato service command.
When you bind a database service to an application running in Stackato, environment variables containing that service's host, port, and credentials are added to the application container. You can use these environment variables in your code to connect to the service, rather than hard coding the details.
Examples of how to parse and use these variables can be found in the Language Specific Deployment section.
If only one database service is bound to an application, use the DATABASE_URL environment variable. It contains the connection string for the bound database in the following format:
protocol://username:password@host:port/database_name
For example, a DATABASE_URL for a PostgreSQL service would look like this:
postgres://u65b0afbc8f8f4a1192b73e8d0eb38a24:[email protected]:5432/da17e48ddc82848499cb387bc65f5d4f9
The "protocol" portion specifies the type of database. For example:
Note
The "database name" portion of the URL is the actual database name (e.g. "da17e48ddc82848499cb387bc65f5d4f9"), not the user-specific service name set during deployment/service creation (e.g. "myapp-db").
If more than one database service type is bound to the application (e.g. MySQL and MongoDB services), the DATABASE_URL variable will not be set, but the following database-specific variables will still be available:
These have the same format as DATABASE_URL.
If more than one database of the same type is bound to the application (e.g. two MongoDB services), none of the URL formatted environment variables will be available. Use STACKATO_SERVICES or VCAP_SERVICES instead.
Contains a JSON string listing the credentials for all bound services, grouped by service name. For example:
{
"postdb": {
"name": "d4854a20e5854464891dbd56c08c440d9",
"host": "192.168.0.112",
"hostname": "192.168.0.112",
"port": 5432,
"user": "u74499595373c4bea84be2a87c2089101",
"username": "u74499595373c4bea84be2a87c2089101",
"password": "pdbbe19398c5a4463bba0644f7798f1f1"
},
"mydb": {
"name": "d0a60c0be931f4982bbef153f993237bc",
"hostname": "192.168.0.112",
"host": "192.168.0.112",
"port": 3306,
"user": "u93Mm8XmGXQ9R",
"username": "u93Mm8XmGXQ9R",
"password": "p8LwNeQXMrNzi"
}
}
Contains a JSON string listing the credentials for all bound services, grouped by service type. For example:
{
"mysql": [
{
"name": "mydb",
"label": "mysql-5.5",
"plan": "free",
"tags": [
"mysql",
"mysql-5.5",
"relational"
],
"credentials": {
"name": "d0a60c0be931f4982bbef153f993237bc",
"hostname": "192.168.0.112",
"host": "192.168.0.112",
"port": 3306,
"user": "u93Mm8XmGXQ9R",
"username": "u93Mm8XmGXQ9R",
"password": "p8LwNeQXMrNzi"
}
}
]
}
This variable contains some additional meta-information, and can be used for compatibility with Cloud Foundry.
Note
VCAP_SERVICES variables in Stackato v2.2 and later use non-versioned service names The version number remains in 'label' key.
Applications running in Stackato can use external databases by hard-coding the host and credentials, or by specifying the them in a custom environment variable.
Alternatively, system administrators can configure Stackato to provision databases on external servers. See External Data Services for more information.
You may need to connect to a database service directly for purposes of initial database setup, modifying fields, running queries, or doing backups. These operations can be done using the dbshell (preferred) or tunnel commands.
The stackato dbshell command creates an SSH tunnel to database services. To open an interactive shell to a service:
$ stackato dbshell <service_name>
The command will automatically open the appropriate database client for the database you're connecting to, provided that client is installed on the local system.
It is also available inside application containers, providing a quick way to import data from dump files, or setting up schemas. For example, to import data from file in an application directory, you could use a hook in stackato.yml such as:
hooks:
post-staging:
- dbshell < setup/sample-data.sql
The stackato tunnel command is an alternative method for accessing database services. The command creates a small Ruby application which proxies database requests over HTTP. This is the standard method for database access in Cloud Foundry, but tends to be slower than using dbshell:
To create or use a tunnel:
$ stackato tunnel <servicename>
Depending on the service you are connecting to, a list of options will be provided. Here is an example of connecting to a MySQL service:
$ stackato tunnel mydb
Getting tunnel url: OK, at https://tunnel-xxxxx.stackato-xxxx.local
Getting tunnel connection info: OK
Service connection info:
+----------+-----------------------------------+
| Key | Value |
+----------+-----------------------------------+
| username | uT9efVVFCk |
| password | pHFitpIU1z |
| name | d5eb2468f70ef4997b1514da1972 |
+----------+-----------------------------------+
1. none
2. mysql
3. mysqldump
Which client would you like to start?
For simple command line access, select option 2. mysql.
To get a dump of the entire database, select option 3. mysqldump. You will be prompted to enter a path to where the dump will be saved to.
If you want to connect with a database viewer, or run multiple commands from the command line, passing in SQL files, select option 1. none. This will set up a port for you to connect with locally:
1. none
2. mysql
3. mysqldump
Which client would you like to start? **none**
Starting tunnel to remarks on port 10000.
Open another shell to run command-line clients or
use a UI tool to connect using the displayed information.
Press Ctrl-C to exit...
You how have all the information you need to access the data. Notice the "Service connection info" box above that tells you your username, password, and the database name.
Open a new command line window. You can connect to the MySQL database directly with:
$ mysql --protocol=TCP --host=localhost --port=10000 --user=<user> --password=<password> <name>
example:
$ mysql --protocol=TCP --host=localhost --port=10000 --user=uT9efVVFCk --password=pHFitpIU1z d5eb2468f70ef4997b1514da1972
To import an SQL file, call the same command, and pipe in the file:
$ mysql --protocol=TCP --host=localhost --port=10000 --user=<user> --password=<pass> <name> < mydatabase.sql
To pull a dump of all databases:
$ mysqldump -A --protocol=TCP --port=10000 --host=localhost --user=<user> --password=<pass>
Applications can use an SQLite database as an alternative to Stackato database services. However, as the filesystem of an application container is ephemeral (i.e. it is destroyed when an application is stopped, restarted, or updated), you should always store the SQLite file on a Persistent File System mount point to avoid losing data.