שימוש ב-Cloud SQL ל-PostgreSQL עם Rails 7 ב-App Engine

איך מתחילים לפתח אפליקציות Ruby on Rails שפועלות בסביבה גמישה ב-App Engine. האפליקציות שאתם יוצרים פועלות על אותה תשתית שמפעילה את כל המוצרים של Google, כך שאתם יכולים להיות בטוחים שהן יכולות להתאים את עצמן לכל המשתמשים שלכם, בין אם יש לכם כמה משתמשים או מיליונים.

המדריך הזה מניח שאתם מכירים את פיתוח האתרים ב-Rails. במדריך מוסבר איך להגדיר את Cloud SQL ל-PostgreSQL באפליקציית Rails חדשה. אתם יכולים להשתמש במדריך גם כחומר עזר להגדרת אפליקציות Rails קיימות לשימוש ב-Cloud SQL ל-PostgreSQL.

המדריך הזה תומך ב-Ruby 3.0 ואילך, ודורש את הגרסה הזו.

לפני שמתחילים

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

    Go to project selector

  2. Verify that billing is enabled for your Google Cloud project.

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

  4. Install the Google Cloud CLI.

  5. Configure the gcloud CLI to use your federated identity.

    For more information, see Sign in to the gcloud CLI with your federated identity.

  6. To initialize the gcloud CLI, run the following command: 

    gcloud init

הכנת מכונה של Cloud SQL ל-PostgreSQL

הגדרת מכונה של Cloud SQL ל-PostgreSQL בשביל המדריך הזה.

  1. יוצרים מכונה של PostgreSQL. במדריך הזה, שם המכונה הוא rails-cloudsql-instance.

  2. יוצרים מסד נתונים במכונה. במדריך הזה, השם של מסד הנתונים בסביבת הייצור הוא cat_list_production.

  3. מגדירים את הסיסמה של משתמש postgres במכונה.

הגדרת הסביבה המקומית ל-Rails

כדי להגדיר את הסביבה המקומית למדריך הזה:

  1. מתקינים את Ruby בגרסה 3.0 ואילך.

  2. מתקינים את gem‏ Rails 7.

  3. מתקינים את ה-gem‏ Bundler.

מידע נוסף על התקנת Rails ויחסי התלות שלו זמין במדריך הרשמי תחילת העבודה עם Rails.

אחרי שמשלימים את הדרישות המוקדמות, יוצרים אפליקציית Rails ופורסים אותה באמצעות Cloud SQL ל-PostgreSQL. בקטעים הבאים מוסבר איך להגדיר אפליקציה, להתחבר ל-Cloud SQL ל-PostgreSQL ולפרוס את האפליקציה.

יצירת אפליקציה חדשה להצגת חתולים

  1. מריצים את הפקודה rails new כדי ליצור אפליקציית Rails חדשה. האפליקציה הזו מאחסנת רשימה של חתולים ב-Cloud SQL ל-PostgreSQL.

    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.

צור תבנית לרשימה של חתולים

צור פיגום למשאב בשם Cat שמשמש ליצירת רשימה של חתולים עם השם והגיל שלהם.

  1. יוצרים את התבנית.

    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 כמו בהוראות הקודמות.

שימוש ב-Cloud SQL ל-PostgreSQL עם App Engine

‫Cloud SQL ל-PostgreSQL הוא שירות מנוהל של מסד נתונים, שבעזרתו אפשר ליצור, לתחזק ולנהל מסדי נתונים רלציוניים של PostgreSQL ב-Google Cloud. אתם יכולים להשתמש ב-Cloud SQL באפליקציית Rails כמו בכל מסד נתונים רלציוני אחר.

הגדרת Cloud SQL ל-PostgreSQL

כדי להתחיל להשתמש ב-Cloud SQL עם אפליקציית Rails בסביבת הייצור:

  1. מוסיפים את ה-gems‏ pg ו-appengine לקובץ Gemfile.

    bundle add pg
bundle add appengine

    ה-Gemfile של Rails מכיל את הרשומות הנוספות הבאות של gem:

    gem "appengine", "~> 0.7"
