{"id":21129071,"url":"https://github.com/ics-software-engineering/play-example-mysql","last_synced_at":"2025-07-09T00:31:36.937Z","repository":{"id":9555833,"uuid":"11464480","full_name":"ics-software-engineering/play-example-mysql","owner":"ics-software-engineering","description":"Example configuration of play framework application to use MySQL","archived":false,"fork":false,"pushed_at":"2013-11-21T16:43:03.000Z","size":1266,"stargazers_count":9,"open_issues_count":0,"forks_count":9,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-03-27T04:19:22.804Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ics-software-engineering.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-07-17T01:38:47.000Z","updated_at":"2024-03-27T04:19:22.805Z","dependencies_parsed_at":"2022-07-12T15:03:31.799Z","dependency_job_id":null,"html_url":"https://github.com/ics-software-engineering/play-example-mysql","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ics-software-engineering%2Fplay-example-mysql","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ics-software-engineering%2Fplay-example-mysql/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ics-software-engineering%2Fplay-example-mysql/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ics-software-engineering%2Fplay-example-mysql/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ics-software-engineering","download_url":"https://codeload.github.com/ics-software-engineering/play-example-mysql/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225470732,"owners_count":17479368,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-20T05:15:06.140Z","updated_at":"2024-11-20T05:15:06.698Z","avatar_url":"https://github.com/ics-software-engineering.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"Summary\n=======\n\nThis project shows how to set up your Play Framework application to:\n\n  * use MySQL locally.\n  * deploy to CloudBees and configure to use their MySQL database.\n  \n\nLocal use of MySQL with Play\n============================\n\nHere are the steps to use MySQL locally for development of Play applications:\n\n**1. Download and install MySQL**\n\nInstall MySQL by downloading the [MySQL Community Server](http://dev.mysql.com/downloads/mysql/) following the [instructions](http://dev.mysql.com/doc/refman/5.6/en/installing.html).\nThis project was tested using MySQL\nCommunity Server 5.6.12 for Mac OS X version 10.7 (x86, 64 bit). \n\n**2. Start MySQL**\n\nThis varies depending upon the platform.  On a Mac, the installation process enables you to create\na preferences panel where you can start or stop your local MySQL server:\n\n![screenshot](https://raw.github.com/ics-software-engineering/play-example-mysql/master/doc/play-example-mysql-mac-prefs-panel.png)\n\n\n**3. Set root password**\n\nThe most important thing to do following your local installation is to immediately create a \npassword for the root accounts.  The following commands show one way to do it:\n\n    $ mysql -u root\n    mysql\u003e select User, Host, Password from mysql.user; \n    mysql\u003e update mysql.user SET Password = PASSWORD('ReplaceWithGoodPassword') WHERE User = 'root';\n    mysql\u003e flush privileges;\n    \nSee the [post-installation instructions](http://dev.mysql.com/doc/refman/5.7/en/postinstallation.html)\nfor more information on configuring your MySQL installation. For example, you might want to drop the \"test\" database, or restrict\nanonymous use. \n\n**4. Create user and password environment variables**\n\nThere are at least two good reasons you shouldn't put your MySQL credentials (username and password) in your Play application.conf file\nif you are using a cloud-based hosting service such as GitHub:\n\n  1. Other developers working on the system will either have to define the same credentials or override yours;\n  2. It is just totally lame to put credentials into publicly available files hosted online.\n   \nFortunately, there is an easy solution: reference environment variables that point to \nthe actual credentials. To support this approach, define three environment variables with the\nMySQL username and password you wish to use for local Play development.  On Unix, you might edit ~/.profile to include:\n\n    export DATABASE_URL_DB=mysql://localhost/playexamplemysql?characterEncoding=UTF-8\n    export DATABASE_USERNAME_DB=root\n    export DATABASE_PASSWORD_DB=YourPasswordHere\n    \nIf you choose to create a new MySQL user rather than using the root user, then \nyou will need to be sure to grant that user privileges for the database\nmanipulated by the application. \n\n**5. Create the database to be used with your Play application**\n\nA significant difference between Play's default \"H2\" database and MySQL\nis that H2 will automatically create the database to be used with your Play\napplication, but MySQL will not. Thus, you have to manually create the MySQL database to be used\nwith your application.\n\nFor this example, we will call our database \"playexamplemysql\". Assuming we \nare using the root user for Play development, you can create it in MySQL with the following\n\n    $ mysql -u root -p\n    Enter password: \u003center password here\u003e\n    mysql\u003e create database playexamplemysql;\n    Query OK, 1 row affected (0.00 sec)\n    mysql\u003e exit\n \n**6. Edit build.sbt**\n\nAdd this line:\n\n    \"mysql\" % \"mysql-connector-java\" % \"5.1.21\"\n\nSee the [example build.sbt file](https://github.com/ics-software-engineering/play-example-mysql/blob/master/build.sbt) for details.\n\n**7. Edit application.conf**\n\nEdit four properties to reference your environment variables as follows:\n\n    db.default.driver=com.mysql.jdbc.Driver\n    db.default.url=\"jdbc:\"${DATABASE_URL_DB}\n    db.default.user=${DATABASE_USERNAME_DB}\n    db.default.password=${DATABASE_PASSWORD_DB}\n    \nNote that this is conveniently the exact syntax required by CloudBees, so the same lines will work\nfor local development and remote CloudBees deployment.\n\nTo enable the ORM to automatically create and maintain the MySQL tables and schemas associated\nwith your application, add the following line in the Evolutions section:\n\n    applyEvolutions.default=true\n\nFinally, to activate the Ebean ORM, uncomment the following line:\n\n    ebean.default=\"models.*\"\n\nSee the [example application.conf](https://github.com/ics-software-engineering/play-example-mysql/blob/master/conf/application.conf) to \nsee all these changes in context.\n\n**8. Delete the existing conf/evolutions directory (if present).**\n\nIf you have been doing development with the default H2 database, and are now transitioning to \nMySQL, you should delete the conf/evolutions directory, because it contains SQL statements \nthat are legal in H2 (such as \"create sequence\") but illegal in MySQL.  This will force\nPlay to recreate the conf/evolutions directory and a 1.sql file from scratch using legal MySQL syntax\nthe next time you invoke \"play run\".\n\n**9. Invoke \"play run\".**\n\nInvoking \"play run\" will run Play in \"development mode\", resulting in the creation of\nMySQL tables appropriate for your Model classes. \n\n\n**(Optional) Test your local Play+MySQL installation.**\n\nIf you run into problems, an easy way to test your local MySQL installation is to run this sample application (play-example-mysql).\nThis application minimally enhances the default Play application with a single entity ([PageRetrieval](https://github.com/ics-software-engineering/play-example-mysql/blob/master/app/models/PageRetrieval.java)),\nan instance of which is created and saved in the MySQL database each time the home page is retrieved.  The [index\ncontroller](https://github.com/ics-software-engineering/play-example-mysql/blob/master/app/controllers/Application.java) is modified to retrieve the total number of PageRetrieval instances from the database\neach time a request for the home page is received, and creates a string indicating the total in the home page.\n\nThe following screen shot illustrates the running application:\n\n![screenshot](https://raw.github.com/ics-software-engineering/play-example-mysql/master/doc/play-example-mysql-home.png)\n\nEach time you refresh the page, the number displayed will increment.\n\nTo test your MySQL installation using play-example-mysql, do the following:\n\n  * Install and run MySQL as described above. \n  * Define the three environment variables as specified above.\n  * Download the source code, cd into the directory, and invoke \"play run\". (Using the run command invokes\n    Play in \"development mode\", which will run evolutions to set up the appropriate tables in your MySQL database.)\n  * Retrieve the system in your browser at http://localhost:9000\n  * Refresh the page.   You should see the top line change to indicate a new number of page retrievals.\n  * Stop the system (control-D in the Play console). You will return to the shell.    \n  * Invoke \"play run\" again, and refresh the page in your browser. You should see an updated number\n    of page retrievals indicating that the state of the database survived a web server restart. \n  \nCloudBees deployment\n====================\n\nYou will normally want to do local development in Play's \"development mode\" so that Play can \nmanage and evolve the database schemas (table definitions) for you automatically.  That's a big win.  The major \nconceptual change for CloudBees deployment is that it uses Play's \"production mode\", which\nrequires database schemas to be managed manually. \n\nSo, to deploy your application to CloudBees, you must:\n\n  1. Create the Play application stack on CloudBees.\n  2. Manually create the table structure of your database.\n  3. Disable database evolution.\n  4. Deploy a distribution of the application to CloudBees.\n  \nHere's one of several possible ways to accomplish the above four steps.\n\n**1. Create the Play application stack on CloudBees.**\n\nLogin to CloudBees, and use the ClickStart mechanism to create a new default Play application.\nFor this example, I created a CloudBees application called \"play-mysql\".  I recommend that you \nkeep your CloudBees application names to 16 characters or less in order to avoid truncation. The\nbenefit of using ClickStart is that it automates the details of associating a MySQL database to\na Play application.\n\n**2. Manually create the table structure of your database.**\n\nAs part of your local development, you will have created the folder conf/evolutions/default\ncontaining a set of .sql files with all of the SQL commands necessary to create your \nMySQL database. For the play-example-mysql application, it consists of just a single table\ndefinition located in [1.sql](https://github.com/ics-software-engineering/play-example-mysql/blob/master/conf/evolutions/default/1.sql).\n\nHere is the table definition from that file that we need to recreate in CloudBees:\n\n    create table page_retrieval (\n      id                        bigint auto_increment not null,\n      timestamp                 bigint,\n      constraint pk_page_retrieval primary key (id))\n    ;\n    \nTo create this table in CloudBees, you will need to login directly to the database using a MySQL\nclient.  On a Mac, a reasonable open source choice for the client is [Sequel Pro](http://www.sequelpro.com/).\nRegardless of the client you choose, you will need to obtain the database credentials from CloudBees.   Do this by installing\nthe [CloudBees SDK](https://wiki.cloudbees.com/bin/view/RUN/BeesSDK) and then invoking \n\"bees db:info -p youraccount/dbname\".  For example, here's what I get for my example application:\n\n    $ bees db:info -p philipmjohnson/play-mysql\n      Database name: play-mysql\n      Account:       philipmjohnson\n      Created:       Mon Jul 29 12:38:19 HST 2013\n      Status:        active\n      Master:        ec2-50-19-213-178.compute-1.amazonaws.com:3306\n      Port:          3306\n      Username:      play-mysql\n      Password:      a8f8notmyrealpassword132904c2f\n\nI can use the \"Master\", \"Port\", \"Username\", \"Database name\", and \"Password\" values to connect \nusing Sequel Pro as shown in the following screen shot:\n\n![screenshot](https://raw.github.com/ics-software-engineering/play-example-mysql/master/doc/play-example-mysql-sequel-pro.png)\n\nOnce connected, I can simply paste the page_retrieval table creation statement into the Query window\nand execute it to create the table. \n\nIt is interesting to note that in local development, you must create the database manually but \ntables are managed for you automatically, while CloudBees deployment is the opposite: it will create the database\nfor you automatically but requires you to manually manage the tables.\n\n**3. Disable database evolutions.**\n\nCloudBees needs you to disable evolutions on your application, even though you will want them enabled for local\ndevelopment.   An easy way to achieve both is to create an alternative configuration file for \nuse by CloudBees.  I do this by creating [application.cloudbees.conf](https://github.com/ics-software-engineering/play-example-mysql/blob/master/conf/application.cloudbees.conf)\nin the same directory as the application.conf file.   It is very simple:\n\n    # This is the CloudBees configuration file for the application.\n    # ~~~~~\n    \n    include \"application.conf\"\n    \n    # Evolutions\n    # ~~~~~\n    \n    # Disable evolutions when using CloudBees\n    evolutionplugin=disabled\n    applyEvolutions.default=false\n\nTo tell CloudBees to use this file instead of application.conf, execute the \"bees config:set\" \ncommand, supplying your account and application names and the alternative application.conf file. \nHere's an example invocation of this command for the play-mysql application:\n\n    $ bees config:set -a philipmjohnson/play-mysql config.resource=application.cloudbees.conf\n      Application config parameters for philipmjohnson/play-mysql: saved\n      \n      Application Parameters:\n        proxyBuffering=false\n        http_version=1.1\n        AppDynamics=false\n        config.resource=application.cloudbees.conf\n      Runtime Parameters:\n        java_version=1.7\n\n**4. Deploy a distribution of the application to CloudBees.**\n\n*Option 1: Manually.*  First, create a distribution zip file of your system by invoking \"play dist\". For example:\n\n    $ play dist\n    [info] Loading project definition from /Users/johnson/projecthosting/github/play-example-mysql/project\n    [info] Set current project to play-example-mysql (in build file:/Users/johnson/projecthosting/github/play-example-mysql/)\n    [info] Packaging /Users/johnson/projecthosting/github/play-example-mysql/target/scala-2.10/play-example-mysql_2.10-1.0-SNAPSHOT-sources.jar ...\n    [info] Done packaging.\n    [info] Main Scala API documentation to /Users/johnson/projecthosting/github/play-example-mysql/target/scala-2.10/api...\n    [info] Wrote /Users/johnson/projecthosting/github/play-example-mysql/target/scala-2.10/play-example-mysql_2.10-1.0-SNAPSHOT.pom\n    [info] Packaging /Users/johnson/projecthosting/github/play-example-mysql/target/scala-2.10/play-example-mysql_2.10-1.0-SNAPSHOT.jar ...\n    [info] Done packaging.\n    model contains 19 documentable templates\n    [info] Main Scala API documentation successful.\n    [info] Packaging /Users/johnson/projecthosting/github/play-example-mysql/target/scala-2.10/play-example-mysql_2.10-1.0-SNAPSHOT-javadoc.jar ...\n    [info] Done packaging.\n    [info] \n    [info] Your package is ready in /Users/johnson/projecthosting/github/play-example-mysql/target/universal/play-example-mysql-1.0-SNAPSHOT.zip\n    [info] \n    [success] Total time: 8 s, completed Nov 12, 2013 4:07:26 PM\n\nNext, send that distribution file to CloudBees using the \"bees app:deploy\" command. For example:\n\n    $ bees app:deploy -d false -R java_version=1.7 -a philipmjohnson/play-mysql -t play2 target/universal/play-example-mysql-1.0-SNAPSHOT.zip \n    Deploying application philipmjohnson/play-mysql (environment: ): target/universal/play-example-mysql-1.0-SNAPSHOT.zip\n    Application parameters: {containerType=play2}\n    Runtime parameters: {java_version=1.7}\n    ........................uploaded 25%\n    ........................uploaded 50%\n    ........................uploaded 75%\n    ........................upload completed\n    deploying application to server(s)...\n    Application philipmjohnson/play-mysql deployed: http://play-mysql.philipmjohnson.cloudbees.net\n\nNow you should be able to retrieve the application at the URL above:\n\n![screenshot](https://raw.github.com/ics-software-engineering/play-example-mysql/master/doc/play-example-mysql-cloudbees.png)\n\nYou can refresh this page and see that the counter is updated. \n\n*Option 2: Continuous Integration.*  Another second approach is to automate the deployment of your \napplication by triggering a build and deployment each time you commit.  To see how to do that, \nlook at the [play-example-continuous-integration](http://ics-software-engineering.github.io/play-example-continuous-integration/)\nproject.\n\nAcknowledgements\n================\n\nMany thanks to Felix Belzunce of CloudBees who patiently and promptly answered my many questions as I developed this tutorial.\n\n\n\n\n\n  \n\n  \n \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fics-software-engineering%2Fplay-example-mysql","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fics-software-engineering%2Fplay-example-mysql","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fics-software-engineering%2Fplay-example-mysql/lists"}