Why queryForList Fails with JdbcTemplate and How Spring Boot Auto‑Configures It

When using Spring's JdbcTemplate, developers often assume that queryForList(String sql, Class<T> elementType) can map an entire row to a complex object, such as Order.class. The method actually delegates to query(sql, getSingleColumnRowMapper(elementType)), which expects a single column result.

Writing code like:

public List<Order> findAllError() {
    return jdbcTemplate.queryForList("select * from tb_order", Order.class);
}

produces an IncorrectResultSetColumnCountException because the mapper expects one column but the query returns three, leading to the error message "Incorrect column count: expected 1, actual 3".

The Javadoc for the method (in JdbcOperations) states that elementType should be a simple type such as Integer.class, String.class, or

Long.class>. It does not support mapping to complex POJOs.</p>
<p>Therefore, <code>queryForList

is suitable only when the query returns a single column; for multi‑column results, other methods like query with a custom RowMapper should be used.

JdbcTemplate Auto‑Configuration in Spring Boot

Spring Boot automatically configures a JdbcTemplate bean via the JdbcTemplateAutoConfiguration class. The relevant source code is:

@Configuration(proxyBeanMethods = false)
@ConditionalOnClass({ DataSource.class, JdbcTemplate.class })
@ConditionalOnSingleCandidate(DataSource.class)
@AutoConfigureAfter(DataSourceAutoConfiguration.class)
@EnableConfigurationProperties(JdbcProperties.class)
@Import({ JdbcTemplateConfiguration.class, NamedParameterJdbcTemplateConfiguration.class })
public class JdbcTemplateAutoConfiguration { }

Key annotations: @ConditionalOnClass activates the configuration only when both DataSource and JdbcTemplate are on the classpath. @ConditionalOnSingleCandidate ensures a single DataSource bean (or a primary one) is present. @AutoConfigureAfter makes this configuration run after the data source has been set up. @EnableConfigurationProperties binds external properties to JdbcProperties.

The imported JdbcTemplateConfiguration defines the actual bean:

@Configuration(proxyBeanMethods = false)
@ConditionalOnMissingBean(JdbcOperations.class)
class JdbcTemplateConfiguration {
    @Bean
    @Primary
    JdbcTemplate jdbcTemplate(DataSource dataSource, JdbcProperties properties) {
        JdbcTemplate jdbcTemplate = new JdbcTemplate(dataSource);
        JdbcProperties.Template template = properties.getTemplate();
        jdbcTemplate.setFetchSize(template.getFetchSize());
        jdbcTemplate.setMaxRows(template.getMaxRows());
        if (template.getQueryTimeout() != null) {
            jdbcTemplate.setQueryTimeout((int) template.getQueryTimeout().getSeconds());
        }
        return jdbcTemplate;
    }
}

This configuration creates a JdbcTemplate using the auto‑configured DataSource and applies properties such as fetch size, max rows, and query timeout from application.yml (via JdbcProperties). Because the bean is marked @Primary, it can be injected directly into user code.

Understanding these internals clarifies why JdbcTemplate works out‑of‑the‑box and provides a solid foundation for customizing the bean or configuring multiple data sources in more advanced scenarios.