dsp-job-data-migration — Migração de camadas genéricas¶

Guia didático do módulo de camadas geográficas (batch.layers) do job dsp-job-data-migration. Visão geral do job: Visão geral.

O que este módulo faz¶

O job lê tabelas PostGIS extras no banco de origem e replica suas feições no banco geo-target (exibição / WMS).

Você informa as colunas de papel (PK, vínculo com AOI, data de criação, geometria). O job descobre o restante do schema e cria a tabela de destino.

Conceitos importantes¶

Premissa: cada feição pertence a uma área de interesse. A coluna que faz essa ligação na origem é declarada no YAML; no destino ela vira sempre area_of_interest_id.

No wizard do core (adopter-config.yaml), esse campo se chama parent_key e é traduzido para area-of-interest-id-column.

Onde os dados vão parar¶

flowchart LR
  src[("Origem<br/>source")]
  geo[("Geo-target<br/>exibição WMS")]
  dsp[("DSP DB<br/>operacional")]

  src -->|"Jobs fixos<br/>(UA, AOI)"| dsp
  src -->|"Jobs fixos"| geo
  src -->|"Camadas genéricas<br/>(este módulo)"| geo

As camadas genéricas só escrevem no geo-target. O destino vem do layer-name resolvido (se omitido, o nome da tabela de origem), com hífen virando underscore:

geo-target → dsp.<layer_name_normalizado>

Exemplos: origem conservation.rivers sem layer-name → dsp.rivers; layer-name: tipo-a → dsp.tipo_a. A mesma source-table pode aparecer em mais de uma entrada se os destinos forem distintos.

Colunas canônicas no destino: id (varchar(255)), area_of_interest_id (varchar(255)), created_at (timestamptz), updated_at (se houver), label (se houver), geom. Só uma geometria é migrada — a informada em geometry-column.

Ordem de execução¶

As camadas dependem de area_of_interest_id apontar para registros que já existem em dsp.area_of_interest.

1. Unidades administrativas (level-1 → level-2 → level-3)
2. Área de interesse (area-of-interest)
3. Camadas genéricas (layer-jobs)   ← este módulo
4. Cálculo de KPIs (kpi-job)        ← depois das camadas usadas nos temas

Na prática, o JobRunner dos jobs fixos roda antes do runner de camadas (@Order(1) e @Order(2)); o kpiCalculationJob roda depois (@Order(3)). Cada KPI de tema no wizard aponta para o layer-name de uma camada migrada aqui.

Pré-requisitos¶

• Banco de origem com PostGIS e tabelas a migrar
• Banco geo-target acessível (spring.datasource.geo-target)
• Cada tabela de origem com PK simples (uma coluna)
• Coluna de geometria informada no YAML
• Coluna de vínculo com AOI preenchida nas feições
• creation-date-column preenchida (watermark)
• Job de área de interesse já executado (valores de FK válidos)
• Schema Spring Batch criado no dsp-db (data_migration)

Configuração mínima¶

1. Datasource geo-target¶

Além de batch, source e target, configure:

spring:
  datasource:
    geo-target:
      url: jdbc:postgresql://localhost:5432/dsp-geoserver-db
      username: dsp_geo
      password: dsp_geo

2. Declarar as camadas¶

batch:
  layers:
    - source-table: conservation.rivers
      primary-key: feature_id
      area-of-interest-id-column: conservation_unit_id
      creation-date-column: created_at
      geometry-column: geom
      layer-name: rivers
      srid: 4674

3. Habilitar a execução¶

execution-jobs:
  layer-jobs: true

4. Paralelização (opcional)¶

O nome do job segue o padrão layerMigrationJob_ + chave da camada (dsp_<nome_físico>):

parallelization:
  jobs:
    layerMigrationJob_dsp_rivers:
      enabled: true
      thread-pool-size: 2
      chunk-size: 100
      page-size: 1000
      queue-capacity: 100

Se não houver entrada para uma camada, o job usa valores padrão.

Propriedades opcionais¶

Se a tabela destino já existir, o job exige created_at timestamptz nela (CREATE TABLE IF NOT EXISTS não altera tabela existente).

O que acontece em cada execução¶

Cada camada gera um job Spring Batch independente.

flowchart TD
  A[Setup] --> B[Change detection por watermark]
  B --> C{Há delta temporal?}
  C -->|Não| D[Fim — SKIP<br/>órfãos já podem ter sido apagados]
  C -->|Sim| E[Leitura particionada]
  E --> F[UPSERT no geo-target]

