Exportar e importar archivos en paralelo

En esta página se describe cómo exportar e importar archivos en instancias de Cloud SQL en paralelo.

Antes de empezar

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

  • Asegúrate de que tu base de datos tenga suficiente espacio libre.

    • Las operaciones de importación y exportación usan recursos de la base de datos, pero no interfieren con las operaciones típicas de la base de datos, a menos que la instancia no tenga suficientes recursos.

  • Sigue las prácticas recomendadas para exportar e importar datos.
  • Después de completar una operación de importación, verifica los resultados.

Exportar datos de Cloud SQL para PostgreSQL a varios archivos en paralelo

En las secciones siguientes se ofrece información sobre cómo exportar datos de Cloud SQL para PostgreSQL a varios archivos en paralelo.

Roles y permisos necesarios para exportar datos de Cloud SQL para PostgreSQL a varios archivos en paralelo

Para exportar datos de Cloud SQL a Cloud Storage, el usuario que inicie la exportación debe tener uno de los siguientes roles:

Además, la cuenta de servicio de la instancia de Cloud SQL debe tener uno de los siguientes roles:

  • El rol storage.objectAdmin Gestión de Identidades y Accesos (IAM)
  • Un rol personalizado que incluya los siguientes permisos:
    • storage.objects.create
    • storage.objects.list (solo para exportar archivos en paralelo)
    • storage.objects.delete (solo para exportar archivos en paralelo)

Para obtener ayuda con los roles de gestión de identidades y accesos, consulta Gestión de identidades y accesos.

Exportar datos a varios archivos en paralelo

Puede exportar datos en paralelo desde varios archivos que residen en Cloud SQL a Cloud Storage. Para ello, usa la utilidad pg_dump con la opción --jobs.

Si tienes previsto importar tus datos en Cloud SQL, sigue las instrucciones que se indican en el artículo Exportar datos desde un servidor de base de datos externo para que tus archivos tengan el formato correcto para Cloud SQL.

gcloud

Para exportar datos de Cloud SQL a varios archivos en paralelo, sigue estos pasos:

  1. Crea un segmento de Cloud Storage.
  2. Para encontrar la cuenta de servicio de la instancia de Cloud SQL desde la que vas a exportar archivos, usa el comando
    gcloud sql instances describe. 
    gcloud sql instances describe INSTANCE_NAME

    3. Sustituye INSTANCE_NAME por el nombre de tu instancia de Cloud SQL.

    En el resultado, busca el valor asociado al campo serviceAccountEmailAddress.

  3. Para asignar el storage.objectAdmin rol de gestión de identidades y accesos a la cuenta de servicio, usa el comando gcloud storage buckets add-iam-policy-binding. Para obtener ayuda con la configuración de permisos de gestión de identidades y accesos, consulta Usar permisos de gestión de identidades y accesos.
  4. Para exportar datos de Cloud SQL a varios archivos en paralelo, usa el comando gcloud sql export sql: 
    gcloud sql export sql INSTANCE_NAME gs://BUCKET_NAME/BUCKET_PATH/FOLDER_NAME \
--offload \
--parallel \
--threads=THREAD_NUMBER \
--database=DATABASE_NAME \
--table=TABLE_EXPRESSION

    Haz las siguientes sustituciones:

    • INSTANCE_NAME: el nombre de la instancia de Cloud SQL desde la que vas a exportar archivos en paralelo.
    • BUCKET_NAME: el nombre del segmento de Cloud Storage.
    • BUCKET_PATH: la ruta al segmento donde se almacenan los archivos de exportación.
    • FOLDER_NAME: la carpeta en la que se almacenan los archivos de exportación.
    • THREAD_NUMBER: número de subprocesos que usa Cloud SQL para exportar archivos en paralelo. Por ejemplo, si quiere exportar tres archivos a la vez en paralelo, especifique 3 como valor de este parámetro.
    • DATABASE_NAME (opcional): el nombre de las bases de datos de la instancia de Cloud SQL desde la que se realiza la exportación. Si no especifica ninguna base de datos, Cloud SQL exportará todas las bases de datos de usuario de la instancia. Para obtener más información, consulta Exportar una instancia completa.
    • TABLE_EXPRESSION: las tablas que se van a exportar de la base de datos especificada.

    El comando export sql no contiene activadores ni procedimientos almacenados, pero sí contiene vistas. Para exportar activadores o procedimientos almacenados, usa un solo subproceso para la exportación. En esta conversación se usa la herramienta pg_dump.

    Una vez que se haya completado la exportación, debería haber archivos en una carpeta del segmento de Cloud Storage con el formato de directorio pg_dump.

  5. Si no necesitas el rol de gestión de identidades y accesos que has definido en Roles y permisos necesarios para exportar datos de Cloud SQL para PostgreSQL, revócalo.

