# SLURM Database Plugin API

## Overview

This document describes SLURM database plugins and the API that defines them. It is intended as a resource to programmers wishing to write their own SLURM database plugins. This is version 1 of the API.

SLURM database plugins must conform to the SLURM Plugin API with the following specifications:

const char plugin_name[]="full text name"

A free-formatted ASCII text string that identifies the plugin.

const char plugin_type[]="major/minor"

The major type must be "jobacct." The minor type can be any suitable name for the type of accounting package. We currently use

- flatfile—Information written to a flat file.
- mysql— Store information in a mysql database.
- pgsql— Store information in a postgresql database.

The programmer is urged to study src/plugins/database/mysql for a sample implementation of a SLURM database plugin.

The database plugin was written to be a generic plugin interface to handle any future loging by different plugins or slurm proper. As of version 1 we handle job accounting and job completion records. When adding a new service to the database plugin one should note each service writes to a different database inside the database server.

## API Functions

The database API uses hooks in the slurmctld.

All of the following functions are required. Functions which are not implemented must be stubbed.

#### Functions called by the jobacct plugin

int database_p_jobacct_init(char *location)

Description:
database_p_jobacct_init() is called to initiate a connection to the database server and check the state of the database table to make sure they are in sync with the table definitions in the plugin. Put global initialization here.

Arguments:
location (input) database name or log file location.

Returns:
SLURM_SUCCESS on success, or
SLURM_ERROR on failure.

int database_p_jobacct_fini()

Description:
database_p_jobacct_fini() is called at the end of the program that has called database_p_jobacct_init this function closes the connection to the database or logfile.

Arguments:
none

Returns:
SLURM_SUCCESS on success, or
SLURM_ERROR on failure.

int database_p_jobacct_job_start(struct job_record *job_ptr)

Description:
database_p_jobacct_job_start() is called in the jobacct plugin when a job starts, inserting information into the database about the new job.

Arguments:
job_ptr (input) information about the job in slurmctld.

Returns:
SLURM_SUCCESS on success, or
SLURM_ERROR on failure.

int database_p_jobacct_job_complete(struct job_record *job_ptr)

Description:
database_p_jobacct_job_complete() is called in the jobacct plugin when a job completes, this updates info about end of a job.

Arguments:
job_ptr (input) information about the job in slurmctld.

Returns:
SLURM_SUCCESS on success, or
SLURM_ERROR on failure.

int database_p_jobacct_step_start(struct step_record *step_ptr)

Description:
database_p_jobacct_step_start() is called in the jobacct plugin at the allocation of a new step in the slurmctld, this inserts info about the beginning of a step.

Arguments:
step_ptr (input) information about the step in slurmctld.

Returns:
SLURM_SUCCESS on success, or
SLURM_ERROR on failure.

int database_p_jobacct_step_complete(struct step_record *step_ptr)

Description:
database_p_jobacct_step_complete() is called in the jobacct plugin at the end of a step in the slurmctld, this updates the ending information about a step.

Arguments:
step_ptr (input) information about the step in slurmctld.

Returns:
SLURM_SUCCESS on success, or
SLURM_ERROR on failure.

int database_p_jobacct_suspend(struct job_record *job_ptr)

Description:
database_p_jobacct_suspend() is called in the jobacct plugin when a job is suspended or resumed in the slurmctld, this updates the database about the suspended time of the job.

Arguments:
job_ptr (input) information about the job in slurmctld.

Returns:
none

void database_p_jobacct_get_jobs(List job_list, List selected_steps, List selected_parts, void *params)

Description:
database_p_jobacct_get_jobs() is called to get a list of jobs from the database given the specific inputs.

Arguments:
List job_list (input/output) list to be filled with jobacct_job_rec_t.
List selected_steps (input) list containing type jobacct_select_step_t to query against.
List selected_parts (input) list containing char *'s of names of partitions to query against.
void *params (input) to be cast as sacct_parameters_t in the plugin.

jobacct_job_rec_t, jobacct_select_step_t, and sacct_parameters_t are all defined in common/slurm_jobacct.h

Returns:
none

void database_p_jobacct_archive(List selected_parts, void *params)

Description:
database_p_jobcomp_archive() used to archive old data.

Arguments:
List selected_parts (input) list containing char *'s of names of partitions to query against.
void *params (input) to be cast as sacct_parameters_t in the plugin.

Returns:
none

#### Functions called by the jobcomp plugin

int database_p_jobcomp_init(char *location)

Description:
database_p_jobcomp_init() is called from the jobcomp plugin, this opens the logfile or initializes the database to be written to. Put global initialization here.

Arguments:
location (input) logfile/database name.

Returns:
SLURM_SUCCESS on success, or
SLURM_ERROR on failure.

int database_p_jobcomp_fini()

Description:
database_p_jobcomp_fini() is called from the jobcomp plugin, this closes the logfile/database.

Arguments:
none

Returns:
SLURM_SUCCESS on success, or
SLURM_ERROR on failure.

int database_p_jobcomp_get_errno()

Description:
database_p_jobcomp_get_errno() called in the jobcomp plugin. Returns the number of a job completion logger specific error.

Arguments:
none

Returns:
Error number for the last failure encountered by the job completion logging plugin.

int database_p_jobcomp_log_record(struct job_record *job_ptr)

Description:
database_p_jobcomp_log_record() called in the jobcomp plugin. Note termation of a job with the specified characteristics.

Argument:
job_ptr (input) Pointer to job record as defined in src/slurmctld/slurmctld.h

Returns: SLURM_SUCCESS on success, or
SLURM_ERROR and set the errno to an appropriate value to indicate the reason for failure.

char *database_p_jobcomp_strerror(int errnum)

Description:
database_p_jobcomp_jobcomp_strerror() called in the jobcomp plugin. Return a string description of a job completion logger specific error code.

Arguments:
errnum (input) a job completion logger specific error code.

Returns:
Pointer to string describing the error or NULL if no description found in this plugin.

void database_p_jobcomp_get_jobs(List job_list, List selected_steps, List selected_parts, void *params)

Description:
database_p_jobcomp_get_jobs() is called to get a list of jobs from the database given the specific inputs.

Arguments:
List job_list (input/output) list to be filled with jobcomp_job_rec_t.
List selected_steps (input) list containing type jobacct_select_step_t to query against.
List selected_parts (input) list containing char *'s of names of partitions to query against.
void *params (input) to be cast as sacct_parameters_t in the plugin.

jobcomp_job_rec_t is defined in common/slurm_jobcomp.h

Returns:
none

void database_p_jobcomp_archive(List selected_parts, void *params)

Description:
database_p_jobcomp_archive() used to archive old data.

Arguments:
List selected_parts (input) list containing char *'s of names of partitions to query against.
void *params (input) to be cast as sacct_parameters_t in the plugin.

Returns:
none

## Parameters

Rather than proliferate slurm.conf parameters for new or evolved plugins, the database API counts on three parameters:

DatabaseType
  Specifies which plugin should be used.
DatabaseHost
  Let the plugin know the host where the database is.
DatabasePort
  Let the plugin know the port to connect to.
DatabaseUser
  Let the plugin know the name of the user to connect to the database with.
DatabasePass
  Let the plugin know the password of the user connecting to the database.

## Versioning

This document describes version 1 of the SLURM Database API. Future releases of SLURM may revise this API. A database plugin conveys its ability to implement a particular API version using the mechanism outlined for SLURM plugins.

Last modified 23 May 2007