在 App Engine 上將 PostgreSQL 適用的 Cloud SQL 與 Rails 7 搭配使用

開始開發在 App Engine 彈性環境中執行的 Ruby on Rails 應用程式。您建立的應用程式與所有 Google 產品採用相同的基礎架構，因此無論使用者人數多寡，都能放心擴大規模，為所有使用者提供服務。

本教學課程假設您熟悉 Rails 網頁程式開發人員。本教學課程將逐步說明如何使用新的 Rails 應用程式設定 PostgreSQL 適用的 Cloud SQL。您也可以參考本教學課程，設定現有的 Rails 應用程式，以便使用 PostgreSQL 適用的 Cloud SQL。

本教學課程支援並需要 Ruby 3.0 以上版本。

事前準備

登入 Google Cloud 帳戶。如果您是 Google Cloud新手，歡迎 建立帳戶，親自體驗產品的實際應用成效。新客戶還能獲得價值 $300 美元的免費抵免額，能用於執行、測試及部署工作負載。

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud SQL Admin API, if it is not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the API

Install the Google Cloud CLI.

If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

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.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud SQL Admin API, if it is not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the API

Install the Google Cloud CLI.

If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

To initialize the gcloud CLI, run the following command:

gcloud init

準備 PostgreSQL 適用的 Cloud SQL 執行個體

為本教學課程設定 PostgreSQL 適用的 Cloud SQL 執行個體。

1. 建立 PostgreSQL 執行個體。在本教學課程中，執行個體的名稱為 rails-cloudsql-instance。

2. 在執行個體中建立資料庫。在本教學課程中，正式資料庫的名稱為 cat_list_production。

3. 設定執行個體的 postgres 使用者密碼。

設定本機環境以使用 Rails

為本教學課程設定本機環境：

1. 安裝 Ruby 3.0 以上版本。

2. 安裝 Rails 7 Gem。

3. 安裝 Bundler Gem。

注意： 您也可以使用 Cloud Shell，其中已預先安裝 Ruby、Rails、Bundler 和 Google Cloud CLI。

如要進一步瞭解如何安裝 Rails 及其依附元件，請參閱官方的「Rails 入門指南」。

完成上述前置步驟後，就能使用 PostgreSQL 適用的 Cloud SQL 建立及部署 Rails 應用程式。以下各節將逐步引導您進行應用程式設定、連結至 PostgreSQL 適用的 Cloud SQL，以及部署應用程式。

建立新應用程式來列出貓咪

1. 執行 rails new 指令，建立新的 Rails 應用程式。這個應用程式會將貓咪清單儲存在 PostgreSQL 適用的 Cloud SQL。

   rails new cat_sample_app
   

2. 前往產生的 Rails 應用程式所屬的目錄。

   cd cat_sample_app
   

在本機執行應用程式

如何在本機電腦上執行新的 Rails 應用程式：

1. 啟動本機網路伺服器：

   bundle exec bin/rails server
   

2. 透過瀏覽器前往 http://localhost:3000/

   範例應用程式會顯示 Rails 標誌，以及 Rails 和 Ruby 版本。

注意： 在終端機視窗中，按下 Ctrl+C 鍵即可結束網路伺服器。

為貓咪清單產生鷹架

產生名為 Cat 的資源的架構，用於建立貓咪清單，並顯示貓咪名稱和年齡。

1. 產生 Scaffolding。

   bundle exec rails generate scaffold Cat name:string age:integer
   

   這個指令會為 Cat 資源產生模型、控制器和檢視畫面。

   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
   

2. 開啟 config/routes.rb 檔案，查看下列生成的內容。

   Rails.application.routes.draw do
     resources :cats
     get 'cats/index'
     # For details on the DSL available within this file, see http://guides.rubyonrails.org/routing.html
   
   end

