📋 Gerenciamento de Tabelas e Databases do Sistema

Status: ✅ Ativo
Última atualização: 08/01/2026
MariaDB: 11.8.5
Servidor: 31GB RAM, SSD/NVMe

Índice

Arquitetura de Databases
Configuração de Performance MariaDB
Connection Pooling
Tabelas Críticas
Manutenção e Operações
Troubleshooting
Documentação Oficial & Links Úteis

Arquitetura de Databases

Separação Multi-Tenant

O ArboreoLab utiliza isolamento por database para garantir segurança entre projetos:

┌─────────────────────────────────────────────────────────────────┐
│                    SERVIDOR MARIADB                             │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌─────────────────────┐     ┌─────────────────────────────────┐│
│  │   ArboreolabADM     │     │   [Projeto]Vector               ││
│  │   (Governança)      │     │   (Dados do Tenant)             ││
│  ├─────────────────────┤     ├─────────────────────────────────┤│
│  │ • usuarios_sistema  │     │ • clio_ocr                      ││
│  │ • projetos          │     │ • clio_ocr_segments             ││
│  │ • projeto_usuarios  │     │ • clio_entidades                ││
│  │ • permissoes        │     │ • clio_documentos               ││
│  │ • tokens            │     │ • embeddings_768                ││
│  └─────────────────────┘     └─────────────────────────────────┘│
│                                                                 │
│  Exemplos de tenants:                                           │
│  • ClioVector                                                   │
│  • GeopoliticasVector                                           │
│  • [NovoProjeto]Vector                                          │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Regra de Nomenclatura

Tipo	Padrão	Exemplo
Governança	`ArboreolabADM`	Único, fixo
Projeto	`[Nome]Vector`	`ClioVector`, `GeopoliticasVector`

Configuração de Performance MariaDB

Visão Geral

O MariaDB está otimizado para busca vetorial em 1M+ segmentos com embeddings de 768 dimensões.

Parâmetros Críticos (Produção)

Parâmetro	Valor	Justificativa
`innodb_buffer_pool_size`	18GB	60% de 31GB RAM; cachear vetores
`innodb_io_capacity`	4000	SSD/NVMe
`innodb_io_capacity_max`	8000	Burst para operações pesadas
`innodb_flush_method`	O_DIRECT	Evitar double buffering
`innodb_log_file_size`	1G	Transações grandes com vetores
`max_connections`	200	8 pool/tenant × ~10 tenants
`skip-name-resolve`	ON	Conexões mais rápidas

Arquivo de Configuração

Localização: /etc/mysql/mariadb.conf.d/50-server.cnf

[mariadbd]

# === BUFFER POOL (Crítico para Performance) ===
innodb_buffer_pool_size = 18G
innodb_buffer_pool_dump_at_shutdown = ON
innodb_buffer_pool_load_at_startup = ON

# === I/O para SSD/NVMe ===
innodb_io_capacity = 4000
innodb_io_capacity_max = 8000
innodb_flush_method = O_DIRECT
innodb_read_io_threads = 8
innodb_write_io_threads = 8

# === LOGGING ===
innodb_log_file_size = 1G
innodb_flush_log_at_trx_commit = 2

# === CONEXÕES ===
max_connections = 200
wait_timeout = 600
interactive_timeout = 600

# === PERFORMANCE ===
skip-name-resolve
query_cache_type = 0
tmp_table_size = 256M
max_heap_table_size = 256M

Script de Tuning Automatizado

Localização: /home/arboreolab/Clio/update_performance_mariadb.sh

# Uso:
sudo bash /home/arboreolab/Clio/update_performance_mariadb.sh
sudo systemctl restart mariadb

O script:

Detecta RAM automaticamente
Calcula buffer pool (60% da RAM)
Cria backup do arquivo original
Valida configuração antes de aplicar

Verificar Configuração Aplicada

-- Buffer Pool
SHOW GLOBAL VARIABLES LIKE 'innodb_buffer_pool_size';

-- I/O
SHOW GLOBAL VARIABLES LIKE 'innodb_io_capacity%';

-- Conexões
SHOW GLOBAL VARIABLES LIKE 'max_connections';

-- Status do Buffer Pool
SHOW GLOBAL STATUS LIKE 'Innodb_buffer_pool%';

Connection Pooling

Arquitetura de Pools

O sistema utiliza pools dinâmicos para gerenciar conexões por tenant:

