DEV Community

Cover image for Conectando Quarkus com Oracle Database: O Guia que Você Precisava
Luis Fabrício De Llamas
Luis Fabrício De Llamas

Posted on • Edited on

Conectando Quarkus com Oracle Database: O Guia que Você Precisava

#java #oracle #quarkus #quarkusclub

Fala, dev! Se você chegou até aqui, provavelmente está querendo conectar sua aplicação Quarkus com um banco Oracle, certo? Pois bem, hoje vou te mostrar que isso é bem mais simples do que parece. E o melhor: vamos fazer isso usando recursos gratuitos da Oracle Cloud!

Por que Oracle + Quarkus?

Olha, eu sei que muita gente torce o nariz quando fala de Oracle Database. "Ah, é caro", "é complexo", "é coisa de empresa grande"... Mas calma lá! A Oracle mudou bastante nos últimos anos. Hoje em dia, eles têm um Free Tier bem generoso que dá pra fazer muita coisa legal sem gastar nada. E combinado com o Quarkus? Meu amigo, é top demais!

Primeiro Passo: Conseguindo um Oracle Database de Graça

Antes de mais nada, você sabia que a Oracle oferece dois Autonomous Databases totalmente gratuitos pra sempre? Isso mesmo, não é trial de 30 dias não. É Always Free! Cada banco vem com 1 OCPU e 20GB de armazenamento. Dá pra fazer muita coisa com isso.

Para começar:

  1. Acesse Oracle Cloud Free Tier
  2. Crie sua conta (vai precisar de um cartão de crédito, mas relaxa, é só pra validação)
  3. Escolha bem sua home region - os recursos Always Free só funcionam lá
  4. Depois de logado, crie um Autonomous Database (pode ser ATP ou ADW)

Dica de ouro: Guarde bem as credenciais e baixe o wallet de conexão. Você vai precisar!

Configurando o Quarkus

Agora vem a parte boa. Vamos configurar o Quarkus pra conversar com o Oracle.

Adicionando as Dependências

No seu pom.xml, adicione:

<!-- Driver JDBC do Oracle -->
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-jdbc-oracle</artifactId>
</dependency>

<!-- Hibernate ORM (opcional, mas muito útil) -->
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-hibernate-orm</artifactId>
</dependency>

<!-- Panache para facilitar os repositórios (opcional) -->
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-hibernate-orm-panache</artifactId>
</dependency>
Enter fullscreen mode Exit fullscreen mode

Configurando o application.properties

Aqui é onde a mágica acontece. No seu src/main/resources/application.properties:

# Configuração básica do datasource
quarkus.datasource.db-kind=oracle
quarkus.datasource.username=ADMIN
quarkus.datasource.password=SuaSenhaSegura123!

# URL de conexão - essa aqui é pra Autonomous Database
quarkus.datasource.jdbc.url=jdbc:oracle:thin:@sua_connection_string_aqui

# Pool de conexões - ajuste conforme sua necessidade
quarkus.datasource.jdbc.min-size=2
quarkus.datasource.jdbc.max-size=8

# Hibernate properties (opcional)
quarkus.hibernate-orm.database.generation=update
quarkus.hibernate-orm.log.sql=true
Enter fullscreen mode Exit fullscreen mode

Atenção: Se você estiver usando o Autonomous Database com wallet, a configuração fica um pouquinho diferente. Você vai precisar configurar o TNS_ADMIN apontando pro diretório do wallet descompactado.

Exemplo Prático: Criando uma API Estilo Naruto!

Bora colocar a mão na massa? Vamos criar uma entidade simples pra testar nossa conexão. Imagina que você está criando um sistema pra gerenciar ninjas e seus jutsus!

package br.com.exemplo.entity;

import jakarta.persistence.*;

@Entity
@Table(name = "NINJA")
public class Ninja {

    @Id
    @GeneratedValue(strategy = GenerationType.SEQUENCE)
    private Long id;

    private String nome;

    private String vila;

    private Integer nivel;

    // Getters e setters básicos
    public Long getId() {
        return id;
    }

    public void setId(Long id) {
        this.id = id;
    }

    public String getNome() {
        return nome;
    }

    public void setNome(String nome) {
        this.nome = nome;
    }

    public String getVila() {
        return vila;
    }

    public void setVila(String vila) {
        this.vila = vila;
    }

    public Integer getNivel() {
        return nivel;
    }

    public void setNivel(Integer nivel) {
        this.nivel = nivel;
    }
}
Enter fullscreen mode Exit fullscreen mode

E vamos criar um repositório simples usando Panache:

package br.com.exemplo.repository;

import br.com.exemplo.entity.Ninja;
import io.quarkus.hibernate.orm.panache.PanacheRepository;
import jakarta.enterprise.context.ApplicationScoped;
import java.util.List;

@ApplicationScoped
public class NinjaRepository implements PanacheRepository<Ninja> {

