Interface JdbcClient

All Superinterfaces:
RuntimeType.Api<JdbcClientConfig>
@Contract public interface JdbcClient extends RuntimeType.Api<JdbcClientConfig>
Executes JDBC statements for applications and generated repositories.

Creating and binding a statement performs no database work. A terminal operation acquires the JDBC resources, fully materializes any result, and releases every resource before returning. The client is safe to share. Statement and result stages are single use and are not safe for concurrent use.

A client created programmatically obtains and closes one connection for each terminal operation. It does not participate in a transaction established by a transaction annotation on its caller. A configured data source name is resolved through the global service registry. When an existing DataSource is supplied directly, the application retains ownership of the data source, while the client closes each connection it obtains from it.

Annotation based applications inject a registry managed client with the jdbc Data.ProviderType and a Service.Named qualifier. A registry managed client uses Helidon's local transaction support and participates in the transaction surrounding the intercepted service invocation.

  • Method Details

    • builder

      static JdbcClientConfig.Builder builder()
      Creates a builder for a JDBC client.
      Returns:
      new JDBC client builder

    • create

      static JdbcClient create(JdbcClientConfig config)
      Creates a JDBC client from an immutable configuration.
      Parameters:
      config - JDBC client configuration
      Returns:
      configured JDBC client
      Throws:
      NullPointerException - if the configuration is null
      DataException - if the configuration is invalid, a named data source cannot be resolved, or a JDBC driver cannot be resolved for direct connection settings

    • create

      static JdbcClient create(Consumer<JdbcClientConfig.Builder> consumer)
      Creates a JDBC client after updating a new builder.
      Parameters:
      consumer - builder updates
      Returns:
      configured JDBC client
      Throws:
      NullPointerException - if the consumer is null
      DataException - if the configuration is invalid, a named data source cannot be resolved, or a JDBC driver cannot be resolved for direct connection settings

    • create

      JdbcClient.Statement create(String sql)
      Creates a description of one JDBC statement from positional SQL.

      A terminal operation supplies the complete SQL string to the driver as one PreparedStatement. Helidon does not parse database grammar, split scripts, or validate statement boundaries specific to a database. The supported contract therefore requires exactly one SQL statement. SQL scripts, batches, compound or multiple statement strings specific to a JDBC driver, stored procedure calls, SQL that controls transactions, and commands that change connection or session state, including auto-commit mode, are not supported.

      A single schema definition statement may be executed when the terminal operation does not participate in a Helidon local JDBC transaction. The operation then uses its own connection in auto-commit mode, and the statement executes as an independent auto-commit operation. Schema definition statements and any other statements with semantics specific to a database that implicitly commit or otherwise end a transaction are not supported while participating in a Helidon local JDBC transaction. This restriction applies regardless of whether the database supports transactional DDL.

      Helidon treats the SQL as opaque: it does not classify statements or reliably detect an implicit commit. If unsupported SQL is executed within a local transaction, a database may commit pending work while leaving JDBC auto-commit disabled. A later rollback cannot undo that committed work. Consequently, a terminal operation or transaction failure does not establish that the database made no changes, and applications must not retry the operation automatically.

      The SQL is trusted executable application input. This method does not sanitize data concatenated into the SQL text. Represent untrusted values with ? markers and supply them through JdbcClient.Statement.bind(int, Object). Bind markers represent values only. Select identifiers, operators, sort directions, and other SQL structure from an explicit application allowlist.

      Marker recognition uses a portable lexical policy. Question marks inside ordinary strings enclosed in single quotes, PostgreSQL escape and dollar quoted strings, identifiers quoted with double quotes or backticks, Oracle alternative strings, and conventional comments are ignored. Square brackets are ordinary punctuation. A doubled question mark is preserved as driver escape syntax rather than counted as bind markers. A -- comment requires following whitespace, a control character, or the end of input. Other sequences containing two hyphens are rejected because their meaning differs among SQL dialects. Nested block comments are rejected.

      Parameters:
      sql - one SQL statement containing zero or more ? markers
      Returns:
      statement description
      Throws:
      NullPointerException - if the SQL is null
      IllegalArgumentException - if the SQL is blank, malformed, or contains named markers