Importar un archivo SQL

En esta página se describe cómo importar datos de un archivo SQL almacenado en un segmento de Cloud Storage a un clúster de AlloyDB para PostgreSQL. Los archivos SQL son archivos de texto sin formato con una secuencia de comandos de SQL.

Nota: Si vas a migrar una base de datos completa desde un servidor de bases de datos compatible (local, en AWS o en AlloyDB) a un nuevo clúster de AlloyDB, puedes usar Database Migration Service en lugar de exportar y, después, importar archivos. Si vas a importar un archivo porque quieres crear un clúster a partir de él, te recomendamos que restaures una copia de seguridad en otro clúster.

Puedes cancelar la importación de datos en clústeres de AlloyDB. Para obtener más información, consulta Cancelar una operación de importación.

Antes de empezar

Antes de iniciar una operación de importación:

• Asegúrate de que tu base de datos tenga suficiente espacio libre.
• Las operaciones de importación usan recursos de la base de datos, pero no interfieren con las operaciones normales de la base de datos, a menos que el clúster no tenga suficientes recursos.

Importante: Antes de iniciar una operación de importación de gran tamaño, asegúrate de que al menos el 25 % del disco esté libre en el clúster. De esta forma, se evitan problemas con el crecimiento automático agresivo, que puede afectar negativamente a la disponibilidad del clúster. Verifica que el archivo SQL tiene los datos esperados.

Roles y permisos necesarios para importar datos a AlloyDB

Para importar datos de Cloud Storage a AlloyDB, el usuario que inicie la importación debe tener uno de los siguientes roles:

• El rol Administrador de AlloyDB
• Un rol personalizado que incluya los siguientes permisos:
  • alloydb.clusters.get
  • alloydb.clusters.import

Además, la cuenta de servicio del clúster de AlloyDB debe tener uno de los siguientes roles:

• Rol de gestión de identidades y accesos storage.objectViewer
• Un rol personalizado que incluya los siguientes permisos:
  • storage.objects.get

Para obtener ayuda con los roles de Gestión de Identidades y Accesos, consulta Gestión de Identidades y Accesos.

Nota: Los cambios que hagas en los permisos y roles de gestión de identidades y accesos pueden tardar unos minutos en aplicarse. Para obtener más información, consulta Propagación de cambios de acceso.

Importar un archivo SQL en clústeres de AlloyDB

Para importar datos a un clúster de AlloyDB mediante un archivo SQL, sigue estos pasos:

Consola

1. Ve a la página Clústeres.

   Ir a Clústeres

2. Haga clic en el nombre de un clúster para abrir la página Resumen de ese clúster.

3. Haz clic en Importar.

4. En Seleccionar archivo de origen, busca en Cloud Storage y selecciona un archivo SQL de un segmento o sube un archivo SQL desde tu máquina local para usarlo en la importación.

   Nota: Puedes importar un archivo comprimido (.gz) o sin comprimir (.sql).

5. Selecciona la base de datos en la que quieres importar los datos.

   De este modo, AlloyDB ejecuta la instrucción USE DATABASE antes de la importación. Si el archivo de volcado de SQL incluye una instrucción USE DATABASE, se anula la base de datos que hayas definido en la consola Google Cloud .

6. Opcional: Especifica un usuario para la operación de importación. Si el archivo de importación contiene instrucciones que debe ejecutar un usuario específico, utilice este campo para especificarlo.

7. Para iniciar la operación de importación, haga clic en Importar.

gcloud

1. Crea un segmento de Cloud Storage.

2. Sube el archivo SQL al segmento. Para obtener ayuda sobre cómo subir archivos a los contenedores, consulta Subir objetos.

3. Usa gcloud storage buckets add-iam-policy-binding para asignar el storage.objectViewer rol de gestión de identidades y accesos a la cuenta de servicio del clúster de AlloyDB para el segmento:

   [e-mail]

   Haz las siguientes sustituciones:

   • CLUSTER_NAME: el nombre del clúster.
   • REGION: la región en la que se despliega el clúster de AlloyDB.
   • BUCKET_NAME: el nombre del segmento de Cloud Storage.
   • FILE_NAME: el nombre del archivo CSV.
   • DATABASE_NAME: el nombre de una base de datos del clúster.
   • USER: el usuario de la operación de importación.
   • TABLE_NAME: la tabla de la base de datos.

   Para obtener ayuda sobre cómo definir permisos de gestión de identidades y accesos, consulta Usar permisos de gestión de identidades y accesos.

4. Importa el archivo:

   gcloud alloydb clusters import CLUSTER_NAME --region=REGION --database=DATABASE_NAME --gcs-uri='gs://BUCKET_NAME/PATH_TO_SQL_FILE' --user=USERNAME --sql

   Nota: Puedes importar un archivo comprimido (.gz) o sin comprimir (.sql).

   Si el comando devuelve un error como PERMISSION_DENIED, revisa los permisos.

   Para obtener información sobre el uso del comando import, consulta la página de referencia del comando alloydb import.

5. Si no necesitas conservar los permisos de gestión de identidades y accesos que has definido anteriormente, quítalos con gcloud storage buckets remove-iam-policy-binding.

REST v1

1. Crea un segmento de Cloud Storage.
2. Sube el archivo SQL al segmento. Para obtener ayuda sobre cómo subir archivos a los contenedores, consulta Subir objetos.

3. Concede permisos a la cuenta de servicio para acceder al segmento de Cloud Storage de la operación de importación. Usa el formato de cuenta de servicio para identificar la cuenta de servicio del proyecto al que vas a importar. El formato de la cuenta de servicio es el siguiente:

   [e-mail]

