Merge pull request #36 from GoogleCloudPlatform/cloud-sql-v2

Update Cloud SQL sample to use Cloud SQL second generation

Author: remi Taylor

appengine/cloudsql/README.md

@@ -1,41 +1,90 @@
 # Ruby Cloud SQL sample on Google App Engine flexible environment
 
-This sample demonstrates how to use [Cloud SQL](https://cloud.google.com/sql/)
-on [Google App Engine flexible environment](https://cloud.google.com/appengine/docs/flexible/).
+This sample demonstrates how to use [Google Cloud SQL][sql] (or any other SQL
+server) on [Google App Engine flexible environment][flexible].
 
 ## Setup
 
 Before you can run or deploy the sample, you will need to do the following:
 
-1. Create a Cloud SQL instance. You can do this from the [Google Developers Console](https://console.developers.google.com)
-or via the [Cloud SDK](https://cloud.google.com/sdk). To create it via the SDK
-use the following command:
+1. Create a [Second Generation Cloud SQL][gen] instance. You can do this from
+the [Cloud Console][console] or via the [Cloud SDK][sdk]. To create it via the
+SDK use the following command:
 
-        gcloud sql instances create [your-instance-name] \
-          --assign-ip \
-          --authorized-networks 0.0.0.0/0 \
-          --tier D0
+        gcloud sql instances create [YOUR_INSTANCE_NAME] \
+            --activation-policy=ALWAYS \
+            --tier=db-n1-standard-1
+
+    where `[YOUR_INSTANCE_NAME]` is a name of your choice.
+
+1. Set the root password on your Cloud SQL instance:
+
+        gcloud sql instances set-root-password [YOUR_INSTANCE_NAME] --password [YOUR_INSTANCE_ROOT_PASSWORD]
+
+    where `[YOUR_INSTANCE_NAME]` is the name you chose in step 1 and
+    `[YOUR_INSTANCE_ROOT_PASSWORD]` is a password of your choice.
+
+1. Create a [Service Account][service] for your project. You will use this
+service account to connect to your Cloud SQL instance locally.
+
+1. Download and install the [Cloud SQL Proxy][proxy].
+
+1. [Start the proxy][start] to allow connecting to your instance from your local
+machine:
+
+        cloud_sql_proxy \
+            -dir /cloudsql \
+            -instances=[YOUR_INSTANCE_CONNECTION_NAME] \
+            -credential_file=PATH_TO_YOUR_SERVICE_ACCOUNT_JSON
+
+    where `[YOUR_INSTANCE_CONNECTION_NAME]` is the connection name of your
+    instance on its Overview page in the Google Cloud Platform Console, or use
+    `[YOUR_PROJECT_ID]:[YOUR_REGION]:[YOUR_INSTANCE_NAME]`.
+
+1. Use the MySQL command line tools (or a management tool of your choice) to
+create a [new user][user] and [database][database] for your application:
+
+        mysql --socket [YOUR_SOCKET_PATH] -u root -p
+          mysql> create database YOUR_DATABASE;
+          mysql> create user 'YOUR_USER'@'%' identified by 'PASSWORD';
+          mysql> grant all on YOUR_DATABASE.* to 'YOUR_USER'@'%';
+
+    where `[YOUR_SOCKET_PATH]` is that socket opened by the proxy. This path was
+    printed to the console when you started the proxy, and is of the format:
+    `/[DIR]/[YOUR_PROJECT_ID]:[YOUR_REGION]:[YOUR_INSTANCE_NAME]`.
+
+1. Set the `MYSQL_USER`, `MYSQL_PASSWORD`, `MYSQL_SOCKET_PATH`, and
+`MYSQL_DATABASE` environment variables. This allows the app to connect to your
+Cloud SQL instance through the proxy.
 
-1. Create a new user and database for the application. The easiest way to do
-this is via the [Google Developers Console](https://console.developers.google.com/project/_/sql/instances/example-instance2/access-control/users).
-Alternatively, you can use MySQL tools such as the command line client or
-workbench.
 1. Update the values in in `app.yaml` with your instance configuration.
+
 1. Finally, run `create_tables.rb` to ensure that the database is properly
 configured and to create the tables needed for the sample.
 
 ## Running locally
 
-Refer to the [appengine/README.md](../README.md) file for instructions on
-running and deploying.
+Refer to the [top-level README](../README.md) for instructions on running and deploying.
 
-To run locally, set the environment variables via your shell before running the
-sample:
+It's recommended to follow the instructions above to run the Cloud SQL proxy.
+You will need to set the following environment variables via your shell before
+running the sample:
 
-    export MYSQL_HOST=<your-cloudsql-host>
-    export MYSQL_USER=<your-cloudsql-user>
-    export MYSQL_PASSWORD=<your-cloudsql-password>
-    export MYSQL_DATABASE=<your-cloudsql-database>
+    export MYSQL_USER="YOUR_USER"
+    export MYSQL_PASSWORD="YOUR_PASSWORD"
+    export MYSQL_SOCKET_PATH="YOUR_SOCKET_PATH"
+    export MYSQL_DATABASE="YOUR_DATABASE"
     bundle install
     bundle exec ruby create_tables.rb
     bundle exec ruby app.rb
+
+[sql]: https://cloud.google.com/sql/
+[flexible]: https://cloud.google.com/appengine
+[gen]: https://cloud.google.com/sql/docs/create-instance
+[console]: https://console.developers.google.com
+[sdk]: https://cloud.google.com/sdk
+[service]: https://cloud.google.com/sql/docs/external#createServiceAccount
+[proxy]: https://cloud.google.com/sql/docs/external#install
+[start]: https://cloud.google.com/sql/docs/external#6_start_the_proxy
+[user]: https://cloud.google.com/sql/docs/create-user
+[database]: https://cloud.google.com/sql/docs/create-database

appengine/cloudsql/app.rb

@@ -17,10 +17,10 @@
 require "sinatra"
 require "sequel"
 
-DB = Sequel.mysql2 host: ENV["MYSQL_HOST"],
-                   user: ENV["MYSQL_USER"],
+DB = Sequel.mysql2 user:     ENV["MYSQL_USER"],
                    password: ENV["MYSQL_PASSWORD"],
-                   database: ENV["MYSQL_DATABASE"]
+                   database: ENV["MYSQL_DATABASE"],
+                   socket:   ENV["MYSQL_SOCKET"]
 
 get "/" do
   # Save visit in database

appengine/cloudsql/app.yaml

@@ -18,10 +18,17 @@ entrypoint: bundle exec ruby app.rb -p $PORT
 
 # [START env_variables]
 env_variables:
-  # Replace user, password, and host with the values obtained when
-  # configuring your Cloud SQL instance.
-  MYSQL_HOST: <your-cloudsql-host>
-  MYSQL_USER: <your-cloudsql-user>
-  MYSQL_PASSWORD: <your-cloudsql-password>
-  MYSQL_DATABASE: <your-cloudsql-database>
+  MYSQL_USER: [YOUR_USER]
+  MYSQL_PASSWORD: [YOUR_PASSWORD]
+  MYSQL_DATABASE: [YOUR_DATABASE]
+  # This path was printed to the console when you started the proxy, and is of
+  # the format: `/[DIR]/[YOUR_PROJECT_ID]:[YOUR_REGION]:[YOUR_INSTANCE_NAME]`
+  MYSQL_SOCKET_PATH: [YOUR_SOCKET_PATH]
 # [END env_variables]
+
+# [START cloudsql_settings]
+beta_settings:
+  # The connection name of your instance on its Overview page in the Google
+  # Cloud Platform Console, or use `[YOUR_PROJECT_ID]:[YOUR_REGION]:[YOUR_INSTANCE_NAME]`
+  cloud_sql_instances: [YOUR_INSTANCE_CONNECTION_NAME]
+# [END cloudsql_settings]

appengine/cloudsql/create_tables.rb

@@ -15,10 +15,10 @@
 # [START all]
 require "sequel"
 
-DB = Sequel.mysql2 host: ENV["MYSQL_HOST"],
-                   user: ENV["MYSQL_USER"],
+DB = Sequel.mysql2 user:     ENV["MYSQL_USER"],
                    password: ENV["MYSQL_PASSWORD"],
-                   database: ENV["MYSQL_DATABASE"]
+                   database: ENV["MYSQL_DATABASE"],
+                   socket:   ENV["MYSQL_SOCKET"]
 
 DB.create_table :visits do
   primary_key :id

appengine/cloudsql/spec/cloudsql_spec.rb

@@ -24,10 +24,10 @@
     app_yaml = File.expand_path("../../app.yaml", __FILE__)
 
     configuration = File.read(app_yaml)
-    configuration.sub! "<your-cloudsql-host>", ENV["MYSQL_HOST"]
-    configuration.sub! "<your-cloudsql-user>", ENV["MYSQL_USER"]
-    configuration.sub! "<your-cloudsql-password>", ENV["MYSQL_PASSWORD"]
-    configuration.sub! "<your-cloudsql-database>", ENV["MYSQL_DATABASE"]
+    configuration.sub! "[YOUR_USER]",        ENV["MYSQL_USER"]
+    configuration.sub! "[YOUR_PASSWORD]",    ENV["MYSQL_PASSWORD"]
+    configuration.sub! "[YOUR_DATABASE]",    ENV["MYSQL_DATABASE"]
+    configuration.sub! "[YOUR_SOCKET_PATH]", ENV["MYSQL_SOCKET_PATH"]
 
     File.write(app_yaml, configuration)