Documentação Operacional — ecosif-database

Público-alvo: DevOps / SRE
Módulo: ecosif-database (biblioteca JAR)

1. Natureza Operacional do Módulo

O ecosif-database é uma biblioteca (JAR). Ele não é implantado nem executado como processo próprio. As variáveis de ambiente, requisitos de infraestrutura e estratégia de logs aplicam-se aos serviços que dependem desta biblioteca (ecosif-auth, ecosif-masterdata, etc.), pois o application.yml e o logback-spring.xml são empacotados no JAR e utilizados quando o classpath do consumidor os incorpora ou sobrescreve.

2. Variáveis de Ambiente

Extraídas do application.yml e do logback-spring.xml. Devem ser definidas no ambiente de execução dos serviços que consomem a biblioteca.

2.1 Banco de Dados (PostgreSQL)

Variável	Obrigatória	Descrição	Exemplo
`ECOSIF_DB_SERVER`	Sim	Host do PostgreSQL	`localhost` ou `db.ecosif.internal`
`ECOSIF_DB_PORT`	Sim	Porta do PostgreSQL	`5432`
`ECOSIF_DB_LOGIN`	Sim	Nome do banco de dados	`ecosif`
`ECOSIF_DB_USER`	Sim	Usuário do banco	`ecosif_app`
`ECOSIF_DB_PASSWORD`	Sim	Senha do usuário	(secret)

Uso no application.yml:

spring:
  datasource:
    url: "jdbc:postgresql://${ECOSIF_DB_SERVER}:${ECOSIF_DB_PORT}/${ECOSIF_DB_LOGIN}"
    username: ${ECOSIF_DB_USER}
    password: ${ECOSIF_DB_PASSWORD}

2.2 Hibernate / JPA

Variável	Obrigatória	Descrição	Valores típicos
`HIBERTENATE_MODE`	Sim*	Comportamento DDL do Hibernate	`validate`, `update`, `create`, `create-drop`, `none`

* Em produção recomenda-se validate. Em desenvolvimento pode ser update.

2.3 Autenticação e Segurança

Variável	Obrigatória	Descrição	Observação
`AUTH_TOKEN_SECRET`	Conforme serviço	Chave secreta para geração/validação de JWT	Usado por serviços que implementam auth
`TOKEN_EXPIRATION`	Conforme serviço	Tempo de expiração do token (ms)	Ex.: `86400000` (24h)
`AUTH2_CLIENTID`	Conforme uso OAuth2	Client ID (ex.: Google)	OAuth2 client
`AUTH2_SECRET`	Conforme uso OAuth2	Client Secret	OAuth2 client

2.4 Logs

Variável	Obrigatória	Descrição	Valores / Padrão
`ECOSIF_LOGSHOW`	Não	Exibir SQL no log (JPA)	`true` / `false` (padrão: `false`)
`ECOSIF_LOGMODE_SPRING`	Não	Nível de log Spring	Padrão: `INFO`
`ECOSIF_LOGMODE_HIBERNATE_SQL`	Não	Nível de log SQL Hibernate	Padrão: `INFO` (yml) / `WARN` (logback)
`ECOSIF_LOGMODE_HIBERNATE`	Não	Nível de log Hibernate (descriptor/transaction)	Padrão: `INFO`
`ECOSIF_LOGMODE_DATABASE`	Não	Nível do logger `io.ecosif.database`	Padrão: `INFO`
`ECOSIF_LOGMODE_HIBERNATE_SQL`	Não	Nível dos loggers SQL no logback	Padrão: `WARN`
`ECOSIF_LOGMODE_ROOT`	Não	Nível root do logback	Padrão: `INFO`

Nota: Todas as variáveis de ambiente devem ser definidas em MAIÚSCULAS (ex.: ECOSIF_LOGMODE_ROOT, ECOSIF_LOGMODE_DATABASE, ECOSIF_LOGMODE_HIBERNATE_SQL).

