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

開始開發在 App Engine 彈性環境上執行的 Ruby on Rails 應用程式。您所建立的應用程式，使用的正是所有 Google 產品採用的基礎架構，因此您可以放心，無論使用者只有幾人還是有數百萬人，應用程式都可調度資源，為所有使用者提供服務。

本教學課程假設您已熟悉 Rails 網路開發流程，並逐步引導您設定 PostgreSQL 適用的 Cloud SQL 和一個新的 Rails 應用程式。您也可以使用本教學課程做為參考資料，來設定現有的 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.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

安裝 Google Cloud CLI。

若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

執行下列指令，初始化 gcloud CLI：

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.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

安裝 Google Cloud CLI。

若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

執行下列指令，初始化 gcloud CLI：

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。

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

如要進一步瞭解如何安裝 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 的資源產生 Scaffolding。

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」(執行個體) 頁面。

   前往「Instances」(執行個體)

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

後續步驟

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

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

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