    // Busca ninjas por vila
    public List<Ninja> findByVila(String vila) {
        return find("vila", vila).list();
    }

    // Busca ninjas de alto nível
    public List<Ninja> findJounin() {
        return find("nivel >= 10").list();
    }
}
Enter fullscreen mode Exit fullscreen mode

Dicas Valiosas do Mundo Real

Depois de alguns anos trabalhando com essa stack, aprendi algumas coisas que podem te poupar muito tempo:

1. Use Connection Pools Adequados

Não seja ganancioso com conexões. O Oracle funciona melhor com pools menores e bem configurados do que com dezenas de conexões ociosas. Comece com min-size=2 e max-size=8 e vá ajustando conforme a necessidade.

2. Sequences vs Identity

No Oracle, prefira sempre SEQUENCE ao invés de IDENTITY para geração de IDs. É mais performático e te dá mais controle. Trust me on this one!

3. Native Queries Quando Necessário

O Oracle tem features muito poderosas que às vezes o JPA não consegue aproveitar totalmente. Não tenha medo de usar native queries para operações específicas:

import jakarta.persistence.Query;


Query query = em.createNativeQuery(
    "SELECT * FROM NINJA WHERE NIVEL > :nivel ORDER BY NOME", 
    Ninja.class
);
query.setParameter("nivel", 5);
List<Ninja> ninjas = query.getResultList();
Enter fullscreen mode Exit fullscreen mode

4. Dev Services, use-os!

Durante o desenvolvimento, você pode usar o Dev Services com Oracle. O Quarkus vai subir um container automaticamente! Adicione no application.properties:

# Em dev mode, o Quarkus vai subir um Oracle container automaticamente
%dev.quarkus.datasource.devservices.enabled=true
%dev.quarkus.datasource.devservices.image-name=gvenzl/oracle-free:23-slim

# Ou se preferir desabilitar e usar sua própria instância
%dev.quarkus.datasource.devservices.enabled=false
Enter fullscreen mode Exit fullscreen mode

Isso vai subir um Oracle Database Free automaticamente quando você rodar em modo dev. Muito útil pra não ficar gastando os recursos do Free Tier durante desenvolvimento!

5. Monitoramento é Essencial

Configure o health check do Quarkus pra monitorar a conexão com o banco:

import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;
import jakarta.persistence.EntityManager;
import org.eclipse.microprofile.health.HealthCheck;
import org.eclipse.microprofile.health.HealthCheckResponse;
import org.eclipse.microprofile.health.Readiness;

@ApplicationScoped
@Readiness
public class DatabaseHealthCheck implements HealthCheck {

    @Inject
    EntityManager em;

    @Override
    public HealthCheckResponse call() {
        try {
            em.createNativeQuery("SELECT 1 FROM DUAL").getSingleResult();
            return HealthCheckResponse.up("Database connection");
        } catch (Exception e) {
            return HealthCheckResponse.down("Database connection");
        }
    }
}
Enter fullscreen mode Exit fullscreen mode

Troubleshooting Comum

Vou te poupar de algumas dores de cabeça que já passei:

"ORA-12154: TNS:could not resolve the connect identifier"
→ Verifique se o wallet está no lugar certo e se o TNS_ADMIN está configurado

"Connection pool exhausted"
→ Aumente o max-size ou verifique se não tem query travando conexões

"Table or view does not exist"
→ Lembre-se que o Oracle é case-sensitive para nomes entre aspas. Use sempre UPPER_CASE

Performance ruim em queries
→ Verifique os índices e use EXPLAIN PLAN pra entender o que tá acontecendo

Próximos Passos

Agora que você já tem o básico funcionando, porque não ver algo a mais? O Oracle tem features incríveis como JSON nativo, spatial data, graph databases... E o Quarkus consegue aproveitar tudo isso!

Ah, e se você curtiu esse conteúdo e quer aprender mais sobre Quarkus, te faço um convite! Temos uma comunidade super ativa onde compartilhamos conhecimento, tiramos dúvidas e fazemos networking.

Junte-se ao Quarkus Club:

E se quiser trocar uma ideia sobre Java, Quarkus, eventos tech ou carreira, me adiciona no LinkedIn! Sempre posto conteúdo por lá:

Conclusão

Viu só? Configurar Oracle com Quarkus não é nenhum bicho de sete cabeças. Com o Free Tier da Oracle, você tem um ambiente robusto pra desenvolver e até mesmo rodar aplicações pequenas em produção. E o Quarkus? Bem, ele faz toda a parte chata pra você poder focar no que importa: resolver problemas de negócio.

Lembre-se: a documentação oficial do Quarkus (https://quarkus.io/guides/datasource) é sempre sua melhor amiga quando bater aquela dúvida específica. Mas agora você já tem uma base sólida pra começar!

Gracias!

Por Luis De Llamas

Developer Advocate

Top comments (0)