Skip to main content

1. Introduction

dbVisitor is a unified data access foundation built on the JDBC standard. Its guiding idea is One Access, expressed in the vision "One APIs Access Any DataBase". It serves storage and retrieval scenarios involving structured, semi-structured and unstructured data, giving Java applications a shared API or consistent programming style across relational, document, key-value, search and vector databases.

For example, one application can keep business records in MySQL, documents in MongoDB and cached values in Redis, search content with Elasticsearch and retrieve similar vectors with Milvus while reusing parameter binding, result mapping, Mappers and connection access patterns. One Access aims to reduce the learning and maintenance cost of different data source categories and let new sources fit existing data access patterns.

Two-layer adapter architecture​

LayerResponsibilityImplementation
Application adapter: how to operate on dataUnify the API used by business code and manage query syntax and mapping differencesLambdaTemplate and BaseMapper generate SQL or target commands through dialects; Mapper annotations and XML organize SQL/DSL; JdbcTemplate executes SQL, DSL or native commands supported by the driver
Protocol adapter: how to connectExpose data source protocols through JDBC connections, statements, parameters and resultsRelational databases use vendor JDBC drivers; jdbc-mongo, jdbc-elastic, jdbc-redis and jdbc-milvus adapt their respective SDKs/protocols into JDBC drivers

JDBC connects the layers: business code uses an application API, that API calls a JDBC driver, and the driver accesses the target data source. The application APIs share underlying mechanisms, while the drivers can also serve other JDBC tools independently. Projects can adopt the complete data access stack or introduce a driver adapter into an existing stack.

To integrate a new data source, implement a custom JDBC adapter using dbvisitor-driver and reuse the application access patterns. Add a matching database dialect when builder support is needed.

Data models and use cases​

Data model or use caseRepresentative data sourceDriver and capability reference
Structured records and relational queriesMySQL, PostgreSQL, Oracle and othersVendor JDBC drivers; capabilities by data source
Documents and semi-structured dataMongoDBjdbc-mongo; document operations and mapping
Key-value data, caching and data structuresRedisjdbc-redis; command access and result mapping
Content search and unstructured text retrievalElasticsearchjdbc-elastic; search, Query DSL and index operations
Vectors and similarity searchMilvusjdbc-milvus; collections, scalar filters and vector operations

One Access recognizes and manages differences: it unifies calling patterns, parameter binding and result handling while preserving native data source capabilities. Consult data source differences for supported commands, builders, transactions, batches and pagination. For example, Redis uses JdbcTemplate or Mappers for commands and currently has no builder dialect.

Choose an API by task​

RequirementEntry pointRead next
Execute existing SQL, DSL or native commands with parameters and mapped resultsJdbcTemplate; use queryForList or queryForObject for queries and executeUpdate for changesProgrammatic API
Reuse condition builders and CRUD patterns across supported data sourcesLambdaTemplate or BaseMapper; the matching dialect generates SQL or target commandsBuilder API
Organize DAOs as Java interfaces and manage SQL/DSL togetherSession.createMapper(...); combine method annotations, BaseMapper CRUD and XMLMapper API
Use Map values as the data carrierDistinguish Map mode with entity mappings from Freedom mode with table and column namesMap queries
Query vector similarityChoose KNN ordering or range filtering supported by the data source dialectVector queries

Configuration creates a Session, which creates Mapper interface instances. Templates, Mappers and builders can be combined within one application; choose a shared builder or native commands according to the target data source capabilities.

Choose dependencies and runtime​

To use both layers, add net.hasor:dbvisitor and the target JDBC driver: a vendor driver for a relational database or a matching jdbc-* adapter for NoSQL or vector databases. To keep an existing access stack such as Spring JDBC or MyBatis, use a driver adapter independently, following its supported commands and JDBC capabilities.

dbVisitor embeds directly in ordinary Java applications and provides framework integrations: dbvisitor-spring-starter for Spring Boot, dbvisitor-spring for ordinary Spring, dbvisitor-hasor for Hasor, dbvisitor-solon-plugin for Solon, or dbvisitor-guice for Guice. All these published modules use groupId net.hasor.

