Follow the PBS Pro Design Document Guidelines.
Link to discussion on Developer Forum: <http://community.pbspro.org/t/design-for-refactoring-pbs-database-code/2009>
Link to issue: <issue link if available>
Link to pull request: <PR link if available>
For easy maintainability, current database-related code within the PBS server needs to be refactored into a separate pluggable dynamic library. And this design page discusses the APIs using which PBS server can talk to Libdb, the database dynamic library using which PBS can talk to the database. Another motivation behind this refactoring is the added advantage of moving to any database without having to do major code changes within PBS itself.
1.1. Files: List of files PBS will need to have database support.
PBS_EXEC/sbin/pbs_dataservice
Description: This script can be used to start, stop and check the status of the PBS database service.
Usage: PBS_EXEC/sbin/pbs_dataservice <start|stop|status>
Options:
start: to start the database
stop: to stop the database
status: check the status of the database.
PBS_EXEC/sbin/pbs_ds_password.bin
Description: This binary executable is used to set password for the current or a new database user.
Usage: PBS_EXEC/sbin/pbs_ds_password.bin -r | -C <user_name>
Options:
-r: set a random password to the current database user.
-C user_name: Create/change database user for the PBS database. This user should exist on the system and have permission to access the database directory under PBS_HOME.
PBS_EXEC/lib/libdb.so
Description: This dynamic library will have the functionality for the PBS server to access the database.
PBS_EXEC/libexec/pbs_db_utility
Description: This script will house all the supporting routines needed by the database. Example routines to install the PBS database, upgrade the database, etc.
Usage: PBS_EXEC/libexec/pbs_db_utility <install_db | upgrade_db | init_db_env>
Parameters:
install_db: Create and initialize the dataservice instance.
upgrade_db: Upgrade the database.
init_db_env: Intitialize the environment with information related to database installation path.
PBS_EXEC/include/pbs_db.h
Description: This header file will provide declarations for APIs and argument structures listed below.
pbs_db_conn_t: Structure used to maintain the database connection information. All elements of this structure are generic and are not bound to any particular database.
struct pbs_db_connection {
void conn_db_handle; / opaque database handle */
char conn_info; / database connect string */
char conn_host; / host */
char conn_port; / port number /
int conn_timeout; / connection timeout (async connects) /
int conn_state; / connected? /
int conn_internal_state; / internal connection state (async connects) /
int conn_db_state; / db up? down? starting? (async connects) /
time_t conn_connect_time; / when was connection initiated /
int conn_trx_nest; / incr/decr with each begin/end trx /
int conn_trx_rollback; / rollback flag in case of nested trx /
int conn_result_format; / 0 - text, 1 - binary /
int conn_trx_async; / 1 - async, 0 - sync, one-shot reset */
void conn_db_err; / opaque database error store */
void conn_data; / any other db specific data */
void conn_resultset; / point to any results data /
char conn_sql[MAX_SQL_LENGTH]; / sql buffer */
};
typedef struct pbs_db_connection pbs_db_conn_t;
pbs_db_obj_info_t: Wrapper object structure. It contains a pointer to one of the several database structures. Most of the database manipulation/query functions take this structure as a parameter. Depending on the contained structure type, an appropriate internal database manipulation/query function is eventually called. This allows keeping the interface simpler and generic.
struct pbs_db_obj_info {
int pbs_db_obj_type; /* identifies the contained object type */
union {
pbs_db_job_info_t *pbs_db_job;
pbs_db_jobscr_info_t *pbs_db_jobscr;
pbs_db_resv_info_t *pbs_db_resv;
pbs_db_svr_info_t *pbs_db_svr;
pbs_db_que_info_t *pbs_db_que;
pbs_db_node_info_t *pbs_db_node;
pbs_db_sched_info_t *pbs_db_sched;
pbs_db_mominfo_time_t *pbs_db_mominfo_tm;
} pbs_db_un;
};
typedef struct pbs_db_obj_info pbs_db_obj_info_t;
Structure used to map database job structure to C
struct pbs_db_job_info {
char ji_jobid[PBS_MAXSVRJOBID + 1]; /* job identifier /
INTEGER ji_state; / INTEGERernal copy of state /
INTEGER ji_substate; / job sub-state /
INTEGER ji_svrflags; / server flags /
INTEGER ji_numattr; / not used /
INTEGER ji_ordering; / special scheduling ordering /
INTEGER ji_priority; / INTEGERernal priority /
BIGINT ji_stime; / time job started execution /
BIGINT ji_endtBdry; / estimate upper bound on end time /
char ji_queue[PBS_MAXQUEUENAME + 1]; / name of current queue /
char ji_destin[PBS_MAXROUTEDEST + 1]; / dest from qmove/route /
INTEGER ji_un_type;
INTEGER ji_momaddr; / host addr of Server /
INTEGER ji_momport; / port # /
INTEGER ji_exitstat; / job exit status from MOM /
BIGINT ji_quetime; / time entered queue /
BIGINT ji_rteretry; / route retry time /
INTEGER ji_fromsock; / socket job coming over /
BIGINT ji_fromaddr; / host job coming from /
char ji_4jid[8];
char ji_4ash[8];
INTEGER ji_credtype;
INTEGER ji_qrank;
BIGINT ji_savetm;
BIGINT ji_creattm;
pbs_db_attr_list_t attr_list; / list of attributes */
};
typedef struct pbs_db_job_info pbs_db_job_info_t;
Structure used to map database resv structure to C
struct pbs_db_resv_info {
char ri_resvid[PBS_MAXSVRJOBID + 1];
char ri_queue[PBS_MAXQUEUENAME + 1];
INTEGER ri_state;
INTEGER ri_substate;
INTEGER ri_type;
BIGINT ri_stime;
BIGINT ri_etime;
BIGINT ri_duration;
INTEGER ri_tactive;
INTEGER ri_svrflags;
INTEGER ri_numattr;
INTEGER ri_resvTag;
INTEGER ri_un_type;
INTEGER ri_fromsock;
BIGINT ri_fromaddr;
BIGINT ri_creattm;
BIGINT ri_savetm;
pbs_db_attr_list_t attr_list; /* list of attributes */
};
typedef struct pbs_db_resv_info pbs_db_resv_info_t;
Structure used to map database server structure to C
struct pbs_db_svr_info {
INTEGER sv_numjobs;
INTEGER sv_numque;
BIGINT sv_jobidnumber;
BIGINT sv_svraddr; / host addr of Server /
INTEGER sv_svrport; / port of host server /
BIGINT sv_creattm;
BIGINT sv_savetm;
pbs_db_attr_list_t attr_list; / list of attributes */
};
typedef struct pbs_db_svr_info pbs_db_svr_info_t;
Structure used to map database scheduler structure to C
struct pbs_db_sched_info {
char sched_name[PBS_MAXSCHEDNAME+1];
BIGINT sched_creattm;
BIGINT sched_savetm;
pbs_db_attr_list_t attr_list; / list of attributes */
};
typedef struct pbs_db_sched_info pbs_db_sched_info_t;
Structure used to map database queue structure to C
struct pbs_db_que_info {
char qu_name[PBS_MAXQUEUENAME +1];
INTEGER qu_type;
BIGINT qu_ctime;
BIGINT qu_mtime;
pbs_db_attr_list_t attr_list; / list of attributes */
};
typedef struct pbs_db_que_info pbs_db_que_info_t;
Structure used to map database node structure to C
struct pbs_db_node_info {
char nd_name[PBS_MAXSERVERNAME+1];
INTEGER nd_index;
BIGINT mom_modtime;
char nd_hostname[PBS_MAXSERVERNAME+1];
INTEGER nd_state;
INTEGER nd_ntype;
char nd_pque[PBS_MAXSERVERNAME+1];
BIGINT nd_creattm;
BIGINT nd_svtime;
pbs_db_attr_list_t attr_list; / list of attributes */
};
typedef struct pbs_db_node_info pbs_db_node_info_t;
Structure used to map database mominfo_time structure to C
struct pbs_db_mominfo_time {
BIGINT mit_time;
INTEGER mit_gen;
};
typedef struct pbs_db_mominfo_time pbs_db_mominfo_time_t;
Structure used to map database job script to C
struct pbs_db_jobscr_info {
char ji_jobid[PBS_MAXSVRJOBID + 1]; / job identifier */
TEXT script;
};
typedef struct pbs_db_jobscr_info pbs_db_jobscr_info_t;
pbs_db_query_options_t: Structure used to pass database query options to database functions. Flags field can be used to pass any flags to a query function. Timestamp field can be used to pass a timestamp, to return rows that have a modification timestamp newer (more recent) than the timestamp passed. (Basically to return rows that have been modified since a point of time)
Structure used to pass database query options to database functions
struct pbs_db_query_options {
int flags; /* Flags field can be used to pass any flags to a query function. */
time_t timestamp; /* Timestamp field can be used to pass a timestamp, to return rows that have a modification timestamp newer (more recent) than the timestamp passed. (Basically to return rows that have been modified since a point of time) */
};
typedef struct pbs_db_query_options pbs_db_query_options_t;
query_cb_t: Function pointer for call back function to process the data returned by the database.
typedef int (*query_cb_t) (pbs_db_obj_info_t *, int *);
pbs_db_attr_list_t: Structure used to map database attr structure to C.
Structure used to map database attr structure to C
struct pbs_db_attr_info {
char attr_name[PBS_MAXATTRNAME+1];
char attr_resc[PBS_MAXATTRRESC+1];
TEXT attr_value;
INTEGER attr_flags;
};
typedef struct pbs_db_attr_info pbs_db_attr_info_t;
struct pbs_db_attr_list {
int attr_count;
pbs_db_attr_info_t *attributes;
};
typedef struct pbs_db_attr_list pbs_db_attr_list_t;
1.2. APIs from libdb.so
1.2.1. PBS Objects: Libdb APIs can work with below mentioned PBS objects.
PBS_DB_JOB: To save and update PBS job objects
PBS_DB_RESV: To save and update PBS reservation objects
PBS_DB_SVR: To save and update PBS server objects
PBS_DB_NODE: To save and update PBS node objects
PBS_DB_QUE: To save and update PBS queue objects
PBS_DB_JOBSCR: To save and update PBS job scripts
PBS_DB_SCHED: To save and update the PBS scheduler objects.
PBS_DB_MOMINFO_TIME: To save/update PBS mominfo_time
1.2.2. pbs_db_connect
Description: Setup a persistent database connection for further use by APIs which will work on PBS objects. On success return the connection information.
Signature:
(pbs_db_conn_t *) pbs_db_connect(char *pbs_ds_host, int pbs_ds_port, int timeout, char **err_msg)
Parameters:
pbs_data_service_host[in]: Hostname information where the database is running.
pbs_data_service_port[in]: Port number information where the database is running.
timeout[in]: Timeout in seconds before the API will return if it is taking too long to connect.
err_msg[out]: Connection/system messages generated by libdb. On connection failure out error messages.
Returns: Pointer to the initialized connection structure of type (pbs_db_conn_t *)
conn: Connection structure with connection handler to the database.
NULL: On connection failure
1.2.3. pbs_db_disconnect
Description: Disconnect PBS server from a database connection.
Signature:
int pbs_db_disconnect(pbs_db_conn_t *conn, char **err_msg)
Parameters:
conn[in]: Connection structure with connection handler to the database which was created by pbs_db_connection.
err_msg[out] : Connection logs/messages generated by libdb. On connecttion failure out error messages.
Returns: Returns status of the disconnection.
0 for successful database disconnect.
1 for failure
1.2.4. pbs_db_save_obj
Description: PBS can use this API to save any of the PBS Objects listed above to the database. Save operation can be an insert or update.
Signature:
int pbs_db_save_obj(pbs_db_conn_t *conn, pbs_db_obj_info_t *obj, int savetype)
Parameters:
conn[in]: The database connnection handle which was created by pbs_db_connection.
obj[in]: The PBS object to save. Based on the type defined within obj structure, right PBS object will be picked and dealt with.
savetype[in]: OBJ_SAVE_QS for quick save and OBJ_SAVE_NEW for insert.
Returns: Error code.
1 - Execution of prepared statement failed.
0 - Success and > 0 rows were affected.
1 - Execution succeeded but the statement did not affect any rows.
1.2.5. pbs_db_delete_obj
Description: This API lets PBS delete PBS objects PBS_DB_JOB, PBS_DB_RESV, PBS_DB_NODE, PBS_DB_QUE and PBS_DB_SCHED from the database.
Signature:
int pbs_db_delete_obj(pbs_db_conn_t *conn, pbs_db_obj_info_t *obj)
Parameters:
conn[in]: The database connection handle which was created by pbs_db_connection.
obj[in]: PBS object information to be deleted. Based on the type defined within the obj structure, the right PBS object will be picked and dealt with.
Returns: Error code.
1 - Failure
0 - Success
1 - Success but no rows deleted
1.2.6. pbs_db_load_obj
Description: This API lets PBS load objects data from the database. This API can work with any of the PBS objects.
Signature:
int pbs_db_load_obj(pbs_db_conn_t *conn, pbs_db_obj_info_t *obj)
Parameters:
conn[in] - The database connection handle which was created by pbs_db_connection..
obj[in/out] - PBS object information to be loaded from the database. Based on the type defined within obj structure, right PBS object will be picked and dealt with.
Returns: Error code
1 - Failure
0 - Success
1 - Success but no rows loaded
1.2.7. pbs_db_find_obj
Description: This API can be used to find/search PBS objects PBS_DB_JOB, PBS_DB_RESV, PBS_DB_NODE, PBS_DB_QUE and PBS_DB_SCHED in the database. This API takes a pointer to the callback function as an argument that will work on the records returned from the database based on the query specified by the PBS.
Signature:
int pbs_db_find_obj(pbs_db_conn_t *conn, pbs_db_obj_info_t *obj, pbs_db_query_options_t *opts, query_cb_t query_cb)
Parameters:
conn[in]: The database connection handle which was created by pbs_db_connection..
obj[in/out]: Information of the object to be found.
opts[in]: Any other custom options (like flags, timestamp) for the query to the database.
query_cb[in]: Function pointer to a callback function that will process the each record returned by the database for the find query made.
Returns: Error code
1 - Failure
0 - Success
1 - Success but no rows found
1.2.8. pbs_db_del_attr_obj
Description: This API can be used to delete attributes of a PBS object.
Signature:
int pg_db_del_attr_obj(pbs_db_conn_t *conn, void *obj_id, char *sv_time, pbs_db_attr_list_t *attr_list)
Parameters:
conn[in]: The database connection handle which was created by pbs_db_connection..
obj_id[in]: Object id for the delete attributes action.
sv_time[in]: Save time stamp for the delete operation.
attr_list[in]: List of attributes to be deleted.
Returns: Error code
0 - Success
1 - On Failure