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>
PBS_EXEC/sbin/pbs_ds_password
Description: This script is used to set password for the current or a new database user.
Usage: PBS_EXEC/sbin/pbs_ds_password -r | -C <user_name>
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.
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.
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)
query_cb_t: Function pointer for call back function to process the data returned by the database.
pbs_db_attr_list_t: Structure used to map database attr structure to C.
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_data_service_host, int pbs_data_service_port, int timeout, int *failcode, 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.
failcode[out]: Output failure code if any. Used to fetch database error messages using get_db_errmsg().
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 from a database connection and stop the database instance.
Signature:
int pbs_db_disconnect(pbs_db_conn_t *conn, int failcode, char **db_msg)
Parameters:
conn[in]: Connection structure with connection handler to the database which was created by pbs_db_connection.
failcode[out]: Output failure code if any.
db_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. get_db_errmsg
Description: Translate the database error code to an error message.
Signature:
void get_db_errmsg(int err_code, char **err_msg)
Parameters:
err_code[in]: Error code to translate.
err_msg[out]: The translated error message.
1.2.5. pbs_start_db
Description: Checks whether the database is down, and if so starts up the database in asynchronous mode.
Signature:
int pbs_start_db(char *pbs_data_service_host, int pbs_data_service_port, char **err_msg)
Parameters:
pbs_data_service_host[in]: Hostname information where the database will be running.
pbs_data_service_port[in]: Port number information where the database will be running.
err_msg[out]: Connection/system messages generated during database startup.
Returns: Failure/Status code
1 - Failed to start the data service
1 - Database is down
2 - Database is starting
3 - Database is up
1.2.6. pbs_stop_db
Description: Stop the database if up whether the database is down. Try to stop till not successful with incremental delay.
Signature:
int pbs_stop_db(char *pbs_data_service_host, int pbs_data_service_port, int retry_attempt, int delay, char **err_msg)
Parameters:
pbs_data_service_host[in]: Hostname information where the database will be running.
pbs_data_service_port[in]: Port number information where the database will be running.
retry_attempt[in]: Number of retires to stop the database before returning.
delay[int]: Delay between retry attempts to stop the database.
err_msg[out]: Connection/system messages generated during database stop.
Returns: Failure/Status code
1 - Failed to stop the data service.
0 - Success
1.2.7. pbs_status_db
Description: Checks whether the database is running.
Signature:
int pbs_status_db(char *pbs_data_service_host, int pbs_data_service_port, 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.
err_msg[out]: Connection/system messages generated during database status check.
Returns: Failure/Status code
1 - Failed to check the data service status.
1 - Data service is down.
2 - Data service is starting.
3 - Data service is up.
4 - Data service is running on a different host.
1.2.8. 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.9. 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.10. 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.11. 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.12. 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