Using MySQL for PCF v2
This topic provides instructions for developers using the MySQL for Pivotal Cloud Foundry (PCF) v2 service for their PCF apps. MySQL provides a relational database for apps and devices.
These procedures use the Cloud Foundry Command Line Interface (cf CLI). For more information, see Managing Service Instances with the cf CLI.
You can also use Apps Manager to do the same tasks using a graphical UI.
To use MySQL for PCF v2 with your PCF apps, you need:
- A PCF installation with MySQL for PCF installed and listed in the Marketplace
- A Space Developer or Admin account on the PCF installation
- A local machine with the following installed:
- To log in to the org and space containing your app
To use MySQL in a PCF app:
Check the service availability in the Marketplace, and see if there is an existing instance of MySQL for PCF in your space.
If there is no existing instance or you want to use a different one, create an instance of the MySQL for PCF service in the same space as the app.
See Create a Service Instance, below.
Push your app into the same space as the MySQL for PCF service instance, using
For information about
cf push, see Push.
Bind the app to the MySQL for PCF service instance, to enable the app to use MySQL.
See Bind a Service Instance to Your App, below.
Call the MySQL for PCF service in your app code, and then re-push your app into the space.
See Use the MySQL Service in Your App, below.
For an app to use the MySQL for PCF v2 service, both of the following must be true:
- The service must be available in the Marketplace for its space.
- An instance of the service must exist in its space.
You can confirm both of these using the cf CLI as follows.
To find out if a MySQL for PCF v2 service is available in the Marketplace, do the following:
If the output lists
servicecolumn, MySQL for PCF v2 is available. If it is not available, ask your operator to install it.
$ cf marketplace Getting services from marketplace in org my-org / space my-space as firstname.lastname@example.org... OK service plans description [...] p.mysql db-small Dedicated instances of MySQL service to provide a relational database [...]
To confirm that a MySQL for PCF v2 instance is running in the space, do the following:
- Use the cf CLI or Apps Manager to log in to the org and space that contains the app.
p.mysqllistings in the
servicecolumn are service instances of MySQL for PCF v2 in the space.
$ cf services Getting services in org my-org / space my-space as email@example.com... OK name service plan bound apps last operation my-instance p.mysql db-small create succeeded
Unlike pre-provisioned services, on-demand services are created asynchronously, not immediately.
watch command shows you when your service instance is ready to bind and use.
To create an instance of the MySQL for PCF v2 service, do the following:
Run the command
cf create-service p.mysql PLAN SERVICE-INSTANCE
PLANis the name of the MySQL for PCF v2 plan you want to use.
SERVICE-INSTANCEis a name you choose to identify the service instance. This name appears under
servicein output from
watch cf servicesand wait for the
last operationfor your instance to show as
$ cf create-service p.mysql db-small my-instance
Creating service my-instance in org my-org / space my-space as firstname.lastname@example.org... OK
$ watch cf services
Getting services in org my-org / space my-space as email@example.com... OK name service plan bound apps last operation my-instance p.mysql db-small create succeeded
If you get an error, see Troubleshooting Instances.
For an app to use a service, you must bind the app to a service instance. Do this after you push or re-push the app using
To bind an app to a MySQL for PCF instance run the command
cf bind-service APP SERVICE-INSTANCE
APP is the app you want to use the MySQL service instance.
SERVICE-INSTANCE is the name you supplied when you ran
$ cf bind-service my-app my-instance
Binding service mydb to my-app in org my-org / space test as firstname.lastname@example.org... OK TIP: Use 'cf push' to ensure your env variable changes take effect
To access the MySQL service from your app:
cf env APP-NAMEwith the name of the app bound to the MySQL for PCF instance.
In the output, note the connection strings listed in the
credentialsobject for the app.
In your app code, call the MySQL service using the connection strings.
This section describes tasks you do over the life cycle of your apps and data:
- Moving your data to a different plan.
- Removing an app’s access to a service it no longer needs.
- Deleting a service instance that is not used.
As apps and their databases grow, it may be necessary to update the service instance to a larger plan. This does not require a rebinding of your app. However, while the instance is being migrated to a new service instance, the database will be unavailable for several minutes.
To update a service instance to a larger plan, run the commannd
cf update-service SERVICE-INSTANCE -p PLAN
PLAN is the plan you want to upgrade the service instance to.
$ cf update-service my-instance -p db-large
To stop an app from using a service it no longer needs, run the following command to unbind the app from the service:
cf unbind-service APP SERVICE-INSTANCE
APP is the app you want to stop using the MySQL service instance.
SERVICE-INSTANCE is the name you supplied when you ran
$ cf unbind-service my-app my-instance
Unbinding app my-app from service my-instance in org my-org / space my-space as email@example.com... OK
You cannot delete a service instance that an app is bound to.
To delete a service instance, do the following:
Run the command
cf delete-service SERVICE-INSTANCE
SERVICE-INSTANCEis the name of the service to delete.
$ cf delete-service my-instance
Are you sure you want to delete the service my-instance ? y Deleting service my-service in org my-org / space my-space as firstname.lastname@example.org... OK
watch cf service SERVICE-INSTANCEand wait for a
Service instance not founderror indicating that the instance no longer exists.
The following tools let developers access their MySQL for PCF databases.
The Pivotal MySQLWeb app provides a web-based UI for managing MySQL for PCF databases. The free app lets you view and operate on tables, indexes, constraints, and other database structures, and directly execute SQL commands.
You can run the Pivotal MySQLWeb app in two ways:
- Standalone on your own machine
- Deployed to PCF
If you deploy Pivotal MySQLWeb to PCF, you can configure it in the deployment manifest to automatically bind to a specific service instance.
To connect to your MySQL for PCF databases from a command line, use the cf CLI MySQL plugin. The plugin lets you:
- Inspect databases for debugging
- Manually adjust database schema or contents in development environments
- Dump and restore databases
To install the cf CLI MySQL plugin, run the following:
$ cf install-plugin -r "CF-Community" mysql-plugin
For more information, see the cf-mysql-plugin repository.
To help app developers get started with MySQL for PCF, we have provided an example app, which can be downloaded here. Instructions can be found in the included README.