Throw an exception in case a statement using ReturningMode.SINGLE produces more than 1 result.

What a returning single statement does when the database answers with more than one row. Off, the first row is returned and the rest are dropped; on, it throws.

A statement declared single is a claim that at most one row can match. Where that claim rests on a unique constraint the database enforces, the check is redundant and the default is right. Where it rests on you being sure — a lookup by something that ought to be unique but is not constrained to be — turning this on converts a silent wrong answer into a loud one.

It costs nothing at run time beyond reading one more row.

Configuration Options

Option: ‘false’

The default. A second row is ignored:

public final class TenantRepository {

    public Optional<Tenant> findTenantBySlug(final String slug) {
        // ... reads every row, answers with the first
    }

}

Option: ’true'

A second row is a defect, and says so:

public final class TenantRepository {

    public Optional<Tenant> findTenantBySlug(final String slug) {
        // ... throws when the statement answers with more than one row
    }

}

Related Options

Also in this group: allowedCallPrefixes , allowedReadPrefixes , allowedWritePrefixes , basePackageName , catchAndRethrow , createConnection , executeBatch , executeOnce , generateConnectionOverloads , generateInterfaces , injectConverters , validateMethodNamePrefixes , writesReturnUpdateCount .

Tooling

Ant

In order to use YoSQL together with Ant , take a look at the tooling documentation for Ant .

Bazel

In order to use YoSQL together with Bazel , take a look at the tooling documentation for Bazel .

CLI

In order to use YoSQL on the command line, take a look at the tooling documentation for CLI .

yosql generate --repositories-throw-on-multiple-results=configValue

Gradle

In order to use YoSQL together with Gradle , take a look at the tooling documentation for Gradle . The throwOnMultipleResults setting can be configured using Gradle in Kotlin syntax like this:

plugins {
  java
  id("wtf.metio.yosql") version "2026.8.8"
}

yosql {
  repositories {
    throwOnMultipleResults.set(configValue)
  }
}

or in Groovy syntax like this:

plugins {
  id "java"
  id "wtf.metio.yosql" version "2026.8.8"
}

yosql {
  repositories {
    throwOnMultipleResults = configValue
  }
}

Maven

In order to use YoSQL together with Maven , take a look at the tooling documentation for Maven . The throwOnMultipleResults setting can be configured using Maven like this:

<build>
  <plugins>
    <plugin>
      <groupId>wtf.metio.yosql.tooling</groupId>
      <artifactId>yosql-tooling-maven</artifactId>
      <version>2026.8.8</version>
      <configuration>
        <repositories>
          <throwOnMultipleResults>configValue</throwOnMultipleResults>
        </repositories>
      </configuration>
    </plugin>
  </plugins>
</build>