┌─────────────────────────────────────────────────────────────────┐
│                     APPLICATION LAYER                           │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Node.js (selectDatabase.js)     Python (tenant_manager.py)    │
│  ┌───────────────────────────┐   ┌───────────────────────────┐  │
│  │ getAdminPool()            │   │ TenantManager.get_pool()  │  │
│  │   → ArboreolabADM         │   │   → [Projeto]Vector       │  │
│  │                           │   │                           │  │
│  │ getProjectPool(dbName)    │   │ Pool Size: 8/tenant       │  │
│  │   → [Projeto]Vector       │   │ Wait Timeout: 2s          │  │
│  └───────────────────────────┘   └───────────────────────────┘  │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                      MARIADB (max_connections=200)              │
└─────────────────────────────────────────────────────────────────┘

Configuração de Pool (motor-rag/Python)

Variáveis de Ambiente (ecosystem.config.js):

Variável	Default	Descrição
`FREGERAG_TENANT_POOL_SIZE`	8	Conexões por tenant
`FREGERAG_POOL_WAIT_SECONDS`	2.0	Timeout para obter conexão

Código de Referência:

# motorRag/services/tenant_manager.py
pool_size = int(os.environ.get('FREGERAG_TENANT_POOL_SIZE', '8'))
pool = mysql.connector.pooling.MySQLConnectionPool(
    pool_name=f"{tenant}_pool",
    pool_size=pool_size,
    ...
)

Dimensionamento de Conexões

Cálculo:
  8 conexões/tenant × 10 tenants = 80 conexões (motor-rag)
  + Node.js pools (~50 conexões)
  + Overhead administrativo (~20)
  = ~150 conexões necessárias

  max_connections = 200 (margem de segurança)

Tabelas Críticas

Tabelas de Busca Vetorial (por Tenant)

Tabela	Propósito	Colunas Críticas
`clio_ocr`	Texto OCR extraído	`id`, `pagina_id`, `texto_ocr`
`clio_ocr_segments`	Segmentos para busca	`id`, `ocr_id`, `segment_text`, `embedding`
`clio_entidades`	Entidades extraídas	`id`, `nome`, `tipo`, `embedding`

Coluna de Embeddings

-- Tipo VECTOR para MariaDB 11.4+
embedding VECTOR(768) NOT NULL

-- Índice vetorial (recomendado para 1M+ registros)
-- NOTA: Criar após população inicial
ALTER TABLE clio_ocr_segments 
ADD VECTOR INDEX idx_embedding (embedding);

Views de Busca

-- View otimizada para busca híbrida (TF-IDF + Vetorial)
CREATE VIEW view_busca_clio AS
SELECT 
    s.id,
    s.segment_text,
    s.embedding,
    o.pagina_id,
    d.titulo AS documento_titulo
FROM clio_ocr_segments s
JOIN clio_ocr o ON s.ocr_id = o.id
JOIN clio_documentos d ON o.documento_id = d.id;

Manutenção e Operações

Comandos Frequentes

# Status do serviço
sudo systemctl status mariadb

# Reiniciar após mudanças de configuração
sudo systemctl restart mariadb

# Verificar logs
sudo journalctl -u mariadb -f

# Acessar console
sudo mariadb -u root -p

Backup de Databases

# Backup completo de um tenant
mysqldump -u root -p ClioVector > backup_clio_$(date +%Y%m%d).sql

# Backup apenas estrutura
mysqldump -u root -p --no-data ClioVector > schema_clio.sql

# Backup da governança
mysqldump -u root -p ArboreolabADM > backup_adm_$(date +%Y%m%d).sql

Monitoramento de Performance

-- Conexões ativas
SHOW PROCESSLIST;

-- Status do InnoDB
SHOW ENGINE INNODB STATUS\G

-- Queries lentas (se slow_query_log habilitado)
SELECT * FROM mysql.slow_log ORDER BY start_time DESC LIMIT 10;

-- Uso de buffer pool
SELECT 
    pool_id,
    pool_size,
    free_buffers,
    database_pages
FROM information_schema.INNODB_BUFFER_POOL_STATS;

Consolidação de Entidades DESCRICAO (Periódica)

Contexto: Entidades com relationshipType="DESCRICAO" são consolidadas automaticamente via UPSERT (ver migração 002_upsert_descricao.sql). Porém, reprocessamentos do mesmo documento podem gerar IDs duplicados dentro do campo CSV inFileID.

Script de Limpeza:

cd /home/arboreolab/estudos/1_funcionais/fregeRAG_v1/enviar_db/

# Simular (dry-run)
python consolidar_entidades_descricao.py --dry-run

# Executar consolidação real
python consolidar_entidades_descricao.py

# Para tenant específico
python consolidar_entidades_descricao.py --database GeopoliticasVector

Frequência: Mensalmente ou após reprocessamentos em massa.

Arquivos Relacionados:

enviar_db/entidadesV2.py - UPSERT e parsing de entidades
enviar_db/consolidar_entidades_descricao.py - Script de consolidação
migracoesdedb/002_upsert_descricao.sql - Migração com UNIQUE KEY

Troubleshooting

Problema: "Access denied" após restart

Causa: skip-name-resolve habilitado + usuário só criado para localhost

Solução:

-- Criar usuário para ambos os hosts
CREATE USER 'usuario'@'127.0.0.1' IDENTIFIED BY 'senha';
GRANT ALL PRIVILEGES ON *.* TO 'usuario'@'127.0.0.1';
FLUSH PRIVILEGES;

Problema: "Pool exhausted" no motor-rag

Causa: Pool muito pequeno para concorrência

Solução:

# ecosystem.config.js
env: {
    FREGERAG_TENANT_POOL_SIZE: '8',
    FREGERAG_POOL_WAIT_SECONDS: '2.0'
}

# Reiniciar
pm2 delete motor-rag && pm2 start ecosystem.config.js --only motor-rag

Problema: Disk I/O alto durante buscas

Causa: Buffer pool pequeno demais para vetores

Solução:

Aumentar innodb_buffer_pool_size (mínimo 60% da RAM)
Executar script de tuning
Reiniciar MariaDB
Aguardar warmup do buffer (~5-10 min)

Problema: Warnings de opções depreciadas (MariaDB 11.8)

Nota: MariaDB 11.8 removeu algumas opções que agora são gerenciadas automaticamente:

Opção Removida	Status
`innodb_buffer_pool_instances`	Gerenciado automaticamente
`innodb_thread_concurrency`	Gerenciado automaticamente

Estes warnings podem ser ignorados ou removidos do arquivo de configuração.

Referências

Script de Tuning: /home/arboreolab/Clio/update_performance_mariadb.sh
Configuração Ativa: /etc/mysql/mariadb.conf.d/50-server.cnf
Relatório Performance: .github/estadodeupdatedosistema/RELATORIO_INFRAESTRUTURA_2026-01-07.md
Pool Python: estudos/1_funcionais/fregeRAG_v1/motorRag/services/tenant_manager.py
Pool Node.js: node/utils/selectDatabase.js

Documentação Oficial & Links Úteis

MariaDB Vector (Busca Vetorial)

Recurso	URL	Descrição
Vector Overview	https://mariadb.com/docs/server/reference/sql-structure/vectors/vector-overview	Introdução completa ao MariaDB Vector
Tipo VECTOR	https://mariadb.com/docs/server/reference/sql-structure/vectors/vector	Documentação do data type VECTOR(N)
CREATE TABLE com Vectors	https://mariadb.com/docs/server/reference/sql-structure/vectors/create-table-with-vectors	Sintaxe para criar tabelas com índice vetorial
Vector System Variables	https://mariadb.com/docs/server/reference/sql-structure/vectors/vector-system-variables	Variáveis `mhnsw_*` para tuning
Vector Functions	https://mariadb.com/docs/server/reference/sql-functions/vector-functions/	Lista de funções vetoriais

Funções Vetoriais (SQL)

Função	URL	Uso
`VEC_DISTANCE_COSINE`	https://mariadb.com/docs/server/reference/sql-functions/vector-functions/vec_distance_cosine	Distância por similaridade de cosseno
`VEC_DISTANCE_EUCLIDEAN`	https://mariadb.com/docs/server/reference/sql-functions/vector-functions/vec_distance_euclidean	Distância Euclidiana (L2)
`VEC_DISTANCE`	https://mariadb.com/docs/server/reference/sql-functions/vector-functions/vector-functions-vec_distance	Função genérica (detecta índice)
`VEC_FromText`	https://mariadb.com/docs/server/reference/sql-functions/vector-functions/vec_fromtext	Converter texto para VECTOR
`VEC_ToText`	https://mariadb.com/docs/server/reference/sql-functions/vector-functions/vec_totext	Converter VECTOR para texto

RAG com MariaDB (Tutoriais)

Recurso	URL	Descrição
Tutorial RAG Oficial	https://mariadb.org/rag-with-mariadb-vector/	Guia completo RAG com MariaDB Vector
Código Exemplo RAG	https://github.com/MariaDB/demos/tree/main/mariadb-kb-rag	Repositório GitHub com exemplo funcional
E-book Vector Search	https://mariadb.com/resources/white-papers/unify-ai-sql-the-practical-guide-to-integrated-vector-search/	Guia prático AI + Vector Search
Hybrid Search (RRF)	https://mariadb.com/docs/server/reference/sql-structure/vectors/optimizing-hybrid-search-query-with-reciprocal-rank-fusion-rrf	Otimização de busca híbrida