Complete a first call​

  1. Identify the data model and target data source, choose the driver and runtime dependencies, and prepare a DataSource or Connection plus target resources such as tables, collections or indexes.
  2. Where the dialect supports it, use new LambdaTemplate(dataSource) to reuse condition builders. For existing SQL/DSL or commands, use new JdbcTemplate(dataSource). For Mapper interfaces, obtain a Session through new Configuration().newSession(dataSource).
  3. Select an overload for a single row, multiple rows, a scalar or a Map. Bind input values and handle results and exceptions.
  4. Establish connection and transaction ownership. Standalone applications close their resources; framework applications use integration-managed objects and transactions instead of creating a separate connection environment.

Start with ordinary Java, or follow the matching Spring, Hasor, Solon or Guice integration guide.

Why use it?​

In the past, when relational databases were dominant, data access methods had become diverse and a large number of mature JDBC-based tools emerged. However, with the rise of NoSQL databases, data storage forms became more diverse and access APIs became more complex. Developers need to switch between different APIs, increasing learning costs and usage difficulty.

Existing data access technologies such as Hibernate, MyBatis, Spring JDBC, etc., mainly target relational databases and show limitations when facing increasingly diverse non-relational storage.

The core breakthrough of dbVisitor lies in the seamless integration of access modes: developers can mix multiple access paradigms in the same project and obtain a unified experience between relational and non-relational storage.

In terms of API design, dbVisitor provides APIs with a style similar to Spring JdbcTemplate, MyBatis. This design allows developers to avoid accepting a large number of new concepts and knowledge, thereby reducing learning costs and usage difficulty.

Using dbVisitor​

  • dbVisitor uses the commercially friendly Apache 2.0 license.
  • The dbVisitor core module only has one dependency, Cobble (cobble is a toolkit similar to Apache Commons or Guava).
  • Published modules are available on Maven Central.

Getting Started​

  • dbVisitor uses the Programmatic API to execute SQL, DSL or native commands supported by the target driver.
  • dbVisitor supports accessing the database using the Declarative API by marking interfaces with annotations.
  • dbVisitor uses the same Builder API across data sources with the required dialect capabilities.
  • dbVisitor supports Map Query Mode for Map-based data, either reusing object mapping or using table and column names directly.
  • dbVisitor supports Vector Query for KNN ordering and vector range filtering.
  • dbVisitor supports organizing DAOs as Java interfaces through the Mapper API, including annotations, BaseMapper CRUD methods, and Mapper files.
  • dbVisitor supports unified management of SQL statements using Mapper XML files.
  • dbVisitor provides multiple ways to handle Arguments, believing that a suitable way can always be found to handle them in various special scenarios.
  • dbVisitor provides a more flexible and efficient Rule mechanism, which makes maintaining application SQL more concise.
  • dbVisitor has built-in multiple Type Handlers, which can conveniently handle most database types.
  • dbVisitor supports using Transactions between multiple different method calls.
  • dbVisitor provides shared APIs or consistent programming patterns for Redis, MongoDB, Elasticsearch and Milvus.

Integration​

  • dbvisitor-spring: Supports automatic configuration and injection of dbVisitor configured Mappers and instances in Spring 4.x and Spring Boot 2, Spring Boot 3.
  • dbvisitor-solon: Supports automatic configuration and injection of dbVisitor configured Mappers and instances in applications using Solon as the application development framework.
  • dbvisitor-hasor: Supports automatic configuration and injection of dbVisitor configured Mappers and instances in applications using Hasor as the application development framework.
  • dbvisitor-guice: Supports automatic configuration and injection of dbVisitor configured Mappers and instances in applications using Google Guice dependency injection.
  • jdbc-redis: A JDBC driver adapter for Redis, allowing developers to operate the database using standard JDBC interfaces and Redis commands.
  • jdbc-mongo: A JDBC driver adapter for MongoDB, allowing developers to operate the database using standard JDBC interfaces and MongoDB commands.
  • jdbc-elastic: A JDBC driver adapter for ElasticSearch, allowing developers to operate the database using standard JDBC interfaces and ElasticSearch QueryDSL.

Version Events​

  • Latest release: v6.8.2
  • This guide describes 6.8.2.
  • 6.x version is a brand new upgrade. While inheriting the functions of 5.x, it has made major improvements to the implementation of different style APIs to keep usage and behavior unified in all aspects.
  • 5.x version: dbVisitor was officially separated from the Hasor framework and provides three different styles of APIs — Programmatic API, Declarative API, and Builder API — to access the database.
  • 4.x and earlier versions did not have their own independent versions, and their release followed the Hasor framework release.

Contact Author​