Importa y exporta mediante archivos CSV

En esta página, se describe cómo importar y exportar datos a instancias de Cloud SQL mediante archivos CSV.

Antes de comenzar

Antes de comenzar una operación de importación o exportación, haz lo siguiente:

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

    • Las operaciones de importación y exportación usan recursos de bases de datos, pero no interfieren en las operaciones normales de la base de datos, a menos que la instancia no cuente con el aprovisionamiento suficiente.

  • Verifica que el archivo CSV tenga los datos esperados y que tenga el formato correcto. Los archivos CSV deben tener una línea por cada fila de campos de datos.
  • Sigue las prácticas recomendadas para exportar e importar datos.

Exporta datos de Cloud SQL para PostgreSQL

Roles y permisos necesarios para exportar desde Cloud SQL para PostgreSQL

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

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

  • El rol de Identity and Access Management (IAM) llamado storage.objectAdmin
  • 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 IAM, consulta Identity and Access Management.

Exporta datos a un archivo CSV desde Cloud SQL para PostgreSQL

Puedes exportar tus datos en el formato CSV de modo que otras herramientas y entornos puedan usarlos. Las exportaciones se realizan a nivel de la base de datos. Durante una exportación de CSV, puedes especificar los esquemas que se exportarán. Todos los esquemas en el nivel de la base de datos son aptos para la exportación.

Para exportar datos de una base de datos en una instancia de Cloud SQL a un archivo CSV en un bucket de Cloud Storage, sigue estos pasos:

Console

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

    Ir a Instancias de Cloud SQL

  2. Para abrir la página de Descripción general de una instancia, haz clic en su nombre.
  3. Haz clic en Exportar.
  4. Selecciona Exportación de descarga para permitir que se realicen otras operaciones mientras la exportación está en curso.
  5. En la sección Ubicación de la exportación de Cloud Storage, agrega el nombre del bucket, la carpeta y el archivo que deseas exportar, o haz clic en Explorar para buscar o crear un bucket, una carpeta o un archivo.

    Si haces clic en Explorar, sigue estos pasos:

    1. En la sección Ubicación, selecciona un bucket o una carpeta de Cloud Storage para la exportación.

    2. En el cuadro Nombre, agrega un nombre para el archivo CSV o selecciona un archivo existente de la lista en la sección Ubicación.

      Puedes usar una extensión de archivo .gz (la extensión completa sería .csv.gz) para comprimir el archivo de exportación.

    3. Haz clic en Seleccionar.
  6. En la sección Formato, haz clic en CSV.
  7. En la sección Base de datos para exportar, selecciona el nombre de la base de datos en el menú desplegable.

  8. En Consulta de SQL, ingresa una consulta de SQL para especificar la tabla desde la que deseas exportar los datos.

    Por ejemplo, para exportar todo el contenido de la tabla entries en la base de datos guestbook, deberías ingresar lo siguiente:

    SELECT * FROM guestbook.entries;
     Tu consulta debe especificar una tabla en la base de datos especificada. No puedes exportar una base de datos completa en formato CSV.

  9. Haz clic en Exportar para comenzar la exportación.
  10. Se abrirá el cuadro de diálogo ¿Exportar base de datos? con un mensaje que indica que el proceso de exportación puede tomar una hora o más en el caso de las bases de datos grandes. Durante la exportación, la única operación que puedes realizar en la instancia es visualizar la información. Una vez que comience la exportación, puedes cancelar la operación. Si es un buen momento para comenzar una exportación, haz clic en Exportar. De lo contrario, haz clic en Cancelar.

gcloud

  1. Crea un bucket de Cloud Storage.

  2. Sube el archivo a tu bucket.

    Para obtener ayuda con la carga de archivos en buckets, consulta Sube objetos.

  3. Busca la cuenta de servicio de la instancia de Cloud SQL desde la que exportas. Puedes hacerlo ejecutando el comando gcloud sql instances describe. Busca el campo serviceAccountEmailAddress en el resultado. 
    gcloud sql instances describe INSTANCE_NAME
  4. Usa gcloud storage buckets add-iam-policy-binding para otorgar el rol de IAM storage.objectAdmin a la cuenta de servicio de la instancia de Cloud SQL. Para obtener ayuda con la configuración de permisos de IAM, consulta Usa permisos de IAM.
  5. Exporta la base de datos: 
    gcloud sql export csv INSTANCE_NAME gs://BUCKET_NAME/FILE_NAME \
