Cómo exportar un archivo CSV

Para extraer datos de tablas o consultas y usarlos en herramientas y entornos externos, puedes exportar datos de clústeres de AlloyDB para PostgreSQL a un bucket de Cloud Storage en formato CSV.

Para obtener información sobre cómo migrar una base de datos completa de un servidor de base de datos compatible a una instancia nueva de AlloyDB, consulta Migra una base de datos a AlloyDB con Database Migration Service. Si exportas porque quieres crear una instancia nueva desde el archivo exportado, considera restablecer un clúster desde una copia de seguridad almacenada.

Puedes cancelar la exportación de datos desde clústeres de AlloyDB para PostgreSQL. Para obtener más información, consulta Cancela una operación de exportación.

Antes de comenzar

• Antes de comenzar una operación de exportación, ten en cuenta que estas operaciones usan recursos de bases de datos, pero no interfieren en las operaciones normales de las bases de datos, a menos que la instancia no cuente con el aprovisionamiento suficiente.
• SELECT_QUERY puede contener comentarios o espacios en blanco iniciales y finales. Los comentarios se ignoran y los espacios en blanco se recortan antes de ejecutar la consulta de exportación.
• Se aplican cargos por transferencia de datos entre regiones cuando el bucket de destino se encuentra en una región diferente a la del clúster de origen. Para obtener más información, consulta Precios de AlloyDB para PostgreSQL.
• Se pueden ejecutar varias operaciones de exportación en paralelo.
• La compresión se habilita si el nombre del objeto termina con la extensión .gz. Luego, el objeto se exporta en formato .gz a Cloud Storage.
• Solo se permiten caracteres ASCII en código hexadecimal (con o sin el prefijo 0x) para los valores de caracteres en las opciones de CSV, como field_delimiter, quote_character y escape_character.

Roles y permisos necesarios para exportar desde AlloyDB

Para exportar datos de AlloyDB a Cloud Storage, el usuario que inicia la exportación debe tener uno de los siguientes roles de Identity and Access Management (IAM):

• El rol de administrador de AlloyDB (roles/alloydb.admin)
• Un rol personalizado que incluya los siguientes permisos:
  • alloydb.clusters.get
  • alloydb.clusters.export

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

• El rol de IAM storage.objectAdmin
• Un rol personalizado que incluya los siguientes permisos:
  • storage.objects.create

Para obtener ayuda con los roles de IAM, consulta Identity and Access Management.

Exportar datos a un archivo CSV

Durante una exportación de CSV, puedes especificar los esquemas que deseas exportar. Todos los esquemas a nivel de la base de datos se pueden exportar.

Nota: AlloyDB usa comillas dobles (valor hexadecimal 22) como el carácter de escape predeterminado. Esto puede ser un problema para las bases de datos en las que los valores de NULL se ingresan como literales de cadena.

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

gcloud

1. Crea buckets de Cloud Storage.

2. Usa gcloud storage buckets add-iam-policy-binding para otorgar el rol de IAM storage.objectAdmin a la cuenta de servicio de AlloyDB para el bucket. El formato de la cuenta de servicio es el siguiente:

   service-PROJECT_NUMBER@gcp-sa-alloydb.

   Para obtener ayuda con la configuración de permisos de IAM, consulta la sección sobre cómo usar permisos de IAM.

   Nota: Si un objeto existente tiene el mismo nombre que el que se exporta al bucket de Cloud Storage, otorgar el rol objectAdmin a la cuenta de servicio hace que se reemplace el objeto más antiguo. Para evitar esto, puedes otorgar a la cuenta de servicio el permiso menos privilegiado storage.objectCreator, que no puede reemplazar objetos existentes.

