Carga datos de PostgreSQL en BigQuery

Para programar transferencias de datos recurrentes de PostgreSQL a BigQuery, puedes crear una configuración de transferencia para especificar qué objetos de datos transferir y con qué frecuencia programar la transferencia de datos. Después de configurar la transferencia, el Servicio de transferencia de datos de BigQuery transfiere los datos más recientes a una tabla de BigQuery según el programa especificado.

Para obtener información general sobre las transferencias de PostgreSQL, incluidas las opciones de configuración, consulta Introducción a las transferencias de datos de PostgreSQL.

Limitaciones

Las transferencias de datos de PostgreSQL están sujetas a las siguientes limitaciones:

  • La cantidad máxima de ejecuciones de transferencias simultáneas a una sola base de datos de PostgreSQL está determinada por la cantidad máxima de conexiones simultáneas que admite la base de datos de PostgreSQL. La cantidad de trabajos de transferencia simultáneos debe limitarse a un valor inferior a la cantidad máxima de conexiones simultáneas que admite la base de datos de PostgreSQL.

  • Una sola configuración de transferencia solo puede admitir una ejecución de transferencia de datos en un momento determinado. Cuando se programa una segunda transferencia de datos para que se ejecute antes de que se complete la primera, solo se completa la primera transferencia de datos, mientras que se omiten las demás transferencias de datos que se superpongan con la primera.

    Para evitar transferencias omitidas dentro de una sola configuración de transferencia, te recomendamos que aumentes la duración del tiempo entre las transferencias de datos grandes configurando la frecuencia de repetición.

  • Durante una transferencia de datos, el conector de PostgreSQL identifica las columnas clave indexadas y particionadas para transferir tus datos en lotes paralelos. Por este motivo, te recomendamos que especifiques columnas de clave primaria o que uses columnas indexadas en tu tabla para mejorar el rendimiento y reducir la tasa de errores en tus transferencias de datos. Ten en cuenta lo siguiente:

    • Si tienes restricciones de clave primaria o indexadas, solo se admiten los siguientes tipos de columnas para crear lotes paralelos:
      • INTEGER
      • TINYINT
      • SMALLINT
      • FLOAT
      • REAL
      • DOUBLE
      • NUMERIC
      • BIGINT
      • DECIMAL
      • DATE
    • Las transferencias de datos de PostgreSQL que no usan clave primaria ni columnas indexadas no pueden admitir más de 2,000,000 de registros por tabla.

Limitaciones de la transferencia incremental

Las transferencias incrementales de PostgreSQL están sujetas a las siguientes limitaciones:

  • Solo puedes elegir TIMESTAMP columnas como columnas de marca de agua.
  • La transferencia incremental solo se admite para los recursos con columnas de marcas de agua válidas.
  • Los valores de una columna de marca de agua deben aumentar de forma monótona.
  • Las transferencias incrementales no pueden sincronizar las operaciones de eliminación en la tabla de origen.
  • Una sola configuración de transferencia solo puede admitir la transferencia incremental o completa.
  • No puedes actualizar los objetos de la lista asset después de la primera ejecución de la incorporación incremental.
  • No puedes cambiar el modo de escritura en una configuración de transferencia después de la primera ejecución de la transferencia incremental.
  • No puedes cambiar la columna de marca de agua ni la clave primaria después de la primera ejecución de la carga incremental.
  • La tabla de BigQuery de destino se agrupa con la clave primaria proporcionada y está sujeta a las limitaciones de las tablas agrupadas.

  • Cuando actualizas una configuración de transferencia existente al modo de transferencia incremental por primera vez, la primera transferencia de datos después de esa actualización transfiere todos los datos disponibles de tu fuente de datos. Todas las transferencias de datos incrementales posteriores solo transferirán las filas nuevas y actualizadas de tu fuente de datos.

  • Te recomendamos que crees índices en la columna de marcas de agua. Este conector usa columnas de marcas de agua para los filtros en las transferencias incrementales, por lo que indexar estas columnas puede mejorar el rendimiento.

  • Cuando realices una transferencia incremental, debes usar la asignación de tipos de datos actualizada.

