Utiliser Cloud SQL pour PostgreSQL avec Rails 7 sur App Engine

Commencez à développer des applications Ruby on Rails qui s'exécutent dans l'environnement flexible App Engine. Les applications créées sont exécutées sur l'infrastructure sur laquelle sont basés tous les produits Google, vous avez la garantie d'un dimensionnement efficace, à même de desservir l'ensemble de vos utilisateurs, qu'ils soient une poignée ou plusieurs millions.

Dans ce tutoriel, nous partons du principe que vous connaissez bien le développement Web avec Rails. Il vous explique comment configurer Cloud SQL pour PostgreSQL avec une nouvelle application Rails. Vous pouvez également utiliser ce tutoriel comme référence pour la configuration d'applications Rails existantes afin d'utiliser Cloud SQL pour PostgreSQL.

Ce tutoriel est compatible avec Ruby 3.0 ou une version ultérieure, et nécessite cette version.

Avant de commencer

  1. Connectez-vous à votre compte Google Cloud . Si vous débutez sur Google Cloud, créez un compte pour évaluer les performances de nos produits en conditions réelles. Les nouveaux clients bénéficient également de 300 $de crédits sans frais pour exécuter, tester et déployer des charges de travail.

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

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

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

  5. Installez la Google Cloud CLI.

  6. Si vous utilisez un fournisseur d'identité (IdP) externe, vous devez d'abord vous connecter à la gcloud CLI avec votre identité fédérée.

  7. Pour initialiser la gcloud CLI, exécutez la commande suivante : 

    gcloud init

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

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

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

  11. Installez la Google Cloud CLI.

  12. Si vous utilisez un fournisseur d'identité (IdP) externe, vous devez d'abord vous connecter à la gcloud CLI avec votre identité fédérée.

  13. Pour initialiser la gcloud CLI, exécutez la commande suivante : 

    gcloud init

Préparer une instance Cloud SQL pour PostgreSQL

Configurez une instance Cloud SQL pour PostgreSQL pour ce tutoriel.

  1. Créez une instance PostgreSQL. Dans le cadre de ce tutoriel, le nom de l'instance est rails-cloudsql-instance.

  2. Créez une base de données dans l'instance. Dans le cadre de ce tutoriel, le nom de la base de données de production est cat_list_production.

  3. Définissez le mot de passe utilisateur postgres pour l'instance.

Configurer votre environnement local pour Rails

Pour configurer votre environnement local pour ce tutoriel, procédez comme suit :

  1. Installez Ruby version 3.0 ou ultérieure.

  2. Installez le gem Rails 7.

  3. Installez le gem Bundler.

Pour obtenir plus d'informations sur l'installation de Rails et de ses dépendances, reportez-vous au guide officiel Getting started with Rails.

Une fois les conditions préalables remplies, vous pouvez créer et déployer une application Rails à l'aide de Cloud SQL pour PostgreSQL. Les sections suivantes vous guident dans la configuration, la connexion à Cloud SQL pour PostgreSQL et le déploiement d'une application.

Créer une application pour répertorier des chats

  1. Exécutez la commande rails new pour créer une application Rails. Cette application stocke une liste de chats dans Cloud SQL pour PostgreSQL.

    rails new cat_sample_app

  2. Accédez au répertoire contenant l'application Rails générée.

    cd cat_sample_app

Exécuter l'application en local

Pour exécuter la nouvelle application Rails sur votre ordinateur local :

  1. Démarrez un serveur Web local :

    bundle exec bin/rails server

  2. Dans un navigateur, accédez à http://localhost:3000/

    L'application exemple affiche le logo Rails avec les versions Rails et Ruby.

Générer un scaffold (échafaudage) pour répertorier des chats

Générez un scaffold pour une ressource nommée Cat qui servira à répertorier les chats avec leur nom et leur âge.

  1. Générez le scaffold.

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

    Cette commande génère un modèle, un contrôleur et des vues pour la ressource 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. Ouvrez le fichier config/routes.rb pour voir le contenu généré, reproduit ci-dessous.

    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. Ajoutez root 'cats#index' au fichier.

    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. Enregistrez le fichier, puis fermez-le.

  5. Testez l'application Rails comme indiqué précédemment.

Utiliser Cloud SQL pour PostgreSQL avec App Engine

Cloud SQL pour PostgreSQL est un service de base de données entièrement géré qui facilite la configuration, la maintenance, la gestion et l'administration de vos bases de données relationnelles PostgreSQL dansGoogle Cloud. Vous pouvez utiliser Cloud SQL dans une application Rails comme toute autre base de données relationnelle.