--database=DATABASE_NAME \
--offload \
--query=SELECT_QUERY

    Para obtener información sobre el uso del comando export csv, consulta la página de referencia del comando sql export csv.

  6. Si no necesitas retener la función de IAM que configuraste antes, revócala ahora.

REST v1

  1. Crea un bucket para la exportación: 
    gcloud storage buckets create gs://BUCKET_NAME --location=LOCATION_NAME --project=PROJECT_NAME

    Este paso no es obligatorio, pero se recomienda para no habilitar el acceso a otros datos.

  2. Otórgale a tu instancia la función de IAM legacyBucketWriter para el depósito. Para obtener ayuda con la configuración de permisos de IAM, consulta Usa permisos de IAM.

  3. Exporta tu base de datos:

    Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

    • project-id: el ID del proyecto
    • instance-id: el ID de la instancia
    • bucket_name: El nombre del depósito de Cloud Storage
    • path_to_csv_file: La ruta de acceso al archivo CSV
    • database_name: El nombre de una base de datos dentro de la instancia de Cloud SQL
    • offload: Habilita la exportación sin servidores. Configúralo como true para usar la exportación sin servidores.
    • select_query: La consulta de SQL para la exportación (opcional)
    • escape_character: Es el carácter que debe aparecer antes de un carácter de datos que se debe escapar. El valor de este argumento debe ser un carácter en el código ASCII de Hex. Por ejemplo, “22” representa comillas dobles. (opcional)
    • quote_character:El carácter que encierra valores de columnas que tienen un tipo de datos de string. El valor de este argumento debe ser un carácter en el código ASCII de Hex. Por ejemplo, “22” representa comillas dobles. (opcional)
    • fields_terminated_by: El carácter que divide los valores de la columna. El valor de este argumento debe ser un carácter en el código ASCII de Hex. Por ejemplo, “2C” representa una coma. (opcional)
    • lines_terminated_by: Es el carácter que divide la línea de registros. El valor de este argumento debe ser un carácter en el código ASCII de Hex. Por ejemplo, “0A” representa una línea nueva. (opcional)

    Método HTTP y URL: 

    POST https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id/export

    Cuerpo JSON de la solicitud:

    {
 "exportContext":
   {
      "fileType": "CSV",
      "uri": "gs://bucket_name/path_to_csv_file",
      "databases": ["database_name"],
      "offload": true | false
      "csvExportOptions":
       {
           "selectQuery":"select_query",
           "escapeCharacter":"escape_character",
           "quoteCharacter":"quote_character",
           "fieldsTerminatedBy":"fields_terminated_by",
           "linesTerminatedBy":"lines_terminated_by"
       }
   }
}

    Para enviar tu solicitud, expande una de estas opciones:

    Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

    Debes especificar de manera exacta una base de datos con la propiedad databases y, si la consulta de selección especifica una base de datos, debe ser la misma.

  4. Si no necesitas conservar los permisos de IAM que configuraste, quítalos ahora.
Si quieres obtener una lista completa de los parámetros de esta solicitud, consulta la página instances:export.