Antes de comenzar

Roles obligatorios

Si quieres configurar las notificaciones de ejecución de transferencias para Pub/Sub, asegúrate de tener el permiso pubsub.topics.setIamPolicy de Identity and Access Management (IAM). Los permisos de Pub/Sub no son necesarios si solo configuras las notificaciones por correo electrónico. Para obtener más información, consulta la sección sobre notificaciones de ejecución del Servicio de transferencia de datos de BigQuery.

Para obtener los permisos que necesitas para crear una transferencia de datos del Servicio de transferencia de datos de BigQuery, pídele a tu administrador que te otorgue el rol de IAM de administrador de BigQuery (roles/bigquery.admin) en tu proyecto. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Este rol predefinido contiene los permisos necesarios para crear una transferencia de datos del Servicio de transferencia de datos de BigQuery. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:

Permisos necesarios

Se requieren los siguientes permisos para crear una transferencia de datos del Servicio de transferencia de datos de BigQuery:

  • Permisos del Servicio de transferencia de datos de BigQuery:
    • bigquery.transfers.update
    • bigquery.transfers.get
  • Permisos de BigQuery:
    • bigquery.datasets.get
    • bigquery.datasets.getIamPolicy
    • bigquery.datasets.update
    • bigquery.datasets.setIamPolicy
    • bigquery.jobs.create

También puedes obtener estos permisos con roles personalizados o con otros roles predefinidos.

Para obtener más información, consulta Cómo otorgar acceso a bigquery.admin.

Conexiones de red

Si no hay una dirección IP pública disponible para la conexión de la base de datos de PostgreSQL, debes configurar un adjunto de red.

Para obtener instrucciones detalladas sobre la configuración de red necesaria, consulta los siguientes documentos:

Configura una transferencia de datos de PostgreSQL

Para agregar datos de PostgreSQL a BigQuery, configura una transferencia con una de las siguientes opciones:

Console

  1. Ve a la página Transferencia de datos.

    Ir a Transferencias de datos

  2. Haz clic en Crear transferencia.

  3. En la sección Tipo de fuente, en Fuente, selecciona PostgreSQL.

  4. En la sección Detalles de fuente de datos, haz lo siguiente:

    • En Adjunto de red, selecciona un adjunto de red existente o haz clic en Crear adjunto de red. Para obtener más información, consulta la sección Conexiones de red de este documento.
    • En Host, ingresa el nombre de host o la dirección IP del servidor de la base de datos de PostgreSQL.
    • En Número de puerto, ingresa el número de puerto del servidor de la base de datos de PostgreSQL.
    • En Nombre de la base de datos, ingresa el nombre de la base de datos de PostgreSQL.
    • En Nombre de usuario, ingresa el nombre de usuario del usuario de PostgreSQL que inicia la conexión a la base de datos de PostgreSQL.
    • En Contraseña, ingresa la contraseña del usuario de PostgreSQL que inicia la conexión a la base de datos de PostgreSQL.
    • En Modo TLS, selecciona una opción del menú. Para obtener más información sobre los modos de TLS, consulta Configuración de TLS.
    • En Certificado PEM de confianza, ingresa el certificado público de la autoridad certificadora (AC) que emitió el certificado TLS del servidor de la base de datos. Para obtener más información, consulta Certificado de servidor de confianza (PEM).
    • En Enable legacy mapping, selecciona true (predeterminado) para usar la asignación de tipos de datos heredada. Selecciona false para usar la asignación de tipos de datos actualizada. Si realizas una transferencia incremental, este valor debe ser false. Para obtener más información sobre las actualizaciones de asignación de tipos de datos, consulta 16 de marzo de 2027.
    • En Ingestion type, selecciona Full o Incremental.

    • En Objetos de PostgreSQL para transferir, haz clic en Explorar.

      Selecciona los objetos que se transferirán al conjunto de datos de destino de BigQuery. También puedes ingresar de forma manual cualquier objeto que quieras incluir en la transferencia de datos en este campo.

      • Si seleccionaste Append como modo de escritura incremental, debes seleccionar una columna como columna de marca de agua.
      • Si seleccionaste Upsert como modo de escritura incremental, debes seleccionar una columna como columna de marca de agua y, luego, seleccionar una o más columnas como clave primaria.

  5. En la sección Nombre de la configuración de transferencia, en Nombre visible, ingresa un nombre para la transferencia. El nombre de la transferencia puede ser cualquier valor que te permita identificarla si necesitas modificarla más adelante.

  6. En la sección Opciones de programación, haz lo siguiente:

    • Selecciona una frecuencia de repetición. Si seleccionas la opción Horas, Días (opción predeterminada), Semanas o Meses, también debes especificar una frecuencia. También puedes seleccionar la opción Personalizado para crear una frecuencia de repetición más específica. Si seleccionas la opción Según demanda, esta transferencia de datos se ejecuta solo cuando activas la transferencia de forma manual.
    • Si corresponde, selecciona la opción Comenzar ahora o Comenzar a una hora determinada y proporciona una fecha de inicio y una hora de ejecución.

  7. En la sección Configuración de destino, en Conjunto de datos, selecciona el conjunto de datos que creaste para almacenar tus datos o haz clic en Crear un conjunto de datos nuevo y crea uno para usarlo como conjunto de datos de destino.

  8. Opcional: En la sección Opciones de notificación, haz lo siguiente:

    • Para habilitar las notificaciones por correo electrónico, haz clic en el botón de activación Notificaciones por correo electrónico y colócalo en la posición de activado. Cuando habilitas esta opción, el administrador de transferencias recibe una notificación por correo electrónico cuando falla una ejecución de transferencia.
    • Para configurar las notificaciones de ejecución de Pub/Sub para tu transferencia, haz clic en el botón de activación Notificaciones de Pub/Sub para activarlo. Puedes seleccionar el nombre del tema o hacer clic en Crear un tema para crear uno.

  9. Haz clic en Guardar.

bq

Ingresa el comando bq mk y suministra la marca de creación de transferencias --transfer_config:

bq mk
    --transfer_config
    --project_id=PROJECT_ID
    --data_source=DATA_SOURCE
    --display_name=DISPLAY_NAME
    --target_dataset=DATASET
    --params='PARAMETERS'

