weather-data/system-dynamic-datasource/CLAUDE.md

CLAUDE.md - system-dynamic-datasource

This file provides guidance to Claude Code when working in the system-dynamic-datasource module.

Purpose

Provides dynamic multi-datasource switching at runtime using Spring's AbstractRoutingDataSource. This module has no main class and is not runnable on its own.

Architecture

@DataSource (annotation)
    ↓ triggers
DataSourceAspect (AOP around advice)
    ↓ sets/clears
DynamicContextHolder (ThreadLocal<Deque<String>>)
    ↓ peek() returns key to
DynamicDataSource (extends AbstractRoutingDataSource)
    ↓ routes to
Multiple DataSources (configured in DynamicDataSourceProperties)

Key Classes

@DataSource annotation

Apply to methods or classes to specify which datasource to use. Takes a datasource name string.

DataSourceAspect

AOP aspect that intercepts @DataSource-annotated methods. Before invocation, pushes the datasource name onto DynamicContextHolder. After invocation (finally block), pops it back off.

DynamicContextHolder

Thread-safe holder using ThreadLocal<Deque<String>>. Uses a deque (stack) to support nested @DataSource calls -- each method restores the previous datasource on exit.

• push(String ds) -- set current datasource
• poll() -- restore previous
• peek() -- get current (used by DynamicDataSource)

DynamicDataSource extends AbstractRoutingDataSource

determineCurrentLookupKey() returns DynamicContextHolder.peek(). If the holder is empty, falls back to the default datasource.

DynamicDataSourceFactory

Creates Druid datasource instances from configuration properties.

Configuration Properties

DynamicDataSourceProperties: Maps to YAML spring.datasource.dynamic.* with multiple named datasource configs. DataSourceProperties: Individual datasource config (url, username, password, driver-class-name, etc.).

Usage

@Service
public class SomeService {
    @DataSource("oracle")
    public List<Data> queryFromOracle() {
        // queries run against the "oracle" datasource
    }
}

When no @DataSource is present, queries use the default (primary) datasource configured in application-*.yml.