Utilizzo di Cloud SQL per PostgreSQL con Rails 7 su App Engine

Inizia a sviluppare app Ruby on Rails eseguite nell'ambiente flessibile di App Engine. Le app che crei vengono eseguite nella stessa infrastruttura su cui si basano tutti i prodotti Google, quindi sono in grado di garantire la scalabilità necessaria per adattarsi a qualsiasi numero di utenti, piccolo o grande che sia.

Questo tutorial presuppone che tu abbia familiarità con lo sviluppo web Rails. Ti guida nella configurazione di Cloud SQL per PostgreSQL con una nuova app Rails. Puoi anche utilizzare questo tutorial come riferimento per configurare le app Rails esistenti in modo che utilizzino Cloud SQL per PostgreSQL.

Questo tutorial supporta e richiede Ruby 3.0 o versioni successive.

Prima di iniziare

  1. Accedi al tuo account Google Cloud . Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti senza costi per l'esecuzione, il test e il deployment dei workload.

  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. Installa Google Cloud CLI.

  6. Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

  7. Per inizializzare gcloud CLI, esegui questo comando: 

    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. Installa Google Cloud CLI.

  12. Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

  13. Per inizializzare gcloud CLI, esegui questo comando: 

    gcloud init

Preparazione di un'istanza Cloud SQL per PostgreSQL

Configura un'istanza Cloud SQL per PostgreSQL per questo tutorial.

  1. Crea un'istanza PostgreSQL. In questo tutorial, il nome dell'istanza è rails-cloudsql-instance.

  2. Crea un database nell'istanza. In questo tutorial, il nome del database di produzione è cat_list_production.

  3. Imposta la password dell'utente postgres per l'istanza.

Configurazione dell'ambiente locale per Rails

Per configurare l'ambiente locale per questo tutorial:

  1. Installa Ruby versione 3.0 o successive.

  2. Installa il gem Rails 7.

  3. Installa il gem Bundler.

Per ulteriori informazioni sull'installazione di Rails e delle relative dipendenze, consulta la guida Guida introduttiva a Rails.

Dopo aver completato i prerequisiti, crea ed esegui il deployment di un'app Rails utilizzando Cloud SQL per PostgreSQL. Le sezioni seguenti ti guidano nella configurazione, nella connessione a Cloud SQL per PostgreSQL e nel deployment di un'app.

Crea una nuova app per elencare i gatti

  1. Esegui il comando rails new per creare una nuova app Rails. Questa app archivia un elenco di gatti in Cloud SQL per PostgreSQL.

    rails new cat_sample_app

  2. Vai alla directory che contiene l'app Rails generata.

    cd cat_sample_app

Esegui l'app localmente

Per eseguire la nuova app Rails sul computer locale:

  1. Avvia un server web locale:

    bundle exec bin/rails server

  2. In un browser, vai alla pagina http://localhost:3000/

    L'app di esempio mostra il logo Rails con le versioni di Rails e Ruby.

Genera lo scaffolding per un elenco di gatti

Genera scaffolding per una risorsa denominata Cat utilizzata per formare un elenco di gatti con nome ed età.

  1. Genera lo scaffolding.

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

    Il comando genera un modello, un controller e le visualizzazioni per la risorsa 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. Apri il file config/routes.rb per visualizzare i seguenti contenuti generati.

    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. Aggiungi root 'cats#index' al file.

    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. Salva il file e chiudilo.

  5. Testa l'app Rails come indicato in precedenza.

Utilizzo di Cloud SQL per PostgreSQL con App Engine

Cloud SQL per PostgreSQL è un servizio di database completamente gestito per configurare, gestire e amministrare i database relazionali PostgreSQL inGoogle Cloud. Puoi utilizzare Cloud SQL in un'app Rails come qualsiasi altro database relazionale.

Configura Cloud SQL per PostgreSQL

Per iniziare a utilizzare Cloud SQL con la tua app Rails in produzione:

  1. Aggiungi le gemme pg e appengine al file Gemfile.

    bundle add pg