Passo 1 — Setup¶

1. Valida se a tabela existe na origem
2. Descobre colunas, PK, geometria, SRID e índices
3. Cria CREATE SCHEMA IF NOT EXISTS dsp no geo-target
4. Cria a tabela dsp.<nome_físico> (se ainda não existir)
5. Cria índice GIST em geom e índice em area_of_interest_id

Passo 2 — Change detection¶

Mesmo motor das unidades administrativas e da AOI:

• Delta — registros com criação (ou updated_at) depois do watermark gravado em BATCH_JOB_EXECUTION_SYNC_STATE
• Órfãos — PK só no geo-target → DELETE (scan a cada 24 h)
• Sem delta → SKIP (mesmo que órfãos tenham sido apagados)

Passo 3 — Carga (UPSERT)¶

• Lê feições da origem em páginas (particionamento quando a PK é numérica ou VARCHAR numérico)
• Grava no geo-target com INSERT ... ON CONFLICT DO UPDATE
• Renomeia a coluna de vínculo: ex. conservation_unit_id → area_of_interest_id
• Geometrias com Z/M são achatadas para 2D (ST_Force2D)

Exemplo com várias camadas¶

batch:
  layers:
    - source-table: conservation.rivers
      primary-key: feature_id
      area-of-interest-id-column: conservation_unit_id
      creation-date-column: created_at
      geometry-column: geom
      layer-name: rivers
      srid: 4674

    - source-table: conservation.lakes
      primary-key: feature_id
      area-of-interest-id-column: conservation_unit_id
      creation-date-column: created_at
      geometry-column: geom
      layer-name: lakes
      srid: 4674

execution-jobs:
  admin-unit-level-1-geoserver-job: true
  admin-unit-level-2-geoserver-job: true
  admin-unit-level-3-geoserver-job: true
  area-of-interest-geoserver-job: true
  layer-jobs: true

parallelization:
  jobs:
    layerMigrationJob_dsp_rivers:
      enabled: true
      thread-pool-size: 1
      chunk-size: 100
      page-size: 1000
    layerMigrationJob_dsp_lakes:
      enabled: true
      thread-pool-size: 1
      chunk-size: 100
      page-size: 1000

Como executar¶

Na raiz do repositório dsp-job-data-migration:

# 1. Metadados Spring Batch no banco de destino (uma vez)
psql -h localhost -U postgres -d dsp_db \
  -f src/main/resources/db/batch_metadata/01_spring_batch_schema.sql

# 2. Subir o job
./mvnw spring-boot:run

Para rodar só as camadas (jobs fixos desligados):

./mvnw spring-boot:run -Dspring-boot.run.arguments="\
--execution-jobs.admin-unit-level-1-geoserver-job=false \
--execution-jobs.admin-unit-level-2-geoserver-job=false \
--execution-jobs.admin-unit-level-3-geoserver-job=false \
--execution-jobs.area-of-interest-geoserver-job=false \
--execution-jobs.layer-jobs=true"

Como validar¶

No geo-target, confira se a tabela foi criada e populada:

SELECT COUNT(*) FROM dsp.rivers;

SELECT area_of_interest_id, COUNT(*)
FROM dsp.rivers
GROUP BY area_of_interest_id;

SELECT COUNT(*) FROM dsp.rivers WHERE geom IS NOT NULL;

Watermark da camada (no dsp-db):

SELECT sync_key, watermark_last_event_at, last_success_at, last_orphan_check_at
FROM data_migration.BATCH_JOB_EXECUTION_SYNC_STATE
WHERE source_table LIKE '%rivers%';

Logs úteis (pacote br.car.dsp_batch):

• Introspection completed for ... — estrutura descoberta
• Target table ready: dsp.rivers — DDL aplicado
• Upserted N features into geo-target dsp.rivers — carga concluída
• No changes detected — reexecução sem delta temporal (SKIP)

Limitações da versão atual¶

Erros comuns¶

Diferença em relação aos jobs fixos¶

No wizard do dsp-core¶

No estágio 2/6 (etl.layers[] do adopter-config.yaml), cada camada é configurada uma vez e alimenta migração, mapa e downloads:

A mesma source_table pode repetir com layer_name diferente; o wizard reaproveita o mapeamento de colunas da camada anterior com a mesma origem.

Para desligar uma camada no fluxo do wizard, remova-a de etl.layers[] e reaplique ./config.sh — o campo enabled não é aceito no adopter-config.yaml.

Detalhe completo do wizard: dsp-core.

Onde aprofundar¶