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/lib/libdb.so
Description: This dynamic library will have the functionality for the PBS server to access the database.
...
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
PBS_EXEC/libexec/pbs_db_env
...
Description: This script will initialize the environment with information related to the database installation path.
PBS_EXEC/include/pbs_db.h
Description: This header file will provide declarations for APIs and argument structures listed below.
pbsconn_db_conn_thandle: Structure Pointer used to maintain the database connection information. All elements of this structure are generic and are not bound to any particular database.
| Code Block |
|---|
void *conn_db_handle; /* opaque database handle */ |
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.
| Code Block | |
|---|---|
| c | struct pbs_db_obj_info {
int pbs_db_obj_type; /* identifies the contained object type */
union {
pbs_db_job_info_t *pbs_db_job; /* map database job structure to C */
pbs_db_jobscr_info_t *pbs_db_jobscr; /* map database job script to C */
pbs_db_resv_info_t *pbs_db_resv; /* map database resv structure to C */
pbs_db_svr_info_t *pbs_db_svr; /* map database server structure to C */
pbs_db_que_info_t *pbs_db_que; /* map database queue structure to C */
pbs_db_node_info_t *pbs_db_node; /* map database node structure to C */
pbs_db_sched_info_t *pbs_db_sched; /* map database scheduler structure to C */
pbs_db_mominfo_time_t *pbs_db_mominfo_tm; /* map database mominfo_time structure to C */
} 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; /* INTEGERernalInternal copy of state */
INTEGER ji_substate; /* job sub-state */
INTEGER ji_svrflags; /* server flags */
INTEGER ji_orderingnumattr; /* specialnot schedulingused ordering */
INTEGER ji_priorityordering; /* INTEGERernal priority *special scheduling ordering */
INTEGER ji_priority; /* 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; /* job's queue 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]; /* extended job save data */
char ji_4ash[8]; /* extended job save data */
INTEGER ji_credtype; /* credential type */
INTEGERBIGINT ji_qrank; /* sort key for db query */
BIGINT ji_savetm; /* job save time */
BIGINT ji_creattm; /* job create time */
pbs_db_attr_list_t attr_list; /* list of attributes */
pbs_db_attr_list_t db_attr_list; /* list of attributes for database */
};
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]; /* reservation identifier */
char ri_queue[PBS_MAXQUEUENAME + 1]; /* queue used by reservation */
INTEGER ri_state; /* internal copy of state */
INTEGER ri_substate; /* substate of resv state */
INTEGERBIGINT ri_typestime; /* "reservation" or "reservation job"left window boundry */
BIGINT ri_stimeetime; /* leftright window boundry */
BIGINT ri_etime; /* right window boundry */
BIGINT ri_duration; /* reservation duration */
INTEGER ri_tactive; /* time reservation became active */
INTEGER ri_svrflags; /* server flags */
INTEGER ri_fromsocknumattr; /* resvnot from sockused */
BIGINTINTEGER ri_fromaddrresvTag; /* resvnot fromused sock addr */
BIGINT INTEGER ri_un_creattmtype; /* resv create time on db not used */
BIGINT INTEGER ri_savetmfromsock; /* resv savefrom timesock on db */
BIGINT ri_fromaddr; /* resv from sock addr */
pbs_db_attr_list_t db_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 {
INTEGERBIGINT sv_numjobsjobidnumber;
pbs_db_attr_list_t db_attr_list; /* numberlist of job owned by serverattributes */
INTEGER sv_numque; /* nuber of queues managed */
BIGINT sv_jobidnumber; /* next number to use in new jobid */
BIGINT sv_creattm; /* time of server db create */
BIGINT sv_savetm; /* time of server db update */
};
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]; /* sched name */
pbs_db_attr_list_t db_attr_list; /* list of attributes */
};
typedef struct pbs_db_svrsched_info pbs_db_svrsched_info_t;
/* Structure used to map database schedulerqueue structure to C */
struct pbs_db_schedque_info {
char schedqu_name[PBS_MAXSCHEDNAMEMAXQUEUENAME +1]; /* schedqueue name */
BIGINTINTEGER schedqu_creattmtype; /* schedqueue createtype: timeexec, onroute db **/
BIGINT sched_savetm; /* sched save time on db */
pbs_db_attr_list_t db_attr_list; /* list of attributes */
};
typedef struct pbs_db_schedque_info pbs_db_schedque_info_t;
/* Structure used to map database queuenode structure to C */
struct pbs_db_quenode_info {
char qu nd_name[PBS_MAXQUEUENAME MAXSERVERNAME+1]; /* queuevnode's name */
INTEGER qund_typeindex; /* queueglobal type:node exec,index route */
BIGINT qu_ctime; mom_modtime; /* timenode config queueupdate createdtime */
BIGINT qu_mtime; char nd_hostname[PBS_MAXSERVERNAME+1]; /* timenode queuehostname last modified */
pbs_db_attr_list_t attr_list; INTEGER nd_state; /* liststate of attributesnode */
};
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]; /* vnode's name */
INTEGER nd_index; /* global node index */
BIGINT mom_modtime; /* node config update time */
char nd_hostname[PBS_MAXSERVERNAME+1]; /* node hostname */
INTEGER nd_state; /* state of node */
INTEGER nd_ntype; /* node type */
char nd_pque[PBS_MAXSERVERNAME+1]; /* queue to which it belongs */
BIGINT nd_creattm; /* node create time */
BIGINT nd_svtime; /* node save time */
pbs_db_attr_list_t attr_list; /* list of attributes INTEGER nd_ntype; /* node type */
char nd_pque[PBS_MAXSERVERNAME+1]; /* queue to which it belongs */
pbs_db_attr_list_t db_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; /* time of the host to vnode map */
INTEGER mit_gen; /* generation of the host to vnode map */
};
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; /* job script */
};
typedef struct pbs_db_nodejobscr_info pbs_db_nodejobscr_info_t;
/* Structure used to map database mominfo_time structure to C */
|
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)
The structure used to pass database query options to database functions
| Code Block |
|---|
struct pbs_db_mominfoquery_timeoptions { BIGINT mit_time int flags; /* time of the host Flags field can be used to pass any flags to vnode mapa query function. */ INTEGER mittime_gent timestamp; /* generationTimestamp field ofcan thebe hostused to vnodepass map 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_mominfoquery_timeoptions pbs_db_mominfoquery_timeoptions_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; /* job 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
| Code Block |
|---|
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 *);
...
Structure used to map database attr structure to C
| Code Block |
|---|
struct pbs_db_attr_info {
char attr_name[PBS_MAXATTRNAME+1]; /* attribute name */
char attr_resc[PBS_MAXATTRRESC+1]; /* resource name */
TEXT attr_value; /* attribute value */
INTEGER attr_flags; /* attribute flags */
};
typedef struct pbs_db_attr_info pbs_db_attr_info_t;
|
query_cb_t: Function pointer for call back function to process the data returned by the database. For each row/record returned by the search result, the function pointed by this pointer is called and the result is processed so that PBS can use it.
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.
The structure used to map database attr structure to C
| Code Block |
|---|
struct pbs_db_attr_list {
int attr_count; /* attribute count */
pbs_db_attr_info_t *attributeslist_head attrs; /* ptr to attr_info structure */
};
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_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.
...
!0: On connection failure.
1.2.3. pbs_db_disconnect
Description: Disconnect the PBS server from a database connection.
...
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.
...
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.
...
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:
...
0 - Success
1 - Success but no rows loaded
1.2.7. pbs_db_
...
search
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_objsearch(void *conn_db_handle, pbs_db_obj_info_t *obj, pbs_db_query_options_t *opts, query_cb_t query_cb)
...
Returns: Error code
-1 - Failure
0 0> - Success
1 0 - 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 pbs_db_deldelete_attr_obj(void *conn, pbs_db_handleobj_info_t *obj, void *obj_id, char *sv_time, pbs_db_attr_list_t *db_attr_list)
Parameters:
conn_db_handle[in]: Connection handler to the database which was created by pbs_db_connect.
obj_id[in]: Object id for the delete attributes actionInformation of the object to be found.
svobj_timeid[in]: Save time stamp Object id for the delete operationattributes action.
attr_list[in]: List of attributes to be deleted from DB.
Returns: Error code
0 - Success
Non zero - On Failure
1.2.9. pbs_start_db
Description: This API can be used to start the database instance.
...
0 - Success
Non zero - On Failure
1.2.10. pbs_stop_db
Description: This API can be used to stop the database instance.
...
0 - Success
Non zero - On Failure
1.2.11. pbs_status_db
Description: This API can be used to check if the database instance is running.
...
2 - Database is running on a different host.
3 0 - Database is running on the localhost.
-1 - On Failure
1.2.12. pbs_db_password
Description: This API can be used to change the database user and password for the database instance.
...
int pbs_db_password(void *conn_db_handle, char *user_name, char *password, int changechar *old_user)
Parameters:
conn_db_handle[in]: Connection handler to the database which was created by pbs_db_connect.
...
password[in]: New password for the database.
changeold_user[in]: Takes values 0 or 1. When set to 1, user_name will be set as new old database user name used in case of -C option to change database user.
Returns: Error code
0 - Success
Non zero - On Failure
1.2.12.
...
pbs_db_get_errmsg
Description: This API can be used to get the error messages from the database library. When any of the above-listed APIs fail, this API can be used to get the error message from libdb.
Signature:
void getpbs_db_get_errmsg(int failcode, char **errmsg)
...