REST v1

Para exportar datos de Cloud SQL a varios archivos en paralelo, sigue estos pasos:

  1. Crea un segmento de Cloud Storage: 
    gcloud storage buckets create gs://BUCKET_NAME --project=PROJECT_NAME --location=LOCATION_NAME
    Haz las siguientes sustituciones:
    • BUCKET_NAME: el nombre del segmento, sujeto a los requisitos de nomenclatura. Por ejemplo, my-bucket.
    • PROJECT_NAME: el nombre del Google Cloud proyecto que contiene el segmento de Cloud Storage que vas a crear.
    • LOCATION_NAME: la ubicación del contenedor en el que quieras almacenar los archivos que vas a exportar. Por ejemplo, us-east1.
  2. Asigna a tu instancia el legacyBucketWriter rol de gestión de identidades y accesos de tu segmento. 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.

  3. Exportar datos de Cloud SQL a varios archivos en paralelo:

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

    • PROJECT_NAME: el nombre del Google Cloud proyecto que contiene el segmento de Cloud Storage que has creado.
    • INSTANCE_NAME: el nombre de la instancia de Cloud SQL desde la que vas a exportar archivos en paralelo.
    • BUCKET_NAME: el nombre del segmento de Cloud Storage.
    • BUCKET_PATH: la ruta al segmento donde se almacenan los archivos de exportación.
    • FOLDER_NAME: la carpeta en la que se almacenan los archivos de exportación.
    • DATABASE_NAME: el nombre de la base de datos de la instancia de Cloud SQL desde la que se realiza la exportación. Si quieres exportar todas las bases de datos de usuarios de la instancia, elimina este campo del cuerpo de la solicitud.
    • THREAD_NUMBER: número de subprocesos que usa Cloud SQL para exportar archivos en paralelo. Por ejemplo, si quiere exportar tres archivos a la vez en paralelo, especifique 3 como valor de este parámetro.

    Método HTTP y URL: 

    POST https://sqladmin.googleapis.com/v1/projects/PROJECT_NAME/instances/INSTANCE_NAME/export

    Cuerpo JSON de la solicitud: 

    {
 "exportContext":
   {
      "fileType": "SQL",
      "uri": "gs://BUCKET_NAME/BUCKET_PATH/FOLDER_NAME",
      "databases": ["DATABASE_NAME"],
      "offload": [TRUE|FALSE],
      "sqlExportOptions": {
        "parallel": [TRUE|FALSE],
        "threads": [THREAD_NUMBER]
       }
   }
}

    Para enviar tu solicitud, despliega una de estas opciones:

    Deberías recibir una respuesta JSON similar a la siguiente:

    4. Una vez que se haya completado la exportación, debería haber archivos en una carpeta del segmento de Cloud Storage con el formato de directorio pg_dump.

  4. Si no necesitas el rol de gestión de identidades y accesos que has definido en Roles y permisos necesarios para exportar datos de Cloud SQL para PostgreSQL, revócalo.
Para ver la lista completa de parámetros de la solicitud, consulta la página de la API Admin de Cloud SQL.

REST v1beta4

