JDBCDataStore
-------------

The ``gt-jdbc`` module is odd in that it provides a single implementation of a ``DataStore`` ( ``JDBCDataStore`` actually) and you are forced to use the ``DataStoreFinder`` mechanism in order to access the different formats.

In this case each format is implementing a custom ``SQLDialect`` as discussed in the :doc:`gt-jdbc internals <internal>` page.

Creating a JDBCDataStore
^^^^^^^^^^^^^^^^^^^^^^^^

The process of creating a JDBC data store follows the regular steps of creating any type of datastore. That is defining the parameters to connect to the database in a map, and then creating the data store factory.:
  
.. literalinclude:: /../src/main/java/org/geotools/jdbc/JDBCExamples.java
   :language: java
   :start-after: // postgisExample start
   :end-before: // postgisExample end

An important parameter is the ``dbtype`` parameter which specifies the type of database to connect to.

Using JNDI
''''''''''

The above example illustrates the case where a direct connection to a database is specified. A JNDI connection can also be specified using the ``JDBCJNDIDataStoreFactory`` class.::
  
  Map map = new HashMap();
  map.put( "dbtype", "postgis");
  map.put( "jndiReferenceName", "java:comp/env/jdbc/geotools");
  
  DataStore store =  DataStoreFinder.getDataStore(map);

Connection Pooling
^^^^^^^^^^^^^^^^^^

Internally JDBC data stores use a connection pool when creating database connections. Properly configuring a connection pool for your application can have a profound impact on performance.

Here is an example::
  
  map.put( "max connections", 25);
  map.put( "min connections", 10);
  map.put( "connection timeout", 5);
  
Connection validation is on by default, it takes a small toll to make sure the connection is still valid before using it (e.g., make sure the DBMS did not drop it due to a server side timeout).
If you want to get extra performance and you're sure the connections will never be dropped you can disable connection validation with::
  
  map.put( "validating connections", false);

Connection Parameters
^^^^^^^^^^^^^^^^^^^^^

All the ``gt-jdbc`` formats have the option of using the following set of connection parameters. You will
need to consult the documentation for the plugin you are using; the following is provided to
help with consistency.

Crucial to this is the agreement that they use a unique ``dbtype`` for each format.

+--------------------------------+----------------------------------------------------+
| Parameter                      | Description                                        |
+================================+====================================================+
| ``dbtype``                     | A unique database type identifier                  |
+--------------------------------+----------------------------------------------------+
| ``host``                       | Server to connect to                               |
+--------------------------------+----------------------------------------------------+
| ``port``                       | Port to connect to.                                |
+--------------------------------+----------------------------------------------------+
| ``database``                   | Database name                                      |
+--------------------------------+----------------------------------------------------+
| ``schema``                     | Database schema                                    |
+--------------------------------+----------------------------------------------------+
| ``user``                       | Username if required                               |
+--------------------------------+----------------------------------------------------+
| ``passwd``                     | Password if required                               |
+--------------------------------+----------------------------------------------------+
| ``namespace``                  | Namespace prefix to use for content                |
+--------------------------------+----------------------------------------------------+

**Advanced**

+--------------------------------+----------------------------------------------------+
| Parameter                      | Description                                        |
+================================+====================================================+
| ``Data Source``                | Optional: DataSource instance to use.              |
+--------------------------------+----------------------------------------------------+

**Connection Pooling**

+----------------------------------+----------------------------------------------------+
| Parameter                        | Description                                        |
+==================================+====================================================+
| ``max connections``              | Maximum number of connection the pool will hold at |
|                                  | any time, default is 10                            |
+----------------------------------+----------------------------------------------------+
| ``min connections``              | Minimum number of connection the pool will hold at |
|                                  | any time, default is 1                             |
+----------------------------------+----------------------------------------------------+
| ``connection timeout``           | Maximum number of second the pool will wait when   |
|                                  | trying to obtain a connection, default is 20       |
|                                  | seconds                                            |
+----------------------------------+----------------------------------------------------+
| ``validate connections``         | Flag controlling if the pool should validate       |
|                                  | connections when a new connection is obtained      |
+----------------------------------+----------------------------------------------------+
| ``Max open prepared statements`` | Maximum number of prepared statements kept open    |
|                                  | and cached for each connection in the pool.        |
|                                  | Set to 0 to have unbounded caching, -1 to disable  |
+----------------------------------+----------------------------------------------------+
| ``Test while idle``              | Periodically test if the connections are still     |
|                                  | valid also while idle in the pool                  | 
+----------------------------------+----------------------------------------------------+
| ``Time between evictor runs``    | Number of seconds between idle object evictor runs.|
|                                  | The default value is 300 seconds.                  | 
+----------------------------------+----------------------------------------------------+
| ``Min evictable time``           | Number of seconds a connection needs to stay idle  |
|                                  | before the evictor starts to consider closing it   |
+----------------------------------+----------------------------------------------------+
| ``Evictor tests per run``        | Number of connections checked by the idle          |
|                                  | connection evictor for each of its runs.           |
|                                  | The default value is 3 connections.                |
+----------------------------------+----------------------------------------------------+

**Tweaking and Performance**

+--------------------------------+----------------------------------------------------+
| Parameter                      | Description                                        |
+================================+====================================================+
| ``fetch size``                 | Number of records to read                          |
+--------------------------------+----------------------------------------------------+
| ``Primary key metadata table`` | The optional table containing primary key          |
|                                | structure and sequence associations. Either        |
|                                | expressed as 'schema.name' or just 'name'          |
+--------------------------------+----------------------------------------------------+
| ``Expose primary keys``        | Expose primary key columns as attributes           |
+--------------------------------+----------------------------------------------------+