Skip to main content

DB plugin

DB plugin is a flexible, extensible database abstraction layer for Brightspot that provides a unified interface for working with multiple database backends. It uses the data mapper pattern to separate domain objects from persistence logic, enabling multi-database routing, caching, and real-time replication.

Key capabilities​

  • Unified database interface — work with SQL, Solr, and other backends through a single API.
  • Fluent query API — build type-safe queries with predicates, sorting, pagination, and grouping.
  • Transaction management — nested transactions with write buffering, validation, and automatic retry.
  • Modifications — composition-based extensions that add cross-cutting concerns without inheritance.
  • Lazy reference resolution — lightweight stubs resolved on-demand with batch loading to prevent N+1 queries.
  • Replication cache — near-zero-latency reads through CDC-powered local caching.
  • Multi-database routing — route reads and writes to different backends transparently.

How it works​

Applications define domain objects as Record subclasses with annotated fields. The State layer stores each object's data independently of its business logic, enabling modifications and polymorphism. Queries are built using a fluent Query API and executed against a Database abstraction, which routes operations to the appropriate back end (SQL, Solr, caching layers, or aggregates). Writes are buffered within transactions, validated in memory, and committed atomically.

Who this documentation is for​

  • Getting started — read Getting started for a hands-on introduction to creating records, querying, and basic operations.
  • Understanding the design — read Architecture overview for a deep dive into the data mapper pattern, core components, and database implementations.
  • Database operations — read Database operations for the full Query API reference plus write operations, index management, and database utilities.
  • Transaction handling — read Transactions and write management for transaction patterns, commit strategies, and error handling.
  • Advanced usage — read Advanced topics for State architecture, modifications, atomic operations, indexing strategies, data flow internals, and key design decisions.