Para exportar datos de Cloud SQL a varios archivos en paralelo, sigue estos pasos:

  1. Crea un segmento de Cloud Storage: 
    gcloud storage buckets create gs://BUCKET_NAME --project=PROJECT_NAME --location=LOCATION_NAME
     Haz las siguientes sustituciones:
    • BUCKET_NAME: el nombre del segmento, sujeto a los requisitos de nomenclatura. Por ejemplo, my-bucket.
    • PROJECT_NAME: el nombre del Google Cloud proyecto que contiene el segmento de Cloud Storage que vas a crear.
    • LOCATION_NAME: la ubicación del contenedor en el que quieras almacenar los archivos que vas a exportar. Por ejemplo, us-east1.
  2. Asigna a tu instancia el storage.objectAdmin rol de gestión de identidades y accesos de tu segmento. 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.

  3. Exportar datos de Cloud SQL a varios archivos en paralelo:

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

    • PROJECT_NAME: el nombre del Google Cloud proyecto que contiene el segmento de Cloud Storage que has creado.
    • INSTANCE_NAME: el nombre de la instancia de Cloud SQL desde la que vas a exportar archivos en paralelo.
    • BUCKET_NAME: el nombre del segmento de Cloud Storage.
    • BUCKET_PATH: la ruta al segmento donde se almacenan los archivos de exportación.
    • FOLDER_NAME: la carpeta en la que se almacenan los archivos de exportación.
    • DATABASE_NAME: el nombre de la base de datos de la instancia de Cloud SQL desde la que se realiza la exportación. Si quieres exportar todas las bases de datos de usuarios de la instancia, elimina este campo del cuerpo de la solicitud.
    • THREAD_NUMBER: número de subprocesos que usa Cloud SQL para exportar archivos en paralelo. Por ejemplo, si quiere exportar tres archivos a la vez en paralelo, especifique 3 como valor de este parámetro.

    Método HTTP y URL: 

    POST https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_NAME/instances/INSTANCE_NAME/export

    Cuerpo JSON de la solicitud: 

    {
 "exportContext":
   {
      "fileType": "SQL",
      "uri": "gs://BUCKET_NAME/BUCKET_PATH/FOLDER_NAME",
      "databases": ["DATABASE_NAME"],
      "offload": [TRUE|FALSE],
      "sqlExportOptions": {
        "parallel": [TRUE|FALSE],
        "threads": [THREAD_NUMBER]
       }
   }
}

    Para enviar tu solicitud, despliega una de estas opciones:

    Deberías recibir una respuesta JSON similar a la siguiente:

    4. Una vez que se haya completado la exportación, debería haber archivos en una carpeta del segmento de Cloud Storage con el formato de directorio pg_dump.

  4. Si no necesitas el rol de gestión de identidades y accesos que has definido en Roles y permisos necesarios para exportar datos de Cloud SQL para PostgreSQL, revócalo.
Para ver la lista completa de parámetros de la solicitud, consulta la página de la API Admin de Cloud SQL.

Exportar e importar una instancia completa

Puedes exportar o importar todas las bases de datos de usuarios de una instancia completa mediante una exportación paralela con formato de directorio.

Para exportar o importar una instancia completa, utilice los mismos comandos que se muestran en las secciones Exportación paralela e Importación paralela, respectivamente, y elimine el campo databases o database. Si no especificas una base de datos, Cloud SQL ejecutará una exportación o importación en paralelo de todas las bases de datos de usuario de la instancia. Esto excluye las bases de datos del sistema y las bases de datos de Cloud SQL que se usan para gestionar operaciones internas.

En una exportación paralela con formato de directorio a Cloud Storage, una vez que se completa correctamente la exportación, los datos asociados a cada base de datos se almacenan en un subdirectorio con el nombre de cada base de datos, como se muestra a continuación:

gs://example-bucket/test-folder/
    |---- postgres/
    |    |---- 3929.dat.gz (table data file)
    |    |---- toc.dat (metadata file)
    |
    |---- second_database/
    |    |---- 3930.dat.gz
    |    |---- 3931.dat.gz
    |    |---- toc.dat

Si quieres ejecutar una importación paralela de una instancia completa y los archivos de la instancia se han creado fuera de Cloud SQL, esta estructura de subdirectorios es obligatoria para que la operación se complete correctamente.