3. 將 root 'cats#index' 新增至檔案。

   Rails.application.routes.draw do
     resources :cats
     get 'cats/index'
   
     # For details on the DSL available within this file, see http://guides.rubyonrails.org/routing.html
     root 'cats#index'
   end

4. 儲存並關閉檔案。

5. 依先前的指示測試 Rails 應用程式。

將 PostgreSQL 適用的 Cloud SQL 搭配使用 App Engine

PostgreSQL 適用的 Cloud SQL 是一項全代管資料庫服務，可協助您在Google Cloud中設定、維護及管理 PostgreSQL 關聯資料庫。您可以在 Rails 應用程式中使用 Cloud SQL，就跟其他關聯式資料庫一樣。

設定 PostgreSQL 適用的 Cloud SQL

如要開始在實際工作環境中搭配 Rails 應用程式使用 Cloud SQL：

1. 將 pg 和 appengine Gem 新增至 Gemfile 檔案。

   bundle add pg
   bundle add appengine
   

   Rails Gemfile 包含下列額外 gem 項目：

   gem "appengine", "~> 0.6"
   gem "pg", "~> 1.2"

   注意： appengine Gem 提供 Rake 工作，可在正式環境中執行資料庫遷移作業。

2. 如要設定 Rails 應用程式連線至 Cloud SQL，請開啟 config/database.yml 檔案。系統會顯示下列 SQLite 的樣板資料庫設定：

   # SQLite version 3.x
   #   gem install sqlite3
   #
   #   Ensure the SQLite 3 gem is defined in your Gemfile
   #   gem 'sqlite3'
   #
   default: &default
     adapter: sqlite3
     pool: 5
     timeout: 5000
   
   development:
     <<: *default
     database: db/development.sqlite3
   
   # Warning: The database defined as "test" will be erased and
   # re-generated from your development database when you run "rake".
   # Do not set this db to the same as development or production.
   test:
     <<: *default
     database: db/test.sqlite3
   
   production:
     <<: *default
     database: db/production.sqlite3

3. 為 App Engine 正式環境設定 Cloud SQL 執行個體連線名稱。

   1. 擷取執行個體連線名稱。

      gcloud sql instances describe rails-cloudsql-instance
      

   2. 複製 connectionName 旁邊的值。

4. 將 database.yml 正式環境資料庫設定修改為下列項目：

   production:
     adapter: postgresql
     encoding: unicode
     pool: 5
     timeout: 5000
     username: "[YOUR_POSTGRES_USERNAME]"
     password: "[YOUR_POSTGRES_PASSWORD]"
     database: "cat_list_production"
     host:   "/cloudsql/[YOUR_INSTANCE_CONNECTION_NAME]"

   其中：

   • [YOUR_POSTGRES_USERNAME] 代表 PostgreSQL 適用的 Cloud SQL 執行個體使用者名稱。
   • [YOUR_POSTGRES_PASSWORD] 代表 PostgreSQL 適用的 Cloud SQL 執行個體密碼。
   • [YOUR_INSTANCE_CONNECTION_NAME] 是您在上一個步驟中複製的執行個體連線名稱。

Rails 應用程式現已設定完畢，並會在部署至 App Engine 彈性環境時使用 Cloud SQL。

將應用程式部署至 App Engine 彈性環境

App Engine 彈性環境會使用名為 app.yaml 的檔案，描述應用程式的部署設定。如果沒有這個檔案，gcloud CLI 會嘗試推測部署設定。不過，您應定義檔案，為 Rails 密鑰和 Cloud SQL 提供必要的設定。

如要設定範例應用程式，以便部署至 App Engine，請在 Rails 應用程式目錄的根目錄中建立名為 app.yaml 的新檔案，然後新增下列內容：

entrypoint: bundle exec rackup --port $PORT
env: flex
runtime: ruby

在 app.yaml 檔案中設定 Rails 密鑰

將 Rails 應用程式部署至 production 環境時，請使用密鑰設定環境變數 SECRET_KEY_BASE，保護使用者工作階段資料。這個環境變數會從 Rails 應用程式中的 config/secrets.yml 檔案讀取。

