This content originally appeared on DEV Community and was authored by Luis Fabrício De Llamas
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:
- Acesse Oracle Cloud Free Tier
- Crie sua conta (vai precisar de um cartão de crédito, mas relaxa, é só pra validação)
- Escolha bem sua home region - os recursos Always Free só funcionam lá
- 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>
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
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;
}
}
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();
}
}
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();
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
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");
}
}
}
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:
- Discord: https://discord.gg/nMeSs2u4ZJ
- YouTube: https://www.youtube.com/@QuarkusClub
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
This content originally appeared on DEV Community and was authored by Luis Fabrício De Llamas
Luis Fabrício De Llamas | Sciencx (2025-08-23T12:28:38+00:00) Conectando Quarkus com Oracle Database: O Guia que Você Precisava. Retrieved from https://www.scien.cx/2025/08/23/conectando-quarkus-com-oracle-database-o-guia-que-voce-precisava/
Please log in to upload a file.
There are no updates yet.
Click the Upload button above to add an update.