Cuando se detecta toda la estructura del volcado de la instancia, se ignora la base de datos de importación especificada en la API. La operación detecta toda la estructura de la instancia a partir del nombre del directorio.

No puedes exportar ni importar una instancia completa en otros formatos de archivo.

No puedes exportar ni importar una instancia completa como un único archivo SQL o CSV.

Importar datos de varios archivos en paralelo a Cloud SQL para PostgreSQL

En las siguientes secciones se incluye información sobre cómo importar datos de varios archivos en paralelo a Cloud SQL para PostgreSQL.

Roles y permisos necesarios para importar datos de varios archivos en paralelo a Cloud SQL para PostgreSQL

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

Además, la cuenta de servicio de la instancia de Cloud SQL debe tener uno de los siguientes roles:

  • Rol de gestión de identidades y accesos storage.objectAdmin
  • Un rol personalizado que incluya los siguientes permisos:
    • storage.objects.get
    • storage.objects.list (solo para importar archivos en paralelo)

Para obtener ayuda con los roles de gestión de identidades y accesos, consulta Gestión de identidades y accesos.

Importar datos en Cloud SQL para PostgreSQL

Puede importar datos en paralelo desde varios archivos que residan en Cloud Storage a su base de datos. Para ello, usa la utilidad pg_restore con la opción --jobs.

gcloud

Para importar datos de varios archivos en paralelo a Cloud SQL, siga estos pasos:

  1. Crea un segmento de Cloud Storage.

  2. Sube los archivos a tu segmento.

    Para obtener ayuda sobre cómo subir archivos a los contenedores, consulta Subir objetos desde archivos.

  3. Para encontrar la cuenta de servicio de la instancia de Cloud SQL a la que vas a importar archivos, usa el comando
    gcloud sql instances describe. 
    gcloud sql instances describe INSTANCE_NAME

    4. Sustituye INSTANCE_NAME por el nombre de tu instancia de Cloud SQL.

    En el resultado, busca el valor asociado al campo serviceAccountEmailAddress.

  4. Para asignar el storage.objectAdmin rol de gestión de identidades y accesos a la cuenta de servicio, usa la utilidad gcloud storage buckets add-iam-policy-binding. Para obtener ayuda con la configuración de permisos de gestión de identidades y accesos, consulta Usar permisos de gestión de identidades y accesos.
  5. Para importar datos de varios archivos en paralelo a Cloud SQL, usa el comando gcloud sql import sql: 
    gcloud sql import sql INSTANCE_NAME gs://BUCKET_NAME/BUCKET_PATH/FOLDER_NAME \
--parallel \ 
--threads=THREAD_NUMBER \
--database=DATABASE_NAME

    Haz las siguientes sustituciones:

    • INSTANCE_NAME: el nombre de la instancia de Cloud SQL a la que vas a importar archivos en paralelo.
    • BUCKET_NAME: el nombre del segmento de Cloud Storage.
    • BUCKET_PATH: la ruta al segmento en el que se almacenan los archivos de importación.
    • FOLDER_NAME: la carpeta en la que se almacenan los archivos de importación.
    • THREAD_NUMBER: número de subprocesos que usa Cloud SQL para importar archivos en paralelo. Por ejemplo, si quiere importar tres archivos a la vez en paralelo, especifique 3 como valor de este parámetro.
    • DATABASE_NAME: el nombre de la base de datos de la instancia de Cloud SQL desde la que se realiza la importación. Solo debe especificar una base de datos.

    Si el comando devuelve un error como ERROR_RDBMS, revisa los permisos, ya que este error suele deberse a problemas con los permisos.

  6. Si no necesitas los permisos de gestión de identidades y accesos que has definido en Roles y permisos necesarios para importar datos a Cloud SQL para PostgreSQL, utiliza gcloud storage buckets remove-iam-policy-binding para eliminarlos.

REST v1