1. 產生新密鑰。

   bundle exec bin/rails secret
   

2. 複製產生的密鑰。

3. 開啟先前建立的 app.yaml 檔案，並新增 env_variables 區段。env_variables 可在 App Engine 彈性環境中定義環境變數。app.yaml 檔案應與下列範例類似，並將 [SECRET_KEY] 換成您的密鑰。

   entrypoint: bundle exec rackup --port $PORT
   env: flex
   runtime: ruby
   
   env_variables:
     SECRET_KEY_BASE: [SECRET_KEY]

在 app.yaml 檔案中設定 Cloud SQL 執行個體

接著，在 app.yaml 設定檔中提供 Cloud SQL 執行個體連線名稱，設定 App Engine 彈性環境以使用指定的 Cloud SQL 執行個體。

1. 開啟 app.yaml 檔案，並新增名為 beta_settings 的區段。

2. 定義巢狀參數 cloud_sql_instances，並將執行個體連線名稱設為值。

   注意： 您可以執行 gcloud sql instances describe rails-cloudsql-instance，擷取 Cloud SQL 執行個體連線名稱。

   app.yaml 應如下所示：

   entrypoint: bundle exec rackup --port $PORT
   env: flex
   runtime: ruby
   
   env_variables:
     SECRET_KEY_BASE: [SECRET_KEY]
   
   beta_settings:
     cloud_sql_instances: [YOUR_INSTANCE_CONNECTION_NAME]

建立 App Engine 彈性環境應用程式

如果您是第一次部署應用程式，請建立 App Engine 彈性環境應用程式，並選取要執行 Rails 應用程式的區域。

1. 建立 App Engine 應用程式。

   gcloud app create
   

2. 選取支援 Ruby 應用程式的 App Engine 彈性環境區域。進一步瞭解地區和區域。

部署新版本

接著，請執行下列指令，部署 app.yaml 檔案中描述的 Rails 應用程式新版本，但不要將流量從目前的預設服務版本重新導向：

gcloud app deploy --no-promote

完成部署可能需要幾分鐘時間。請等待系統顯示成功訊息。您可以在 App Engine 版本清單中查看已部署的版本。

警告： 舊版應用程式及其相關聯的 VM 執行個體仍會保留。請注意，所有這些應用程式版本和 VM 執行個體都是計費資源。

如果您在部署新版本之後嘗試存取這個新版本，會因為您尚未遷移資料庫而看到以下錯誤訊息。

授予 appengine Gem 的必要權限

接著，授予 cloudbuild 服務帳戶存取權，以便使用 appengine gem 執行正式資料庫遷移作業。

1. 列出可用的專案。

   gcloud projects list
   

2. 在輸出中，找出您要用於部署應用程式的專案，然後複製該專案編號。

3. 在專案 IAM 政策中新增角色 roles/editor 的成員，以執行資料庫遷移作業。將 PROJECT_ID 替換為 Google Cloud 專案 ID，並將 PROJECT_NUMBER 替換為您在上一個步驟中複製的專案編號。

   gcloud projects add-iam-policy-binding PROJECT_ID \
     --member=serviceAccount:[e-mail] \
     --role=roles/editor
   

遷移您的 Rails 資料庫

您可以遷移 Rails 資料庫來更新資料庫結構定義，而不直接使用 SQL 語法。接著遷移 cat_list_production資料庫。

appengine gem 提供 Rake 工作 appengine:exec，可針對正式版 App Engine 彈性環境中最新部署的應用程式版本執行指令。

1. 遷移正式環境中的 PostgreSQL 適用的 Cloud SQL cat_list_production 資料庫。

   bundle exec rake appengine:exec -- bundle exec rake db:migrate
   

   畫面會顯示類似以下的輸出：

   ---------- 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 ----------
   

   注意： 嘗試執行資料庫遷移作業時，如果發生權限錯誤，請確認 [e-mail] 具有 roles/editor 角色。