bundle add appengine

    Il binario Gemfile contiene le seguenti voci gem aggiuntive:

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

  2. Per configurare l'app Rails in modo che si connetta a Cloud SQL, apri il file config/database.yml. Vengono visualizzate le seguenti impostazioni predefinite del database per 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. Configura il nome della connessione dell'istanza Cloud SQL per l'ambiente di produzione App Engine.

    1. Recupera il nome di connessione istanza.

      gcloud sql instances describe rails-cloudsql-instance

    2. Copia il valore accanto a connectionName.

  4. Modifica la configurazione del database di produzione database.yml nel seguente modo:

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

    Dove:

    • [YOUR_POSTGRES_USERNAME] rappresenta il nome utente dell'istanza Cloud SQL per PostgreSQL.
    • [YOUR_POSTGRES_PASSWORD] rappresenta la password dell'istanza Cloud SQL per PostgreSQL.
    • [YOUR_INSTANCE_CONNECTION_NAME] rappresenta il nome di connessione dell'istanza che hai copiato nel passaggio precedente.

L'app Rails è ora configurata per utilizzare Cloud SQL durante il deployment nell'ambiente flessibile di App Engine.

Distribuzione dell'applicazione nell'ambiente flessibile di App Engine

L'ambiente flessibile di App Engine utilizza un file denominato app.yaml per descrivere la configurazione di deployment di un'app. Se questo file non è presente, gcloud CLI tenta di indovinare la configurazione di deployment. Tuttavia, devi definire il file per fornire le impostazioni di configurazione richieste per la chiave segreta Rails e Cloud SQL.

Per configurare l'app di esempio per il deployment in App Engine, crea un nuovo file denominato app.yaml nella directory radice dell'app Rails e aggiungi quanto segue:

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

Configura la chiave segreta di Rails nel file app.yaml

Quando un'app Rails viene implementata nell'ambiente production, imposta la variabile di ambiente SECRET_KEY_BASE con una chiave segreta per proteggere i dati della sessione utente. Questa variabile di ambiente viene letta dal file config/secrets.yml nella tua app Rails.

  1. Genera una nuova chiave segreta.

    bundle exec bin/rails secret

  2. Copia la chiave segreta generata.

  3. Apri il file app.yaml che hai creato in precedenza e aggiungi una sezione env_variables. Il file env_variables definisce le variabili di ambiente nell'ambiente flessibile di App Engine. Il file app.yaml dovrebbe essere simile all'esempio seguente, con [SECRET_KEY] sostituito dalla tua chiave segreta.

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

env_variables:
  SECRET_KEY_BASE: [SECRET_KEY]

Configura l'istanza Cloud SQL nel file app.yaml

Successivamente, configura l'ambiente flessibile App Engine per utilizzare un'istanza Cloud SQL specificata fornendo il nome della connessione all'istanza Cloud SQL nel file di configurazione app.yaml.

  1. Apri il file app.yaml e aggiungi una nuova sezione denominata beta_settings.

  2. Definisci un parametro nidificato cloud_sql_instances con il nome della connessione all'istanza come valore.

    Il app.yaml dovrebbe essere simile al seguente:

    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]

Crea un'app per l'ambiente flessibile di App Engine

Se è la prima volta che esegui il deployment di un'app, devi creare un'app dell'ambiente flessibile App Engine e selezionare la regione in cui vuoi eseguire l'app Rails.

  1. Crea un'app App Engine.

    gcloud app create

  2. Seleziona una regione che supporti l'ambiente flessibile di App Engine per le app Ruby. Scopri di più su Regioni e zone.

Esegui il deployment di una nuova versione

Successivamente, esegui il deployment di una nuova versione dell'app Rails descritta nel file app.yaml senza reindirizzare il traffico dalla versione di pubblicazione predefinita corrente eseguendo questo comando:

gcloud app deploy --no-promote

Il completamento del deployment può richiedere diversi minuti. Attendi un messaggio di conferma. Puoi visualizzare le versioni di cui è stato eseguito il deployment nell'elenco delle versioni di App Engine.