Para importar datos de varios archivos en paralelo a Cloud SQL, siga estos pasos:

  1. Crea un segmento de Cloud Storage: 
    gcloud storage buckets create gs://BUCKET_NAME --project=PROJECT_NAME --location=LOCATION_NAME
    Haz las siguientes sustituciones:
    • BUCKET_NAME: el nombre del segmento, sujeto a los requisitos de nomenclatura. Por ejemplo, my-bucket.
    • PROJECT_NAME: el nombre del Google Cloud proyecto que contiene el segmento de Cloud Storage que vas a crear.
    • LOCATION_NAME: la ubicación del contenedor en el que quieres almacenar los archivos que vas a importar. Por ejemplo, us-east1.

  2. Sube los archivos a tu segmento.

    Para obtener ayuda sobre cómo subir archivos a los contenedores, consulta Subir objetos desde archivos.

  3. Proporciona a tu instancia el storage.objectAdmin rol de gestión de identidades y accesos para tu segmento. Para obtener ayuda sobre cómo definir permisos de gestión de identidades y accesos, consulta el artículo Usar permisos de gestión de identidades y accesos.

  4. Importar datos de varios archivos en paralelo en Cloud SQL:

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

    • PROJECT_NAME: el nombre del Google Cloud proyecto que contiene el segmento de Cloud Storage que has creado.
    • INSTANCE_NAME: el nombre de la instancia de Cloud SQL a la que vas a importar archivos en paralelo.
    • BUCKET_NAME: el nombre del segmento de Cloud Storage.
    • BUCKET_PATH: la ruta al segmento en el que se almacenan los archivos de importación.
    • FOLDER_NAME: la carpeta en la que se almacenan los archivos de importación.
    • DATABASE_NAME: el nombre de la base de datos de la instancia de Cloud SQL desde la que se realiza la importación. Solo debe especificar una base de datos.
    • THREAD_NUMBER: número de subprocesos que usa Cloud SQL para importar archivos en paralelo. Por ejemplo, si quiere importar tres archivos a la vez en paralelo, especifique 3 como valor de este parámetro.

    Método HTTP y URL: 

    POST https://sqladmin.googleapis.com/v1/projects/PROJECT_NAME/instances/INSTANCE_NAME/import

    Cuerpo JSON de la solicitud: 

    
{
  "importContext":
    {
       "fileType": "SQL",
       "uri": "gs://BUCKET_NAME/BUCKET_PATH/FOLDER_NAME",
       "databases": ["DATABASE_NAME"],
       "offload": [TRUE|FALSE],
       "sqlImportOptions": {
         "parallel": [TRUE|FALSE],
         "clean": [TRUE|FALSE],
         "ifExists": [TRUE|FALSE],
         "threads": [THREAD_NUMBER]
        }
    }
 }

    Para enviar tu solicitud, despliega una de estas opciones:

    Deberías recibir una respuesta JSON similar a la siguiente:

    Para usar otro usuario en la importación, especifica la propiedad importContext.importUser.

    Para ver la lista completa de parámetros de la solicitud, consulta la página de la API Admin de Cloud SQL.
  5. Si no necesitas los permisos de gestión de identidades y accesos que has definido en Roles y permisos necesarios para importar datos a Cloud SQL para PostgreSQL, utiliza gcloud storage buckets remove-iam-policy-binding para eliminarlos.

REST v1beta4