Configurer Cloud SQL pour PostgreSQL

Pour commencer à utiliser Cloud SQL avec votre application Rails en production :

  1. Ajoutez les gems pg et appengine au fichier Gemfile.

    bundle add pg
bundle add appengine

    Le fichier Rails Gemfile contient les entrées gem supplémentaires suivantes :

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

  2. Pour configurer l'application Rails afin qu'elle se connecte à Cloud SQL, ouvrez le fichier config/database.yml. Les paramètres de base de données réutilisables ci-dessous, définis pour SQLite, s'affichent :

    # 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. Configurez le nom de connexion de l'instance Cloud SQL pour l'environnement de production App Engine.

    1. Récupérez le nom de connexion de l'instance.

      gcloud sql instances describe rails-cloudsql-instance

    2. Copiez la valeur en regard de connectionName.

  4. Modifiez la configuration de la base de données de production database.yml comme suit :

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

    Où :

    • [YOUR_POSTGRES_USERNAME] représente le nom d'utilisateur de votre instance Cloud SQL pour PostgreSQL.
    • [YOUR_POSTGRES_PASSWORD] représente le mot de passe de votre instance Cloud SQL pour PostgreSQL.
    • [YOUR_INSTANCE_CONNECTION_NAME] représente le nom de connexion de l'instance que vous avez copié à l'étape précédente.

L'application Rails est désormais configurée pour utiliser Cloud SQL lors du déploiement dans l'environnement flexible App Engine.

Déployer l'application dans l'environnement flexible App Engine

L'environnement flexible App Engine utilise un fichier appelé app.yaml pour décrire la configuration de déploiement d'une application. Si ce fichier est absent, gcloud CLI tente de deviner la configuration de déploiement. Cependant, vous devez définir ce fichier pour fournir les paramètres de configuration requis pour la clé secrète Rails et pour Cloud SQL.

Pour configurer l'exemple d'application en vue du déploiement sur App Engine, créez un fichier nommé app.yaml à la racine du répertoire de l'application Rails et ajoutez-y les lignes suivantes :

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

Configurer la clé secrète Rails dans le fichier app.yaml

Lorsqu'une application Rails est déployée dans l'environnement production, définissez la variable d'environnement SECRET_KEY_BASE sur une valeur de clé secrète afin de protéger les données de session des utilisateurs. Cette variable d'environnement est lue à partir du fichier config/secrets.yml dans votre application Rails.

  1. Générez une nouvelle clé secrète.

    bundle exec bin/rails secret

  2. Copiez la clé secrète générée.

  3. Ouvrez le fichier app.yaml que vous avez créé précédemment et ajoutez une section env_variables. Le fichier env_variables définit les variables d'environnement dans l'environnement flexible App Engine. Le fichier app.yaml doit alors ressembler à l'exemple suivant, la valeur de [SECRET_KEY] étant remplacée par votre clé secrète.

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

env_variables:
  SECRET_KEY_BASE: [SECRET_KEY]

Configurer l'instance Cloud SQL dans le fichier app.yaml

Ensuite, configurez l'environnement flexible App Engine pour utiliser l'instance Cloud SQL spécifiée. Pour cela, indiquez le nom de connexion de l'instance Cloud SQL dans le fichier de configuration app.yaml.

  1. Ouvrez le fichier app.yaml et ajoutez une section appelée beta_settings.

  2. Définissez un paramètre imbriqué cloud_sql_instances ayant comme valeur le nom de connexion de l'instance.

    Le fichier app.yaml doit ressembler à ceci :

    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]

Créer une application d'environnement flexible App Engine

Si vous déployez une application pour la première fois, vous devez créer une application d'environnement flexible App Engine et sélectionner la région dans laquelle vous souhaitez exécuter l'application Rails.

  1. Créez une application App Engine.

    gcloud app create

  2. Sélectionnez une région prenant en charge l'environnement flexible App Engine pour les applications Ruby. Obtenez plus d'informations sur les régions et les zones.

Déployer une nouvelle version

L'étape suivante consiste à déployer une nouvelle version de l'application Rails décrite dans le fichier app.yaml sans rediriger le trafic depuis la version de diffusion par défaut actuelle en exécutant la commande suivante :

gcloud app deploy --no-promote

