24601/surreal-skills

Surreal-Sync -- Migração e Sincronização de Dados

Surreal-Sync é uma ferramenta CLI para migrar dados de várias fontes de banco de dados para o SurrealDB com sincronização completa e incremental via Change Data Capture (CDC).

Fontes Suportadas

Fonte	Sincronização Completa	CDC Incremental	Método
MongoDB	Sim	Sim	Change streams
MySQL	Sim	Sim	CDC baseado em triggers + checkpoints de sequência
PostgreSQL (triggers)	Sim	Sim	CDC baseado em triggers + checkpoints de sequência
PostgreSQL (wal2json)	Sim	Sim	Replicação lógica com plugin wal2json
Neo4j	Sim	Sim	Rastreamento baseado em timestamp
Arquivos JSONL	Sim	N/A	Importação em lote a partir de JSON Lines
Apache Kafka	Sim	Sim	Assinaturas de consumidor com deduplicação

Início Rápido

# Instalar surreal-sync (binário Rust)
cargo install surreal-sync

# Sincronização completa do PostgreSQL (baseado em triggers)
surreal-sync from postgres trigger-full \
  --connection-string "postgresql://user:pass@localhost/mydb" \
  --surreal-endpoint "http://localhost:8000" \
  --surreal-username root \
  --surreal-password root \
  --to-namespace prod \
  --to-database main

# CDC incremental do PostgreSQL (wal2json)
surreal-sync from postgres wal2json \
  --connection-string "postgresql://user:pass@localhost/mydb" \
  --surreal-endpoint "http://localhost:8000" \
  --surreal-username root \
  --surreal-password root \
  --to-namespace prod \
  --to-database main

# Sincronização completa do MongoDB
surreal-sync from mongo full \
  --connection-string "mongodb://localhost:27017/mydb" \
  --surreal-endpoint "http://localhost:8000" \
  --surreal-username root \
  --surreal-password root \
  --to-namespace prod \
  --to-database main

# Importação em lote a partir de JSONL
surreal-sync from jsonl import \
  --file data.jsonl \
  --surreal-endpoint "http://localhost:8000" \
  --surreal-username root \
  --surreal-password root \
  --to-namespace prod \
  --to-database main

# Consumir do Kafka
surreal-sync from kafka consume \
  --bootstrap-servers "localhost:9092" \
  --topic my-events \
  --surreal-endpoint "http://localhost:8000" \
  --surreal-username root \
  --surreal-password root \
  --to-namespace prod \
  --to-database main

Padrão CLI

surreal-sync from <FONTE> <COMANDO> \
  --connection-string [STRING DE CONEXÃO] \
  --surreal-endpoint [ENDPOINT SURREAL] \
  --surreal-username [NOME DE USUÁRIO SURREAL] \
  --surreal-password [SENHA SURREAL] \
  --to-namespace <NS> \
  --to-database <DB>

Principais Recursos

• Inferência automática de esquema e criação de tabelas SurrealDB
• Mapeamento de IDs de registros a partir de chaves primárias
• Extração de relacionamentos e criação de arestas de grafo
• Tamanhos de lote e paralelismo configuráveis
• Sincronização retomável com rastreamento de checkpoint
• Deduplicação para consumidores Kafka

Documentação Completa

Consulte o arquivo de regras principal da skill para orientação completa:

• rules/surreal-sync.md -- configuração de fonte, mapeamento de esquema, configuração CDC, resolução de conflitos e implantação em produção
• surrealdb/surreal-sync -- repositório upstream