Reemplaza lo siguiente:

  • PROJECT_ID (opcional): Tu ID del proyecto de Google Cloud . Si no se proporciona la marca --project_id para especificar un proyecto en particular, se usa el proyecto predeterminado.
  • DATA_SOURCE: Es la fuente de datos, que es postgresql.
  • DISPLAY_NAME: el nombre visible de la configuración de transferencia de datos. El nombre de la transferencia puede ser cualquier valor que te permita identificarla con facilidad si es necesario hacerle modificaciones más tarde.
  • DATASET: el conjunto de datos de destino para la configuración de transferencia de datos.

  • PARAMETERS son los parámetros de la configuración de transferencia creada en formato JSON. Por ejemplo: --params='{"param":"param_value"}' Los siguientes son los parámetros para una transferencia de PostgreSQL:

    • connector.networkAttachment (opcional): Nombre del adjunto de red para conectarse a la base de datos de PostgreSQL.
    • connector.database: Es el nombre de la base de datos de PostgreSQL.
    • connector.endpoint.host: Es el nombre de host o la dirección IP de la base de datos.
    • connector.endpoint.port: Es el número de puerto de la base de datos.
    • connector.authentication.username: Es el nombre de usuario del usuario de la base de datos.
    • connector.authentication.password: Es la contraseña del usuario de la base de datos.
    • connector.tls.mode: Especifica una configuración de TLS para usar con esta transferencia:
      • ENCRYPT_VERIFY_CA_AND_HOST para encriptar datos y verificar la CA y el nombre de host
      • ENCRYPT_VERIFY_CA para encriptar datos y verificar solo la AC
      • ENCRYPT_VERIFY_NONE solo para la encriptación de datos
      • DISABLE para indicar que no hay encriptación ni verificación
    • connector.tls.trustedServerCertificate: (Opcional) Proporciona uno o más certificados codificados con PEM. Solo es obligatorio si connector.tls.mode es ENCRYPT_VERIFY_CA_AND_HOST o ENCRYPT_VERIFY_CA.
    • ingestionType: Especifica full o incremental. Las transferencias incrementales son compatibles con la versión preliminar. Para obtener más información, consulta Transferencias completas o incrementales.
    • writeMode: Especifica WRITE_MODE_APPEND o WRITE_MODE_UPSERT.
    • watermarkColumns: Especifica columnas en tu tabla como columnas de marca de agua. Este campo es obligatorio para las transferencias incrementales.
    • primaryKeys: Especifica columnas en tu tabla como claves primarias. Este campo es obligatorio para las transferencias incrementales.
    • connector.legacyMapping: Se establece en true (predeterminado) para usar la asignación de tipos de datos heredada. Establece el valor en false para usar la asignación de tipos de datos actualizada. Si realizas una transferencia incremental, este valor debe ser false. Para obtener más información sobre las actualizaciones de asignación de tipos de datos, consulta 16 de marzo de 2027.
    • assets: Es una lista de los nombres de las tablas de PostgreSQL que se transferirán desde la base de datos de PostgreSQL como parte de la transferencia.

Por ejemplo, el siguiente comando crea una transferencia de PostgreSQL llamada My Transfer:

bq mk
    --transfer_config
    --target_dataset=mydataset
    --data_source=postgresql
    --display_name='My Transfer'
    --params='{"assets":["DB1/PUBLIC/DEPARTMENT","DB1/PUBLIC/EMPLOYEES"],
        "connector.authentication.username": "User1",
        "connector.authentication.password":"ABC12345",
        "connector.database":"DB1",
        "connector.endpoint.host":"192.168.0.1",
        "connector.endpoint.port":5432,
        "ingestionType":"incremental",
        "writeMode":"WRITE_MODE_APPEND",
        "watermarkColumns":["createdAt","createdAt"],
        "primaryKeys":[['dep_id'], ['report_by','report_title']],
        "connector.tls.mode": "ENCRYPT_VERIFY_CA_AND_HOST",
        "connector.tls.trustedServerCertificate": "PEM-encoded certificate"}'

Cuando especificas varios recursos durante una transferencia incremental, los valores de los campos watermarkColumns y primaryKeys corresponden a la posición de los valores en el campo assets. En el siguiente ejemplo, dep_id corresponde a la tabla DB1/USER1/DEPARTMENT, mientras que report_by y report_title corresponden a la tabla DB1/USER1/EMPLOYEES.

      "primaryKeys":[['dep_id'], ['report_by','report_title']],
      "assets":["DB1/USER1/DEPARTMENT","DB1/USER1/EMPLOYEES"],

API

Usa el método projects.locations.transferConfigs.create y proporciona una instancia del recurso TransferConfig.

Cuando guardas la configuración de transferencia, el conector de PostgreSQL activa automáticamente una ejecución de transferencia según la opción de programación que elijas. Con cada ejecución de transferencia, el conector de PostgreSQL transfiere todos los datos disponibles de PostgreSQL a BigQuery.

Para ejecutar manualmente una transferencia de datos fuera de tu programa habitual, puedes iniciar una ejecución de reabastecimiento.

Solucionar problemas

Si tienes problemas para configurar tu transferencia de datos, consulta Problemas de transferencia de PostgreSQL.

Transferir metadatos

También puedes usar el conector de PostgreSQL para transferir metadatos a Knowledge Catalog. Para obtener más información, consulta Carga metadatos de PostgreSQL en Knowledge Catalog.

¿Qué sigue?