Para importar datos de varios archivos en paralelo a Cloud SQL, siga estos pasos:

  1. Crea un segmento de Cloud Storage: 
    gcloud storage buckets create gs://BUCKET_NAME --project=PROJECT_NAME --location=LOCATION_NAME
    Haz las siguientes sustituciones:
    • BUCKET_NAME: el nombre del segmento, sujeto a los requisitos de nomenclatura. Por ejemplo, my-bucket.
    • PROJECT_NAME: el nombre del Google Cloud proyecto que contiene el segmento de Cloud Storage que vas a crear.
    • LOCATION_NAME: la ubicación del contenedor en el que quieres almacenar los archivos que vas a importar. Por ejemplo, us-east1.

  2. Sube los archivos a tu segmento.

    Para obtener ayuda sobre cómo subir archivos a los contenedores, consulta Subir objetos desde archivos.

  3. Proporciona a tu instancia el storage.objectAdmin rol de gestión de identidades y accesos para tu segmento. Para obtener ayuda sobre cómo definir permisos de gestión de identidades y accesos, consulta el artículo Usar permisos de gestión de identidades y accesos.

  4. Importar datos de varios archivos en paralelo en Cloud SQL:

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

    • PROJECT_NAME: el nombre del Google Cloud proyecto que contiene el segmento de Cloud Storage que has creado.
    • INSTANCE_NAME: el nombre de la instancia de Cloud SQL desde la que vas a importar archivos en paralelo.
    • BUCKET_NAME: el nombre del segmento de Cloud Storage.
    • BUCKET_PATH: la ruta al segmento en el que se almacenan los archivos de importación.
    • FOLDER_NAME: la carpeta en la que se almacenan los archivos de importación.
    • DATABASE_NAME: el nombre de la base de datos de la instancia de Cloud SQL desde la que se realiza la importación. Solo debe especificar una base de datos.
    • THREAD_NUMBER: número de subprocesos que usa Cloud SQL para importar archivos en paralelo. Por ejemplo, si quiere importar tres archivos a la vez en paralelo, especifique 3 como valor de este parámetro.

    Método HTTP y URL: 

    POST https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_NAME/instances/INSTANCE_NAME/import

    Cuerpo JSON de la solicitud: 

    
 {
   "importContext":
     {
        "fileType": "SQL",
        "uri": "gs://BUCKET_NAME/BUCKET_PATH/FOLDER_NAME",
        "databases": ["DATABASE_NAME"],
        "offload": [TRUE|FALSE],
        "sqlImportOptions": {
          "parallel": [TRUE|FALSE],
          "clean": [TRUE|FALSE],
          "ifExists": [TRUE|FALSE],
          "threads": [THREAD_NUMBER]
         }
     }
  }

    Para enviar tu solicitud, despliega una de estas opciones:

    Deberías recibir una respuesta JSON similar a la siguiente:

    Para usar otro usuario en la importación, especifica la propiedad importContext.importUser.

    Para ver la lista completa de parámetros de la solicitud, consulta la página de la API Admin de Cloud SQL.
  5. Si no necesitas los permisos de gestión de identidades y accesos que has definido en Roles y permisos necesarios para importar datos a Cloud SQL para PostgreSQL, utiliza gcloud storage buckets remove-iam-policy-binding para eliminarlos.

Limitaciones

  • Si especificas demasiados subprocesos al importar o exportar datos de varios archivos en paralelo, es posible que uses más memoria de la que tiene tu instancia de Cloud SQL. Si esto ocurre, aparecerá un mensaje de error interno. Comprueba el uso de memoria de tu instancia y aumenta su tamaño si es necesario. Para obtener más información, consulta Acerca de la configuración de instancias.

  • Cuando se realiza una exportación, no se admiten comas en los nombres de las bases de datos ni en los nombres de las tablas de los campos databases o tables.

  • Asegúrate de que tienes suficiente espacio en disco para descargar el archivo de volcado inicial. De lo contrario, aparecerá un error no space left on disk.

  • Si tu instancia solo tiene una CPU virtual (vCPU), no podrás importar ni exportar varios archivos en paralelo. El número de vCPUs de tu instancia no puede ser inferior al número de hilos que estés usando para la operación de importación o exportación, y el número de hilos debe ser al menos dos.

  • Las importaciones y exportaciones multiproceso (paralelas) no son compatibles con las importaciones y exportaciones de un solo proceso. Por ejemplo, los archivos de volcado generados por una exportación de un solo subproceso solo se pueden importar mediante importaciones de un solo subproceso. Del mismo modo, los archivos de volcado generados por exportaciones paralelas solo se pueden importar mediante importaciones paralelas.

  • La utilidad pg_dump no puede dividir en fragmentos las tablas que exportes. Por lo tanto, si tiene una tabla muy grande, puede convertirse en un cuello de botella para la velocidad de la operación de exportación.

Siguientes pasos