Usa Cloud SQL para PostgreSQL con Rails 7 en App Engine

Comienza a desarrollar apps de Ruby on Rails que se ejecuten en el entorno flexible de App Engine. Las apps que crees se ejecutarán en la misma infraestructura que impulsa todos los productos de Google, ten la confianza de que escalarán para atender a todos tus usuarios, sin importar si son unos pocos o millones.

Para este instructivo, suponemos que conoces el desarrollo web con Rails. Te guía a través de la configuración de Cloud SQL para PostgreSQL con una nueva app de Rails. También puedes usar este instructivo como referencia para configurar apps de Rails existentes a fin de usar Cloud SQL para PostgreSQL.

Este instructivo admite y requiere Ruby 3.0 o una versión posterior.

Antes de comenzar

Accede a tu cuenta de Google Cloud . Si eres nuevo en Google Cloud, crea una cuenta para evaluar el rendimiento de nuestros productos en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.

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

Instala Google Cloud CLI.

Si usas un proveedor de identidad externo (IdP), primero debes acceder a la gcloud CLI con tu identidad federada.

Para inicializar gcloud CLI, ejecuta el siguiente comando:

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

Instala Google Cloud CLI.

Si usas un proveedor de identidad externo (IdP), primero debes acceder a la gcloud CLI con tu identidad federada.

Para inicializar gcloud CLI, ejecuta el siguiente comando:

gcloud init

Prepara una instancia de Cloud SQL para PostgreSQL

Configura una instancia de Cloud SQL para PostgreSQL a fin de usarla en este instructivo.

1. Crea una instancia de PostgreSQL. En este instructivo, el nombre de la instancia es rails-cloudsql-instance.

2. Crea una base de datos en la instancia. En este instructivo, el nombre de la base de datos de producción es cat_list_production.

3. Configura la contraseña del usuario de postgres para la instancia.

Configura el entorno local para Rails

Para configurar tu entorno local para este instructivo, haz lo siguiente:

1. Instala la versión 3.0 o posterior de Ruby.

2. Instala la gema de Rails 7.

3. Instala la gema de Bundler.

Nota: De manera alternativa, puedes usar Cloud Shell, que incluye Ruby, Rails, Bundler y Google Cloud CLI ya instalados.

Para obtener información adicional sobre la instalación de Rails y sus dependencias, consulta la guía oficial Comenzar a usar Rails.

Una vez que completes los requisitos previos, crea e implementa una app de Rails con Cloud SQL para PostgreSQL. En las siguientes secciones, se te guiará en la configuración, la conexión a Cloud SQL para PostgreSQL y la implementación de una app.

Crea una app nueva que muestre una lista de gatos

1. Ejecuta el comando rails new si deseas crear una nueva app de Rails. Esta aplicación almacena una lista de cats en Cloud SQL para PostgreSQL.

   rails new cat_sample_app
   

2. Ve al directorio que contiene la app de Rails que se generó.

   cd cat_sample_app
   

Ejecuta la app de forma local

Para ejecutar la app de Rails nueva en tu computadora local, haz lo siguiente:

1. Inicia un servidor web local:

   bundle exec bin/rails server
   

2. En un navegador, ve a http://localhost:3000.

   La app de ejemplo muestra el logotipo de Rails con las versiones de Rails y Ruby.

Nota: En la ventana de la terminal, presiona Ctrl+C para salir del servidor web.

Genera un andamiaje para una lista de gatos

Genere una estructura para un recurso llamado Cat que se usa para formar una lista de gatos con sus nombres y edades.

1. Genera el andamiaje.

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

   El comando genera un modelo, un controlador y vistas para el recurso 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. Abre el archivo config/routes.rb para ver el siguiente contenido autogenerado.

   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. Agrega root 'cats#index' al archivo.

   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. Guarde y cierre el archivo.

5. Prueba la app de Rails como se indicó antes.

Cómo usar Cloud SQL para PostgreSQL con App Engine

Cloud SQL para PostgreSQL es un servicio de bases de datos completamente administrado que te permite configurar, mantener, administrar y controlar tus bases de datos relacionales de PostgreSQL enGoogle Cloud. Puedes usar Cloud SQL en una app de Rails como cualquier otra base de datos relacional.

Configura Cloud SQL para PostgreSQL

Para comenzar a usar Cloud SQL con tu app de Rails en producción, haz lo siguiente:

1. Agrega las gemas pg y appengine al archivo Gemfile.

   bundle add pg
   bundle add appengine
   

   El archivo Gemfile de Rails contiene las siguientes entradas gem adicionales:

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

   Nota: La gema appengine proporciona una tarea de Rake para ejecutar migraciones de bases de datos en la producción.