3. Exporta la base de datos a tu bucket de Cloud Storage.

   Ejecuta el comando para exportar a CSV: gcloud alloydb clusters export.

   En la siguiente lista, se describen las opciones para exportar datos en formato CSV:

   • --select-query (obligatorio): Es la consulta de selección que se usa para extraer los datos.
   Nota: Mientras está en tránsito, la consulta puede procesarse en ubicaciones intermedias, excepto la ubicación de la instancia de destino.
   • --async (opcional): Se muestra de inmediato, sin esperar a que se complete la operación en curso.
   • --field-delimiter (opcional): Especifica el carácter que separa las columnas en cada fila (línea) del archivo. El valor predeterminado es una coma. El valor de este argumento debe ser un carácter en código ASCII hexadecimal.
   • --quote-character (opcional): Especifica el carácter de comillas que se usará cuando se entrecomille un valor de datos. El valor predeterminado es una comilla doble. El valor de este argumento debe ser un carácter en código ASCII hexadecimal.
   • --escape-character (opcional): Especifica el carácter que debe aparecer antes de un carácter de datos que se debe escapar. El valor predeterminado es el mismo que --quote-character. El valor de este argumento debe ser un carácter en código ASCII hexadecimal.

   Para usar estas funciones, incluye estas opciones en el comando de gcloud CLI.

   De lo contrario, quita estos parámetros del siguiente comando:

   gcloud alloydb clusters export CLUSTER_NAME \
     --region=REGION \
     --database=DATABASE_NAME \
     --gcs-uri="gs://BUCKET_NAME/OBJECT_NAME" \
     --select-query=SELECT_QUERY \
     --field-delimiter=FIELD_DELIMITER \
     --quote-character=QUOTE_CHARACTER \
     --escape-character=ESCAPE_CHARACTER \
     --csv

4. Si no necesitas conservar el rol de IAM que configuraste antes, revócalo.

REST v1

1. Crea un bucket para la exportación:

   gcloud storage buckets create gs://BUCKET_NAME --location=LOCATION_NAME --project=PROJECT_NAME

2. Usa gcloud storage buckets add-iam-policy-binding para otorgar el rol de IAM storage.objectAdmin a la cuenta de servicio de AlloyDB para el bucket. El formato de la cuenta de servicio es el siguiente:

   service-PROJECT_NUMBER@gcp-sa-alloydb.

   Para obtener ayuda con la configuración de permisos de IAM, consulta la sección sobre cómo usar permisos de IAM.

   Nota: En el caso de que ya exista un objeto con el mismo nombre que el que se exporta en el bucket de Cloud Storage, otorgar el rol objectAdmin a la cuenta de servicio hará que se reemplace el objeto más antiguo. Para evitar esto, puedes otorgar el permiso con menos privilegios storage.objectCreator a la cuenta de servicio, que no puede reemplazar los objetos existentes.

3. Exporta tu base de datos.
   

   Usa el siguiente método HTTP y la URL:

   POST https://alloydb.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/clusters/CLUSTER_ID:export

   Antes de usar cualquiera de los datos de solicitud, realiza los siguientes reemplazos:

   • PROJECT_ID: Es el ID del proyecto.
   • REGION: Es la región en la que se implementa el clúster de AlloyDB.
   • CLUSTER_ID: Es el ID del clúster.
   • BUCKET_NAME: Es el nombre del bucket de Cloud Storage.
   • PATH_TO_CSV_FILE: Es la ruta de acceso al archivo CSV.
   • DATABASE_NAME: Es el nombre de una base de datos dentro del clúster de AlloyDB.

   • SELECT_QUERY: Es la consulta en SQL para la exportación.

     Nota: Mientras está en tránsito, la consulta puede procesarse en ubicaciones intermedias, excepto la ubicación de la instancia de destino.

   • ESCAPE_CHARACTER (opcional): 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 código ASCII hexadecimal. Por ejemplo, 22 representa una comilla doble.

   • QUOTE_CHARACTER (opcional): Es el carácter que encierra los valores de las columnas que tienen un tipo de datos de cadena. El valor de este argumento debe ser un carácter en código ASCII hexadecimal. Por ejemplo, 22 representa una comilla doble.

   • FIELD_DELIMITER (opcional): Es el carácter que divide los valores de las columnas. El valor de este argumento debe ser un carácter en código ASCII hexadecimal. Por ejemplo, 2C representa una coma.

   Cuerpo JSON de la solicitud:

   {
     "gcs_destination": {
       "uri": "gs://BUCKET_NAME/PATH_TO_CSV_FILE"
     },
     "database": "DATABASE_NAME",
     "csv_export_options": {
       "select_query": "SELECT_QUERY",
       "escape_character": "ESCAPE_CHARACTER",
       "quote_character": "QUOTE_CHARACTER",
       "field_delimiter": "FIELD_DELIMITER"
     }
   }
   

   Para enviar tu solicitud, usa una de estas opciones:

curl (Linux, macOS o Cloud Shell)

En el siguiente comando, se supone que accediste a Google Cloud CLI con tu cuenta de usuario ejecutando gcloud init o gcloud auth login, o usando Cloud Shell, que accede automáticamente a gcloud CLI. Para comprobar la cuenta activa, ejecuta 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/REGION/clusters/CLUSTER_ID:export"
  

PowerShell (Windows)

En el siguiente comando, se supone que accediste a Google Cloud CLI con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login, o con Cloud Shell, que accede de forma automática a gcloud CLI. Para comprobar la cuenta activa, ejecuta 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/REGION/clusters/CLUSTER_ID:export"| Select-Object -Expand Content
  

Recibirás una respuesta JSON similar a la que se muestra a continuación:

Respuesta

    {
     "name": "projects/PROJECT_ID/locations/REGION/operations/OPERATION_ID",
     "metadata": {
      "@type": "type.googleapis.com/google.cloud.alloydb.v1.OperationMetadata",
      "createTime": "2024-09-17T06:05:31.244428646Z",
      "target": "projects/PROJECT_ID/locations/REGION/clusters/TARGET_CLUSTER",
      "verb": "export",
      "requestedCancellation": false,
      "apiVersion": "v1"
     },
     "done": false
    }
  

Si no necesitas conservar los permisos de IAM que configuraste antes, quítalos.

Para obtener la lista completa de los parámetros de esta solicitud, consulta clusters.export.

Personaliza el formato de un archivo de exportación CSV

Puedes usar gcloud CLI 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 de CSV	Valor predeterminado	Marca de gcloud	Propiedad de la API de REST	Descripción
Escape	El valor predeterminado es el mismo que el de QUOTE.	--escape-character	escape_character	Es el carácter que aparece antes de un carácter de datos que se debe escapar.
Cotización	"22" Código hexadecimal ASCII para comillas dobles.	--quote-character	quote_character	Especifica el carácter de comillas que se usará cuando se entrecomille un valor de datos.
Delimitador de campos	"2C" Código hexadecimal ASCII para la coma.	--field-delimiter	field_delimiter	Carácter que divide los valores de la columna.

Usa los siguientes ejemplos de gcloud CLI y la API de REST para personalizar el formato de archivo de exportación CSV:

gcloud

gcloud alloydb clusters export CLUSTER_NAME \
  --region=REGION \
  --database=DATABASE_NAME \
  --gcs-uri='gs://BUCKET_NAME/PATH_TO_CSV_FILE' \
  --select-query=SELECT_QUERY \
  --field-delimiter='2C' \
  --quote-character='22' \
  --escape-character='5C' \
  --csv

REST v1

El cuerpo de la solicitud a la API de REST equivalente es similar al siguiente:

{
  "gcs_destination": {
    "uri": "gs://BUCKET_NAME/PATH_TO_CSV_FILE"
  },
  "database": "DATABASE_NAME",
  "csv_export_options": {
    "select_query": "SELECT_QUERY",
    "escape_character": "5C",
    "quote_character": "22",
    "field_delimiter": "2C"
  }
}

De forma predeterminada, la exportación a CSV crea una salida CSV estándar. Si necesitas más opciones que las que proporciona AlloyDB, puedes usar la siguiente sentencia en un cliente de 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');

¿Qué sigue?

• Obtén información para exportar un archivo de volcado de SQL.
• Cancela una operación de exportación.