gem "pg", "~> 1.5"

  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. מגדירים את שם החיבור של מכונת Cloud SQL לסביבת הייצור של App Engine.

    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] מייצג את שם המשתמש של המכונה של Cloud SQL ל-PostgreSQL.
    • ‫[YOUR_POSTGRES_PASSWORD] מייצג את הסיסמה של המכונה של Cloud SQL ל-PostgreSQL.
    • ‫[YOUR_INSTANCE_CONNECTION_NAME] מייצג את שם החיבור למכונה שהעתקתם בשלב הקודם.

עכשיו אפליקציית Rails מוגדרת להשתמש ב-Cloud SQL כשפורסים אותה בסביבה הגמישה ב-App Engine.

פריסת האפליקציה בסביבה הגמישה של App Engine

בסביבה הגמישה ב-App Engine משתמשים בקובץ שנקרא app.yaml כדי לתאר את הגדרות הפריסה של האפליקציה. אם הקובץ הזה לא קיים, ה-CLI של gcloud ינסה לנחש את הגדרות הפריסה. עם זאת, צריך להגדיר את הקובץ כדי לספק את הגדרות התצורה הנדרשות למפתח הסודי של Rails ול-Cloud SQL.

כדי להגדיר את האפליקציה לדוגמה לפריסה ב-App Engine, יוצרים קובץ חדש בשם app.yaml בתיקיית השורש של אפליקציית Rails ומוסיפים את הפרטים הבאים:

entrypoint: bundle exec rackup --port $PORT
env: flex
runtime: ruby
runtime_config:
  operating_system: "ubuntu22"

מגדירים את המפתח הסודי של Rails בקובץ app.yaml

כשפורסים אפליקציית Rails בסביבת production, צריך להגדיר את משתנה הסביבה SECRET_KEY_BASE עם מפתח סודי כדי להגן על נתוני הסשן של המשתמשים. ‫Rails קורא את משתנה הסביבה הזה בסביבה production.

  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
runtime_config:
  operating_system: "ubuntu22"

env_variables:
  SECRET_KEY_BASE: [SECRET_KEY]

הגדרת המכונה של Cloud SQL בקובץ app.yaml

בשלב הבא, מגדירים את סביבה גמישה ב-App Engine כך שתשתמש במכונה ספציפית של Cloud SQL. כדי לעשות את זה, צריך לציין את שם החיבור של המכונה של Cloud SQL בקובץ התצורה app.yaml.

  1. פותחים את הקובץ app.yaml ומוסיפים קטע חדש בשם beta_settings.

  2. מגדירים פרמטר בתצורה של עץ cloud_sql_instances עם שם החיבור של המכונה בתור הערך.

    ה-app.yaml אמור להיראות כך:

    entrypoint: bundle exec rackup --port $PORT
env: flex
runtime: ruby
runtime_config:
  operating_system: "ubuntu22"

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. בוחרים אזור שתומך בסביבה הגמישה ב-App Engine לאפליקציות Ruby. מידע נוסף על אזורים ו-zones

פריסת גרסה חדשה

בשלב הבא, מריצים את הפקודה הבאה כדי לפרוס גרסה חדשה של אפליקציית Rails שמתוארת בקובץ app.yaml, בלי להפנות את התנועה מגרסת ברירת המחדל הנוכחית:

gcloud app deploy --no-promote

הפריסה יכולה להימשך כמה דקות. מחכים להודעה שהפעולה בוצעה בהצלחה. אפשר לראות את הגרסאות שנפרסו ברשימת הגרסאות של App Engine.

אחרי שפורסים את הגרסה החדשה, אם מנסים לגשת אליה, מופיעה הודעת השגיאה הבאה כי לא העברתם את מסד הנתונים.

צילום מסך של הודעת השגיאה באפליקציית Rails החדשה

מתן ההרשאה הנדרשת ל-Gem appengine