2. Para configurar la app de Rails para que se conecte con Cloud SQL, abre el archivo config/database.yml. Se muestra la siguiente configuración de base de datos estándar para 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 el nombre de conexión de la instancia de Cloud SQL para el entorno de producción de App Engine.

   1. Recupera el nombre de conexión de la instancia.

      gcloud sql instances describe rails-cloudsql-instance
      

   2. Copia el valor que aparece junto a connectionName.

4. Modifica la configuración de la base de datos de producción database.yml de la siguiente manera:

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

   Aquí:

   • [YOUR_POSTGRES_USERNAME] representa el nombre de usuario de tu instancia de Cloud SQL para PostgreSQL.
   • [YOUR_POSTGRES_PASSWORD] representa la contraseña de tu instancia de Cloud SQL para PostgreSQL.
   • [YOUR_INSTANCE_CONNECTION_NAME] representa el nombre de conexión de la instancia que copiaste en el paso anterior.

Ahora, la app de Rails está configurada para usar Cloud SQL cuando se implemente en el entorno flexible de App Engine.

Cómo implementar la app en el entorno flexible de App Engine

El entorno flexible de App Engine usa un archivo llamado app.yaml para describir la configuración de implementación de una app. Si este archivo no está presente, la gcloud CLI intentará predecir la configuración de implementación. Sin embargo, debes definir el archivo a fin de proporcionar la configuración necesaria para la clave secreta de Rails y Cloud SQL.

A fin de configurar la app de muestra para tu implementación en App Engine, crea un archivo nuevo llamado app.yaml en la raíz del directorio de la app de Rails y agrega lo siguiente:

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

Configura la clave secreta de Rails en el archivo app.yaml

Cuando se implementa una app de Rails en el entorno production, configura la variable de entorno SECRET_KEY_BASE con una clave secreta para proteger los datos de sesión del usuario. Esta variable de entorno se lee desde el archivo config/secrets.yml de tu app de Rails.

1. Genera una clave secreta nueva.

   bundle exec bin/rails secret
   

2. Copia la clave secreta generada.

3. Abre el archivo app.yaml que creaste anteriormente y agrega una sección env_variables. env_variables define las variables del entorno en el entorno flexible de App Engine. El archivo app.yaml debería ser similar al siguiente ejemplo, con [SECRET_KEY] reemplazado por tu clave secreta.

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

Configura la instancia de Cloud SQL en el archivo app.yaml

A continuación, configura el entorno flexible de App Engine para usar una instancia de Cloud SQL especificada. Para ello, proporciona el nombre de conexión de la instancia de Cloud SQL en el archivo de configuración app.yaml.

1. Abre el archivo app.yaml y agrega una sección nueva llamada beta_settings.

2. Define un parámetro anidado cloud_sql_instances con el nombre de conexión de la instancia como valor.

   Nota: Para recuperar el nombre de conexión de la instancia de Cloud SQL, ejecuta gcloud sql instances describe rails-cloudsql-instance.

   El app.yaml debería ser similar al siguiente:

   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]

Creación de una app en el entorno flexible de App Engine

Si es la primera vez que implementas una app, debes crear una app del entorno flexible de App Engine y seleccionar la región en la que deseas ejecutar la app de Rails.

1. Crea una aplicación de App Engine.

   gcloud app create
   

2. Selecciona una región compatible con el entorno flexible de App Engine para apps de Ruby. Obtén más información sobre las regiones y zonas.

Implementación de una versión nueva

A continuación, implementa una versión nueva de la app de Rails descrita en el archivo app.yaml sin redireccionar el tráfico desde la versión predeterminada actualmente en uso mediante este comando:

gcloud app deploy --no-promote

La implementación puede tardar varios minutos en completarse. Espera un mensaje de operación correcta. Puedes ver las versiones implementadas en la lista de versiones de App Engine.

Advertencia: Las versiones anteriores de la app se conservan, al igual que las instancias de VM asociadas a ellas. Ten en cuenta que todas estas instancias de VM y versiones de la app son recursos facturables.

Después de implementar la versión nueva, si intentas acceder a esta, aparecerá el siguiente mensaje de error porque no migraste la base de datos.

Otorgamiento del permiso necesario a la gema appengine

Luego, otorga acceso a la cuenta de servicio de CloudBuild para ejecutar migraciones de bases de datos de producción con la gema appengine.

1. Enumera los proyectos disponibles.

   gcloud projects list
   

2. En el resultado, busca el proyecto que deseas usar para implementar tu app y copia el número del proyecto.

3. Agrega un miembro nuevo a la política de IAM de tu proyecto para el rol roles/editor para ejecutar migraciones de bases de datos. Reemplaza PROJECT_ID por el ID de tu proyecto de Google Cloud y reemplaza PROJECT_NUMBER por el número de proyecto que copiaste en el paso anterior.

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

