revisions to DB module

mostly involved adding new functions / updating "draft" functions implemented elsewhere; plus updated documentation and tests.