Package org.apache.ignite

## Class IgniteJdbcDriver

- java.lang.Object
- - org.apache.ignite.IgniteJdbcDriver

- All Implemented Interfaces:
    `Driver`

      public class IgniteJdbcDriver
      extends Object
      implements Driver

  JDBC driver implementation for In-Memory Data Grid.

  Driver allows to get distributed data from Ignite cache using standard SQL queries and standard JDBC API. It will automatically get only fields that you actually need from objects stored in cache.

  # Limitations

  Data in Ignite cache is usually distributed across several nodes, so some queries may not work as expected since the query will be sent to each individual node and results will then be collected and returned as JDBC result set. Keep in mind following limitations (not applied if data is queried from one node only, or data is fully co-located or fully replicated on multiple nodes):
  - Joins will work correctly only if joined objects are stored in collocated mode. Refer to `AffinityKey` javadoc for more details.
  - Note that if you are connected to local or replicated cache, all data will be queried only on one node, not depending on what caches participate in the query (some data from partitioned cache can be lost). And visa versa, if you are connected to partitioned cache, data from replicated caches will be duplicated.

  # SQL Notice

  Driver allows to query data from several caches. Cache that driver is connected to is treated as default schema in this case. Other caches can be referenced by their names.

  Note that cache name is case sensitive and you have to always specify it in quotes.

  # Dependencies

  JDBC driver is located in main Ignite JAR and depends on all libraries located in `IGNITE_HOME/libs` folder. So if you are using JDBC driver in any external tool, you have to add main Ignite JAR will all dependencies to its classpath.

  # Configuration

  JDBC driver return Ignite client node based connection.

  ## Configuration of Ignite client node based connection

  JDBC connection URL has the following pattern: `jdbc:ignite:cfg://[<params>@]<config_url>`.
  `<config_url>` represents any valid URL which points to Ignite configuration file. It is required.
  `<params>` are optional and have the following format: `param1=value1:param2=value2:...:paramN=valueN`.
  The following parameters are supported:
  - `cache` - cache name. If it is not defined than default cache will be used.
  - `nodeId` - ID of node where query will be executed. It can be useful for querying through local caches. If node with provided ID doesn't exist, exception is thrown.
  - `local` - query will be executed only on local node. Use this parameter with `nodeId` parameter. Default value is `false`.
  - `collocated` - flag that used for optimization purposes. Whenever Ignite executes a distributed query, it sends sub-queries to individual cluster members. If you know in advance that the elements of your query selection are collocated together on the same node, usually based on some affinity-key, Ignite can make significant performance and network optimizations. Default value is `false`.
  - `distributedJoins` - enables support of distributed joins feature. This flag does not make sense in combination with `local` and/or `collocated` flags with `true` value or in case of querying of local cache. Default value is `false`.
  - `enforceJoinOrder` - Sets flag to enforce join order of tables in the query. If set to `true` query optimizer will not reorder tables in join. By default is `false`.
  - `lazy` - Sets flag to enable lazy query execution. By default Ignite attempts to fetch the whole query result set to memory and send it to the client. For small and medium result sets this provides optimal performance and minimize duration of internal database locks, thus increasing concurrency.

    If result set is too big to fit in available memory this could lead to excessive GC pauses and even OutOfMemoryError. Use this flag as a hint for Ignite to fetch result set lazily, thus minimizing memory consumption at the cost of moderate performance hit.

    Defaults to `false`, meaning that the whole result set is fetched to memory eagerly.

  # Example

        // Open JDBC connection.
       Connection conn = DriverManager.getConnection("jdbc:ignite:cfg//cache=persons@file:///etc/configs/ignite-jdbc.xml");

       // Query persons' names
       ResultSet rs = conn.createStatement().executeQuery("select name from Person");

       while (rs.next()) {
           String name = rs.getString(1);

           ...
       }

       // Query persons with specific age
       PreparedStatement stmt = conn.prepareStatement("select name, age from Person where age = ?");

       stmt.setInt(1, 30);

       ResultSet rs = stmt.executeQuery();

       while (rs.next()) {
           String name = rs.getString("name");
           int age = rs.getInt("age");

           ...
       }

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static String` | `CFG_URL_PREFIX` | Config URL prefix.
    `static int` | `DFLT_PORT` | Default port.
    `static String` | `PARAM_ENFORCE_JOIN_ORDER` | Parameter: enforce join order flag (SQL hint).
    `static String` | `PARAM_LAZY` | Parameter: replicated only flag (SQL hint).
    `static String` | `PARAM_SCHEMA` | Parameter: schema name.
    `static String` | `PROP_CACHE` | Cache name property name.
    `static String` | `PROP_CFG` | Cache name property name.
    `static String` | `PROP_COLLOCATED` | Collocated property name.
    `static String` | `PROP_DISTRIBUTED_JOINS` | Distributed joins property name.
    `static String` | `PROP_ENFORCE_JOIN_ORDER` | Transactions allowed property name.
    `static String` | `PROP_HOST` | Hostname property name.
    `static String` | `PROP_LAZY` | Lazy property name.
    `static String` | `PROP_LOCAL` | Local property name.
    `static String` | `PROP_MULTIPLE_STMTS` | Allow query with multiple statements.
    `static String` | `PROP_NODE_ID` | Node ID property name.
    `static String` | `PROP_PORT` | Port number property name.
    `static String` | `PROP_SCHEMA` | Schema property name.
    `static String` | `PROP_SKIP_REDUCER_ON_UPDATE` | Skip reducer on update update property name.
    `static String` | `PROP_STREAMING` | DML streaming property name.
    `static String` | `PROP_STREAMING_ALLOW_OVERWRITE` | Whether DML streaming will overwrite existing cache entries.
    `static String` | `PROP_STREAMING_FLUSH_FREQ` | DML stream auto flush frequency property name.
    `static String` | `PROP_STREAMING_PER_NODE_BUF_SIZE` | DML stream node buffer size property name.
    `static String` | `PROP_STREAMING_PER_NODE_PAR_OPS` | DML stream parallel operations per node property name.
    `static String` | `PROP_TX_ALLOWED` | Transactions allowed property name.

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `IgniteJdbcDriver()` |

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `boolean` | `acceptsURL​(String url)`
    `Connection` | `connect​(String url, Properties props)`
    `int` | `getMajorVersion()`
    `int` | `getMinorVersion()`
    `Logger` | `getParentLogger()`
    `DriverPropertyInfo[]` | `getPropertyInfo​(String url, Properties info)`
    `boolean` | `jdbcCompliant()`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### PARAM_ENFORCE_JOIN_ORDER

          public static final String PARAM_ENFORCE_JOIN_ORDER

      Parameter: enforce join order flag (SQL hint).
      See Also:
        Constant Field Values

    - #### PARAM_LAZY

          public static final String PARAM_LAZY

      Parameter: replicated only flag (SQL hint).
      See Also:
        Constant Field Values

    - #### PARAM_SCHEMA

          public static final String PARAM_SCHEMA

      Parameter: schema name.
      See Also:
        Constant Field Values

    - #### PROP_HOST

          public static final String PROP_HOST

      Hostname property name.
      See Also:
        Constant Field Values

    - #### PROP_PORT

          public static final String PROP_PORT

      Port number property name.
      See Also:
        Constant Field Values

    - #### PROP_CACHE

          public static final String PROP_CACHE

      Cache name property name.
      See Also:
        Constant Field Values

    - #### PROP_NODE_ID

          public static final String PROP_NODE_ID

      Node ID property name.
      See Also:
        Constant Field Values

    - #### PROP_LOCAL

          public static final String PROP_LOCAL

      Local property name.
      See Also:
        Constant Field Values

    - #### PROP_COLLOCATED

          public static final String PROP_COLLOCATED

      Collocated property name.
      See Also:
        Constant Field Values

    - #### PROP_DISTRIBUTED_JOINS

          public static final String PROP_DISTRIBUTED_JOINS

      Distributed joins property name.
      See Also:
        Constant Field Values

    - #### PROP_TX_ALLOWED

          public static final String PROP_TX_ALLOWED

      Transactions allowed property name.
      See Also:
        Constant Field Values

    - #### PROP_STREAMING

          public static final String PROP_STREAMING

      DML streaming property name.
      See Also:
        Constant Field Values

    - #### PROP_STREAMING_FLUSH_FREQ

          public static final String PROP_STREAMING_FLUSH_FREQ

      DML stream auto flush frequency property name.
      See Also:
        Constant Field Values

    - #### PROP_STREAMING_PER_NODE_BUF_SIZE

          public static final String PROP_STREAMING_PER_NODE_BUF_SIZE

      DML stream node buffer size property name.
      See Also:
        Constant Field Values

    - #### PROP_STREAMING_PER_NODE_PAR_OPS

          public static final String PROP_STREAMING_PER_NODE_PAR_OPS

      DML stream parallel operations per node property name.
      See Also:
        Constant Field Values

    - #### PROP_STREAMING_ALLOW_OVERWRITE

          public static final String PROP_STREAMING_ALLOW_OVERWRITE

      Whether DML streaming will overwrite existing cache entries.
      See Also:
        Constant Field Values

    - #### PROP_MULTIPLE_STMTS

          public static final String PROP_MULTIPLE_STMTS

      Allow query with multiple statements.
      See Also:
        Constant Field Values

    - #### PROP_SKIP_REDUCER_ON_UPDATE

          public static final String PROP_SKIP_REDUCER_ON_UPDATE

      Skip reducer on update update property name.
      See Also:
        Constant Field Values

    - #### PROP_ENFORCE_JOIN_ORDER

          public static final String PROP_ENFORCE_JOIN_ORDER

      Transactions allowed property name.
      See Also:
        Constant Field Values

    - #### PROP_LAZY

          public static final String PROP_LAZY

      Lazy property name.
      See Also:
        Constant Field Values

    - #### PROP_SCHEMA

          public static final String PROP_SCHEMA

      Schema property name.
      See Also:
        Constant Field Values

    - #### PROP_CFG

          public static final String PROP_CFG

      Cache name property name.
      See Also:
        Constant Field Values

    - #### CFG_URL_PREFIX

          public static final String CFG_URL_PREFIX

      Config URL prefix.
      See Also:
        Constant Field Values

    - #### DFLT_PORT

          public static final int DFLT_PORT

      Default port.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### IgniteJdbcDriver

          public IgniteJdbcDriver()

  - ### Method Detail

    - #### connect

          public Connection connect​(String url,
                                    Properties props)
                             throws SQLException

      Specified by:
        `connect` in interface `Driver`
      Throws:
        `SQLException`

    - #### acceptsURL

          public boolean acceptsURL​(String url)
                             throws SQLException

      Specified by:
        `acceptsURL` in interface `Driver`
      Throws:
        `SQLException`

    - #### getPropertyInfo

          public DriverPropertyInfo[] getPropertyInfo​(String url,
                                                      Properties info)
                                               throws SQLException

      Specified by:
        `getPropertyInfo` in interface `Driver`
      Throws:
        `SQLException`

    - #### getMajorVersion

          public int getMajorVersion()

      Specified by:
        `getMajorVersion` in interface `Driver`

    - #### getMinorVersion

          public int getMinorVersion()

      Specified by:
        `getMinorVersion` in interface `Driver`

    - #### jdbcCompliant

          public boolean jdbcCompliant()

      Specified by:
        `jdbcCompliant` in interface `Driver`

    - #### getParentLogger

          public Logger getParentLogger()
                                 throws SQLFeatureNotSupportedException

      Specified by:
        `getParentLogger` in interface `Driver`
      Throws:
        `SQLFeatureNotSupportedException`