בשלב הבא, נותנים לחשבון השירות של cloudbuild גישה להרצת העברות של מסדי נתונים בסביבת הייצור באמצעות ה-gem‏ appengine.

  1. רשימת הפרויקטים הזמינים.

    gcloud projects list

  2. בפלט, מאתרים את הפרויקט שבו רוצים להשתמש כדי לפרוס את האפליקציה ומעתיקים את מספר הפרויקט.

  3. מוסיפים חבר חדש למדיניות ה-IAM של הפרויקט לתפקיד roles/editor כדי להריץ העברות של מסדי נתונים. מחליפים את PROJECT_ID במזהה הפרויקט ב- Google Cloud , ואת PROJECT_NUMBER במספר הפרויקט שהעתקתם בשלב הקודם.

    gcloud projects add-iam-policy-binding PROJECT_ID \
  --member=serviceAccount:PROJECT_NUMBER@cloudbuild. \
  --role=roles/editor

העברת מסד הנתונים של Rails

העברות של מסדי נתונים ב-Rails משמשות לעדכון הסכימה של מסד הנתונים בלי להשתמש ישירות בתחביר SQL. בשלב הבא מעבירים את מסד הנתונים של cat_list_production.

ה-gem‏ appengine מספק את המשימה appengine:exec של Rake כדי להריץ פקודה בגרסה האחרונה של האפליקציה שנפרסה בסביבה הגמישה ב-App Engine בסביבת הייצור.

  1. מעבירים את מסד הנתונים של Cloud SQL ל-PostgreSQL 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 ----------

  2. כדי לאמת את העברת מסד הנתונים, מזינים את כתובת ה-URL הבאה בדפדפן:

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

    מחליפים את מה שכתוב בשדות הבאים:

    • ‫VERSION_ID: הגרסה החדשה של האפליקציה שפרסתם קודם. כדי לקבל רשימה של גרסאות, משתמשים ב-gcloud app versions list. הפריט האחרון של גרסת השירות default הוא הפריסה האחרונה.
    • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud
    • ‫REGION_ID: קוד ש-App Engine מקצה לאפליקציה

אם הפריסה בוצעה בהצלחה, יוצג הטקסט הבא:

צילום מסך של אפליקציית Rails חדשה שפועלת

העברת תנועה לגרסה חדשה

לבסוף, מפנים את התנועה לגרסה החדשה שנפרסה באמצעות הפקודה הבאה:

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

הגרסה החדשה של האפליקציה זמינה עכשיו בכתובת ה-URL הבאה:

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

קריאת יומנים של App Engine

אחרי שפרסתם את אפליקציית Rails, אתם יכולים לקרוא את היומנים. אפשר לקרוא את יומני האפליקציה באמצעות Logs Explorer שנמצא במסוף Google Cloud .

מידע נוסף על קריאת יומנים באמצעות ה-CLI של gcloud

מחיקת משאבים

אחרי שמסיימים את המדריך, אפשר למחוק את המשאבים שנוצרו, כדי שהם יפסיקו להשתמש במכסה ולצבור חיובים. בסעיפים הבאים מוסבר איך למחוק או להשבית את המשאבים האלו.

מחק את הפרויקט

הדרך הקלה ביותר לבטל את החיוב היא למחוק את הפרויקט שיצרתם בשביל המדריך.

כדי למחוק את הפרויקט:

  1. במסוף Google Cloud , נכנסים לדף Manage resources.

    כניסה לדף Manage resources

  2. ברשימת הפרויקטים, בוחרים את הפרויקט שרוצים למחוק ולוחצים על Delete.
  3. כדי למחוק את הפרויקט, כותבים את מזהה הפרויקט בתיבת הדו-שיח ולוחצים על Shut down.

מחיקת גרסה של App Engine

כדי למחוק גרסת אפליקציה:

  1. במסוף Google Cloud , נכנסים לדף Versions של App Engine.

    כניסה לדף Versions

  2. מסמנים את התיבה שלצד גרסת האפליקציה שלא מוגדרת כברירת מחדל ושרוצים למחוק.
  3. כדי למחוק את גרסת האפליקציה, לוחצים על Delete.

מחיקת מכונה של Cloud SQL

כדי למחוק מכונה של Cloud SQL:

  1. נכנסים לדף Instances במסוף Google Cloud .

    כניסה לדף Instances

  2. לוחצים על השם של מכונת ה-SQL שרוצים למחוק.
  3. כדי למחוק את המכונה, לוחצים על Delete ופועלים לפי ההוראות.

המאמרים הבאים