Sentence Transformers (Embeddings)

Recurso	URL	Descrição
Documentação SBERT	https://sbert.net/docs/quickstart.html	Quickstart oficial
Modelo Multilingual (usado)	https://huggingface.co/sentence-transformers/paraphrase-multilingual-mpnet-base-v2	Modelo 768 dimensões, 50 idiomas
Pretrained Models	https://sbert.net/docs/sentence_transformer/pretrained_models.html	Lista completa de modelos
Speed Optimization	https://sbert.net/docs/sentence_transformer/usage/efficiency.html	Como acelerar inferência 2-3x

MariaDB Geral

Recurso	URL	Descrição
Documentação Principal	https://mariadb.com/docs/	Portal de documentação
Developer Hub	https://mariadb.com/developers/	Recursos para desenvolvedores
InnoDB Buffer Pool	https://mariadb.com/kb/en/innodb-buffer-pool/	Tuning de buffer pool
MariaDB Downloads	https://mariadb.com/downloads/	Versões disponíveis

Vídeos Recomendados (MariaDB Vector)

Título	Link	Autor
Rocket-Fast Native Vector Search	https://www.youtube.com/watch?v=gNyzcy_6qJM	Sergei Golubchyk
MariaDB Vector Open Source	https://www.youtube.com/watch?v=r9af4bvF7jI	Sergei Golubchik
AI First Apps with MariaDB	https://www.youtube.com/watch?v=vp126N1QOws	Vicentiu Ciorbaru
Storage Engine for LLMs	https://www.youtube.com/watch?v=3y-yWoH-CF8	Kaj Arnö, Jonah Harris

Checklist de Validação

Antes de considerar o MariaDB configurado corretamente:

□ Buffer pool configurado (mínimo 60% RAM)?
□ Backup do arquivo original existe?
□ Usuário criado para localhost E 127.0.0.1?
□ max_connections suficiente para pools?
□ Serviço reiniciado após mudanças?
□ Verificado que aplicação conecta normalmente?
□ Verificado performance com busca vetorial?

Índice​

Arquitetura de Databases​

Separação Multi-Tenant​

Regra de Nomenclatura​

Configuração de Performance MariaDB​

Visão Geral​

Parâmetros Críticos (Produção)​

Arquivo de Configuração​

Script de Tuning Automatizado​

Verificar Configuração Aplicada​

Connection Pooling​

Arquitetura de Pools​

Configuração de Pool (motor-rag/Python)​

Dimensionamento de Conexões​

Tabelas Críticas​

Tabelas de Busca Vetorial (por Tenant)​

Coluna de Embeddings​

Views de Busca​

Manutenção e Operações​

Comandos Frequentes​

Backup de Databases​

Monitoramento de Performance​

Consolidação de Entidades DESCRICAO (Periódica)​

Troubleshooting​

Problema: "Access denied" após restart​

Problema: "Pool exhausted" no motor-rag​

Problema: Disk I/O alto durante buscas​

Problema: Warnings de opções depreciadas (MariaDB 11.8)​

Referências​

Documentação Oficial & Links Úteis​

MariaDB Vector (Busca Vetorial)​

Funções Vetoriais (SQL)​

RAG com MariaDB (Tutoriais)​

Sentence Transformers (Embeddings)​

MariaDB Geral​

Vídeos Recomendados (MariaDB Vector)​

Checklist de Validação​

Índice

Arquitetura de Databases

Separação Multi-Tenant

Regra de Nomenclatura

Configuração de Performance MariaDB

Visão Geral

Parâmetros Críticos (Produção)

Arquivo de Configuração

Script de Tuning Automatizado

Verificar Configuração Aplicada

Connection Pooling

Arquitetura de Pools

Configuração de Pool (motor-rag/Python)

Dimensionamento de Conexões

Tabelas Críticas

Tabelas de Busca Vetorial (por Tenant)

Coluna de Embeddings

Views de Busca

Manutenção e Operações

Comandos Frequentes

Backup de Databases

Monitoramento de Performance

Consolidação de Entidades DESCRICAO (Periódica)

Troubleshooting

Problema: "Access denied" após restart

Problema: "Pool exhausted" no motor-rag

Problema: Disk I/O alto durante buscas

Problema: Warnings de opções depreciadas (MariaDB 11.8)

Referências

Documentação Oficial & Links Úteis

MariaDB Vector (Busca Vetorial)

Funções Vetoriais (SQL)

RAG com MariaDB (Tutoriais)

Sentence Transformers (Embeddings)

MariaDB Geral

Vídeos Recomendados (MariaDB Vector)

Checklist de Validação