2. 如要驗證資料庫遷移作業，請在瀏覽器中輸入下列網址：

   https://VERSION_ID-dot-PROJECT_ID.REGION_ID.r.appspot.com
   

   更改下列內容：

   • VERSION_ID：先前部署的新版應用程式。 如要取得版本清單，請使用 gcloud app versions list。最後一個預設服務版本項目是最新部署項目。
   • PROJECT_ID：您的 Google Cloud 專案 ID
   • REGION_ID：App Engine 指派給應用程式的代碼

如果部署成功，畫面將顯示如下：

將流量遷移至新版本

最後，使用以下指令將流量導向新部署的版本：

gcloud app services set-traffic default --splits VERSION=1

您現在可以透過下列網址存取新版應用程式：

https://PROJECT_ID.REGION_ID.r.appspot.com

讀取 App Engine 記錄

Rails 應用程式現已部署完畢，接下來您可能會想讀取記錄。您可以使用 Google Cloud 控制台中的「Logs Explorer」讀取應用程式記錄。

如要進一步瞭解如何使用 gcloud CLI 讀取記錄，請參閱這篇文章。

清除所用資源

完成教學課程後，您可以清除所建立的資源，這樣資源就不會繼續使用配額，也不會產生費用。下列各節將說明如何刪除或關閉這些資源。

刪除專案

如要避免付費，最簡單的方法就是刪除您為了本教學課程所建立的專案。

刪除專案的方法如下：

警告：刪除專案會造成以下影響：

• 專案中的所有內容都會遭到刪除。如果使用現有專案來進行本文中的任務，刪除專案將一併移除當中已完成的其他任務'。
• 自訂專案 ID 會消失。當您之前建立這個專案時，可能建立了想要在日後使用的自訂專案 ID。如要保留使用該專案 ID 的網址 (例如 appspot.com 網址)，請刪除在該專案中選取的資源，而不是刪除整個專案。

如果打算探索多種架構、教學課程或快速入門導覽課程，重複使用專案可避免超出專案配額限制。

1. 前往 Google Cloud 控制台的「Manage resources」(管理資源) 頁面。

   前往「Manage resources」(管理資源)

2. 在專案清單中選取要刪除的專案，然後點選「Delete」(刪除)。
3. 在對話方塊中輸入專案 ID，然後按一下 [Shut down] (關閉) 以刪除專案。

刪除 App Engine 版本

若要刪除應用程式版本：

1. 在 Google Cloud 控制台中，前往 App Engine 的「Versions」(版本) 頁面。

   前往「版本」

2. 找出要刪除的非預設應用程式版本，然後勾選對應的核取方塊。
   注意： 如要刪除 App Engine 應用程式的預設版本，唯一方法是刪除專案。不過，您可以在 Google Cloud 控制台中停止預設版本。這麼做會關閉所有與該版本相關的執行個體。稍後如有需要，您可以重新啟動這些執行個體。

   在 App Engine 標準環境中，只有在應用程式採用手動或基本資源調度時，才能停止預設版本。

3. 如要刪除應用程式版本，請按一下 「刪除」。

刪除 Cloud SQL 執行個體

如要刪除 Cloud SQL 執行個體：

1. 前往 Google Cloud 控制台的「Instances」(執行個體) 頁面。

   前往「執行個體」頁面

2. 按一下要刪除的 SQL 執行個體名稱。
3. 如要刪除執行個體，請依序點選 和「Delete」(刪除)，然後按照指示操作。

後續步驟

• 瞭解如何在 App Engine 彈性環境中執行 Ruby Bookshelf 範例應用程式。

• 瞭解如何在 Compute Engine 中執行 Ruby Bookshelf 範例應用程式。

• 瞭解如何在 Google Kubernetes Engine 中執行 Ruby Bookshelf 範例應用程式。