REST v1beta4

  1. Crea un bucket para la exportación: 
    gcloud storage buckets create gs://BUCKET_NAME --location=LOCATION_NAME --project=PROJECT_NAME

    Este paso no es obligatorio, pero se recomienda para no habilitar el acceso a otros datos.

  2. Otórgale a tu instancia la función de IAM storage.objectAdmin para el depósito. Para obtener ayuda con la configuración de permisos de IAM, consulta Usa permisos de IAM.

  3. Exporta tu base de datos:

    Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

    • project-id: el ID del proyecto
    • instance-id: el ID de la instancia
    • bucket_name: El nombre del depósito de Cloud Storage
    • path_to_csv_file: La ruta de acceso al archivo CSV
    • database_name: El nombre de una base de datos dentro de la instancia de Cloud SQL
    • offload: Habilita la exportación sin servidores. Configúralo como true para usar la exportación sin servidores.
    • select_query: La consulta de SQL para la exportación (opcional)
    • escape_character: Es el carácter que debe aparecer antes de un carácter de datos que se debe escapar. El valor de este argumento debe tener el formato hexadecimal ASCII. Por ejemplo, “22” representa comillas dobles. (opcional)
    • quote_character: Es el carácter que encierra valores de columnas que tienen un tipo de datos de string. El valor de este argumento debe tener el formato hexadecimal ASCII. Por ejemplo, “22” representa comillas dobles. (opcional)
    • fields_terminated_by: El carácter que divide los valores de la columna. El valor de este argumento debe tener el formato hexadecimal ASCII. Por ejemplo, “2C” representa una coma. (opcional)
    • lines_terminated_by: Es el carácter que divide la línea de registros. El valor de este argumento debe tener el formato hexadecimal ASCII. Por ejemplo, “0A” representa una línea nueva. (opcional)

    Método HTTP y URL: 

    POST https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id/export

    Cuerpo JSON de la solicitud:

    {
 "exportContext":
   {
      "fileType": "CSV",
      "uri": "gs://bucket_name/path_to_csv_file",
      "databases": ["database_name"],
      "offload": true | false
      "csvExportOptions":
       {
           "selectQuery": "select_query",
           "escapeCharacter":  "escape_character",
           "quoteCharacter": "quote_character",
           "fieldsTerminatedBy": "fields_terminated_by",
           "linesTerminatedBy": "lines_terminated_by"
       }
   }
}

    Para enviar tu solicitud, expande una de estas opciones:

    Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

    Debes especificar de manera exacta una base de datos con la propiedad databases y, si la consulta de selección especifica una base de datos, debe ser la misma.

  4. Si no necesitas retener la función de IAM que configuraste antes, revócala ahora.
Si quieres obtener una lista completa de los parámetros de esta solicitud, consulta la página instances:export.

Personaliza el formato de un archivo de exportación CSV

Puedes usar gcloud o la API de REST para personalizar el formato de archivo CSV. Cuando realizas una exportación, puedes especificar las siguientes opciones de formato:

Opción CSV Valor predeterminado Marca de gcloud Propiedad de la API de REST Descripción
Escape

"5C"

Código hexadecimal ASCII para el separador de archivos.

--escape escapeCharacter

Carácter que aparece antes de un carácter de datos que se debe escapar.

Disponible solo para MySQL y PostgreSQL.

Cotización

"22"

Código hexadecimal ASCII para comillas dobles.

--quote quoteCharacter

Es el carácter que encierra valores de columnas que tienen un tipo de datos de string.

Disponible solo para MySQL y PostgreSQL.

Delimitador de campos

"2C"

Código hexadecimal ASCII para coma.

--fields-terminated-by fieldsTerminatedBy

Carácter que divide los valores de la columna.

Disponible solo para MySQL y PostgreSQL.

Carácter de salto de línea

"0A"

Código hexadecimal ASCII para un salto de línea.

--lines-terminated-by linesTerminatedBy

Carácter que divide los registros de línea

Disponible solo para MySQL.

Por ejemplo, un comando de gcloud con todos estos argumentos podría ser similar al siguiente:

gcloud sql export csv INSTANCE_NAME gs://BUCKET_NAME/FILE_NAME \
--database=DATABASE_NAME \
--offload \
--query=SELECT_QUERY \
--quote="22" \
--escape="5C" \
--fields-terminated-by="2C" \
--lines-terminated-by="0A"

El cuerpo de la solicitud a la API de REST equivalente se vería así:

{
 "exportContext":
   {
      "fileType": "CSV",
      "uri": "gs://bucket_name/path_to_csv_file",
      "databases": ["DATABASE_NAME"],
      "offload": true,
      "csvExportOptions":
       {
           "selectQuery": "SELECT_QUERY",
           "escapeCharacter":  "5C",
           "quoteCharacter": "22",
           "fieldsTerminatedBy": "2C",
           "linesTerminatedBy": "0A"
       }
   }
}

La exportación a CSV crea una salida CSV estándar de forma predeterminada. Si necesitas aún más opciones de las que proporciona Cloud SQL, puedes usar la siguiente sentencia en un cliente psql:

      \copy [table_name] TO '[csv_file_name].csv' WITH
          (FORMAT csv, ESCAPE '[escape_character]', QUOTE '[quote_character]',
          DELIMITER '[delimiter_character]', ENCODING 'UTF8', NULL '[null_marker_string]');

Importa datos a Cloud SQL para PostgreSQL

Roles y permisos obligatorios para importar a Cloud SQL para PostgreSQL

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

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

  • El rol de IAM 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 IAM, consulta Identity and Access Management.

Importa datos de un archivo CSV a Cloud SQL para PostgreSQL