4. Usa gcloud storage buckets add-iam-policy-binding para asignar el storage.objectViewer rol de gestión de identidades y accesos a la cuenta de servicio del clúster de AlloyDB para el segmento. Para obtener ayuda sobre cómo configurar permisos de gestión de identidades y accesos, consulta Usar permisos de gestión de identidades y accesos.

5. Importa tu archivo SQL.

   Nota: Puedes importar un archivo comprimido (.gz) o sin comprimir (.sql).

   Usa el siguiente método HTTP y la siguiente URL:

   POST https://alloydbadmin.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/clusters/CLUSTER_ID:import

   Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

   • PROJECT_ID: el ID del proyecto.
   • LOCATION_ID: la región en la que se despliega el clúster de AlloyDB.
   • CLUSTER_ID: el ID del clúster.
   • BUCKET_NAME: el nombre del segmento de Cloud Storage.
   • PATH_TO_SQL_FILE: la ruta al archivo SQL.
   • USER: el usuario que se va a usar para la importación.
   • DATABASE_NAME: nombre de una base de datos del clúster de AlloyDB.

   Cuerpo JSON de la solicitud:

   {
      "gcsUri": "gs://BUCKET_NAME/PATH_TO_SQL_FILE",
      "database": "DATABASE_NAME",
      "user": "USER",
      "sqlImportOptions": {}
   }
   

   Para enviar tu solicitud, despliega una de estas opciones:

   curl (Linux, macOS o Cloud Shell)

   Con el siguiente comando se da por hecho que has iniciado sesión en la CLI de Google Cloud con tu cuenta de usuario ejecutando gcloud init o gcloud auth login, o bien usando Cloud Shell, que inicia sesión automáticamente en la CLI de gcloud. Puedes comprobar la cuenta activa ejecutando gcloud auth list.

   Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

      curl -X POST \
            -H "Authorization: Bearer $(gcloud auth print-access-token)" \
            -H "Content-Type: application/json; charset=utf-8" \
            -d @request.json \
            "https://alloydb.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/clusters/CLUSTER_ID:import"
   

   PowerShell (Windows)

   Con el siguiente comando se da por hecho que has iniciado sesión en la CLI de Google Cloud con tu cuenta de usuario ejecutando gcloud init o gcloud auth login, o bien usando Cloud Shell, que inicia sesión automáticamente en la CLI de gcloud. Puedes comprobar la cuenta activa ejecutando gcloud auth list.

   Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

   $cred = gcloud auth print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
     -Method POST `
     -Headers $headers `
     -ContentType: "application/json; charset=utf-8" `
     -InFile request.json `
     -Uri "https://alloydb.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/clusters/CLUSTER_ID:import"| Select-Object -Expand Content
   

   Recibirás una respuesta JSON similar a la siguiente:

   Respuesta

   {
    "name": "projects/project-id/locations/location-id/operations/operation-id",
    "metadata": {
     "@type": "type.googleapis.com/google.cloud.alloydb.v1.OperationMetadata",
     "createTime": "2025-01-04T13:12:32.363393723Z",
     "target": "projects/project-id/locations/location-id/clusters/cluster-id",
     "verb": "import",
     "requestedCancellation": false,
     "apiVersion": "v1"
    },
    "done": false
   }
   

   Para usar otro usuario en la importación, especifique la propiedad de usuario.

6. Si no necesitas conservar los permisos de gestión de identidades y accesos que has definido anteriormente, quítalos ahora.

   Para ver la lista completa de parámetros de la solicitud, consulta clusters:import.

Consultar el estado de una operación de importación

Para comprobar el estado de una operación de importación, sigue estos pasos:

gcloud

Ejecuta lo siguiente con el comando gcloud alloydb operations describe:

gcloud alloydb operations describe OPERATION_ID --region=REGION

También puedes consultar los detalles de una operación específica o cancelarla. Para obtener más información sobre este comando, consulta la página de referencia del comando gcloud alloydb operations.

REST v1

Usa el método GET y la siguiente URL:

GET https://alloydb.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/operations/OPERATION_ID

Para obtener más información, consulta get.

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

• REGION: la región en la que se despliega el clúster de AlloyDB.
• PROJECT_ID: el ID del proyecto.
• OPERATION_ID: ID de la operación de importación. Para obtener más información, consulta la sección Antes de empezar.

Para enviar tu solicitud, despliega una de estas opciones:

curl (Linux, macOS o Cloud Shell)

En el siguiente comando se da por hecho que has iniciado sesión en la CLI de gcloud con tu cuenta de usuario ejecutando gcloud init o gcloud auth login, o bien usando Cloud Shell, que inicia sesión automáticamente en la CLI de gcloud. Puedes comprobar la cuenta activa ejecutando gcloud auth list.

Ejecuta el comando siguiente:

  curl -X GET \
       -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  https://alloydb.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/operations/OPERATION_ID
 

PowerShell (Windows)

El siguiente comando presupone que has iniciado sesión en la CLI de gcloud con tu cuenta de usuario ejecutando gcloud init o gcloud auth login. Puedes comprobar la cuenta activa ejecutando gcloud auth list.

Ejecuta el comando siguiente:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
  -Method GET `
  -Headers $headers `
  -Uri "https://alloydb.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/operations/OPERATION_ID | Select-Object -Expand Content

Recibirás una respuesta JSON similar a la siguiente:

Si la solicitud se completa correctamente, en el cuerpo de la respuesta se incluye una instancia de Operation.

Siguientes pasos

• Consulta cómo importar un archivo CSV.
• Consulta cómo cancelar una operación de importación.