3. Requisitos de Infraestrutura

3.1 Onde a Biblioteca é Usada

A biblioteca não tem processo, porta nem health check próprios. Os requisitos abaixo aplicam-se aos serviços que a utilizam (ecosif-auth, ecosif-masterdata, ecosif-moviments, ecosif-querys, ecosif-reports, ecosif-compliance).

3.2 Recursos Comuns aos Serviços Consumidores

Recurso	Requisito
Banco de dados	PostgreSQL 12+ (recomendado 15+), acessível na rede dos serviços
Portas	Definidas por cada serviço (ex.: 8080, 8081); esta lib não abre porta
Rede	Conectividade dos pods/instâncias dos serviços até o PostgreSQL
Secrets	`ECOSIF_DB_*`, `AUTH_TOKEN_SECRET`, e opcionalmente OAuth2, via vault, Secrets Manager ou variáveis de ambiente

3.3 Dependências entre Módulos

Os serviços dependem do ecosif-database (JAR) em tempo de build e execução.
Ao atualizar a versão da biblioteca, é necessário rebuild e redeploy dos serviços que a referenciam.
Não há dependência inversa: ecosif-database não depende de outros módulos ds-ecosif.

4. Estratégia de Logs (logback-spring.xml)

A biblioteca inclui logback-spring.xml. Em cenários em que o serviço consumidor não define seu próprio logback, ou inclui este como recurso, o comportamento abaixo se aplica.

4.1 Perfis Spring

Perfil	Comportamento
Não prod (`!prod`)	Logs em CONSOLE (stdout).
prod	Logs em arquivo + arquivo de erros.

4.2 Desenvolvimento / Não Prod

Appender: CONSOLE.
Formato: %d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n.
Nível root: configurável via ${ECOSIF_LOGMODE_ROOT:INFO}.

4.3 Produção (perfil `prod`)

Appender	Arquivo	Política de rotação	Tamanho máximo por arquivo	Retenção	Tamanho total (apenas FILE)
FILE	`logs/ecosif-database.log`	SizeAndTimeBased	100MB	30 dias	3GB
ERROR_FILE	`logs/ecosif-database-error.log`	SizeAndTimeBased	50MB	90 dias	-

FILE: todos os níveis (INFO, WARN, ERROR, etc.).
ERROR_FILE: apenas eventos de nível ERROR (ThresholdFilter).
Formato: mesmo pattern do desenvolvimento.

4.4 Loggers Específicos

Logger	Variável de nível	Padrão
`io.ecosif.database`	`ECOSIF_LOGMODE_DATABASE`	INFO
`org.hibernate.SQL`	`ECOSIF_LOGMODE_HIBERNATE_SQL`	WARN
`org.hibernate.type.descriptor.sql.BasicBinder`	`ECOSIF_LOGMODE_HIBERNATE_SQL`	WARN
Root	`ECOSIF_LOGMODE_ROOT`	INFO

4.5 Resumo para SRE

Desenvolvimento: tudo em stdout; nível controlado por ECOSIF_LOGMODE_ROOT e ECOSIF_LOGMODE_DATABASE.
Produção: garantir que o diretório logs/ exista e seja gravável; monitorar espaço (3GB + 90 dias de erro); considerar envio para agregador (ex.: CloudWatch, ELK) a partir dos arquivos ou do stdout, conforme padrão do ecossistema.

5. Build e Distribuição da Biblioteca

Build: mvn clean install -DskipTests (repositório local) ou deploy para CodeArtifact.
Publicação: distributionManagement aponta para CodeArtifact (AWS). Credenciais e perfil Maven devem estar configurados no pipeline ou máquina de build.
Consumidores: atualizam a versão no pom.xml e fazem rebuild; não há rollout automático apenas por publicar o JAR.

Para detalhes de uso da biblioteca por desenvolvedores, veja ../architecture/modelo_e_consumo.md. Para visão de negócio, veja ../user/visao_geral.md.