On the Database Config screen, provide the required information to establish a JDBC connection to your database server.

Note:

PingFederate has been tested with vendor-specific JDBC 4.2 drivers. For more information, see Database driver information. To obtain your database driver JAR file, contact your database vendor. Database driver file should be installed to the <pf_install>/pingfederate/server/default/lib directory. You must restart the server after installing the driver.

  1. On the Database Config screen, configure your JDBC connection.
    For more information about each field, refer to the following table.
    Field Description
    Data Store Name The name of the datastore.

    Applicable only when editing an existing datastore.

    JDBC URL The location of the database server and the database. The structure of the JDBC URL varies depending on the vendor. You can add multiple JDBC URLs. You can also specify which node is the default by clicking Set as Default under Action.
    Tip:

    For Oracle MySQL, to enable automatic reconnection attempts when the connection is not available at runtime, enter a SQL statement in the Validate Connection SQL field and add the following query string to the JDBC URL:

    ?autoReconnect=true

    Tags Tags are defined in the node.tags property in the <pf_install>/pingfederate/bin/run.properties file. See Deploying cluster servers for a description of the node.tags property.

    In PingFederate deployments that are regional, you can enter one or more tags for a JDBC URL, which will specify which datastore that particular PingFederate node should communicate with. If none of the tags match what is defined for the node.tags property, the default node is used.

    The following rules apply to tags:

    • Multiple tags specified for one node must be separated with spaces.
    • No tag can be used more than once per datastore.
    • Tags are optional. If needed, you can configure a non-default node without tags. Doing this can be useful if you are not yet ready to tag the node, or if you are still in the planning stage but want to enter the address for the node now.
    Driver Class The name of the driver class used to communicate with the source database. The driver class name should be supplied by the database software vendor in a JAR file.
    Username The name that identifies the user when connecting to the database.
    Password The password needed to access the database.
    Validate Connection SQL

    (Optional but recommended)

    A simple SQL statement used by the PingFederate runtime server to verify that the database connection is still active and to reconnect if needed.

    If a SQL statement is not provided here, PingFederate may not be able to reconnect to the database if the connection is broken.

    Important:

    Ensure that the SQL statement is valid for your database; for example:

    • SELECT 1 from dual (for Oracle Database or Oracle MySQL)
    • SELECT getdate() (for Microsoft SQL Server)
    • SELECT 1 (for PostgreSQL)
    Tip:

    To use this feature for Oracle MySQL, you must also add the ?autoReconnect=true query parameter to the JDBC URL.

    Mask Values in Log Determines whether all attribute values returned through this datastore should be masked in PingFederate logs.

    Applicable only when editing an existing datastore.

    Allow Multi-Value Attributes When selected (the default), indicates that this JDBC datastore can select more than one records from a column and return the results as a multivalued attribute. Otherwise, a query returns only the first value in the column.
  2. Click Test Connection to determine whether the administrative node can communicate with the specified datastore.
    Note:

    Datastore validation is no longer enabled during configuration. This feature lets you configure datastores without requiring a successful connection between the administrative node and the datastore. You can also save the datastore even if the connection is not currently successful.

  3. Click Advanced to configure additional settings.
    1. On the Advanced Database Options screen, click Apply Defaults to view or restore default values.
      Tip:

      The default values are conservative based on the server thread pool settings configured in the <pf_install>/pingfederate/etc/jetty-runtime.xml file. If any changes are made to thread pooling, we recommend updating settings as outlined in the next step.

    2. Configure advanced settings.
      For more information about each field, refer to the following table.
      Field Description
      Minimum Pool Size The smallest number of database connections that can remain in the pool for the given datastore. A minimum value of 0 means that the number of connections in the pool can be reduced to zero.
      Note:

      For optimal performance, the value for this setting should be equal to 50% of the maxThreads value in the Jetty server configuration (Configuring connection pools to datastores).

      Note that PingFederate does not establish the connection pool for the given datastore until it receives a request that requires one or more attributes from that datastore.

      The default value (after clicking on Apply Defaults) is 10.

      Maximum Pool Size The largest number of database connections that can remain in the pool for the given datastore.
      Note:

      For optimal performance, the value for this setting should be equal to 75% to 100% of maxThreads value in the Jetty server configuration (see Configuring connection pools to datastores).

      The default value (after clicking on Apply Defaults) is 100.

      Blocking Timeout (ms) The amount of time a request waits to get a connection from the connection pool before it fails. A value of -1 means that a request waits indefinitely for the connection pool to return a connection.

      The default value (after clicking on Apply Defaults) is 5000.

      Idle Timeout (min) The length of time the connections can be idle in the pool before it closes them. A value of -1 means that the connection pool does not close its connections (once established).

      Note that PingFederate maintains the minimum connection pool for the given datastore once the pool is established.

      The default value (after clicking on Apply Defaults) is 5.

  4. Click Save to keep your configuration.