Get started developing Ruby on Rails apps that run on the App Engine flexible environment. The apps you create run on the same infrastructure that powers all of Google's products, so you can be confident that they can scale to serve all of your users, whether there are a few or millions of them.
This tutorial assumes you are familiar with Rails web development. It walks you through setting up Cloud SQL for MySQL with a new Rails app. You can also use this tutorial as a reference for configuring existing Rails apps to use Cloud SQL for MySQL.
This tutorial supports and requires Ruby 3.0 or later.
Before you begin
- Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
-
Enable the Cloud SQL Admin API.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
-
Enable the Cloud SQL Admin API.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
Preparing Cloud SQL for a MySQL instance
To set up Cloud SQL for a MySQL instance for this tutorial:
Create a Second Generation instance. In this tutorial the name for the instance is
rails-cloudsql-instance
.Create a database in the instance. In this tutorial the name for the production database is
cat_list_production
.
Setting up your local environment for Rails
To set up your local environment for this tutorial:
For additional information on installing Rails and its dependencies, see the official Getting started with Rails guide.
After you complete the prerequisites, you can create and deploy a Rails app using Cloud SQL for MySQL. The following sections guide you through configuring, connecting to Cloud SQL for MySQL, and deploying an app.
Create a new app to list cats
Run the
rails new
command to create a new Rails app. This app stores a list of cats in Cloud SQL for MySQL.rails new cat_sample_app
You might also need to install mysql libraries for mysql gems using a command like the following example:
sudo apt-get install libmysqlclient-dev
Go to the directory that contains the generated Rails app.
cd cat_sample_app
Run the application locally
To run the new Rails application on your local computer:
Start a local web server:
bundle exec bin/rails server
In a web browser, go to http://localhost:3000/
The sample app displays the Rails logo with the Rails and Ruby versions.
Generate scaffolding for a list of cats
Generate scaffolding for a resource named Cat
that is used to form a list
of cats with their name and age.
Generate the scaffolding.
bundle exec rails generate scaffold Cat name:string age:integer
The command generates a model, controller, and views for the
Cat
resource.invoke active_record create db/migrate/20230922063608_create_cats.rb create app/models/cat.rb invoke test_unit create test/models/cat_test.rb create test/fixtures/cats.yml invoke resource_route route resources :cats invoke scaffold_controller create app/controllers/cats_controller.rb invoke erb create app/views/cats create app/views/cats/index.html.erb create app/views/cats/edit.html.erb create app/views/cats/show.html.erb create app/views/cats/new.html.erb create app/views/cats/_form.html.erb create app/views/cats/_cat.html.erb invoke resource_route invoke test_unit create test/controllers/cats_controller_test.rb create test/system/cats_test.rb invoke helper create app/helpers/cats_helper.rb invoke test_unit invoke jbuilder create app/views/cats/index.json.jbuilder create app/views/cats/show.json.jbuilder create app/views/cats/_cat.json.jbuilder
Open the
config/routes.rb
file to see the following generated content.Add
root 'cats#index'
to the file.Save the file and close it.
Test the Rails app as instructed before.
Using Cloud SQL for MySQL with App Engine
Cloud SQL for MySQL is a fully managed database service to set up, maintain, manage, and administer your relational MySQL databases in Google Cloud. You can use Cloud SQL in a Rails app like any other relational database.
Set up Cloud SQL for MySQL
To begin using Cloud SQL with your Rails app in production:
Add the
mysql2
andappengine
gems to theGemfile
file.bundle add mysql2 bundle add appengine
The Rails
Gemfile
contains the following additionalgem
entries:To configure the Rails app to connect to Cloud SQL, open the
config/database.yml
file. The following boilerplate database settings for SQLite are displayed:Configure the Cloud SQL instance connection name for the App Engine production environment.
Retrieve the instance connection name.
gcloud sql instances describe rails-cloudsql-instance
Copy the value next to
connectionName
.
Modify the
database.yml
production database configuration to the following:Where:
[YOUR_MYSQL_USERNAME]
represents your MySQL username.[YOUR_MYSQL_PASSWORD]
represents your MySQL password.[YOUR_INSTANCE_CONNECTION_NAME]
represents the instance connection name that you copied in the previous step.
The Rails app is now set up to use Cloud SQL when deploying to the App Engine flexible environment.
Deploying the app to the App Engine flexible environment
The App Engine flexible environment uses a file called
app.yaml
to describe an app's deployment configuration. If this file isn't
present, the gcloud CLI tries to guess the deployment configuration.
However, you should define the file to provide required configuration settings
for the Rails secret key and Cloud SQL.
To configure the sample app for deployment to App Engine, create a new
file named app.yaml
at the root of the Rails application directory and add
the following:
Configure the Rails secret key in the app.yaml
file
When a Rails app is deployed to the production
environment, set the
environment variable SECRET_KEY_BASE
with a secret key to protect user
session data. This environment variable is read from the config/secrets.yml
file in your Rails app.
Generate a new secret key.
bundle exec bin/rails secret
Copy the generated secret key.
Open the
app.yaml
file that you created earlier, and add anenv_variables
section. Theenv_variables
defines environment variables in the App Engine flexible environment. Theapp.yaml
file should look similar to the following example with[SECRET_KEY]
replaced with your secret key.
Configure the Cloud SQL instance in the app.yaml
file
Next, configure the App Engine flexible environment to use a specified
Cloud SQL instance by providing the Cloud SQL instance
connection name in the app.yaml
configuration file.
Open the
app.yaml
file, and add a new section namedbeta_settings
.Define a nested parameter
cloud_sql_instances
with the instance connection name as the value.The
app.yaml
should look similar to the following:
Create an App Engine flexible environment app
If this is the first time you are deploying an app, you need to create an App Engine flexible environment app and select the region where you want to run the Rails app.
Create an App Engine app.
gcloud app create
Select a region that supports App Engine flexible environment for Ruby apps. Read more about Regions and zones.
Deploy a new version
Next, deploy a new version of the Rails app described in the app.yaml
file
without redirecting traffic from the current default serving version.
Precompile the Rails assets.
bundle exec bin/rails assets:precompile
After the assets finish compiling, deploy a new version of the app.
gcloud app deploy --no-promote
It can take several minutes to finish the deployment. Wait for a success message. You can view deployed versions in the App Engine version list.
After you deploy the new version, if you attempt to access this new version, it shows the following error message because you haven't migrated the database.
Grant required permission for the appengine
gem
Next, grant access to the cloudbuild service account to run production database
migrations with the appengine
gem.
List available projects.
gcloud projects list
In the output, find the project you want to use to deploy your app, and copy the project number.
Add a new member to your project IAM policy for the role
roles/editor
to run database migrations. ReplacePROJECT_ID
with your Google Cloud project ID and replacePROJECT_NUMBER
with the project number you copied in the previous step.gcloud projects add-iam-policy-binding PROJECT_ID \ --member=serviceAccount:PROJECT_NUMBER@cloudbuild.gserviceaccount.com \ --role=roles/editor
Migrate your Rails database
Rails database migrations are used to update the schema of your database without
using SQL syntax directly. Next you migrate your cat_list_production
database.
The appengine
gem provides the Rake task appengine:exec
to run a command
against the most recent deployed version of your app in the production
App Engine flexible environment.
Migrate the Cloud SQL for MySQL
cat_list_production
database in production.bundle exec rake appengine:exec -- bundle exec rake db:migrate
You should see output similar to:
---------- EXECUTE COMMAND ---------- bundle exec rake db:migrate Debuggee gcp:787021104993:8dae9032f8b02004 successfully registered == 20230922063608 CreateCats: migrating ======================================= -- create_table(:cats) -> 0.0219s == 20230922063608 CreateCats: migrated (0.0220s) ============================== ---------- CLEANUP ----------
To verify the database migration, go to:
VERSION-dot-PROJECT_ID.appspot.com
The following is displayed for a successful deployment:
Migrate traffic to new version
Finally, direct traffic to your newly deployed version by using the following command:
gcloud app services set-traffic default --splits VERSION=1
The new version of the app is now accessible from:
https://PROJECT_ID.appspot.com
Reading App Engine logs
Now that you have deployed your Rails app, you might want to read the logs. You can read the app logs by using the Logs Explorer located in the Google Cloud console.
You can learn more about reading logs using the gcloud CLI.
Clean up resources
After you finish the tutorial, you can clean up the resources that you created so that they stop using quota and incurring charges. The following sections describe how to delete or turn off these resources.
Delete project
The easiest way to eliminate billing is to delete the project that you created for the tutorial.
To delete the project:
- In the Google Cloud console, go to the Manage resources page.
- In the project list, select the project that you want to delete, and then click Delete.
- In the dialog, type the project ID, and then click Shut down to delete the project.
Delete an App Engine version
To delete an app version:
- In the Google Cloud console, go to the Versions page for App Engine.
- Select the checkbox for the non-default app version that you want to delete.
- To delete the app version, click Delete.
Delete a Cloud SQL instance
To delete a Cloud SQL instance:
- In the Google Cloud console, go to the Instances page.
- Click the name of the SQL instance you that want to delete.
- To delete the instance, click Delete, and then follow the instructions.