Dopo aver eseguito il deployment della nuova versione, se tenti di accedervi, viene visualizzato il seguente messaggio di errore perché non hai eseguito la migrazione del database.

Screenshot del nuovo messaggio di errore dell&#39;app Rails

Concedi l'autorizzazione richiesta per il Gem appengine

Successivamente, concedi l'accesso al account di servizio Cloud Build per eseguire le migrazioni del database di produzione con il gem appengine.

  1. Elenca i progetti disponibili.

    gcloud projects list

  2. Nell'output, individua il progetto che vuoi utilizzare per il deployment dell'app e copia il numero del progetto.

  3. Aggiungi un nuovo membro alla policy IAM del progetto per il ruolo roles/editor per eseguire le migrazioni del database. Sostituisci PROJECT_ID con l'ID progetto Google Cloud e PROJECT_NUMBER con il numero di progetto che hai copiato nel passaggio precedente.

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

Eseguire la migrazione del database Rails

Le migrazioni del database Rails vengono utilizzate per aggiornare lo schema del database senza utilizzare direttamente la sintassi SQL. A questo punto, esegui la migrazione del database cat_list_production.

La gemma appengine fornisce l'attività Rake appengine:exec per eseguire un comando sulla versione di deployment più recente della tua app nell'ambiente flessibile App Engine di produzione.

  1. Esegui la migrazione del database Cloud SQL per PostgreSQL cat_list_production in produzione.

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

    Dovresti visualizzare un output simile al seguente:

    ---------- 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. Per verificare la migrazione del database, inserisci il seguente URL nel browser:

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

    Sostituisci quanto segue:

    • VERSION_ID: la nuova versione dell'app che hai eseguito il deployment in precedenza. Per ottenere un elenco delle versioni, utilizza gcloud app versions list. L'ultimo elemento della versione del servizio predefinita è l'ultimo deployment.
    • PROJECT_ID: il tuo ID progetto Google Cloud
    • REGION_ID: un codice assegnato da App Engine alla tua app

Per un deployment riuscito, viene visualizzato quanto segue:

Screenshot della nuova app Rails in esecuzione

Esegui la migrazione del traffico alla nuova versione

Infine, indirizza il traffico alla versione appena implementata utilizzando il seguente comando:

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

La nuova versione dell'app è ora accessibile dal seguente URL:

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

Lettura dei log di App Engine

Ora che hai eseguito il deployment dell'app Rails, potresti voler leggere i log. Puoi leggere i log dell'app utilizzando Esplora log nella console Google Cloud .

Puoi scoprire di più sulla lettura dei log utilizzando gcloud CLI.

Libera spazio

Al termine del tutorial, puoi eliminare le risorse che hai creato in modo che non utilizzino più la quota generando addebiti. Le seguenti sezioni descrivono come eliminare o disattivare queste risorse.

Elimina progetto

Il modo più semplice per eliminare la fatturazione è eliminare il progetto creato per il tutorial.

Per eliminare il progetto:

  1. Nella console Google Cloud , vai alla pagina Gestisci risorse.

    Vai a Gestisci risorse

  2. Nell'elenco dei progetti, seleziona quello che vuoi eliminare, quindi fai clic su Elimina.
  3. Nella finestra di dialogo, digita l'ID del progetto e fai clic su Chiudi per eliminare il progetto.

Eliminare una versione di App Engine

Per eliminare una versione dell'applicazione:

  1. Nella console Google Cloud , vai alla pagina Versioni per App Engine.

    Vai a Versioni

  2. Seleziona la casella di controllo per la versione dell'app non predefinita che vuoi eliminare.
  3. Per eliminare la versione dell'app, fai clic su Elimina.

Elimina un'istanza Cloud SQL

Per eliminare un'istanza Cloud SQL:

  1. Nella console Google Cloud , vai alla pagina Istanze.

    Vai a Istanze

  2. Fai clic sul nome dell'istanza SQL che vuoi eliminare.
  3. Per eliminare l'istanza, fai clic su Elimina, quindi segui le istruzioni.

Passaggi successivi