Requisitos de formato de archivo CSV

Los archivos CSV deben tener una línea por cada fila de datos y usar campos separados por comas.

Para importar datos a una instancia de Cloud SQL con un archivo CSV, sigue estos pasos:

Console

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

    Ir a Instancias de Cloud SQL

  2. Para abrir la página de Descripción general de una instancia, haz clic en su nombre.
  3. Haz clic en Importar.
  4. En la sección Elige el archivo del cual deseas importar datos, ingresa la ruta de acceso al bucket y el archivo CSV que se usará para la importación. O bien, navega al archivo mediante estos pasos:
    1. Haga clic en Browse.
    2. En la sección Ubicación, haz doble clic en el nombre del bucket en la lista.
    3. Selecciona el archivo de la lista.
    4. Haz clic en Seleccionar.

    Puedes importar un archivo comprimido (.gz) o uno sin comprimir (.csv).

  5. En la sección Formato, selecciona CSV.
  6. Especifica las opciones de Base de datos y Tabla en la instancia de Cloud SQL en la que deseas importar el archivo CSV.
  7. De manera opcional, puedes especificar un usuario para la operación de importación.
  8. Haz clic en Importar para comenzar la importación.

gcloud

  1. Crea un bucket de Cloud Storage.

  2. Sube el archivo a tu bucket.

    Para obtener ayuda con la carga de archivos en buckets, consulta Sube objetos.

  3. Sube datos del archivo CSV al depósito.
  4. Identifica la cuenta de servicio de la instancia de Cloud SQL desde la que exportas. Puedes hacerlo mediante la ejecución del comando gcloud sql instances describe con el nombre de la instancia. Busca el campo serviceAccountEmailAddress en el resultado. 
    gcloud sql instances describe INSTANCE_NAME
  5. Copia el campo serviceAccountEmailAddress.
  6. Usa gcloud storage buckets add-iam-policy-binding para otorgar el rol de IAM storage.objectAdmin a la cuenta de servicio de la instancia de Cloud SQL del bucket. Para obtener ayuda con la configuración de permisos de IAM, consulta la sección sobre cómo usar permisos de IAM.
  7. Importa el archivo:
    gcloud sql import csv INSTANCE_NAME gs://BUCKET_NAME/FILE_NAME \
--database=DATABASE_NAME \
--table=TABLE_NAME

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

  8. Si no necesitas conservar los permisos de IAM que configuraste antes, quítalos con gcloud storage buckets remove-iam-policy-binding.

REST v1

  1. Crea un bucket de Cloud Storage.

  2. Sube el archivo a tu bucket.

    Para obtener ayuda con la carga de archivos en buckets, consulta Sube objetos.

  3. Otórgale a la instancia las funciones de Cloud IAM legacyBucketWriter y objectViewer para el bucket. Para obtener ayuda con la configuración de permisos de IAM, consulta Usa permisos de IAM.
  4. Importa el archivo:

    Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

    • project-id: el ID del proyecto
    • instance-id: el ID de la instancia
    • bucket_name: El nombre del depósito de Cloud Storage
    • path_to_csv_file: La ruta de acceso al archivo CSV
    • database_name: El nombre de una base de datos dentro de la instancia de Cloud SQL
    • table_name: El nombre de la tabla de la base de datos
    • escape_character: Es el carácter que debe aparecer antes de un carácter de datos que se debe escapar. El valor de este argumento debe ser un carácter en el código ASCII de Hex. Por ejemplo, “22” representa comillas dobles. (opcional)
    • quote_character: Es el carácter que encierra valores de columnas que tienen un tipo de datos de string. El valor de este argumento debe ser un carácter en el código ASCII de Hex. Por ejemplo, “22” representa comillas dobles. (opcional)
    • fields_terminated_by: El carácter que divide los valores de la columna. El valor de este argumento debe ser un carácter en el código ASCII de Hex. Por ejemplo, “2C” representa una coma. (opcional)
    • lines_terminated_by: Es el carácter que divide la línea de registros. El valor de este argumento debe ser un carácter en el código ASCII de Hex. Por ejemplo, “0A” representa una línea nueva. (opcional)

    Método HTTP y URL: 

    POST https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id/import

    Cuerpo JSON de la solicitud:

    {
 "importContext":
   {
      "fileType": "CSV",
      "uri": "gs://bucket_name/path_to_csv_file",
      "database": "database_name",
      "csvImportOptions":
       {
         "table": "table_name",
         "escapeCharacter": "escape_character",
         "quoteCharacter": "quote_character",
         "fieldsTerminatedBy": "fields_terminated_by",
         "linesTerminatedBy": "lines_terminated_by"
       }
   }
}

    Para enviar tu solicitud, expande una de estas opciones:

    Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

    Si quieres obtener una lista completa de parámetros de esta solicitud, consulta la página instances:import.
  5. Si no necesitas conservar los permisos de IAM que configuraste antes, quítalos.

