
= JDBCStoredProcedureMonitor
:description: Learn about the JDBCStoredProcedureMonitor in OpenNMS {page-component-title} that checks the result of a stored procedure in a remote database.

The JDBCStoredProcedureMonitor checks the result of a stored procedure in a remote database.
The result of the stored procedure has to be a boolean value (representing true or false).
The service associated with this monitor is marked as up if the stored procedure returns true and marked as down in all other cases.
It is based on the http://www.oracle.com/technetwork/java/javase/jdbc/index.html[JDBC] technology to connect and communicate with the database.

== Monitor facts

[cols="1,7"]
|===
| Class Name
| `org.opennms.netmgt.poller.monitors.JDBCStoredProcedureMonitor`
|===

== Configuration and use

.Monitor-specific parameters for the JDBCStoredProcedureMonitor
[options="header"]
[cols="1,3,2"]
|===
| Parameter
| Description
| Default

3+|*Required*

| driver
| JDBC driver class to use.
| org.postgresql.Driver

| url kbd:[{}]
| JDBC URL to connect to.
|jdbc:postgresql://:OPENNMS_JDBC_HOSTNAME/opennms

| user kbd:[{}]
| Database user
| postgres

| password kbd:[{}]
| Database password
| empty string

| stored-procedure
| Name of the database stored procedure to call.
| n/a

3+|*Optional*

| retries
| How many retries to perform before failing the test.
| 0

| schema
| Name of the database schema where the stored procedure is.
| test
|===

kbd:[{}] _indicates the parameter supports <<reference:service-assurance/introduction.adoc#ref-service-assurance-monitors-placeholder-substitution-parameters, placeholder substitution>>._

NOTE: The OPENNMS_JDBC_HOSTNAME is replaced in the url parameter with the IP or resolved hostname of the interface the monitored service is assigned to.

This monitor implements the <<reference:service-assurance/introduction.adoc#ref-service-assurance-monitors-common-parameters, Common Configuration Parameters>>.

== Provide the database driver

The JDBCStoredProcedureMonitor is based on JDBC and requires a JDBC driver to communicate with any database.
Since {page-component-title} itself uses a PostgreSQL database, the PostgreSQL JDBC driver is available out of the box.
For all other database systems, you must provide a compatible JDBC driver to {page-component-title} as a JAR file.
To provide a JDBC driver, place the driver-jar in your `$OPENNMS_HOME/lib` folder.

== Examples

The following example checks a stored procedure added to the PostgreSQL database {page-component-title} uses.
The stored procedure returns true as long as less than 250,000 events are in the {page-component-title} `events` table.

Note that you must include the `monitor` section in your definition.

.Stored procedure used in the monitor
[source, sql]
----
CREATE OR REPLACE FUNCTION eventlimit_sp() RETURNS boolean AS
$BODY$DECLARE
num_events integer;
BEGIN
	SELECT COUNT(*) into num_events from events;
	RETURN num_events > 250000;
END;$BODY$
LANGUAGE plpgsql VOLATILE NOT LEAKPROOF
COST 100;
----

[source, xml]
----
<service name="OpenNMS-DB-SP-Event-Limit" interval="300000" user-defined="true" status="on">
  <parameter key="driver" value="org.postgresql.Driver"/>
  <parameter key="url" value="jdbc:postgresql://OPENNMS_JDBC_HOSTNAME:5432/opennms"/>
  <parameter key="user" value="opennms"/>
  <parameter key="password" value="opennms"/>
  <parameter key="stored-procedure" value="eventlimit_sp"/>
  <parameter key="schema" value="public"/>
</service>

<monitor service="OpenNMS-DB-SP-Event-Limit" class-name="org.opennms.netmgt.poller.monitors.JDBCStoredProcedureMonitor"/> <1>
----
<1> Required *monitor* section.