Le déploiement peut prendre quelques minutes. Attendez qu'un message de réussite apparaisse. Vous pouvez afficher les versions déployées dans la liste des versions d'App Engine.

Une fois que vous avez déployé la nouvelle version, si vous tentez d'y accéder, le message d'erreur suivant s'affiche car vous n'avez pas migré la base de données.

Capture d&#39;écran du message d&#39;erreur de la nouvelle application Rails

Accorder l'autorisation d'accès au gem appengine

Ensuite, accordez l'accès au compte de service cloudbuild pour exécuter des migrations de base de données de production à l'aide du appengine.

  1. Répertoriez les projets disponibles.

    gcloud projects list

  2. Dans le résultat, recherchez le projet que vous souhaitez utiliser pour déployer votre application et copiez le numéro de projet associé.

  3. Ajoutez un membre à la stratégie IAM de votre projet afin d'autoriser le rôle roles/editor à exécuter des migrations de base de données. Remplacez PROJECT_ID par l'ID de votre projet Google Cloud et PROJECT_NUMBER par le numéro de projet que vous avez copié à l'étape précédente.

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

Migrer votre base de données Rails

Les migrations de base de données Rails permettent de mettre à jour le schéma de votre base de données sans utiliser directement la syntaxe SQL. Vous allez ensuite migrer votre base de données cat_list_production.

Le gem appengine fournit la tâche Rake appengine:exec qui permet d'exécuter une commande sur la dernière version déployée pour votre application dans l'environnement flexible App Engine de production.

  1. Migrez en production la base de données cat_list_production Cloud SQL pour PostgreSQL.

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

    Un résultat semblable à celui-ci s'affiche :

    ---------- 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. Pour valider la migration de la base de données, saisissez l'URL suivante dans votre navigateur :

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

    Remplacez les éléments suivants :

    • VERSION_ID : nouvelle version de l'application que vous avez déployée précédemment. Pour obtenir la liste des versions, utilisez la commande gcloud app versions list. Le dernier élément default de version de service correspond au déploiement le plus récent.
    • PROJECT_ID : ID de votre projet Google Cloud
    • REGION_ID : code attribué par App Engine à votre application

Si le déploiement a réussi, les éléments suivants s'affichent :

Capture d&#39;écran de la nouvelle application Rails en cours d&#39;exécution

Migrer le trafic vers une nouvelle version

Enfin, dirigez le trafic vers la version nouvellement déployée à l'aide de la commande suivante :

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

La nouvelle version de l'application est désormais accessible à travers l'URL suivante :

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

Lire les journaux App Engine

Maintenant que vous avez déployé votre application Rails, vous souhaiterez peut-être en consulter les journaux. Vous pouvez lire les journaux d'application à l'aide de l'explorateur de journaux disponible dans la console Google Cloud .

Pour en savoir plus sur la lecture des journaux à l'aide de la gcloud CLI.

Effectuer un nettoyage des ressources

Une fois le tutoriel terminé, vous pouvez procéder au nettoyage des ressources que vous avez créées afin qu'elles ne soient plus comptabilisées dans votre quota et qu'elles ne vous soient plus facturées. Dans les sections suivantes, nous allons voir comment supprimer ou désactiver ces ressources.

Supprimer le projet

Le moyen le plus simple d'empêcher la facturation est de supprimer le projet que vous avez créé pour ce tutoriel.

Pour supprimer le projet :

  1. Dans la console Google Cloud , accédez à la page Gérer les ressources.

    Accéder à la page "Gérer les ressources"

  2. Dans la liste des projets, sélectionnez le projet que vous souhaitez supprimer, puis cliquez sur Supprimer.
  3. Dans la boîte de dialogue, saisissez l'ID du projet, puis cliquez sur Arrêter pour supprimer le projet.

Supprimer une version App Engine

Pour supprimer une version d'application :

  1. Dans la console Google Cloud , accédez à la page Versions pour App Engine.

    Accéder à la page "Versions"

  2. Cochez la case correspondant à la version de l'application autre que celle par défaut que vous souhaitez supprimer.
  3. Pour supprimer la version de l'application, cliquez sur  Supprimer.

Supprimer une instance Cloud SQL

Pour supprimer une instance Cloud SQL :

  1. Dans la console Google Cloud , accédez à la page Instances.

    Accéder à la page "Instances"

  2. Cliquez sur le nom de l'instance SQL que vous souhaitez supprimer.
  3. Pour supprimer l'instance, cliquez sur Supprimer , puis suivez les instructions.

Étapes suivantes