Migra tu base de datos de Rails

Las migraciones de bases de datos de Rails se usan para actualizar el esquema de tu base de datos sin usar la sintaxis de SQL directamente. A continuación, migra tu base de datos cat_list_production.

La gema appengine proporciona la tarea Rake appengine:exec para ejecutar un comando en la versión de tu app implementada más reciente en el entorno flexible de App Engine de producción.

1. Migra la base de datos cat_list_production de Cloud SQL para PostgreSQL en producción.

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

   Deberías ver un resultado similar a este:

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

   Nota: Si se produce un error de permiso cuando se intentan ejecutar migraciones de bases de datos, verifica que [e-mail] tiene el rol roles/editor.

2. Para verificar la migración de la base de datos, ingresa la siguiente URL en tu navegador:

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

   Reemplaza lo siguiente:

   • VERSION_ID: Es la nueva versión de la app que implementaste anteriormente. Para obtener una lista de versiones, usa gcloud app versions list. El elemento de la última versión del servicio predeterminada corresponde a la implementación más reciente.
   • PROJECT_ID: ID de tu proyecto de Google Cloud
   • REGION_ID: Un código que App Engine asigna a la app

Se muestra lo siguiente en caso de una implementación exitosa:

Migración del tráfico a la versión nueva

Por último, dirige el tráfico a la versión recién implementada con el siguiente comando:

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

Ahora, se puede acceder a la nueva versión de la app desde la siguiente URL:

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

Lee registros de App Engine

Ahora que implementaste tu app de Rails, te recomendamos leer los registros. Puedes leer los registros de la app con el Explorador de registros ubicado en la consola de Google Cloud .

Puedes obtener más información para leer registros con la CLI de gcloud.

Limpia los recursos

Una vez que termines el instructivo, puedes limpiar los recursos que creaste para que dejen de usar la cuota y generar cargos. En las siguientes secciones, se describe cómo borrar o desactivar estos recursos.

Borrar proyecto

La manera más fácil de eliminar la facturación es borrar el proyecto que creaste para el instructivo.

Para borrar el proyecto, sigue estos pasos:

Precaución: Borrar un proyecto tiene las siguientes consecuencias:

• Se borra todo su contenido. Si usaste un proyecto existente para las tareas de este documento, cuando lo borres, también se borrará cualquier otro trabajo que hayas realizado en el proyecto.
• Se pierden los IDs personalizados de los proyectos. Cuando creaste este proyecto, es posible que hayas creado un ID personalizado del proyecto que desees utilizar en el futuro. Para conservar las URLs que usan el ID del proyecto, como una URL appspot.com, borra los recursos seleccionados dentro del proyecto, en lugar de todo el proyecto.

Si planeas explorar varios instructivos, arquitecturas o guías de inicio rápido, reutilizar proyectos puede ser útil para no exceder los límites de cuota de los proyectos.

1. En la Google Cloud consola, ve a la página Administrar recursos.

   Ir a Administrar recursos

2. En la lista de proyectos, elige el proyecto que quieres borrar y haz clic en Borrar.
3. En el diálogo, escribe el ID del proyecto y, luego, haz clic en Cerrar para borrar el proyecto.

Borra una versión de App Engine

Para borrar la versión de una aplicación, haz lo siguiente:

1. En la consola de Google Cloud , ve a la página Versiones de App Engine.

   Ir a Versiones

2. Selecciona la casilla de verificación de la versión no predeterminada de la app que deseas borrar.
   Nota: La única forma de borrar la versión predeterminada de tu aplicación de App Engine es borrar tu proyecto. Sin embargo, puedes detener la versión predeterminada en la Google Cloud consola. Esta acción detiene todas las instancias asociadas a la versión. Puedes reiniciar estas instancias más tarde si es necesario.

   En el entorno estándar de App Engine, puedes detener la versión predeterminada si tu aplicación tiene ajuste de escala básico o manual.

3. Para borrar la versión de la app, haz clic en Borrar.

Borrar una instancia de Cloud SQL

Para borrar una instancia de Cloud SQL, haz lo siguiente:

1. En la consola de Google Cloud , ve a la página Instancias.

   Ir a Instancias

2. Haz clic en el nombre de la instancia de SQL que deseas borrar.
3. Para borrar la instancia, haz clic en Borrar y sigue las instrucciones.

¿Qué sigue?

• Aprende a ejecutar la aplicación de muestra de Bookshelf para Ruby en el entorno flexible de App Engine.

• Aprende a ejecutar la aplicación de muestra de Bookshelf para Ruby en Compute Engine.

• Aprende a ejecutar la aplicación de muestra de Bookshelf para Ruby en Google Kubernetes Engine.