REST v1beta4

  1. Crea un bucket de Cloud Storage.

  2. Sube el archivo a tu bucket.

    Para obtener ayuda con la carga de archivos en buckets, consulta Sube objetos.

  3. Otórgale a tu instancia la función de IAM storage.objectAdmin para el depósito. Para obtener ayuda con la configuración de permisos de IAM, consulta la sección sobre cómo usar permisos de IAM.
  4. Importa el archivo:

    Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

    • project-id: el ID del proyecto
    • instance-id: el ID de la instancia
    • bucket_name: El nombre del depósito de Cloud Storage
    • path_to_csv_file: La ruta de acceso al archivo CSV
    • database_name: El nombre de una base de datos dentro de la instancia de Cloud SQL
    • table_name: El nombre de la tabla de la base de datos
    • escape_character: Es el carácter que debe aparecer antes de un carácter de datos que se debe escapar. El valor de este argumento debe tener el formato hexadecimal ASCII. Por ejemplo, “22” representa comillas dobles. (opcional)
    • quote_character: Es el carácter que encierra valores de columnas que tienen un tipo de datos de string. El valor de este argumento debe tener el formato hexadecimal ASCII. Por ejemplo, “22” representa comillas dobles. (opcional)
    • fields_terminated_by: El carácter que divide los valores de la columna. El valor de este argumento debe tener el formato hexadecimal ASCII. Por ejemplo, “2C” representa una coma. (opcional)
    • lines_terminated_by: Es el carácter que divide la línea de registros. El valor de este argumento debe tener el formato hexadecimal ASCII. Por ejemplo, “0A” representa una línea nueva. (opcional)

    Método HTTP y URL: 

    POST https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id/import

    Cuerpo JSON de la solicitud:

    {
 "importContext":
   {
      "fileType": "CSV",
      "uri": "gs://bucket_name/path_to_csv_file",
      "database": "database_name",
      "csvImportOptions":
       {
         "table": "table_name",
         "escapeCharacter": "escape_character",
         "quoteCharacter": "quote_character",
         "fieldsTerminatedBy": "fields_terminated_by",
         "linesTerminatedBy": "lines_terminated_by"
       }
   }
}

    Para enviar tu solicitud, expande una de estas opciones:

    Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

    Si quieres obtener una lista completa de parámetros de esta solicitud, consulta la página instances:import.
  5. Si no necesitas conservar los permisos de IAM que configuraste antes, quítalos.

Personaliza el formato de un archivo CSV para Cloud SQL para PostgreSQL

Puedes usar gcloud o la API de REST para personalizar el formato de archivo CSV.

A continuación, se muestra un comando gcloud de muestra:

gcloud sql import csv INSTANCE_NAME gs://BUCKET_NAME/FILE_NAME \
--database=DATABASE_NAME \
--table=TABLE_NAME \
--quote="22" \
--escape="5C" \
--fields-terminated-by="2C" \
--lines-terminated-by="0A"

El cuerpo de la solicitud a la API de REST equivalente se vería así:

{
 "importContext":
   {
      "fileType": "CSV",
      "uri": "gs://bucket_name/path_to_csv_file",
      "database": ["DATABASE_NAME"],
      "csvImportOptions":
       {
           "table": "TABLE_NAME",
           "escapeCharacter":  "5C",
           "quoteCharacter": "22",
           "fieldsTerminatedBy": "2C",
           "linesTerminatedBy": "0A"
       }
   }
}

Si obtienes un error como ERROR_RDBMS, asegúrate de que la tabla exista. Si la tabla existe, confirma que tienes los permisos correctos en el depósito. Si quieres obtener ayuda para configurar el control de acceso en Cloud Storage, consulta Crea y administra listas de control de acceso (LCA).

Para ver cómo se realiza la solicitud subyacente a la API de REST de esta tarea, consulta Explorador de API en la página instances:import.

¿Qué sigue?