diff --git a/.github/workflows/run-pytest.yml b/.github/workflows/run-pytest.yml
index 216adf26..2d1c4916 100644
--- a/.github/workflows/run-pytest.yml
+++ b/.github/workflows/run-pytest.yml
@@ -2,15 +2,15 @@ name: Run pytests
 
 on:
   push:
-    branches: [master, dev]
+    branches: [master]
   pull_request:
-    branches: [master, dev]
+    branches: [master]
 
 jobs:
   pytest:
     strategy:
       matrix:
-        python-version: [3.6, 3.7, 3.8, 3.9]
+        python-version: [3.6, 3.9]
         os: [ubuntu-latest] # can't use macOS when using service containers or container jobs
     runs-on: ${{ matrix.os }}
     services:
@@ -47,4 +47,4 @@ jobs:
       uses: codecov/codecov-action@v1
       with:
         file: ./coverage.xml
-        name: py-${{ matrix.python-version }}-${{ matrix.os }}
\ No newline at end of file
+        name: py-${{ matrix.python-version }}-${{ matrix.os }}
diff --git a/.gitignore b/.gitignore
index fcf0f3c8..b07a8870 100644
--- a/.gitignore
+++ b/.gitignore
@@ -7,6 +7,7 @@ __pycache__
 *.py[cod]
 *$py.class
 __pycache__/
+.vscode/
 
 # C extensions
 *.so
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 16cccb97..05d4cd4b 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -1,21 +1,21 @@
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v3.4.0
+    rev: v4.0.1
     hooks:
       - id: trailing-whitespace
       - id: check-yaml
-      - id: check-json
       - id: end-of-file-fixer
-      - id: name-tests-test
       - id: requirements-txt-fixer
       - id: trailing-whitespace
-
-  - repo: https://github.com/psf/black
-    rev: 20.8b1
-    hooks:
-      - id: black
+      - id: check-ast
 
   - repo: https://github.com/PyCQA/isort
-    rev: 5.7.0
+    rev: 5.9.1
     hooks:
       - id: isort
+        args: ["--profile", "black"]
+
+  - repo: https://github.com/psf/black
+    rev: 21.6b0
+    hooks:
+      - id: black
diff --git a/MANIFEST.in b/MANIFEST.in
index 19044bd6..be6e936b 100644
--- a/MANIFEST.in
+++ b/MANIFEST.in
@@ -1,3 +1,3 @@
 include requirements/*
 include README.md
-include pipestat/schemas/*
\ No newline at end of file
+include pipestat/schemas/*
diff --git a/README.md b/README.md
index ea931792..4f8c41f7 100644
--- a/README.md
+++ b/README.md
@@ -30,7 +30,9 @@ export PIPESTAT_RESULTS_FILE=results_file.yaml
 export PIPESTAT_NAMESPACE=my_namespace
 ```
 
-## Report a result
+## Pipeline results reporting and retrieval
+
+### Report a result
 
 From command line:
 
@@ -46,8 +48,8 @@ import pipestat
 psm = pipestat.PipestatManager()
 psm.report(values={"result_name": 1.1})
 ```
- 
-## Retrieve a result
+
+### Retrieve a result
 
 From command line:
 
@@ -63,5 +65,39 @@ import pipestat
 psm = pipestat.PipestatManager()
 psm.retrieve(result_identifier="result_name")
 ```
- 
 
+## Pipeline status management
+
+## Set status
+
+From command line:
+
+```console
+pipestat status set running
+```
+
+From Python:
+
+```python
+import pipestat
+
+psm = pipestat.PipestatManager()
+psm.set_status(status_identifier="running")
+```
+
+## Get status
+
+From command line:
+
+```console
+pipestat status get
+```
+
+From Python:
+
+```python
+import pipestat
+
+psm = pipestat.PipestatManager()
+psm.get_status()
+```
diff --git a/codecov.yml b/codecov.yml
index bc5f12fb..be72bc25 100644
--- a/codecov.yml
+++ b/codecov.yml
@@ -2,4 +2,4 @@ ignore:
   - "*/argparser.py"
   - "*/cli.py"
   - "*/__main__.py"
-  - "setup.py"
\ No newline at end of file
+  - "setup.py"
diff --git a/docs/README.md b/docs/README.md
index ea931792..4f8c41f7 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -30,7 +30,9 @@ export PIPESTAT_RESULTS_FILE=results_file.yaml
 export PIPESTAT_NAMESPACE=my_namespace
 ```
 
-## Report a result
+## Pipeline results reporting and retrieval
+
+### Report a result
 
 From command line:
 
@@ -46,8 +48,8 @@ import pipestat
 psm = pipestat.PipestatManager()
 psm.report(values={"result_name": 1.1})
 ```
- 
-## Retrieve a result
+
+### Retrieve a result
 
 From command line:
 
@@ -63,5 +65,39 @@ import pipestat
 psm = pipestat.PipestatManager()
 psm.retrieve(result_identifier="result_name")
 ```
- 
 
+## Pipeline status management
+
+## Set status
+
+From command line:
+
+```console
+pipestat status set running
+```
+
+From Python:
+
+```python
+import pipestat
+
+psm = pipestat.PipestatManager()
+psm.set_status(status_identifier="running")
+```
+
+## Get status
+
+From command line:
+
+```console
+pipestat status get
+```
+
+From Python:
+
+```python
+import pipestat
+
+psm = pipestat.PipestatManager()
+psm.get_status()
+```
diff --git a/docs/api_docs.md b/docs/api_docs.md
index 21f94abe..8c52ebe9 100644
--- a/docs/api_docs.md
+++ b/docs/api_docs.md
@@ -8,7 +8,7 @@ document.addEventListener('DOMContentLoaded', (event) => {
 </script>
 
 <style>
-h3 .content { 
+h3 .content {
     padding-left: 22px;
     text-indent: -15px;
  }
@@ -19,7 +19,7 @@ h3 .hljs .content {
     martin-bottom: 0px;
 }
 h4 .content, table .content, p .content, li .content { margin-left: 30px; }
-h4 .content { 
+h4 .content {
     font-style: italic;
     font-size: 1em;
     margin-bottom: 0px;
@@ -31,11 +31,11 @@ h4 .content {
 # Package `pipestat` Documentation
 
 ## <a name="PipestatManager"></a> Class `PipestatManager`
-Pipestat standardizes reporting of pipeline results and pipeline status management. It formalizes a way for pipeline developers and downstream tools developers to communicate -- results produced by a pipeline can easily and reliably become an input for downstream analyses. The object exposes API for interacting with the results and pipeline status and can be backed by either a YAML-formatted file or a PostgreSQL database.
+Pipestat standardizes reporting of pipeline results and pipeline status management. It formalizes a way for pipeline developers and downstream tools developers to communicate -- results produced by a pipeline can easily and reliably become an input for downstream analyses. The object exposes API for interacting with the results and pipeline status and can be backed by either a YAML-formatted file or a database.
 
 
 ```python
-def __init__(self, namespace=None, record_identifier=None, schema_path=None, results_file_path=None, database_only=False, config=None, status_schema_path=None, flag_file_dir=None)
+def __init__(self, namespace: Optional[str]=None, record_identifier: Optional[str]=None, schema_path: Optional[str]=None, results_file_path: Optional[str]=None, database_only: Optional[bool]=True, config: Union[str, dict, NoneType]=None, status_schema_path: Optional[str]=None, flag_file_dir: Optional[str]=None, custom_declarative_base: Optional[sqlalchemy.orm.decl_api.DeclarativeMeta]=None, show_db_logs: bool=False)
 ```
 
 Initialize the object
@@ -48,18 +48,19 @@ Initialize the object
 - `database_only` (`bool`):  whether the reported data should not bestored in the memory, but only in the database
 - `config` (`str | dict`):  path to the configuration file or a mappingwith the config file content
 - `status_schema_path` (`str`):  path to the status schema that formalizesthe status flags structure
+- `custom_declarative_base` (`sqlalchemy.orm.DeclarativeMeta`):  a declarative base touse for ORMs creation a new instance will be created if not provided
 
 
 
 
 ```python
-def assert_results_defined(self, results)
+def assert_results_defined(self, results: List[str]) -> None
 ```
 
 Assert provided list of results is defined in the schema
 #### Parameters:
 
-- `results` (`list[str]`):  list of results tocheck for existence in the schema
+- `results` (`List[str]`):  list of results tocheck for existence in the schema
 
 
 #### Raises:
@@ -70,54 +71,61 @@ Assert provided list of results is defined in the schema
 
 
 ```python
-def check_connection(self)
+def check_record_exists(self, record_identifier: str, table_name: str=None) -> bool
 ```
 
-Check whether a PostgreSQL connection has been established
+Check if the specified record exists in the table
+#### Parameters:
+
+- `record_identifier` (`str`):  record to check for
+- `table_name` (`str`):  table name to check
+
+
 #### Returns:
 
-- `bool`:  whether the connection has been established
+- `bool`:  whether the record exists in the table
 
 
 
 
 ```python
-def check_record_exists(self, record_identifier=None)
+def check_result_exists(self, result_identifier: str, record_identifier: str=None) -> bool
 ```
 
-Check if the record exists
+Check if the result has been reported
 #### Parameters:
 
 - `record_identifier` (`str`):  unique identifier of the record
+- `result_identifier` (`str`):  name of the result to check
 
 
 #### Returns:
 
-- `bool`:  whether the record exists
+- `bool`:  whether the specified result has been reported for theindicated record in current namespace
 
 
 
 
 ```python
-def check_result_exists(self, result_identifier, record_identifier=None)
+def check_which_results_exist(self, results: List[str], rid: Optional[str]=None, table_name: Optional[str]=None) -> List[str]
 ```
 
-Check if the result has been reported
+Check which results have been reported
 #### Parameters:
 
-- `record_identifier` (`str`):  unique identifier of the record
-- `result_identifier` (`str`):  name of the result to check
+- `rid` (`str`):  unique identifier of the record
+- `results` (`List[str]`):  names of the results to check
 
 
 #### Returns:
 
-- `bool`:  whether the specified result has been reported for theindicated record in current namespace
+- `List[str]`:  whether the specified result has been reported for theindicated record in current namespace
 
 
 
 
 ```python
-def clear_status(self, record_identifier=None, flag_names=None)
+def clear_status(self, record_identifier: str=None, flag_names: List[str]=None) -> List[Optional[str]]
 ```
 
 Remove status flags
@@ -129,16 +137,8 @@ Remove status flags
 
 #### Returns:
 
-- `list[str]`:  Collection of names of flags removed
-
-
-
+- `List[str]`:  Collection of names of flags removed
 
-```python
-def close_postgres_connection(self)
-```
-
-Close connection and remove client bound
 
 
 
@@ -167,27 +167,53 @@ Data object
 
 
 ```python
-def db_cursor(self)
+def db_column_kwargs_by_result(self)
 ```
 
-Establish connection and get a PostgreSQL database cursor, commit and close the connection afterwards
+Database column key word arguments for every result, sourced from the results schema in the `db_column` section
 #### Returns:
 
-- `LoggingCursor`:  Database cursor object
+- `Dict[str, Any]`:  key word arguments for every result
 
 
 
 
 ```python
-def establish_postgres_connection(self, suppress=False)
+def db_column_relationships_by_result(self)
 ```
 
-Establish PostgreSQL connection using the config data
-#### Parameters:
+Database column relationships for every result, sourced from the results schema in the `relationship` section
 
-- `suppress` (`bool`):  whether to suppress any connection errors
+*Note: this is an experimental feature*
+#### Returns:
 
+- `Dict[str, Dict[str, str]]`:  relationships for every result
+
+
+
+
+```python
+def db_url(self)
+```
+
+Database URL, generated based on config credentials
+#### Returns:
+
+- `str`:  database URL
+
+
+#### Raises:
+
+- `PipestatDatabaseError`:  if the object is not backed by a database
+
+
+
+
+```python
+def establish_db_connection(self) -> bool
+```
 
+Establish DB connection using the config data
 #### Returns:
 
 - `bool`:  whether the connection has been established successfully
@@ -208,7 +234,24 @@ File path that the object is reporting the results into
 
 
 ```python
-def get_status(self, record_identifier=None)
+def get_orm(self, table_name: str=None) -> Any
+```
+
+Get an object relational mapper class
+#### Parameters:
+
+- `table_name` (`str`):  table name to get a class for
+
+
+#### Returns:
+
+- `Any`:  Object relational mapper class
+
+
+
+
+```python
+def get_status(self, record_identifier: str=None) -> Optional[str]
 ```
 
 Get the current pipeline status
@@ -220,7 +263,7 @@ Get the current pipeline status
 
 
 ```python
-def get_status_flag_path(self, status_identifier, record_identifier=None)
+def get_status_flag_path(self, status_identifier: str, record_identifier=None) -> str
 ```
 
 Get the path to the status file flag
@@ -244,7 +287,19 @@ def highlighted_results(self)
 Highlighted results
 #### Returns:
 
-- `list[str]`:  a collection of highlighted results
+- `List[str]`:  a collection of highlighted results
+
+
+
+
+```python
+def is_db_connected(self) -> bool
+```
+
+Check whether a DB connection has been established
+#### Returns:
+
+- `bool`:  whether the connection has been established
 
 
 
@@ -286,7 +341,7 @@ Unique identifier of the record
 
 
 ```python
-def remove(self, record_identifier=None, result_identifier=None)
+def remove(self, record_identifier: str=None, result_identifier: str=None) -> bool
 ```
 
 Remove a result.
@@ -307,13 +362,13 @@ will be removed.
 
 
 ```python
-def report(self, values, record_identifier=None, force_overwrite=False, strict_type=True, return_id=False)
+def report(self, values: Dict[str, Any], record_identifier: str=None, force_overwrite: bool=False, strict_type: bool=True, return_id: bool=False) -> Union[bool, int]
 ```
 
 Report a result.
 #### Parameters:
 
-- `values` (`dict[str, any]`):  dictionary of result-value pairs
+- `values` (`Dict[str, any]`):  dictionary of result-value pairs
 - `record_identifier` (`str`):  unique identifier of the record, valuein 'record_identifier' column to look for to determine if the record already exists
 - `force_overwrite` (`bool`):  whether to overwrite the existing record
 - `strict_type` (`bool`):  whether the type of the reported values shouldremain as is. Pipestat would attempt to convert to the schema-defined one otherwise
@@ -340,7 +395,7 @@ Result schema mappings
 
 
 ```python
-def retrieve(self, record_identifier=None, result_identifier=None)
+def retrieve(self, record_identifier: Optional[str]=None, result_identifier: Optional[str]=None) -> Union[Any, Dict[str, Any]]
 ```
 
 Retrieve a result for a record.
@@ -355,7 +410,7 @@ be returned.
 
 #### Returns:
 
-- `any | dict[str, any]`:  a single result or a mapping with all theresults reported for the record
+- `any | Dict[str, any]`:  a single result or a mapping with all theresults reported for the record
 
 
 
@@ -385,28 +440,56 @@ Schema path
 
 
 ```python
-def select(self, columns=None, condition=None, condition_val=None, offset=None, limit=None)
+def select(self, table_name: Optional[str]=None, columns: Optional[List[str]]=None, filter_conditions: Optional[List[Tuple[str, str, Union[str, List[str]]]]]=None, json_filter_conditions: Optional[List[Tuple[str, str, str]]]=None, offset: Optional[int]=None, limit: Optional[int]=None) -> List[Any]
 ```
 
-Get all the contents from the selected table, possibly restricted by the provided condition.
+Perform a `SELECT` on the table
 #### Parameters:
 
-- `columns` (`str | list[str]`):  columns to select
-- `condition` (`str`):  condition to restrict the resultswith, will be appended to the end of the SELECT statement and safely populated with 'condition_val', for example: `"id=%s"`
-- `condition_val` (`list`):  values to fill the placeholderin 'condition' with
-- `offset` (`int`):  number of records to be skipped
-- `limit` (`int`):  max number of records to be returned
+- `table_name` (`str`):  name of the table to SELECT from
+- `columns` (`List[str]`):  columns to include in the result
+- `filter_conditions` (`[(key,operator,value)]`): - eq for == - lt for < - ge for >= - in for in_ - like for like
+- `json_filter_conditions` (`[(col,key,value)]`):  conditions for JSONB column toquery that include JSON column name, key withing the JSON object in that column and the value to check the identity against. Therefore only '==' is supported in non-nested checks, e.g. [("other", "genome", "hg38")]
+- `offset` (`int`):  skip this number of rows
+- `limit` (`int`):  include this number of rows
+
+
+
+
+```python
+def select_txt(self, filter_templ: Optional[str]='', filter_params: Optional[Dict[str, Any]]={}, table_name: Optional[str]=None, offset: Optional[int]=None, limit: Optional[int]=None) -> List[Any]
+```
+
+Execute a query with a textual filter. Returns all results.
+
+To retrieve all table contents, leave the filter arguments out.
+Table name defaults to the namespace
+#### Parameters:
+
+- `filter_templ` (`str`):  filter template with value placeholders,formatted as follows `id<:value and name=:name`
+- `filter_params` (`Dict[str, Any]`):  a mapping keys specified in the `filter_templ`to parameters that are supposed to replace the placeholders
+- `table_name` (`str`):  name of the table to query
+- `offset` (`int`):  skip this number of rows
+- `limit` (`int`):  include this number of rows
 
 
 #### Returns:
 
-- `list[psycopg2.extras.DictRow]`:  all table contents
+- `List[Any]`:  a list of matched records
+
+
+
+
+```python
+def session(self)
+```
 
+Provide a transactional scope around a series of query operations.
 
 
 
 ```python
-def set_status(self, status_identifier, record_identifier=None)
+def set_status(self, status_identifier: str, record_identifier: str=None) -> None
 ```
 
 Set pipeline run status.
@@ -447,7 +530,7 @@ Status schema source
 
 
 ```python
-def validate_schema(self)
+def validate_schema(self) -> None
 ```
 
 Check schema for any possible issues
@@ -461,4 +544,4 @@ Check schema for any possible issues
 
 
 
-*Version Information: `pipestat` v0.0.3-dev, generated by `lucidoc` v0.4.3*
+*Version Information: `pipestat` v0.1.0-dev, generated by `lucidoc` v0.4.2*
diff --git a/docs/autodoc_build/pipestat.md b/docs/autodoc_build/pipestat.md
index 46782529..4fb1ec54 100644
--- a/docs/autodoc_build/pipestat.md
+++ b/docs/autodoc_build/pipestat.md
@@ -7,7 +7,7 @@ document.addEventListener('DOMContentLoaded', (event) => {
 </script>
 
 <style>
-h3 .content { 
+h3 .content {
     padding-left: 22px;
     text-indent: -15px;
  }
@@ -18,7 +18,7 @@ h3 .hljs .content {
     martin-bottom: 0px;
 }
 h4 .content, table .content, p .content, li .content { margin-left: 30px; }
-h4 .content { 
+h4 .content {
     font-style: italic;
     font-size: 1em;
     margin-bottom: 0px;
@@ -30,11 +30,11 @@ h4 .content {
 # Package `pipestat` Documentation
 
 ## <a name="PipestatManager"></a> Class `PipestatManager`
-Pipestat standardizes reporting of pipeline results and pipeline status management. It formalizes a way for pipeline developers and downstream tools developers to communicate -- results produced by a pipeline can easily and reliably become an input for downstream analyses. The object exposes API for interacting with the results and pipeline status and can be backed by either a YAML-formatted file or a PostgreSQL database.
+Pipestat standardizes reporting of pipeline results and pipeline status management. It formalizes a way for pipeline developers and downstream tools developers to communicate -- results produced by a pipeline can easily and reliably become an input for downstream analyses. The object exposes API for interacting with the results and pipeline status and can be backed by either a YAML-formatted file or a database.
 
 
 ```python
-def __init__(self, namespace=None, record_identifier=None, schema_path=None, results_file_path=None, database_only=False, config=None, status_schema_path=None, flag_file_dir=None)
+def __init__(self, namespace: Optional[str]=None, record_identifier: Optional[str]=None, schema_path: Optional[str]=None, results_file_path: Optional[str]=None, database_only: Optional[bool]=True, config: Union[str, dict, NoneType]=None, status_schema_path: Optional[str]=None, flag_file_dir: Optional[str]=None, custom_declarative_base: Optional[sqlalchemy.orm.decl_api.DeclarativeMeta]=None, show_db_logs: bool=False)
 ```
 
 Initialize the object
@@ -47,18 +47,19 @@ Initialize the object
 - `database_only` (`bool`):  whether the reported data should not bestored in the memory, but only in the database
 - `config` (`str | dict`):  path to the configuration file or a mappingwith the config file content
 - `status_schema_path` (`str`):  path to the status schema that formalizesthe status flags structure
+- `custom_declarative_base` (`sqlalchemy.orm.DeclarativeMeta`):  a declarative base touse for ORMs creation a new instance will be created if not provided
 
 
 
 
 ```python
-def assert_results_defined(self, results)
+def assert_results_defined(self, results: List[str]) -> None
 ```
 
 Assert provided list of results is defined in the schema
 #### Parameters:
 
-- `results` (`list[str]`):  list of results tocheck for existence in the schema
+- `results` (`List[str]`):  list of results tocheck for existence in the schema
 
 
 #### Raises:
@@ -69,54 +70,61 @@ Assert provided list of results is defined in the schema
 
 
 ```python
-def check_connection(self)
+def check_record_exists(self, record_identifier: str, table_name: str=None) -> bool
 ```
 
-Check whether a PostgreSQL connection has been established
+Check if the specified record exists in the table
+#### Parameters:
+
+- `record_identifier` (`str`):  record to check for
+- `table_name` (`str`):  table name to check
+
+
 #### Returns:
 
-- `bool`:  whether the connection has been established
+- `bool`:  whether the record exists in the table
 
 
 
 
 ```python
-def check_record_exists(self, record_identifier=None)
+def check_result_exists(self, result_identifier: str, record_identifier: str=None) -> bool
 ```
 
-Check if the record exists
+Check if the result has been reported
 #### Parameters:
 
 - `record_identifier` (`str`):  unique identifier of the record
+- `result_identifier` (`str`):  name of the result to check
 
 
 #### Returns:
 
-- `bool`:  whether the record exists
+- `bool`:  whether the specified result has been reported for theindicated record in current namespace
 
 
 
 
 ```python
-def check_result_exists(self, result_identifier, record_identifier=None)
+def check_which_results_exist(self, results: List[str], rid: Optional[str]=None, table_name: Optional[str]=None) -> List[str]
 ```
 
-Check if the result has been reported
+Check which results have been reported
 #### Parameters:
 
-- `record_identifier` (`str`):  unique identifier of the record
-- `result_identifier` (`str`):  name of the result to check
+- `rid` (`str`):  unique identifier of the record
+- `results` (`List[str]`):  names of the results to check
 
 
 #### Returns:
 
-- `bool`:  whether the specified result has been reported for theindicated record in current namespace
+- `List[str]`:  whether the specified result has been reported for theindicated record in current namespace
 
 
 
 
 ```python
-def clear_status(self, record_identifier=None, flag_names=None)
+def clear_status(self, record_identifier: str=None, flag_names: List[str]=None) -> List[Optional[str]]
 ```
 
 Remove status flags
@@ -128,16 +136,8 @@ Remove status flags
 
 #### Returns:
 
-- `list[str]`:  Collection of names of flags removed
-
-
-
+- `List[str]`:  Collection of names of flags removed
 
-```python
-def close_postgres_connection(self)
-```
-
-Close connection and remove client bound
 
 
 
@@ -166,27 +166,53 @@ Data object
 
 
 ```python
-def db_cursor(self)
+def db_column_kwargs_by_result(self)
 ```
 
-Establish connection and get a PostgreSQL database cursor, commit and close the connection afterwards
+Database column key word arguments for every result, sourced from the results schema in the `db_column` section
 #### Returns:
 
-- `LoggingCursor`:  Database cursor object
+- `Dict[str, Any]`:  key word arguments for every result
 
 
 
 
 ```python
-def establish_postgres_connection(self, suppress=False)
+def db_column_relationships_by_result(self)
 ```
 
-Establish PostgreSQL connection using the config data
-#### Parameters:
+Database column relationships for every result, sourced from the results schema in the `relationship` section
 
-- `suppress` (`bool`):  whether to suppress any connection errors
+*Note: this is an experimental feature*
+#### Returns:
 
+- `Dict[str, Dict[str, str]]`:  relationships for every result
+
+
+
+
+```python
+def db_url(self)
+```
+
+Database URL, generated based on config credentials
+#### Returns:
+
+- `str`:  database URL
+
+
+#### Raises:
+
+- `PipestatDatabaseError`:  if the object is not backed by a database
+
+
+
+
+```python
+def establish_db_connection(self) -> bool
+```
 
+Establish DB connection using the config data
 #### Returns:
 
 - `bool`:  whether the connection has been established successfully
@@ -207,7 +233,24 @@ File path that the object is reporting the results into
 
 
 ```python
-def get_status(self, record_identifier=None)
+def get_orm(self, table_name: str=None) -> Any
+```
+
+Get an object relational mapper class
+#### Parameters:
+
+- `table_name` (`str`):  table name to get a class for
+
+
+#### Returns:
+
+- `Any`:  Object relational mapper class
+
+
+
+
+```python
+def get_status(self, record_identifier: str=None) -> Optional[str]
 ```
 
 Get the current pipeline status
@@ -219,7 +262,7 @@ Get the current pipeline status
 
 
 ```python
-def get_status_flag_path(self, status_identifier, record_identifier=None)
+def get_status_flag_path(self, status_identifier: str, record_identifier=None) -> str
 ```
 
 Get the path to the status file flag
@@ -243,7 +286,19 @@ def highlighted_results(self)
 Highlighted results
 #### Returns:
 
-- `list[str]`:  a collection of highlighted results
+- `List[str]`:  a collection of highlighted results
+
+
+
+
+```python
+def is_db_connected(self) -> bool
+```
+
+Check whether a DB connection has been established
+#### Returns:
+
+- `bool`:  whether the connection has been established
 
 
 
@@ -285,7 +340,7 @@ Unique identifier of the record
 
 
 ```python
-def remove(self, record_identifier=None, result_identifier=None)
+def remove(self, record_identifier: str=None, result_identifier: str=None) -> bool
 ```
 
 Remove a result.
@@ -306,13 +361,13 @@ will be removed.
 
 
 ```python
-def report(self, values, record_identifier=None, force_overwrite=False, strict_type=True, return_id=False)
+def report(self, values: Dict[str, Any], record_identifier: str=None, force_overwrite: bool=False, strict_type: bool=True, return_id: bool=False) -> Union[bool, int]
 ```
 
 Report a result.
 #### Parameters:
 
-- `values` (`dict[str, any]`):  dictionary of result-value pairs
+- `values` (`Dict[str, any]`):  dictionary of result-value pairs
 - `record_identifier` (`str`):  unique identifier of the record, valuein 'record_identifier' column to look for to determine if the record already exists
 - `force_overwrite` (`bool`):  whether to overwrite the existing record
 - `strict_type` (`bool`):  whether the type of the reported values shouldremain as is. Pipestat would attempt to convert to the schema-defined one otherwise
@@ -339,7 +394,7 @@ Result schema mappings
 
 
 ```python
-def retrieve(self, record_identifier=None, result_identifier=None)
+def retrieve(self, record_identifier: Optional[str]=None, result_identifier: Optional[str]=None) -> Union[Any, Dict[str, Any]]
 ```
 
 Retrieve a result for a record.
@@ -354,7 +409,7 @@ be returned.
 
 #### Returns:
 
-- `any | dict[str, any]`:  a single result or a mapping with all theresults reported for the record
+- `any | Dict[str, any]`:  a single result or a mapping with all theresults reported for the record
 
 
 
@@ -384,28 +439,56 @@ Schema path
 
 
 ```python
-def select(self, columns=None, condition=None, condition_val=None, offset=None, limit=None)
+def select(self, table_name: Optional[str]=None, columns: Optional[List[str]]=None, filter_conditions: Optional[List[Tuple[str, str, Union[str, List[str]]]]]=None, json_filter_conditions: Optional[List[Tuple[str, str, str]]]=None, offset: Optional[int]=None, limit: Optional[int]=None) -> List[Any]
 ```
 
-Get all the contents from the selected table, possibly restricted by the provided condition.
+Perform a `SELECT` on the table
 #### Parameters:
 
-- `columns` (`str | list[str]`):  columns to select
-- `condition` (`str`):  condition to restrict the resultswith, will be appended to the end of the SELECT statement and safely populated with 'condition_val', for example: `"id=%s"`
-- `condition_val` (`list`):  values to fill the placeholderin 'condition' with
-- `offset` (`int`):  number of records to be skipped
-- `limit` (`int`):  max number of records to be returned
+- `table_name` (`str`):  name of the table to SELECT from
+- `columns` (`List[str]`):  columns to include in the result
+- `filter_conditions` (`[(key,operator,value)]`): - eq for == - lt for < - ge for >= - in for in_ - like for like
+- `json_filter_conditions` (`[(col,key,value)]`):  conditions for JSONB column toquery that include JSON column name, key withing the JSON object in that column and the value to check the identity against. Therefore only '==' is supported in non-nested checks, e.g. [("other", "genome", "hg38")]
+- `offset` (`int`):  skip this number of rows
+- `limit` (`int`):  include this number of rows
+
+
+
+
+```python
+def select_txt(self, filter_templ: Optional[str]='', filter_params: Optional[Dict[str, Any]]={}, table_name: Optional[str]=None, offset: Optional[int]=None, limit: Optional[int]=None) -> List[Any]
+```
+
+Execute a query with a textual filter. Returns all results.
+
+To retrieve all table contents, leave the filter arguments out.
+Table name defaults to the namespace
+#### Parameters:
+
+- `filter_templ` (`str`):  filter template with value placeholders,formatted as follows `id<:value and name=:name`
+- `filter_params` (`Dict[str, Any]`):  a mapping keys specified in the `filter_templ`to parameters that are supposed to replace the placeholders
+- `table_name` (`str`):  name of the table to query
+- `offset` (`int`):  skip this number of rows
+- `limit` (`int`):  include this number of rows
 
 
 #### Returns:
 
-- `list[psycopg2.extras.DictRow]`:  all table contents
+- `List[Any]`:  a list of matched records
+
+
+
+
+```python
+def session(self)
+```
 
+Provide a transactional scope around a series of query operations.
 
 
 
 ```python
-def set_status(self, status_identifier, record_identifier=None)
+def set_status(self, status_identifier: str, record_identifier: str=None) -> None
 ```
 
 Set pipeline run status.
@@ -446,7 +529,7 @@ Status schema source
 
 
 ```python
-def validate_schema(self)
+def validate_schema(self) -> None
 ```
 
 Check schema for any possible issues
@@ -460,4 +543,4 @@ Check schema for any possible issues
 
 
 
-*Version Information: `pipestat` v0.0.3-dev, generated by `lucidoc` v0.4.3*
\ No newline at end of file
+*Version Information: `pipestat` v0.1.0-dev, generated by `lucidoc` v0.4.2*
diff --git a/docs/changelog.md b/docs/changelog.md
index 8419336f..7e48bec2 100644
--- a/docs/changelog.md
+++ b/docs/changelog.md
@@ -2,17 +2,36 @@
 
 This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html) and [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) format.
 
+## [0.1.0] - 2021-06-24
+
+**This update introduces some backwards-incompatible changes due to database interface redesign**
+
+### Changed
+
+- database interface type from a driver to an Object–relational mapping (ORM) approach
+
+### Added
+
+- results highligting support
+- database column parametrizing from the results schema
+- static typing
+- possibility to initialize the `PipestatManager` object (or use the `pipestat status` CLI) with no results schema defined for pipeline status management even when backed by a database; [Issue #1](https://github.com/pepkit/pipestat/issues/1)
+
 ## [0.0.4] - 2021-04-02
+
 ### Added
+
 - config validation
 - typing in code
 
-
 ## [0.0.3] - 2021-03-12
+
 ### Added
-- possibility to initialize the `PipestatManager` object (or use the `pipestat status` CLI) with no results schema defined for pipeline status management; [Issue #1](https://github.com/pepkit/pipestat/issues/1)
 
+- possibility to initialize the `PipestatManager` object (or use the `pipestat status` CLI) with no results schema defined for pipeline status management; [Issue #1](https://github.com/pepkit/pipestat/issues/1)
 
 ## [0.0.2] - 2021-02-22
+
 ### Added
+
 - initial package release
diff --git a/docs/config.md b/docs/config.md
index 21019931..a9a28755 100644
--- a/docs/config.md
+++ b/docs/config.md
@@ -8,28 +8,30 @@ schema_path: <path to the schema>
 record_identifier: <unique record ID>
 results_file_path: <path to results file> # either "results_file_path"
 database: # or DB login credentials
-    name: <database name>
-    user: <user name>
-    password: <user password>
-    host: <database address>
-    port: <database port>
+  name: <database name>
+  user: <user name>
+  password: <user password>
+  host: <database address>
+  port: <database port>
+  dialect: <database type>
+  driver: <python database driver>
 ```
 
 If both `results_file_path` and DB login credentials are provided, the YAML results file is given priority.
 
-Any of the settings specified in the configuration file, apart from the database login credentials, can be overwritten with the respectively named arguments in the `PipestatManager` object constructor, which implies the fact that the configuration file is *required* only if the the intended pipestat back-end is a database.     
+Any of the settings specified in the configuration file, apart from the database login credentials, can be overwritten with the respectively named arguments in the `PipestatManager` object constructor, which implies the fact that the configuration file is *required* only if the the intended pipestat back-end is a database.
 
 ## Example
 
 For the [PostgreSQL](https://www.postgresql.org/) instance has been started in a container, with the following command:
 
 ```console
-docker run -d 
-    --name pipestat-postgres \ 
-    -p 5432:5432 \ 
+docker run -d
+    --name pipestat-postgres \
+    -p 5432:5432 \
     -e POSTGRES_PASSWORD=b4fd34f^Fshdwede \
-    -e POSTGRES_USER=john \ 
-    -e POSTGRES_DB=pipestat-test \ 
+    -e POSTGRES_USER=john \
+    -e POSTGRES_DB=pipestat-test \
     -v postgres-data:/var/lib/postgresql/data postgres
 ```
 
@@ -39,9 +41,11 @@ The configuration file should look like this:
 namespace: my_pipeline
 schema_path: /path/to/schema.yaml
 database:
-    name: pipestat-test
-    user: john
-    password: b4fd34f^Fshdwede
-    host: localhost
-    port: 5432
-```
\ No newline at end of file
+  name: pipestat-test
+  user: john
+  password: b4fd34f^Fshdwede
+  host: 127.0.0.1
+  port: 5432
+  dialect: postgresql
+  driver: psycopg2
+```
diff --git a/docs/configuration.md b/docs/configuration.md
new file mode 100644
index 00000000..0ac6460f
--- /dev/null
+++ b/docs/configuration.md
@@ -0,0 +1,17 @@
+# Pipestat configuration
+
+Pipestat *requires* a few pieces of information to run:
+
+- a **namespace** to write into, for example the name of the pipeline
+- a path to the **schema** file that describes results that can be reported
+- **backend info**: either path to a YAML-formatted file or pipestat config with PostgreSQL database login credentials
+
+Apart from that, there are many other *optional* configuration points that have defaults. Please refer to the [environment variables reference](http://pipestat.databio.org/en/dev/env_vars/) to learn about the the optional configuration options and their meaning.
+
+## Configuration sources
+
+Pipestat configuration can come from 3 sources, with the following priority:
+
+1. `PipestatManager` constructor
+2. Pipestat configuration file
+3. Environment variables
diff --git a/docs/contributing.md b/docs/contributing.md
index e53b307a..d2e6cd6b 100644
--- a/docs/contributing.md
+++ b/docs/contributing.md
@@ -1,7 +1,7 @@
-## Contributing
+# Contributing
 
 We welcome contributions from the community.
 
-## Suggestions and feedback
+# Suggestions and feedback
 
 Please open an issue on the github issue tracker with suggestions, bug reports, or other feedback.
diff --git a/docs/env_vars.md b/docs/env_vars.md
index c68fc9ab..0dc32e51 100644
--- a/docs/env_vars.md
+++ b/docs/env_vars.md
@@ -4,7 +4,6 @@ Both the command line interface (CLI) and Python API support a collection of env
 
 Here is a list of the supported environment variables:
 
-
 | Environment variable       | API argument       | Description                                                                                                                 |
 |----------------------------|--------------------|-----------------------------------------------------------------------------------------------------------------------------|
 | **PIPESTAT_NAMESPACE**     | namespace          | namespace to report into. This will be the DBtable name if using DB as the object back-end                                  |
@@ -12,4 +11,4 @@ Here is a list of the supported environment variables:
 | **PIPESTAT_CONFIG**         | config             | path to the configuration file or a mappingwith the config file content                                                     |
 | **PIPESTAT_RESULTS_FILE**   | results_file_path  | YAML file to report into, if file isused as the object back-end                                                             |
 | **PIPESTAT_RESULTS_SCHEMA** | schema_path        | path to the output schema that formalizesthe results structure                                                              |
-| **PIPESTAT_STATUS_SCHEMA**  | status_schema_path | path to the status schema that formalizes the status flags structure                                                        |
\ No newline at end of file
+| **PIPESTAT_STATUS_SCHEMA**  | status_schema_path | path to the status schema that formalizes the status flags structure                                                        |
diff --git a/docs/install.md b/docs/install.md
index 6ccde5e5..9282d686 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -8,6 +8,7 @@ Install pipestat from [GitHub releases](https://github.com/pepkit/pipestat/relea
 - `pip install --upgrade pipestat`: update in virtual environment.
 
 See if your install worked by calling `pipestat -h` on the command line. If the `pipestat` executable is not in your `$PATH`, append this to your `.bashrc` or `.profile` (or `.bash_profile` on macOS):
+
 ```console
 export PATH=~/.local/bin:$PATH
-```
\ No newline at end of file
+```
diff --git a/docs/pipestat_specification.md b/docs/pipestat_specification.md
index 61169abf..a1a987e2 100644
--- a/docs/pipestat_specification.md
+++ b/docs/pipestat_specification.md
@@ -6,11 +6,10 @@
 
 Pipelines, or workflows, are made from a set of commands that process input data and produce results. These results may take many forms, such as simple statistics, string variables, images, or processed data files. How do pipelines structure the results they produce? There is no standard structure for results, so usually, it's done differently for each pipeline. This restricts the portability of the outputs of pipelines, and makes it difficult to write software that can process results from a variety of different pipelines. As a result, each pipeline author usually writes dedicated report functions for each pipeline.
 
-Pipestat provides a formal specification for how a pipeline should structure its results. Therefore, any pipeline that follows the pipestat specification will record results in the same way. This makes it possible to build generic report software that can work with any pipestat-compatible pipeline, offloading the task of making pretty result reports to generic tools. 
+Pipestat provides a formal specification for how a pipeline should structure its results. Therefore, any pipeline that follows the pipestat specification will record results in the same way. This makes it possible to build generic report software that can work with any pipestat-compatible pipeline, offloading the task of making pretty result reports to generic tools.
 
 This document outlines the specification for pipestat results. If your pipeline stores results like this, then downstream tools that read pipestat results will be able to build nice summaries of your pipeline runs automatically. To write results according to this specification, you can use the reference implementation (the `pipestat` python package), or you can simply write your results to this specification using whatever system you like.
 
-
 # Terminology
 
 - *result*: An element produced by a pipeline. Results have defined data types, described herein.
@@ -33,13 +32,13 @@ Each *result* reported by a pipeline must have a specified data type. Pipestat i
 
 Importantly, pipestat extends the jsonschema vocabulary by adding two additional types, which are common results of a pipeline: `image` and `file`. These types require reporting objects with the following attributes:
 
-- `file`: 
-    - `path`: path to the reported file
-    - `title`: human readable description of the file
-- `image`: 
-    - `path`: path to the reported image, usually PDF
-    - `thumbnail`: path to the reported thumbnail, usually PNG or JPEG
-    - `title`: human readable description of the image    
+- `file`:
+  - `path`: path to the reported file
+  - `title`: human readable description of the file
+- `image`:
+  - `path`: path to the reported image, usually PDF
+  - `thumbnail`: path to the reported thumbnail, usually PNG or JPEG
+  - `title`: human readable description of the image
 
 # Pipestat schema
 
@@ -60,11 +59,10 @@ The pipestat schema is a YAML-formatted file. The top level keys are the unique
 ```yaml
 result_identifier:
   type: <type>
-``` 
+```
 
 Here, `result_identifier` can be whatever name you want to use to identify this result. Here's a simple schema example that showcases most of the supported types:
 
-
 ```yaml
 number_of_things:
   type: integer
@@ -90,7 +88,7 @@ output_file:
 output_image:
   type: image
   description: "This a path to the output image"
-``` 
+```
 
 Here's a more complex schema example that showcases some of the more advanced jsonschema features:
 
@@ -114,18 +112,18 @@ output_object:
   properties:
     property1:
       array:
-        items: 
+        items:
           type: integer
     property2:
       type: boolean
   required:
     - property1
   description: "Object output with required array of integers and optional boolean"
-``` 
+```
 
 ## Results highlighting
 
-The pipestat specification allows to highlight results by adding `highlight: true` attribute under result identifier in the schema file. In the example below the `log_file` result will be highlighted. 
+The pipestat specification allows to highlight results by adding `highlight: true` attribute under result identifier in the schema file. In the example below the `log_file` result will be highlighted.
 
 ```yaml
 number_of_things:
@@ -142,13 +140,28 @@ log_file:
 
 The highlighted results can be later retrieved by pipestat clients via `PipestatManager.highlighted_results` property, which simply returns a list of result identifiers.
 
+## Database columns configuration (DB backend only)
+If the `PipestatManager` object is backed by a database, the database columns can be easily configured using the results schema via `db_column` section. For example:
+
+```yaml
+important_numeric_id:
+  type: integer
+  description: "An important ID that must be unique and always exist"
+  db_column:
+    unique: true
+    nullable: false
+```
+
+The values provided in the `db_column` section are passed to the `sqlalchemy.schema.Column` constructor. Therefore, please refer to [`sqlalchemy.Column` class constructor documentation](https://docs.sqlalchemy.org/en/14/core/metadata.html?highlight=column#sqlalchemy.schema.Column.__init__) to learn more about the keys that can be specified in this section.
+
+In the above example, the `important_numeric_id` result reported with the `PipestatManager` instance initialized with that schema will be forced to be always provided and unique across all records.
+
 # Status schema
 
 Apart from results reporting pipestat provides a robust pipeline status management system, which can be used to report pipeline status from within the pipeline and monitor pipeline's status in other software. Status schema file defines the possible pipeline status identifiers and provides other metadata, like `description` or `color` for display purposes.
 
 Here's an example of the pipestat status schema, which at the same time is the default status schema shipped with the pipestat Python package:
 
-
 ```yaml
 running:
   description: "the pipeline is running"
@@ -174,7 +187,7 @@ As depicted above the top-level attributes are the status identifiers. Within ea
 
 # Backends
 
-The pipestat specification describes two backend types for storing results: a [YAML-formatted file](https://yaml.org/spec/1.2/spec.html) or a [PostgreSQL database](https://www.postgresql.org/). This flexibility makes pipestat useful for a wide variety of use cases. Some users just need a simple text file for smaller-scale needs, which is convenient and universal, requiring no database infrastructure. For larger-scale systems, a database back-end is necssary. The pipestat specification provides a layer that spans the two possibilities, so that reports can be made in the same way, regardless of which back-end is used in a particular use case. 
+The pipestat specification describes two backend types for storing results: a [YAML-formatted file](https://yaml.org/spec/1.2/spec.html) or a [PostgreSQL database](https://www.postgresql.org/). This flexibility makes pipestat useful for a wide variety of use cases. Some users just need a simple text file for smaller-scale needs, which is convenient and universal, requiring no database infrastructure. For larger-scale systems, a database back-end is necssary. The pipestat specification provides a layer that spans the two possibilities, so that reports can be made in the same way, regardless of which back-end is used in a particular use case.
 
 By using the `pipestat` package to write results, the pipeline author need not be concerned with database connections or dealing with racefree file writing, as these tasks are already implemented. The user who runs the pipeline will simply configure the pipestat backend as required.
 
@@ -190,32 +203,29 @@ For the YAML file backend, each file represents a namespace. The file always beg
 my_namespace:
     record1:
         my_result: 10
-        my_result1: 
+        my_result1:
             key: "value1"
     record2:
         my_result: 3
-        my_result1: 
+        my_result1:
             key: "value2"
-```  
+```
 
 A more concrete example would be:
 
-
 ```yaml
 rnaseq-pipe:
     patient1:
         duplicate_rate: 10
-        genomic_distribution: 
+        genomic_distribution:
             promoter: 15
             enhancer: 85
     patient2:
         duplicate_rate: 3
-        genomic_distribution: 
+        genomic_distribution:
             promoter: 30
             enhancer: 70
-```  
-
-
+```
 
 ## PostgreSQL database
 
diff --git a/docs/schema.md b/docs/schema.md
deleted file mode 100644
index 2e9bb4c5..00000000
--- a/docs/schema.md
+++ /dev/null
@@ -1,100 +0,0 @@
-# Schema specification
-
-One of the *required* pipestat inputs is a schema file. **The schema specifies the results types and names that can be reported with pipestat.** As a pipeline developer, you create a schema to describe all of the important results to be recorded from your pipeline.
-
-Pipestat uses the schema as a base for creating a collection of self-contained result-specific [jsonschema schemas](https://json-schema.org/) that are used to **validate** the reported results prior to inserting into the database or saving in the YAML results file, depending on the selected backend.
-
-## Components
-
-Each schema is a YAML-formatted file composed of a set of self-contained result definitions. The top level keys are the unique result identifiers. The result definitions are jsonschema schemas. For a minimal schema, only the `type` attribute is required, which indicates the required type of the result to be reported. Please refer to the jsonschema documentation to learn more about the types and other attributes. This is an example of such component:
-
-```yaml
-result_identifier:
-  type: <type>
-``` 
-
-Here, `result_identifier` can be whatever name you want to use to identify this result. Importantly, pipestat extends the jsonschema vocabulary by adding two additional types: `image` and `file`. These types require reporting objects with the following attributes:
-
-- `file`: 
-    - `path`: path to the reported file
-    - `title`: human readable description of the file
-- `image`: 
-    - `path`: path to the reported image, usually PDF
-    - `thumbnail`: path to the reported thumbnail, usually PNG or JPEG
-    - `title`: human readable description of the image    
-
-Therefore, in practice, a result of type `file` is equivalent to:
-
-```yaml
-type: object
-properties:
-    path:
-      type: string
-    title:
-      type: string
-``` 
-
-## Basic example
-
-Here's a simple schema example that showcases most of the supported types:
-
-
-```yaml
-number_of_things:
-  type: integer
-  description: "Number of things"
-percentage_of_things:
-  type: number
-  description: "Percentage of things"
-name_of_something:
-  type: string
-  description: "Name of something"
-swtich_value:
-  type: boolean
-  description: "Is the switch on of off"
-collection_of_things:
-  type: array
-  description: "This store collection of values"
-output_object:
-  type: object
-  description: "Object output"
-output_file:
-  type: file
-  description: "This a path to the output file"
-output_image:
-  type: image
-  description: "This a path to the output image"
-``` 
-
-## More complex example
-
-Here's a more complex schema example that showcases some of the more advanced jsonschema features:
-
-```yaml
-number_of_things:
-  type: integer
-  description: "Number of things, min 20, multiple of 10"
-  multipleOf: 10
-  minimum: 20
-name_of_something:
-  type: string
-  description: "Name of something, min len 2 characters"
-  minLength: 2
-collection_of_things:
-  type: array
-  items:
-    type: string
-  description: "This store collection of strings"
-output_object:
-  type: object
-  properties:
-    property1:
-      array:
-        items: 
-          type: integer
-    property2:
-      type: boolean
-  required:
-    - property1
-  description: "Object output with required array of integers and optional boolean"
-``` 
diff --git a/docs/usage.md b/docs/usage.md
new file mode 100644
index 00000000..df9c6c45
--- /dev/null
+++ b/docs/usage.md
@@ -0,0 +1,254 @@
+# Usage reference
+
+Pipestat offers a CLI that can be access via the `pipestat` command in the shell. It offers complete control over reporting, inspecting, etc, via a series of subcommands.
+
+Here you can see the command-line usage instructions for the main command and for each subcommand:
+## `pipestat --help`
+```console
+version: 0.1.0-dev
+usage: pipestat [-h] [--version] [--silent] [--verbosity V] [--logdev]
+                {report,inspect,remove,retrieve,status} ...
+
+pipestat - report pipeline results
+
+positional arguments:
+  {report,inspect,remove,retrieve,status}
+    report              Report a result.
+    inspect             Inspect a database.
+    remove              Remove a result.
+    retrieve            Retrieve a result.
+    status              Manage pipeline status.
+
+optional arguments:
+  -h, --help            show this help message and exit
+  --version             show program's version number and exit
+  --silent              Silence logging. Overrides verbosity.
+  --verbosity V         Set logging level (1-5 or logging module level name)
+  --logdev              Expand content of logging message format.
+
+Pipestat standardizes reporting of pipeline results and pipeline status
+management. It formalizes a way for pipeline developers and downstream tools
+developers to communicate -- results produced by a pipeline can easily and
+reliably become an input for downstream analyses. The object exposes API for
+interacting with the results and pipeline status and can be backed by either a
+YAML-formatted file or a database.
+```
+
+## `pipestat report --help`
+```console
+usage: pipestat report [-h] [-n N] [-f F] [-c C] [-a] [-s S] [--status-schema ST]
+                       [--flag-dir FD] -i I [-r R] -v V [-o] [-t]
+
+Report a result.
+
+optional arguments:
+  -h, --help                   show this help message and exit
+  -n N, --namespace N          Name of the pipeline to report result for. If not provided
+                               'PIPESTAT_NAMESPACE' env var will be used. Currently not
+                               set
+  -f F, --results-file F       Path to the YAML file where the results will be stored.
+                               This file will be used as pipestat backend and to restore
+                               the reported results across sessions
+  -c C, --config C             Path to the YAML configuration file. If not provided
+                               'PIPESTAT_CONFIG' env var will be used. Currently not set
+  -a, --database-only          Whether the reported data should not be stored in the
+                               memory, only in the database.
+  -s S, --schema S             Path to the schema that defines the results that can be
+                               reported. If not provided 'PIPESTAT_RESULTS_SCHEMA' env var
+                               will be used. Currently not set
+  --status-schema ST           Path to the status schema. Default will be used if not
+                               provided: /usr/local/lib/python3.9/site-
+                               packages/pipestat/schemas/status_schema.yaml
+  --flag-dir FD                Path to the flag directory in case YAML file is the
+                               pipestat backend.
+  -i I, --result-identifier I  ID of the result to report; needs to be defined in the
+                               schema
+  -r R, --record-identifier R  ID of the record to report the result for. If not provided
+                               'PIPESTAT_RECORD_ID' env var will be used. Currently not
+                               set
+  -v V, --value V              Value of the result to report
+  -o, --overwrite              Whether the result should override existing ones in case of
+                               name clashes
+  -t, --skip-convert           Whether skip result type conversion into the reqiuired
+                               class in case it does not meet the schema requirements
+```
+
+## `pipestat inspect --help`
+```console
+usage: pipestat inspect [-h] [-n N] [-f F] [-c C] [-a] [-s S] [--status-schema ST]
+                        [--flag-dir FD] [-d]
+
+Inspect a database.
+
+optional arguments:
+  -h, --help              show this help message and exit
+  -n N, --namespace N     Name of the pipeline to report result for. If not provided
+                          'PIPESTAT_NAMESPACE' env var will be used. Currently not set
+  -f F, --results-file F  Path to the YAML file where the results will be stored. This
+                          file will be used as pipestat backend and to restore the
+                          reported results across sessions
+  -c C, --config C        Path to the YAML configuration file. If not provided
+                          'PIPESTAT_CONFIG' env var will be used. Currently not set
+  -a, --database-only     Whether the reported data should not be stored in the memory,
+                          only in the database.
+  -s S, --schema S        Path to the schema that defines the results that can be
+                          reported. If not provided 'PIPESTAT_RESULTS_SCHEMA' env var will
+                          be used. Currently not set
+  --status-schema ST      Path to the status schema. Default will be used if not provided:
+                          /usr/local/lib/python3.9/site-
+                          packages/pipestat/schemas/status_schema.yaml
+  --flag-dir FD           Path to the flag directory in case YAML file is the pipestat
+                          backend.
+  -d, --data              Whether to display the data
+```
+
+## `pipestat remove --help`
+```console
+usage: pipestat remove [-h] [-n N] [-f F] [-c C] [-a] [-s S] [--status-schema ST]
+                       [--flag-dir FD] -i I [-r R]
+
+Remove a result.
+
+optional arguments:
+  -h, --help                   show this help message and exit
+  -n N, --namespace N          Name of the pipeline to report result for. If not provided
+                               'PIPESTAT_NAMESPACE' env var will be used. Currently not
+                               set
+  -f F, --results-file F       Path to the YAML file where the results will be stored.
+                               This file will be used as pipestat backend and to restore
+                               the reported results across sessions
+  -c C, --config C             Path to the YAML configuration file. If not provided
+                               'PIPESTAT_CONFIG' env var will be used. Currently not set
+  -a, --database-only          Whether the reported data should not be stored in the
+                               memory, only in the database.
+  -s S, --schema S             Path to the schema that defines the results that can be
+                               reported. If not provided 'PIPESTAT_RESULTS_SCHEMA' env var
+                               will be used. Currently not set
+  --status-schema ST           Path to the status schema. Default will be used if not
+                               provided: /usr/local/lib/python3.9/site-
+                               packages/pipestat/schemas/status_schema.yaml
+  --flag-dir FD                Path to the flag directory in case YAML file is the
+                               pipestat backend.
+  -i I, --result-identifier I  ID of the result to report; needs to be defined in the
+                               schema
+  -r R, --record-identifier R  ID of the record to report the result for. If not provided
+                               'PIPESTAT_RECORD_ID' env var will be used. Currently not
+                               set
+```
+
+## `pipestat retrieve --help`
+```console
+usage: pipestat retrieve [-h] [-n N] [-f F] [-c C] [-a] [-s S] [--status-schema ST]
+                         [--flag-dir FD] -i I [-r R]
+
+Retrieve a result.
+
+optional arguments:
+  -h, --help                   show this help message and exit
+  -n N, --namespace N          Name of the pipeline to report result for. If not provided
+                               'PIPESTAT_NAMESPACE' env var will be used. Currently not
+                               set
+  -f F, --results-file F       Path to the YAML file where the results will be stored.
+                               This file will be used as pipestat backend and to restore
+                               the reported results across sessions
+  -c C, --config C             Path to the YAML configuration file. If not provided
+                               'PIPESTAT_CONFIG' env var will be used. Currently not set
+  -a, --database-only          Whether the reported data should not be stored in the
+                               memory, only in the database.
+  -s S, --schema S             Path to the schema that defines the results that can be
+                               reported. If not provided 'PIPESTAT_RESULTS_SCHEMA' env var
+                               will be used. Currently not set
+  --status-schema ST           Path to the status schema. Default will be used if not
+                               provided: /usr/local/lib/python3.9/site-
+                               packages/pipestat/schemas/status_schema.yaml
+  --flag-dir FD                Path to the flag directory in case YAML file is the
+                               pipestat backend.
+  -i I, --result-identifier I  ID of the result to report; needs to be defined in the
+                               schema
+  -r R, --record-identifier R  ID of the record to report the result for. If not provided
+                               'PIPESTAT_RECORD_ID' env var will be used. Currently not
+                               set
+```
+
+## `pipestat status --help`
+```console
+usage: pipestat status [-h] {set,get} ...
+
+Manage pipeline status.
+
+positional arguments:
+  {set,get}
+    set       Set status.
+    get       Get status.
+
+optional arguments:
+  -h, --help  show this help message and exit
+```
+
+## `pipestat status get --help`
+```console
+usage: pipestat status get [-h] [-n N] [-f F] [-c C] [-a] [-s S] [--status-schema ST]
+                           [--flag-dir FD] [-r R]
+
+Get status.
+
+optional arguments:
+  -h, --help                   show this help message and exit
+  -n N, --namespace N          Name of the pipeline to report result for. If not provided
+                               'PIPESTAT_NAMESPACE' env var will be used. Currently not
+                               set
+  -f F, --results-file F       Path to the YAML file where the results will be stored.
+                               This file will be used as pipestat backend and to restore
+                               the reported results across sessions
+  -c C, --config C             Path to the YAML configuration file. If not provided
+                               'PIPESTAT_CONFIG' env var will be used. Currently not set
+  -a, --database-only          Whether the reported data should not be stored in the
+                               memory, only in the database.
+  -s S, --schema S             Path to the schema that defines the results that can be
+                               reported. If not provided 'PIPESTAT_RESULTS_SCHEMA' env var
+                               will be used. Currently not set
+  --status-schema ST           Path to the status schema. Default will be used if not
+                               provided: /usr/local/lib/python3.9/site-
+                               packages/pipestat/schemas/status_schema.yaml
+  --flag-dir FD                Path to the flag directory in case YAML file is the
+                               pipestat backend.
+  -r R, --record-identifier R  ID of the record to report the result for. If not provided
+                               'PIPESTAT_RECORD_ID' env var will be used. Currently not
+                               set
+```
+
+## `pipestat status set --help`
+```console
+usage: pipestat status set [-h] [-n N] [-f F] [-c C] [-a] [-s S] [--status-schema ST]
+                           [--flag-dir FD] [-r R]
+                           status_identifier
+
+Set status.
+
+positional arguments:
+  status_identifier            Status identifier to set.
+
+optional arguments:
+  -h, --help                   show this help message and exit
+  -n N, --namespace N          Name of the pipeline to report result for. If not provided
+                               'PIPESTAT_NAMESPACE' env var will be used. Currently not
+                               set
+  -f F, --results-file F       Path to the YAML file where the results will be stored.
+                               This file will be used as pipestat backend and to restore
+                               the reported results across sessions
+  -c C, --config C             Path to the YAML configuration file. If not provided
+                               'PIPESTAT_CONFIG' env var will be used. Currently not set
+  -a, --database-only          Whether the reported data should not be stored in the
+                               memory, only in the database.
+  -s S, --schema S             Path to the schema that defines the results that can be
+                               reported. If not provided 'PIPESTAT_RESULTS_SCHEMA' env var
+                               will be used. Currently not set
+  --status-schema ST           Path to the status schema. Default will be used if not
+                               provided: /usr/local/lib/python3.9/site-
+                               packages/pipestat/schemas/status_schema.yaml
+  --flag-dir FD                Path to the flag directory in case YAML file is the
+                               pipestat backend.
+  -r R, --record-identifier R  ID of the record to report the result for. If not provided
+                               'PIPESTAT_RECORD_ID' env var will be used. Currently not
+                               set
+```
diff --git a/docs/usage.template b/docs/usage.template
new file mode 100644
index 00000000..abbab4da
--- /dev/null
+++ b/docs/usage.template
@@ -0,0 +1,5 @@
+# Usage reference
+
+Pipestat offers a CLI that can be access via the `pipestat` command in the shell. It offers complete control over reporting, inspecting, etc, via a series of subcommands.
+
+Here you can see the command-line usage instructions for the main command and for each subcommand:
diff --git a/docs_jupyter/cli.ipynb b/docs_jupyter/cli.ipynb
index 914ace6f..9efec6fa 100644
--- a/docs_jupyter/cli.ipynb
+++ b/docs_jupyter/cli.ipynb
@@ -6,403 +6,130 @@
    "source": [
     "# Pipestat CLI\n",
     "\n",
-    "**Before following this tutorial please make sure you're familiar with more information-rich \"Pipestat Python API\" tutorial.**"
+    "This tutorial demonstrates how to use the pipeline command-line interface (CLI). You should have already installed pipestat. **Before following this tutorial please make sure you're familiar with more information-rich \"Pipestat Python API\" tutorial.**"
    ]
   },
   {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "## Prepare environment\n",
-    "\n",
-    "Pipestat command line interface can use multiple environment variables to avoid copious repetition of arguments in subsequent `pipestat` calls. \n",
-    "\n",
-    "Please refer to the [Environment variables reference](http://pipestat.databio.org/en/latest/env_vars/) for the complete list of supported environment variables. We will set a few for this tutorial:"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 1,
-   "metadata": {},
-   "outputs": [],
    "source": [
-    "export PIPESTAT_RESULTS_SCHEMA=../tests/data/sample_output_schema.yaml\n",
-    "export PIPESTAT_RECORD_ID=sample1\n",
-    "export PIPESTAT_RESULTS_FILE=`mktemp` # temporary file for results storage\n",
-    "export PIPESTAT_NAMESPACE=test"
-   ]
-  },
-  {
+    "Report results from the command line by calling `pipestat` and passing in all relevant information:"
+   ],
    "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "\n",
-    "## Usage reference\n",
-    "\n",
-    "To learn about the usage `pipestat` usage use `--help`/`-h` option on any level. If the environment variables are set, the `pipestat` command help will reflect that:"
-   ]
+   "metadata": {}
   },
   {
    "cell_type": "code",
-   "execution_count": 2,
+   "execution_count": 35,
    "metadata": {},
    "outputs": [
     {
-     "name": "stdout",
      "output_type": "stream",
-     "text": [
-      "version: 0.0.3\n",
-      "usage: pipestat [-h] [--version] [--silent] [--verbosity V] [--logdev]\n",
-      "                {report,inspect,remove,retrieve,status} ...\n",
-      "\n",
-      "pipestat - report pipeline results\n",
-      "\n",
-      "positional arguments:\n",
-      "  {report,inspect,remove,retrieve,status}\n",
-      "    report              Report a result.\n",
-      "    inspect             Inspect a database.\n",
-      "    remove              Remove a result.\n",
-      "    retrieve            Retrieve a result.\n",
-      "    status              Manage pipeline status.\n",
-      "\n",
-      "optional arguments:\n",
-      "  -h, --help            show this help message and exit\n",
-      "  --version             show program's version number and exit\n",
-      "  --silent              Silence logging. Overrides verbosity.\n",
-      "  --verbosity V         Set logging level (1-5 or logging module level name)\n",
-      "  --logdev              Expand content of logging message format.\n",
-      "\n",
-      "Pipestat standardizes reporting of pipeline results and pipeline status\n",
-      "management. It formalizes a way for pipeline developers and downstream tools\n",
-      "developers to communicate -- results produced by a pipeline can easily and\n",
-      "reliably become an input for downstream analyses. The object exposes API for\n",
-      "interacting with the results and pipeline status and can be backed by either a\n",
-      "YAML-formatted file or a PostgreSQL database.\n"
-     ]
-    }
-   ],
-   "source": [
-    "pipestat -h"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 3,
-   "metadata": {},
-   "outputs": [
-    {
      "name": "stdout",
-     "output_type": "stream",
      "text": [
-      "usage: pipestat report [-h] [-n N] [-f F] [-c C] [-a] [-s S] [--status-schema ST]\n",
-      "                       [--flag-dir FD] -i I [-r R] -v V [-o] [-t]\n",
-      "\n",
-      "Report a result.\n",
-      "\n",
-      "optional arguments:\n",
-      "  -h, --help                   show this help message and exit\n",
-      "  -n N, --namespace N          Name of the pipeline to report result for. If not provided\n",
-      "                               'PIPESTAT_NAMESPACE' env var will be used. Currently set\n",
-      "                               to: test\n",
-      "  -f F, --results-file F       Path to the YAML file where the results will be stored.\n",
-      "                               This file will be used as pipestat backend and to restore\n",
-      "                               the reported results across sessions\n",
-      "  -c C, --config C             Path to the YAML configuration file. If not provided\n",
-      "                               'PIPESTAT_CONFIG' env var will be used. Currently not set\n",
-      "  -a, --database-only          Whether the reported data should not be stored in the\n",
-      "                               memory, only in the database.\n",
-      "  -s S, --schema S             Path to the schema that defines the results that can be\n",
-      "                               reported. If not provided 'PIPESTAT_RESULTS_SCHEMA' env var\n",
-      "                               will be used. Currently set to:\n",
-      "                               ../tests/data/sample_output_schema.yaml\n",
-      "  --status-schema ST           Path to the status schema. Default will be used if not\n",
-      "                               provided: /Library/Frameworks/Python.framework/Versions/3.6\n",
-      "                               /lib/python3.6/site-\n",
-      "                               packages/pipestat/schemas/status_schema.yaml\n",
-      "  --flag-dir FD                Path to the flag directory in case YAML file is the\n",
-      "                               pipestat backend.\n",
-      "  -i I, --result-identifier I  ID of the result to report; needs to be defined in the\n",
-      "                               schema\n",
-      "  -r R, --record-identifier R  ID of the record to report the result for. If not provided\n",
-      "                               'PIPESTAT_RECORD_ID' env var will be used. Currently set\n",
-      "                               to: sample1\n",
-      "  -v V, --value V              Value of the result to report\n",
-      "  -o, --overwrite              Whether the result should override existing ones in case of\n",
-      "                               name clashes\n",
-      "  -t, --try-convert            Whether to try to convert the reported value into reqiuired\n",
-      "                               class in case it does not meet the schema requirements\n"
+      "Reported records for 'sample_name' in 'pipeline_name' namespace:\n",
+      " - percentage_of_things: 12\n"
      ]
     }
    ],
    "source": [
-    "pipestat report -h"
+    "rm ../tests/data/test_results_1.yaml\n",
+    "touch ../tests/data/test_results_1.yaml\n",
+    "pipestat report \\\n",
+    "    --namespace pipeline_name \\\n",
+    "    --record-identifier sample_name \\\n",
+    "    --result-identifier percentage_of_things \\\n",
+    "    --value 12 \\\n",
+    "    --results-file ../tests/data/test_results_1.yaml \\\n",
+    "    --schema ../tests/data/sample_output_schema.yaml"
    ]
   },
   {
-   "cell_type": "code",
-   "execution_count": 4,
+   "cell_type": "markdown",
    "metadata": {},
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "usage: pipestat retrieve [-h] [-n N] [-f F] [-c C] [-a] [-s S] [--status-schema ST]\n",
-      "                         [--flag-dir FD] -i I [-r R]\n",
-      "\n",
-      "Retrieve a result.\n",
-      "\n",
-      "optional arguments:\n",
-      "  -h, --help                   show this help message and exit\n",
-      "  -n N, --namespace N          Name of the pipeline to report result for. If not provided\n",
-      "                               'PIPESTAT_NAMESPACE' env var will be used. Currently set\n",
-      "                               to: test\n",
-      "  -f F, --results-file F       Path to the YAML file where the results will be stored.\n",
-      "                               This file will be used as pipestat backend and to restore\n",
-      "                               the reported results across sessions\n",
-      "  -c C, --config C             Path to the YAML configuration file. If not provided\n",
-      "                               'PIPESTAT_CONFIG' env var will be used. Currently not set\n",
-      "  -a, --database-only          Whether the reported data should not be stored in the\n",
-      "                               memory, only in the database.\n",
-      "  -s S, --schema S             Path to the schema that defines the results that can be\n",
-      "                               reported. If not provided 'PIPESTAT_RESULTS_SCHEMA' env var\n",
-      "                               will be used. Currently set to:\n",
-      "                               ../tests/data/sample_output_schema.yaml\n",
-      "  --status-schema ST           Path to the status schema. Default will be used if not\n",
-      "                               provided: /Library/Frameworks/Python.framework/Versions/3.6\n",
-      "                               /lib/python3.6/site-\n",
-      "                               packages/pipestat/schemas/status_schema.yaml\n",
-      "  --flag-dir FD                Path to the flag directory in case YAML file is the\n",
-      "                               pipestat backend.\n",
-      "  -i I, --result-identifier I  ID of the result to report; needs to be defined in the\n",
-      "                               schema\n",
-      "  -r R, --record-identifier R  ID of the record to report the result for. If not provided\n",
-      "                               'PIPESTAT_RECORD_ID' env var will be used. Currently set\n",
-      "                               to: sample1\n"
-     ]
-    }
-   ],
    "source": [
-    "pipestat retrieve -h"
+    "But this is obviously pretty cumbsersome, since you have to pass lots of constant information to every call to report a result. So instead, you have an option to set up environment variables for a particular pipeline run:"
    ]
   },
   {
-   "cell_type": "code",
-   "execution_count": 5,
+   "cell_type": "markdown",
    "metadata": {},
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "usage: pipestat remove [-h] [-n N] [-f F] [-c C] [-a] [-s S] [--status-schema ST]\n",
-      "                       [--flag-dir FD] -i I [-r R]\n",
-      "\n",
-      "Remove a result.\n",
-      "\n",
-      "optional arguments:\n",
-      "  -h, --help                   show this help message and exit\n",
-      "  -n N, --namespace N          Name of the pipeline to report result for. If not provided\n",
-      "                               'PIPESTAT_NAMESPACE' env var will be used. Currently set\n",
-      "                               to: test\n",
-      "  -f F, --results-file F       Path to the YAML file where the results will be stored.\n",
-      "                               This file will be used as pipestat backend and to restore\n",
-      "                               the reported results across sessions\n",
-      "  -c C, --config C             Path to the YAML configuration file. If not provided\n",
-      "                               'PIPESTAT_CONFIG' env var will be used. Currently not set\n",
-      "  -a, --database-only          Whether the reported data should not be stored in the\n",
-      "                               memory, only in the database.\n",
-      "  -s S, --schema S             Path to the schema that defines the results that can be\n",
-      "                               reported. If not provided 'PIPESTAT_RESULTS_SCHEMA' env var\n",
-      "                               will be used. Currently set to:\n",
-      "                               ../tests/data/sample_output_schema.yaml\n",
-      "  --status-schema ST           Path to the status schema. Default will be used if not\n",
-      "                               provided: /Library/Frameworks/Python.framework/Versions/3.6\n",
-      "                               /lib/python3.6/site-\n",
-      "                               packages/pipestat/schemas/status_schema.yaml\n",
-      "  --flag-dir FD                Path to the flag directory in case YAML file is the\n",
-      "                               pipestat backend.\n",
-      "  -i I, --result-identifier I  ID of the result to report; needs to be defined in the\n",
-      "                               schema\n",
-      "  -r R, --record-identifier R  ID of the record to report the result for. If not provided\n",
-      "                               'PIPESTAT_RECORD_ID' env var will be used. Currently set\n",
-      "                               to: sample1\n"
-     ]
-    }
-   ],
    "source": [
-    "pipestat remove -h"
+    "## Prepare environment"
    ]
   },
   {
-   "cell_type": "code",
-   "execution_count": 6,
+   "cell_type": "markdown",
    "metadata": {},
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "usage: pipestat inspect [-h] [-n N] [-f F] [-c C] [-a] [-s S] [--status-schema ST]\n",
-      "                        [--flag-dir FD] [-d]\n",
-      "\n",
-      "Inspect a database.\n",
-      "\n",
-      "optional arguments:\n",
-      "  -h, --help              show this help message and exit\n",
-      "  -n N, --namespace N     Name of the pipeline to report result for. If not provided\n",
-      "                          'PIPESTAT_NAMESPACE' env var will be used. Currently set to:\n",
-      "                          test\n",
-      "  -f F, --results-file F  Path to the YAML file where the results will be stored. This\n",
-      "                          file will be used as pipestat backend and to restore the\n",
-      "                          reported results across sessions\n",
-      "  -c C, --config C        Path to the YAML configuration file. If not provided\n",
-      "                          'PIPESTAT_CONFIG' env var will be used. Currently not set\n",
-      "  -a, --database-only     Whether the reported data should not be stored in the memory,\n",
-      "                          only in the database.\n",
-      "  -s S, --schema S        Path to the schema that defines the results that can be\n",
-      "                          reported. If not provided 'PIPESTAT_RESULTS_SCHEMA' env var will\n",
-      "                          be used. Currently set to:\n",
-      "                          ../tests/data/sample_output_schema.yaml\n",
-      "  --status-schema ST      Path to the status schema. Default will be used if not provided:\n",
-      "                          /Library/Frameworks/Python.framework/Versions/3.6/lib/python3.6/\n",
-      "                          site-packages/pipestat/schemas/status_schema.yaml\n",
-      "  --flag-dir FD           Path to the flag directory in case YAML file is the pipestat\n",
-      "                          backend.\n",
-      "  -d, --data              Whether to display the data\n"
-     ]
-    }
-   ],
    "source": [
-    "pipestat inspect -h"
+    "Pipestat environment variables avoid copious repetition of arguments in subsequent `pipestat` calls. Refer to the [Environment variables reference](http://pipestat.databio.org/en/latest/env_vars/) for the complete list of supported environment variables. We will set a few for this tutorial:"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 7,
+   "execution_count": 36,
    "metadata": {},
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "usage: pipestat status [-h] {set,get} ...\n",
-      "\n",
-      "Manage pipeline status.\n",
-      "\n",
-      "positional arguments:\n",
-      "  {set,get}\n",
-      "    set       Set status.\n",
-      "    get       Get status.\n",
-      "\n",
-      "optional arguments:\n",
-      "  -h, --help  show this help message and exit\n"
-     ]
-    }
-   ],
+   "outputs": [],
    "source": [
-    "pipestat status -h"
+    "export PIPESTAT_RESULTS_SCHEMA=../tests/data/sample_output_schema.yaml\n",
+    "export PIPESTAT_RECORD_ID=sample1\n",
+    "export PIPESTAT_RESULTS_FILE=`mktemp` # temporary file for results storage\n",
+    "export PIPESTAT_NAMESPACE=test"
    ]
   },
   {
-   "cell_type": "code",
-   "execution_count": 8,
+   "cell_type": "markdown",
    "metadata": {},
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "usage: pipestat status get [-h] [-n N] [-f F] [-c C] [-a] [-s S] [--status-schema ST]\n",
-      "                           [--flag-dir FD] [-r R]\n",
-      "\n",
-      "Get status.\n",
-      "\n",
-      "optional arguments:\n",
-      "  -h, --help                   show this help message and exit\n",
-      "  -n N, --namespace N          Name of the pipeline to report result for. If not provided\n",
-      "                               'PIPESTAT_NAMESPACE' env var will be used. Currently set\n",
-      "                               to: test\n",
-      "  -f F, --results-file F       Path to the YAML file where the results will be stored.\n",
-      "                               This file will be used as pipestat backend and to restore\n",
-      "                               the reported results across sessions\n",
-      "  -c C, --config C             Path to the YAML configuration file. If not provided\n",
-      "                               'PIPESTAT_CONFIG' env var will be used. Currently not set\n",
-      "  -a, --database-only          Whether the reported data should not be stored in the\n",
-      "                               memory, only in the database.\n",
-      "  -s S, --schema S             Path to the schema that defines the results that can be\n",
-      "                               reported. If not provided 'PIPESTAT_RESULTS_SCHEMA' env var\n",
-      "                               will be used. Currently set to:\n",
-      "                               ../tests/data/sample_output_schema.yaml\n",
-      "  --status-schema ST           Path to the status schema. Default will be used if not\n",
-      "                               provided: /Library/Frameworks/Python.framework/Versions/3.6\n",
-      "                               /lib/python3.6/site-\n",
-      "                               packages/pipestat/schemas/status_schema.yaml\n",
-      "  --flag-dir FD                Path to the flag directory in case YAML file is the\n",
-      "                               pipestat backend.\n",
-      "  -r R, --record-identifier R  ID of the record to report the result for. If not provided\n",
-      "                               'PIPESTAT_RECORD_ID' env var will be used. Currently set\n",
-      "                               to: sample1\n"
-     ]
-    }
-   ],
    "source": [
-    "pipestat status get -h"
+    "Before we dive in, let's take a quick glance at the schema. This is the file that describes what sort of results are reported by this pipeline:"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 9,
+   "execution_count": 37,
    "metadata": {},
    "outputs": [
     {
-     "name": "stdout",
      "output_type": "stream",
+     "name": "stdout",
      "text": [
-      "usage: pipestat status set [-h] [-n N] -i S [-f F] [-c C] [-a] [-s S] [--status-schema ST]\n",
-      "                           [--flag-dir FD] [-r R]\n",
-      "\n",
-      "Set status.\n",
-      "\n",
-      "optional arguments:\n",
-      "  -h, --help                   show this help message and exit\n",
-      "  -n N, --namespace N          Name of the pipeline to report result for. If not provided\n",
-      "                               'PIPESTAT_NAMESPACE' env var will be used. Currently set\n",
-      "                               to: test\n",
-      "  -i S, --status-identifier S  Status identifier to use\n",
-      "  -f F, --results-file F       Path to the YAML file where the results will be stored.\n",
-      "                               This file will be used as pipestat backend and to restore\n",
-      "                               the reported results across sessions\n",
-      "  -c C, --config C             Path to the YAML configuration file. If not provided\n",
-      "                               'PIPESTAT_CONFIG' env var will be used. Currently not set\n",
-      "  -a, --database-only          Whether the reported data should not be stored in the\n",
-      "                               memory, only in the database.\n",
-      "  -s S, --schema S             Path to the schema that defines the results that can be\n",
-      "                               reported. If not provided 'PIPESTAT_RESULTS_SCHEMA' env var\n",
-      "                               will be used. Currently set to:\n",
-      "                               ../tests/data/sample_output_schema.yaml\n",
-      "  --status-schema ST           Path to the status schema. Default will be used if not\n",
-      "                               provided: /Library/Frameworks/Python.framework/Versions/3.6\n",
-      "                               /lib/python3.6/site-\n",
-      "                               packages/pipestat/schemas/status_schema.yaml\n",
-      "  --flag-dir FD                Path to the flag directory in case YAML file is the\n",
-      "                               pipestat backend.\n",
-      "  -r R, --record-identifier R  ID of the record to report the result for. If not provided\n",
-      "                               'PIPESTAT_RECORD_ID' env var will be used. Currently set\n",
-      "                               to: sample1\n"
+      "number_of_things:\n",
+      "  type: integer\n",
+      "  description: \"Number of things\"\n",
+      "percentage_of_things:\n",
+      "  type: number\n",
+      "  description: \"Percentage of things\"\n",
+      "name_of_something:\n",
+      "  type: string\n",
+      "  description: \"Name of something\"\n",
+      "swtich_value:\n",
+      "  type: boolean\n",
+      "  description: \"Is the switch on of off\"\n",
+      "collection_of_things:\n",
+      "  type: array\n",
+      "  description: \"This store collection of values\"\n",
+      "output_object:\n",
+      "  type: object\n",
+      "  description: \"Object output\"\n",
+      "output_file:\n",
+      "  type: file\n",
+      "  description: \"This a path to the output file\"\n",
+      "output_image:\n",
+      "  type: image\n",
+      "  description: \"This a path to the output image\"\n",
+      "md5sum:\n",
+      "  type: string\n",
+      "  description: \"MD5SUM of an object\"\n",
+      "  highlight: true\n"
      ]
     }
    ],
    "source": [
-    "pipestat status set -h"
+    "cat $PIPESTAT_RESULTS_SCHEMA"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Usage demonstration\n",
-    "\n",
     "### Reporting\n",
     "\n",
     "Naturally, the command line interface provides access to all the Python API functionalities of `pipestat`. So, for example, to report a result and back the object by a file use:"
@@ -410,12 +137,12 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 10,
+   "execution_count": 38,
    "metadata": {},
    "outputs": [
     {
-     "name": "stdout",
      "output_type": "stream",
+     "name": "stdout",
      "text": [
       "Reported records for 'sample1' in 'test' namespace:\n",
       " - number_of_things: 100\n"
@@ -423,7 +150,7 @@
     }
    ],
    "source": [
-    "pipestat report -i number_of_things -v 100 --try-convert"
+    "pipestat report -i number_of_things -v 100"
    ]
   },
   {
@@ -435,12 +162,12 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 11,
+   "execution_count": 39,
    "metadata": {},
    "outputs": [
     {
-     "name": "stdout",
      "output_type": "stream",
+     "name": "stdout",
      "text": [
       "test:\n",
       "  sample1:\n",
@@ -461,12 +188,12 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 12,
+   "execution_count": 40,
    "metadata": {},
    "outputs": [
     {
-     "name": "stdout",
      "output_type": "stream",
+     "name": "stdout",
      "text": [
       "Reported records for 'sample1' in 'test' namespace:\n",
       " - percentage_of_things: 1.1\n"
@@ -474,17 +201,17 @@
     }
    ],
    "source": [
-    "pipestat report -i percentage_of_things -v 1.1 --try-convert"
+    "pipestat report -i percentage_of_things -v 1.1"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 13,
+   "execution_count": 41,
    "metadata": {},
    "outputs": [
     {
-     "name": "stdout",
      "output_type": "stream",
+     "name": "stdout",
      "text": [
       "test:\n",
       "  sample1:\n",
@@ -508,20 +235,23 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 14,
+   "execution_count": 42,
    "metadata": {},
    "outputs": [
     {
-     "name": "stdout",
      "output_type": "stream",
+     "name": "stdout",
      "text": [
       "\n",
       "\n",
       "PipestatManager (test)\n",
-      "Backend: file (/var/folders/3f/0wj7rs2144l9zsgxd3jn5nxc0000gn/T/tmp.Zid7BMd1)\n",
+      "Backend: File \n",
+      " - results: /var/folders/h8/8npwnh2s4rb8lr6hsy2ydrsh0000gp/T/tmp.hk8q23wT\n",
+      " - status: /var/folders/h8/8npwnh2s4rb8lr6hsy2ydrsh0000gp/T)\n",
       "Results schema source: ../tests/data/sample_output_schema.yaml\n",
-      "Status schema source: /Library/Frameworks/Python.framework/Versions/3.6/lib/python3.6/site-packages/pipestat/schemas/status_schema.yaml\n",
-      "Records count: 1\n"
+      "Status schema source: /usr/local/lib/python3.9/site-packages/pipestat/schemas/status_schema.yaml\n",
+      "Records count: 1\n",
+      "Highlighted results: md5sum\n"
      ]
     }
    ],
@@ -538,20 +268,23 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 15,
+   "execution_count": 43,
    "metadata": {},
    "outputs": [
     {
-     "name": "stdout",
      "output_type": "stream",
+     "name": "stdout",
      "text": [
       "\n",
       "\n",
       "PipestatManager (test)\n",
-      "Backend: file (/var/folders/3f/0wj7rs2144l9zsgxd3jn5nxc0000gn/T/tmp.Zid7BMd1)\n",
+      "Backend: File \n",
+      " - results: /var/folders/h8/8npwnh2s4rb8lr6hsy2ydrsh0000gp/T/tmp.hk8q23wT\n",
+      " - status: /var/folders/h8/8npwnh2s4rb8lr6hsy2ydrsh0000gp/T)\n",
       "Results schema source: ../tests/data/sample_output_schema.yaml\n",
-      "Status schema source: /Library/Frameworks/Python.framework/Versions/3.6/lib/python3.6/site-packages/pipestat/schemas/status_schema.yaml\n",
+      "Status schema source: /usr/local/lib/python3.9/site-packages/pipestat/schemas/status_schema.yaml\n",
       "Records count: 1\n",
+      "Highlighted results: md5sum\n",
       "\n",
       "Data:\n",
       "test:\n",
@@ -576,12 +309,12 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 16,
+   "execution_count": 44,
    "metadata": {},
    "outputs": [
     {
-     "name": "stdout",
      "output_type": "stream",
+     "name": "stdout",
      "text": [
       "1.1\n"
      ]
@@ -602,12 +335,12 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 17,
+   "execution_count": 45,
    "metadata": {},
    "outputs": [
     {
-     "name": "stdout",
      "output_type": "stream",
+     "name": "stdout",
      "text": [
       "Removed result 'percentage_of_things' for record 'sample1' from 'test' namespace\n"
      ]
@@ -626,12 +359,12 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 18,
+   "execution_count": 46,
    "metadata": {},
    "outputs": [
     {
-     "name": "stdout",
      "output_type": "stream",
+     "name": "stdout",
      "text": [
       "test:\n",
       "  sample1:\n",
@@ -645,20 +378,23 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 19,
+   "execution_count": 47,
    "metadata": {},
    "outputs": [
     {
-     "name": "stdout",
      "output_type": "stream",
+     "name": "stdout",
      "text": [
       "\n",
       "\n",
       "PipestatManager (test)\n",
-      "Backend: file (/var/folders/3f/0wj7rs2144l9zsgxd3jn5nxc0000gn/T/tmp.Zid7BMd1)\n",
+      "Backend: File \n",
+      " - results: /var/folders/h8/8npwnh2s4rb8lr6hsy2ydrsh0000gp/T/tmp.hk8q23wT\n",
+      " - status: /var/folders/h8/8npwnh2s4rb8lr6hsy2ydrsh0000gp/T)\n",
       "Results schema source: ../tests/data/sample_output_schema.yaml\n",
-      "Status schema source: /Library/Frameworks/Python.framework/Versions/3.6/lib/python3.6/site-packages/pipestat/schemas/status_schema.yaml\n",
+      "Status schema source: /usr/local/lib/python3.9/site-packages/pipestat/schemas/status_schema.yaml\n",
       "Records count: 1\n",
+      "Highlighted results: md5sum\n",
       "\n",
       "Data:\n",
       "test:\n",
@@ -682,37 +418,76 @@
     "- `set` to set pipeline statuses\n",
     "- `get` to retrieve pipeline statuses\n",
     "\n",
-    "Starting with `pipestat 0.0.3` the `--schema` argument is not required for status management if YAML file is used as the backend."
+    "Starting with `pipestat 0.0.3` the `--schema` argument is not required for status management."
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 20,
+   "execution_count": 48,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "pipestat status set running"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 49,
    "metadata": {},
    "outputs": [
     {
-     "name": "stdout",
      "output_type": "stream",
+     "name": "stdout",
      "text": [
       "running\n"
      ]
     }
    ],
    "source": [
-    "pipestat status set --status-identifier running\n",
     "pipestat status get"
    ]
   },
   {
+   "source": [
+    "Note that only statuses defined in the status schema are supported:"
+   ],
    "cell_type": "markdown",
+   "metadata": {}
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 50,
    "metadata": {},
+   "outputs": [
+    {
+     "output_type": "stream",
+     "name": "stdout",
+     "text": [
+      "running:\n",
+      "  description: \"the pipeline is running\"\n",
+      "  color: [30, 144, 255] # dodgerblue\n",
+      "completed:\n",
+      "  description: \"the pipeline has completed\"\n",
+      "  color: [50, 205, 50] # limegreen\n",
+      "failed:\n",
+      "  description: \"the pipeline has failed\"\n",
+      "  color: [220, 20, 60] # crimson\n",
+      "waiting:\n",
+      "  description: \"the pipeline is waiting\"\n",
+      "  color: [240, 230, 140] # khaki\n",
+      "partial:\n",
+      "  description: \"the pipeline stopped before completion point\"\n",
+      "  color: [169, 169, 169] # darkgray\n"
+     ]
+    }
+   ],
    "source": [
-    "Note that only statuses defined in the status schema are supported:"
+    "cat /usr/local/lib/python3.9/site-packages/pipestat/schemas/status_schema.yaml"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 21,
+   "execution_count": 51,
    "metadata": {},
    "outputs": [],
    "source": [
diff --git a/docs_jupyter/cli.md b/docs_jupyter/cli.md
deleted file mode 100644
index 24acad15..00000000
--- a/docs_jupyter/cli.md
+++ /dev/null
@@ -1,312 +0,0 @@
-# Pipestat CLI
-
-Before following this tutorial please make sure you're familiar with "Pipestat Python API" tutorial.
-
-## Usage reference
-
-To learn about the usage `pipestat` usage use `--help`/`-h` option on any level:
-
-
-```bash
-pipestat -h
-```
-
-    version: 0.0.1
-    usage: pipestat [-h] [--version] [--silent] [--verbosity V] [--logdev]
-                    {report,inspect,remove,retrieve} ...
-    
-    pipestat - report pipeline results
-    
-    positional arguments:
-      {report,inspect,remove,retrieve}
-        report              Report a result.
-        inspect             Inspect a database.
-        remove              Remove a result.
-        retrieve            Retrieve a result.
-    
-    optional arguments:
-      -h, --help            show this help message and exit
-      --version             show program's version number and exit
-      --silent              Silence logging. Overrides verbosity.
-      --verbosity V         Set logging level (1-5 or logging module level name)
-      --logdev              Expand content of logging message format.
-    
-    pipestat standardizes reporting of pipeline results. It formalizes a way for
-    pipeline developers and downstream tools developers to communicate -- results
-    produced by a pipeline can easily and reliably become an input for downstream
-    analyses. The ovject exposes API for interacting with the results can be
-    backed by either a YAML-formatted file or a PostgreSQL database.
-
-
-
-```bash
-pipestat report -h
-```
-
-    usage: pipestat report [-h] -n N (-f F | -c C | -a) -s S -i I -r R -v V [-o]
-                           [-t]
-    
-    Report a result.
-    
-    optional arguments:
-      -h, --help            show this help message and exit
-      -n N, --namespace N   Name of the pipeline to report result for
-      -f F, --results-file F
-                            Path to the YAML file where the results will be
-                            stored. This file will be used as pipestat backend and
-                            to restore the reported results across sesssions
-      -c C, --database-config C
-                            Path to the YAML file with PostgreSQL database
-                            configuration. Please refer to the documentation for
-                            the file format requirements.
-      -a, --database-only   Whether the reported data should not be stored in the
-                            memory, only in the database.
-      -s S, --schema S      Path to the schema that defines the results that can
-                            be eported
-      -i I, --result-identifier I
-                            ID of the result to report; needs to be defined in the
-                            schema
-      -r R, --record-identifier R
-                            ID of the record to report the result for
-      -v V, --value V       Value of the result to report
-      -o, --overwrite       Whether the result should override existing ones in
-                            case of name clashes
-      -t, --try-convert     Whether to try to convert the reported value into
-                            reqiuired class in case it does not meet the schema
-                            requirements
-
-
-
-```bash
-pipestat retrieve -h
-```
-
-    usage: pipestat retrieve [-h] -n N (-f F | -c C | -a) [-s S] -i I -r R
-    
-    Retrieve a result.
-    
-    optional arguments:
-      -h, --help            show this help message and exit
-      -n N, --namespace N   Name of the pipeline to report result for
-      -f F, --results-file F
-                            Path to the YAML file where the results will be
-                            stored. This file will be used as pipestat backend and
-                            to restore the reported results across sesssions
-      -c C, --database-config C
-                            Path to the YAML file with PostgreSQL database
-                            configuration. Please refer to the documentation for
-                            the file format requirements.
-      -a, --database-only   Whether the reported data should not be stored in the
-                            memory, only in the database.
-      -s S, --schema S      Path to the schema that defines the results that can
-                            be eported
-      -i I, --result-identifier I
-                            ID of the result to report; needs to be defined in the
-                            schema
-      -r R, --record-identifier R
-                            ID of the record to report the result for
-
-
-
-```bash
-pipestat remove -h
-```
-
-    usage: pipestat remove [-h] -n N (-f F | -c C | -a) [-s S] -i I -r R
-    
-    Remove a result.
-    
-    optional arguments:
-      -h, --help            show this help message and exit
-      -n N, --namespace N   Name of the pipeline to report result for
-      -f F, --results-file F
-                            Path to the YAML file where the results will be
-                            stored. This file will be used as pipestat backend and
-                            to restore the reported results across sesssions
-      -c C, --database-config C
-                            Path to the YAML file with PostgreSQL database
-                            configuration. Please refer to the documentation for
-                            the file format requirements.
-      -a, --database-only   Whether the reported data should not be stored in the
-                            memory, only in the database.
-      -s S, --schema S      Path to the schema that defines the results that can
-                            be eported
-      -i I, --result-identifier I
-                            ID of the result to report; needs to be defined in the
-                            schema
-      -r R, --record-identifier R
-                            ID of the record to report the result for
-
-
-
-```bash
-pipestat inspect -h
-```
-
-    usage: pipestat inspect [-h] -n N (-f F | -c C | -a) [-s S] [-d]
-    
-    Inspect a database.
-    
-    optional arguments:
-      -h, --help            show this help message and exit
-      -n N, --namespace N   Name of the pipeline to report result for
-      -f F, --results-file F
-                            Path to the YAML file where the results will be
-                            stored. This file will be used as pipestat backend and
-                            to restore the reported results across sesssions
-      -c C, --database-config C
-                            Path to the YAML file with PostgreSQL database
-                            configuration. Please refer to the documentation for
-                            the file format requirements.
-      -a, --database-only   Whether the reported data should not be stored in the
-                            memory, only in the database.
-      -s S, --schema S      Path to the schema that defines the results that can
-                            be eported
-      -d, --data            Whether to display the data
-
-
-## Usage demonstration
-
-### Reporting
-
-Naturally, the command line interface provides access to all the Python API functionalities of `pipestat`. So, for example, to report a result and back the object by a file use:
-
-
-```bash
-temp_file=`mktemp`
-pipestat report -f $temp_file -n test -r sample1 -i number_of_things -v 100 -s ../tests/data/sample_output_schema.yaml --try-convert
-```
-
-    Reading data from '/var/folders/3f/0wj7rs2144l9zsgxd3jn5nxc0000gn/T/tmp.G6Gtt93d'
-    Reported records for 'sample1' in 'test' namespace:
-     - number_of_things: 100
-
-
-The result has been reported and the database file has been updated:
-
-
-```bash
-cat $temp_file
-```
-
-    test:
-      sample1:
-        number_of_things: 100
-
-
-Let's report another result:
-
-
-```bash
-pipestat report -f $temp_file -n test -r sample1 -i percentage_of_things -v 1.1 -s ../tests/data/sample_output_schema.yaml --try-convert
-```
-
-    Reading data from '/var/folders/3f/0wj7rs2144l9zsgxd3jn5nxc0000gn/T/tmp.G6Gtt93d'
-    Reported records for 'sample1' in 'test' namespace:
-     - percentage_of_things: 1.1
-
-
-
-```bash
-cat $temp_file
-```
-
-    test:
-      sample1:
-        number_of_things: 100
-        percentage_of_things: 1.1
-
-
-### Inspection
-
-`pipestat inspect` command is a way to briefly look at the general `PipestatManager` state, like number of records, type of backend etc.
-
-
-```bash
-pipestat inspect -f $temp_file -n test
-```
-
-    Reading data from '/var/folders/3f/0wj7rs2144l9zsgxd3jn5nxc0000gn/T/tmp.G6Gtt93d'
-    
-    
-    PipestatManager (test)
-    Backend: file (/var/folders/3f/0wj7rs2144l9zsgxd3jn5nxc0000gn/T/tmp.G6Gtt93d)
-    Records count: 1
-
-
-In order to display the contents of the results file or database table associated with the indicated namespace, add `--data` flag:
-
-
-```bash
-pipestat inspect --data -f $temp_file -n test
-```
-
-    Reading data from '/var/folders/3f/0wj7rs2144l9zsgxd3jn5nxc0000gn/T/tmp.G6Gtt93d'
-    
-    
-    PipestatManager (test)
-    Backend: file (/var/folders/3f/0wj7rs2144l9zsgxd3jn5nxc0000gn/T/tmp.G6Gtt93d)
-    Records count: 1
-    
-    Data:
-    test:
-      sample1:
-        number_of_things: 100
-        percentage_of_things: 1.1
-
-
-### Retrieval
-
-Naturally, the reported results can be retrieved. Just call `pipestat retrieve` to do so:
-
-
-```bash
-pipestat retrieve -f $temp_file -n test -r sample1 -i percentage_of_things
-```
-
-    Reading data from '/var/folders/3f/0wj7rs2144l9zsgxd3jn5nxc0000gn/T/tmp.G6Gtt93d'
-    1.1
-
-
-### Removal
-
-In order to remove a result call `pipestat remove`:
-
-
-```bash
-pipestat remove -f $temp_file -n test -r sample1 -i percentage_of_things
-```
-
-    Reading data from '/var/folders/3f/0wj7rs2144l9zsgxd3jn5nxc0000gn/T/tmp.G6Gtt93d'
-    Removed result 'percentage_of_things' for record 'sample1' from 'test' namespace
-
-
-The results file and the state of the `PipestatManager` object reflect the removal:
-
-
-```bash
-cat $temp_file
-```
-
-    test:
-      sample1:
-        number_of_things: 100
-
-
-
-```bash
-pipestat inspect --data -f $temp_file -n test
-```
-
-    Reading data from '/var/folders/3f/0wj7rs2144l9zsgxd3jn5nxc0000gn/T/tmp.G6Gtt93d'
-    
-    
-    PipestatManager (test)
-    Backend: file (/var/folders/3f/0wj7rs2144l9zsgxd3jn5nxc0000gn/T/tmp.G6Gtt93d)
-    Records count: 1
-    
-    Data:
-    test:
-      sample1:
-        number_of_things: 100
-
diff --git a/docs_jupyter/python_api.ipynb b/docs_jupyter/python_api.ipynb
index f70bce46..851e3c87 100644
--- a/docs_jupyter/python_api.ipynb
+++ b/docs_jupyter/python_api.ipynb
@@ -6,18 +6,43 @@
    "source": [
     "# Pipestat Python API\n",
     "\n",
-    "Pipestat is a [Python package](https://pypi.org/project/pipestat/) for a standardized reporting of pipeline statistics.\n",
+    "Pipestat is a [Python package](https://pypi.org/project/pipestat/) for a standardized reporting of pipeline statistics. It formalizes a way to communicate between pipelines and downstream tools that analyze their results so that pipeline results can easily become input for downstream analyses.\n",
     "\n",
-    "It formalizes a way for pipeline developers and downstream tools developers to communicate -- results produced by a pipeline can easily and reliably become an input for downstream analyses.\n",
+    "This tutorial is targeted toward pipeline developers, and shows how to use pipestat to manage pipeline results. This tutorial assumes you're writing your pipeline in Python; if not, there's another tutorial that accomplishes the same thing for any pipeline using the command-line interface.\n",
     "\n",
-    "## Usage\n",
+    "## Introduction\n",
     "\n",
-    "Here's how a pipeline developer can use `pipestat` to report results:"
+    "To make your Python pipeline pipestat-compatible, you first need to initialize pipestat with some important configuration setup:\n",
+    "\n",
+    "1. **pipestat schema**: a path to a JSON-schema file that defines results reported by this pipeline\n",
+    "2. **namespace**: defines a unique group name for reported results, typically a pipeline name\n",
+    "3. **record identifier**: a unique name for a particular *run* of the pipeline, typically corresponding to a sample name\n",
+    "4. **backend**: where the results should be stored. either path to a YAML-formatted file or pipestat config with PostgreSQL database login credentials\n",
+    "\n",
+    "## Back-end types\n",
+    "\n",
+    "Two types of back-ends are currently supported:\n",
+    "\n",
+    "1. a **file** (pass a file path to the constructor)  \n",
+    "The changes reported using the `report` method of `PipestatManger` will be securely written to the file. Currently only [YAML](https://yaml.org/) format is supported. \n",
+    "\n",
+    "2. a **PostgreSQL database** (pass a path to the pipestat config to the constructor)\n",
+    "This option gives the user the possibility to use a fully fledged database to back `PipestatManager`. \n",
+    "\n",
+    "\n",
+    "## Initializing a pipestat session\n",
+    "\n",
+    "Start by importing the `pipestat` package in Python."
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": []
+  },
   {
    "cell_type": "code",
-   "execution_count": 1,
+   "execution_count": 239,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -29,35 +54,19 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "After importing the package, create an `PipestatManager` object. The object constructor requires a few pieces of information: \n",
-    "\n",
-    "1. a namespace to write into, for example the name of the pipeline\n",
-    "2. a path to the schema file that describes results that can be reported\n",
-    "3. backend info: either path to a YAML-formatted file or pipestat config with PostgreSQL database login credentials\n",
-    "\n",
-    "## Back-end types\n",
-    "\n",
-    "Two types of back-ends are currently supported:\n",
-    "\n",
-    "1. a **file** (pass a file path to the constructor)  \n",
-    "The changes reported using the `report` method of `PipestatManger` will be securely written to the file. Currently only [YAML](https://yaml.org/) format is supported. \n",
-    "\n",
-    "2. a **PostgreSQL database** (pass a path to the pipestat config to the constructor)\n",
-    "This option gives the user the possibility to use a fully fledged database to back `PipestatManager`. \n",
-    "\n",
-    "To use a file as the back-end, just pass a file path string to the constructor. Let's create a temporary file first:"
+    "After importing the package, we need to create an `PipestatManager` object. The object constructor requires a few pieces of information. We'll use a file as the back-end, by passing a file path string to the constructor. Let's create a temporary file first:"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 2,
+   "execution_count": 240,
    "metadata": {},
    "outputs": [
     {
-     "name": "stdout",
      "output_type": "stream",
+     "name": "stdout",
      "text": [
-      "/var/folders/3f/0wj7rs2144l9zsgxd3jn5nxc0000gn/T/tmpa6poai5_.yaml\n"
+      "/var/folders/h8/8npwnh2s4rb8lr6hsy2ydrsh0000gp/T/tmpjupp4wcz.yaml\n"
      ]
     }
    ],
@@ -77,7 +86,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 3,
+   "execution_count": 241,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -93,23 +102,23 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The results will be reported to a \"test\" namespace."
+    "You can also put these settings into a config file and just pass that to the `config` argument, instead of specifying each argument separately. The results will be reported to a \"test\" namespace."
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 4,
+   "execution_count": 242,
    "metadata": {},
    "outputs": [
     {
+     "output_type": "execute_result",
      "data": {
       "text/plain": [
        "'test'"
       ]
      },
-     "execution_count": 4,
      "metadata": {},
-     "output_type": "execute_result"
+     "execution_count": 242
     }
    ],
    "source": [
@@ -125,18 +134,18 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 5,
+   "execution_count": 243,
    "metadata": {},
    "outputs": [
     {
+     "output_type": "execute_result",
      "data": {
       "text/plain": [
        "'sample1'"
       ]
      },
-     "execution_count": 5,
      "metadata": {},
-     "output_type": "execute_result"
+     "execution_count": 243
     }
    ],
    "source": [
@@ -152,18 +161,18 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 6,
+   "execution_count": 244,
    "metadata": {},
    "outputs": [
     {
+     "output_type": "execute_result",
      "data": {
       "text/plain": [
        "YacAttMap: {}"
       ]
      },
-     "execution_count": 6,
      "metadata": {},
-     "output_type": "execute_result"
+     "execution_count": 244
     }
    ],
    "source": [
@@ -181,10 +190,10 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "To report a result, use a `report` method. It requires three pieces of information:\n",
+    "To report a result, use a `report` method. It requires two pieces of information:\n",
     "\n",
     "1. record identifier -- record to report the result for, for example a unique name of the sample (optional if provided at `PipestatManager` initialization stage)\n",
-    "2. values -- a Python `dict` of resultID-value pairs to report. The top level keys need to correspond to the results identifiers defined in the schema\n",
+    "2. values -- a Python `dict` of resultID-value pairs to report. The top level keys must correspond to the results identifiers defined in the schema\n",
     "\n",
     "### Available results defined in schemas\n",
     "\n",
@@ -193,10 +202,11 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 7,
+   "execution_count": 245,
    "metadata": {},
    "outputs": [
     {
+     "output_type": "execute_result",
      "data": {
       "text/plain": [
        "{'number_of_things': {'type': 'integer', 'description': 'Number of things'},\n",
@@ -210,12 +220,14 @@
        " 'output_file': {'type': 'file',\n",
        "  'description': 'This a path to the output file'},\n",
        " 'output_image': {'type': 'image',\n",
-       "  'description': 'This a path to the output image'}}"
+       "  'description': 'This a path to the output image'},\n",
+       " 'md5sum': {'type': 'string',\n",
+       "  'description': 'MD5SUM of an object',\n",
+       "  'highlight': True}}"
       ]
      },
-     "execution_count": 7,
      "metadata": {},
-     "output_type": "execute_result"
+     "execution_count": 245
     }
    ],
    "source": [
@@ -231,10 +243,11 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 8,
+   "execution_count": 246,
    "metadata": {},
    "outputs": [
     {
+     "output_type": "execute_result",
      "data": {
       "text/plain": [
        "{'type': 'object',\n",
@@ -243,9 +256,8 @@
        " 'required': ['path', 'title']}"
       ]
      },
-     "execution_count": 8,
      "metadata": {},
-     "output_type": "execute_result"
+     "execution_count": 246
     }
    ],
    "source": [
@@ -262,24 +274,14 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 9,
+   "execution_count": 247,
    "metadata": {},
    "outputs": [
     {
-     "name": "stdout",
      "output_type": "stream",
+     "name": "stdout",
      "text": [
-      "'title' is a required property\n",
-      "\n",
-      "Failed validating 'required' in schema:\n",
-      "    {'description': 'This a path to the output file',\n",
-      "     'properties': {'path': {'type': 'string'},\n",
-      "                    'title': {'type': 'string'}},\n",
-      "     'required': ['path', 'title'],\n",
-      "     'type': 'object'}\n",
-      "\n",
-      "On instance:\n",
-      "    {'path': '/home/user/path.csv'}\n"
+      "'title' is a required property\n\nFailed validating 'required' in schema:\n    {'description': 'This a path to the output file',\n     'properties': {'path': {'type': 'string'},\n                    'title': {'type': 'string'}},\n     'required': ['path', 'title'],\n     'type': 'object'}\n\nOn instance:\n    {'path': '/home/user/path.csv'}\n"
      ]
     }
    ],
@@ -299,26 +301,25 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 10,
+   "execution_count": 248,
    "metadata": {},
    "outputs": [
     {
-     "name": "stderr",
      "output_type": "stream",
+     "name": "stderr",
      "text": [
-      "Reported records for 'sample1' in 'test' namespace:\n",
-      " - output_file: {'path': '/home/user/path.csv', 'title': 'CSV file with some data'}\n"
+      "Reported records for 'sample1' in 'test' namespace:\n - output_file: {'path': '/home/user/path.csv', 'title': 'CSV file with some data'}\n"
      ]
     },
     {
+     "output_type": "execute_result",
      "data": {
       "text/plain": [
        "True"
       ]
      },
-     "execution_count": 10,
      "metadata": {},
-     "output_type": "execute_result"
+     "execution_count": 248
     }
    ],
    "source": [
@@ -341,10 +342,11 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 11,
+   "execution_count": 249,
    "metadata": {},
    "outputs": [
     {
+     "output_type": "execute_result",
      "data": {
       "text/plain": [
        "test:\n",
@@ -354,9 +356,8 @@
        "      title: CSV file with some data"
       ]
      },
-     "execution_count": 11,
      "metadata": {},
-     "output_type": "execute_result"
+     "execution_count": 249
     }
    ],
    "source": [
@@ -372,25 +373,25 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 12,
+   "execution_count": 250,
    "metadata": {},
    "outputs": [
     {
-     "name": "stderr",
      "output_type": "stream",
+     "name": "stderr",
      "text": [
-      "These results exist for 'sample1': ['output_file']\n"
+      "These results exist for 'sample1': output_file\n"
      ]
     },
     {
+     "output_type": "execute_result",
      "data": {
       "text/plain": [
        "False"
       ]
      },
-     "execution_count": 12,
      "metadata": {},
-     "output_type": "execute_result"
+     "execution_count": 250
     }
    ],
    "source": [
@@ -406,20 +407,21 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 13,
+   "execution_count": 251,
    "metadata": {},
    "outputs": [
     {
-     "name": "stderr",
      "output_type": "stream",
+     "name": "stderr",
      "text": [
-      "These results exist for 'sample1': ['output_file']\n",
-      "Overwriting existing results: ['output_file']\n",
+      "These results exist for 'sample1': output_file\n",
+      "Overwriting existing results: output_file\n",
       "Reported records for 'sample1' in 'test' namespace:\n",
       " - output_file: {'path': '/home/user/path_new.csv', 'title': 'new CSV file with some data'}\n"
      ]
     },
     {
+     "output_type": "execute_result",
      "data": {
       "text/plain": [
        "test:\n",
@@ -429,9 +431,8 @@
        "      title: new CSV file with some data"
       ]
      },
-     "execution_count": 13,
      "metadata": {},
-     "output_type": "execute_result"
+     "execution_count": 251
     }
    ],
    "source": [
@@ -456,7 +457,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 14,
+   "execution_count": 252,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -470,10 +471,11 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 15,
+   "execution_count": 253,
    "metadata": {},
    "outputs": [
     {
+     "output_type": "execute_result",
      "data": {
       "text/plain": [
        "test:\n",
@@ -483,9 +485,8 @@
        "      title: new CSV file with some data"
       ]
      },
-     "execution_count": 15,
      "metadata": {},
-     "output_type": "execute_result"
+     "execution_count": 253
     }
    ],
    "source": [
@@ -501,14 +502,14 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 16,
+   "execution_count": 254,
    "metadata": {},
    "outputs": [
     {
-     "name": "stdout",
      "output_type": "stream",
+     "name": "stdout",
      "text": [
-      "/var/folders/3f/0wj7rs2144l9zsgxd3jn5nxc0000gn/T/tmpa6poai5_.yaml\n",
+      "/var/folders/h8/8npwnh2s4rb8lr6hsy2ydrsh0000gp/T/tmpjupp4wcz.yaml\n",
       "test:\n",
       "  sample1:\n",
       "    output_file:\n",
@@ -532,23 +533,23 @@
     "\n",
     "By default `PipestatManager` raises an exception if a non-compatible result value is reported. \n",
     "\n",
-    "This behavior can be changed by setting `stric_type` to `True` in `PipestatManager.report` method. In thi case `PipestatManager` tries to cast the reported results values to the Python classes required by schema. For example, if a result defined as `integer` is reported and a `str` value is passed, the eventual value will be `int`:"
+    "This behavior can be changed by setting `strict_type` to `True` in `PipestatManager.report` method. In this case `PipestatManager` tries to cast the reported results values to the Python classes required by schema. For example, if a result defined as `integer` is reported and a `str` value is passed, the eventual value will be `int`:"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 17,
+   "execution_count": 255,
    "metadata": {},
    "outputs": [
     {
+     "output_type": "execute_result",
      "data": {
       "text/plain": [
        "{'type': 'integer', 'description': 'Number of things'}"
       ]
      },
-     "execution_count": 17,
      "metadata": {},
-     "output_type": "execute_result"
+     "execution_count": 255
     }
    ],
    "source": [
@@ -557,26 +558,25 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 18,
+   "execution_count": 256,
    "metadata": {},
    "outputs": [
     {
-     "name": "stderr",
      "output_type": "stream",
+     "name": "stderr",
      "text": [
-      "Reported records for 'sample1' in 'test' namespace:\n",
-      " - number_of_things: 10\n"
+      "Reported records for 'sample1' in 'test' namespace:\n - number_of_things: 10\n"
      ]
     },
     {
+     "output_type": "execute_result",
      "data": {
       "text/plain": [
        "True"
       ]
      },
-     "execution_count": 18,
      "metadata": {},
-     "output_type": "execute_result"
+     "execution_count": 256
     }
    ],
    "source": [
@@ -592,12 +592,12 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 19,
+   "execution_count": 257,
    "metadata": {},
    "outputs": [
     {
-     "name": "stdout",
      "output_type": "stream",
+     "name": "stdout",
      "text": [
       "int() argument must be a string, a bytes-like object or a number, not 'list'\n"
      ]
@@ -621,10 +621,11 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 20,
+   "execution_count": 258,
    "metadata": {},
    "outputs": [
     {
+     "output_type": "execute_result",
      "data": {
       "text/plain": [
        "test:\n",
@@ -635,9 +636,8 @@
        "    number_of_things: 10"
       ]
      },
-     "execution_count": 20,
      "metadata": {},
-     "output_type": "execute_result"
+     "execution_count": 258
     }
    ],
    "source": [
@@ -657,18 +657,18 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 21,
+   "execution_count": 259,
    "metadata": {},
    "outputs": [
     {
+     "output_type": "execute_result",
      "data": {
       "text/plain": [
        "'10'"
       ]
      },
-     "execution_count": 21,
      "metadata": {},
-     "output_type": "execute_result"
+     "execution_count": 259
     }
    ],
    "source": [
@@ -684,10 +684,11 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 22,
+   "execution_count": 260,
    "metadata": {},
    "outputs": [
     {
+     "output_type": "execute_result",
      "data": {
       "text/plain": [
        "{'output_file': {'path': '/home/user/path_new.csv',\n",
@@ -695,9 +696,8 @@
        " 'number_of_things': '10'}"
       ]
      },
-     "execution_count": 22,
      "metadata": {},
-     "output_type": "execute_result"
+     "execution_count": 260
     }
    ],
    "source": [
@@ -715,30 +715,30 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "`PipestatManager` object also supports results removal. Call `remove` method and provide `record_identifier` and  `result_identifier` method to do so:"
+    "`PipestatManager` object also supports results removal. Call `remove` method and provide `record_identifier` and  `result_identifier` arguments to do so:"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 23,
+   "execution_count": 261,
    "metadata": {},
    "outputs": [
     {
-     "name": "stderr",
      "output_type": "stream",
+     "name": "stderr",
      "text": [
       "Removed result 'number_of_things' for record 'sample1' from 'test' namespace\n"
      ]
     },
     {
+     "output_type": "execute_result",
      "data": {
       "text/plain": [
        "True"
       ]
      },
-     "execution_count": 23,
      "metadata": {},
-     "output_type": "execute_result"
+     "execution_count": 261
     }
    ],
    "source": [
@@ -754,25 +754,25 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 24,
+   "execution_count": 262,
    "metadata": {},
    "outputs": [
     {
-     "name": "stderr",
      "output_type": "stream",
+     "name": "stderr",
      "text": [
       "Removing 'sample1' record\n"
      ]
     },
     {
+     "output_type": "execute_result",
      "data": {
       "text/plain": [
        "True"
       ]
      },
-     "execution_count": 24,
      "metadata": {},
-     "output_type": "execute_result"
+     "execution_count": 262
     }
    ],
    "source": [
@@ -788,7 +788,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 25,
+   "execution_count": 263,
    "metadata": {
     "pycharm": {
      "name": "#%%\n"
@@ -796,14 +796,14 @@
    },
    "outputs": [
     {
+     "output_type": "execute_result",
      "data": {
       "text/plain": [
        "test: OrderedDict()"
       ]
      },
-     "execution_count": 25,
      "metadata": {},
-     "output_type": "execute_result"
+     "execution_count": 263
     }
    ],
    "source": [
@@ -821,14 +821,14 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 26,
+   "execution_count": 264,
    "metadata": {},
    "outputs": [
     {
-     "name": "stdout",
      "output_type": "stream",
+     "name": "stdout",
      "text": [
-      "/var/folders/3f/0wj7rs2144l9zsgxd3jn5nxc0000gn/T/tmpf9m81e1n.yaml\n"
+      "/var/folders/h8/8npwnh2s4rb8lr6hsy2ydrsh0000gp/T/tmpshtnle33.yaml\n"
      ]
     }
    ],
@@ -855,10 +855,11 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 27,
+   "execution_count": 265,
    "metadata": {},
    "outputs": [
     {
+     "output_type": "execute_result",
      "data": {
       "text/plain": [
        "{'number_of_things': {'type': 'integer', 'description': 'Number of things'},\n",
@@ -888,9 +889,8 @@
        "  'description': 'Pipeline version'}}"
       ]
      },
-     "execution_count": 27,
      "metadata": {},
-     "output_type": "execute_result"
+     "execution_count": 265
     }
    ],
    "source": [
@@ -906,18 +906,18 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 28,
+   "execution_count": 266,
    "metadata": {},
    "outputs": [
     {
+     "output_type": "execute_result",
      "data": {
       "text/plain": [
        "['log', 'profile', 'commands', 'version']"
       ]
      },
-     "execution_count": 28,
      "metadata": {},
-     "output_type": "execute_result"
+     "execution_count": 266
     }
    ],
    "source": [
@@ -937,7 +937,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 29,
+   "execution_count": 267,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -953,18 +953,18 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 30,
+   "execution_count": 268,
    "metadata": {},
    "outputs": [
     {
+     "output_type": "execute_result",
      "data": {
       "text/plain": [
        "'running'"
       ]
      },
-     "execution_count": 30,
      "metadata": {},
-     "output_type": "execute_result"
+     "execution_count": 268
     }
    ],
    "source": [
@@ -980,10 +980,11 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 31,
+   "execution_count": 269,
    "metadata": {},
    "outputs": [
     {
+     "output_type": "execute_result",
      "data": {
       "text/plain": [
        "{'running': {'description': 'the pipeline is running',\n",
@@ -997,9 +998,8 @@
        "  'color': [169, 169, 169]}}"
       ]
      },
-     "execution_count": 31,
      "metadata": {},
-     "output_type": "execute_result"
+     "execution_count": 269
     }
    ],
    "source": [
@@ -1028,14 +1028,14 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 32,
+   "execution_count": 270,
    "metadata": {},
    "outputs": [
     {
-     "name": "stdout",
      "output_type": "stream",
+     "name": "stdout",
      "text": [
-      "/var/folders/3f/0wj7rs2144l9zsgxd3jn5nxc0000gn/T/tmpq81inuvn.yaml\n"
+      "/var/folders/h8/8npwnh2s4rb8lr6hsy2ydrsh0000gp/T/tmpauamyheb.yaml\n"
      ]
     }
    ],
@@ -1052,21 +1052,19 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "As you can see, the object has been initialized successfully. Obviuosly, the schema has to be defined to report and retrieve results as the requirement to predefine results and therefore the possibility to rely on the schema to gather all the possible results metadata in the pipestat clients is a big advantage.\n",
-    "\n",
-    "Moreover, initialization with a database as a backend is impossible without schema due to the characteristics of relational databases, which must have columns predefined, when created."
+    "As you can see, the object has been initialized successfully. Obviously, the schema has to be defined to report and retrieve results as the requirement to predefine results and therefore the possibility to rely on the schema to gather all the possible results metadata in the pipestat clients is a big advantage."
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 33,
+   "execution_count": 271,
    "metadata": {},
    "outputs": [
     {
-     "name": "stdout",
      "output_type": "stream",
+     "name": "stdout",
      "text": [
-      "Results schema not found. The schema is required to report results. It needs to be supplied to the object constructor.\n"
+      "Results schema not found. The schema is required to report results. It needs to be supplied to the object constructor or via 'PIPESTAT_RESULTS_SCHEMA' environment variable.\n"
      ]
     }
    ],
@@ -1086,18 +1084,18 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 34,
+   "execution_count": 272,
    "metadata": {},
    "outputs": [
     {
+     "output_type": "execute_result",
      "data": {
       "text/plain": [
        "'running'"
       ]
      },
-     "execution_count": 34,
      "metadata": {},
-     "output_type": "execute_result"
+     "execution_count": 272
     }
    ],
    "source": [
@@ -1108,9 +1106,8 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3",
-   "language": "python",
-   "name": "python3"
+   "name": "python3",
+   "display_name": "Python 3.9.5 64-bit ('python@3.9')"
   },
   "language_info": {
    "codemirror_mode": {
@@ -1122,7 +1119,10 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.6.5"
+   "version": "3.9.5"
+  },
+  "interpreter": {
+   "hash": "ac2eaa0ea0ebeafcc7822e65e46aa9d4f966f30b695406963e145ea4a91cd4fc"
   }
  },
  "nbformat": 4,
diff --git a/mkdocs.yml b/mkdocs.yml
index c76d9ec4..52ca57fa 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -5,14 +5,16 @@ repo_url: http://github.com/pepkit/pipestat
 pypi_name: pipestat
 
 nav:
-  - Getting Started: 
+  - Getting Started:
     - Introduction: README.md
     - Install and configure: install.md
   - How-to guides:
     - Use Python API: python_api.md
     - Use command line interface: cli.md
+    - Configure pipestat: configuration.md
   - Reference:
-    - Configuration format : config.md
+    - CLI usage: usage.md
+    - Configuration format: config.md
     - Environment variables: env_vars.md
     - Pipestat specification: pipestat_specification.md
     - Python API: autodoc_build/pipestat.md
@@ -29,4 +31,4 @@ plugins:
     autodoc_build: "docs/autodoc_build"
     autodoc_package: "pipestat"
     no_top_level: true
-- search
\ No newline at end of file
+- search
diff --git a/pipestat/__init__.py b/pipestat/__init__.py
index 02cdabbb..57d036ff 100644
--- a/pipestat/__init__.py
+++ b/pipestat/__init__.py
@@ -9,4 +9,4 @@
 __classes__ = ["PipestatManager"]
 __all__ = __classes__
 
-logmuse.init_logger("pipestat")
+logmuse.init_logger(PKG_NAME)
diff --git a/pipestat/_version.py b/pipestat/_version.py
index 81f0fdec..3dc1f76b 100644
--- a/pipestat/_version.py
+++ b/pipestat/_version.py
@@ -1 +1 @@
-__version__ = "0.0.4"
+__version__ = "0.1.0"
diff --git a/pipestat/argparser.py b/pipestat/argparser.py
index 1418664f..34253ebb 100644
--- a/pipestat/argparser.py
+++ b/pipestat/argparser.py
@@ -71,11 +71,8 @@ def add_subparser(cmd, msg, subparsers):
         )
         if cmd == STATUS_SET_CMD:
             status_sps[cmd].add_argument(
-                "-i",
-                "--status-identifier",
-                metavar="S",
-                help="Status identifier to use",
-                required=True,
+                "status_identifier",
+                help="Status identifier to set.",
             )
         status_sps[cmd].add_argument(
             "-f",
@@ -213,9 +210,9 @@ def add_subparser(cmd, msg, subparsers):
 
     sps[REPORT_CMD].add_argument(
         "-t",
-        "--try-convert",
+        "--skip-convert",
         action="store_true",
-        help="Whether to try to convert the reported value into reqiuired "
+        help="Whether skip result type conversion into the reqiuired "
         "class in case it does not meet the schema requirements",
     )
 
diff --git a/pipestat/cli.py b/pipestat/cli.py
index ab52c931..eb084208 100644
--- a/pipestat/cli.py
+++ b/pipestat/cli.py
@@ -6,13 +6,14 @@
 
 from .argparser import build_argparser
 from .const import *
+from .exceptions import SchemaNotFoundError
 from .pipestat import PipestatManager
 
 _LOGGER = getLogger(PKG_NAME)
 
 
 def main():
-    """ Primary workflow """
+    """Primary workflow"""
     from inspect import getdoc
 
     parser = logmuse.add_logging_options(build_argparser(getdoc(PipestatManager)))
@@ -23,7 +24,7 @@ def main():
     global _LOGGER
     _LOGGER = logmuse.logger_via_cli(args, make_root=True)
     _LOGGER.debug("Args namespace:\n{}".format(args))
-    if args.config and not args.schema:
+    if args.config and not args.schema and args.command != STATUS_CMD:
         parser.error("the following arguments are required: -s/--schema")
     psm = PipestatManager(
         namespace=args.namespace,
@@ -36,6 +37,8 @@ def main():
     )
     if args.command == REPORT_CMD:
         value = args.value
+        if psm.schema is None:
+            raise SchemaNotFoundError(msg="report", cli=True)
         result_metadata = psm.schema[args.result_identifier]
         if (
             result_metadata[SCHEMA_TYPE_KEY]
@@ -57,7 +60,7 @@ def main():
             record_identifier=args.record_identifier,
             values={args.result_identifier: value},
             force_overwrite=args.overwrite,
-            strict_type=not args.try_convert,
+            strict_type=args.skip_convert,
         )
     if args.command == INSPECT_CMD:
         print("\n")
diff --git a/pipestat/const.py b/pipestat/const.py
index 3c72253a..b5868bfa 100644
--- a/pipestat/const.py
+++ b/pipestat/const.py
@@ -1,5 +1,8 @@
 import os
 
+from sqlalchemy.dialects.postgresql.json import JSONB
+from sqlalchemy.types import ARRAY, JSON, Boolean, Float, Integer, String
+
 PKG_NAME = "pipestat"
 LOCK_PREFIX = "lock."
 REPORT_CMD = "report"
@@ -23,17 +26,6 @@
     STATUS_GET_CMD: "Get status.",
 }
 
-TABLE_COLS_BY_TYPE = {
-    "integer": "{} INT",
-    "number": "{} NUMERIC",
-    "string": "{} TEXT",
-    "boolean": "{} BOOLEAN",
-    "object": "{} JSONB",
-    "array": "{} TEXT[]",
-    "file": "{} JSONB",
-    "image": "{} JSONB",
-}
-
 DOC_URL = "http://pipestat.databio.org/en/latest/db_config/"
 
 # DB config keys
@@ -43,6 +35,8 @@
 CFG_PORT_KEY = "port"
 CFG_PASSWORD_KEY = "password"
 CFG_USER_KEY = "user"
+CFG_DIALECT_KEY = "dialect"  # sqlite, mysql, postgresql, oracle, or mssql
+CFG_DRIVER_KEY = "driver"
 
 DB_CREDENTIALS = [
     CFG_HOST_KEY,
@@ -50,6 +44,8 @@
     CFG_PASSWORD_KEY,
     CFG_USER_KEY,
     CFG_NAME_KEY,
+    CFG_DIALECT_KEY,
+    CFG_DRIVER_KEY,
 ]
 
 # object attribute names
@@ -61,16 +57,33 @@
 STATUS_SCHEMA_SOURCE_KEY = "_status_schema_source"
 STATUS_FILE_DIR = "_status_file_dir"
 RES_SCHEMAS_KEY = "_result_schemas"
+DB_BASE_KEY = "_declarative_base"
+DB_ORMS_KEY = "_orms"
 DATA_KEY = "_data"
 NAME_KEY = "_name"
 FILE_KEY = "_file"
 RECORD_ID_KEY = "_record_id"
-DB_CONNECTION_KEY = "_db_connnection"
+DB_SESSION_KEY = "_db_session"
+DB_SCOPED_SESSION_KEY = "_db_scoped_session"
+DB_ENGINE_KEY = "_db_engine"
 HIGHLIGHTED_KEY = "_highlighted"
+DB_COLUMN_KEY = "db_column"
+DB_RELATIONSHIP_KEY = "relationship"
+DB_RELATIONSHIP_NAME_KEY = "name"
+DB_RELATIONSHIP_TABLE_KEY = "table"
+DB_RELATIONSHIP_COL_KEY = "column"
+DB_RELATIONSHIP_BACKREF_KEY = "backref"
+DB_RELATIONSHIP_ELEMENTS = [
+    DB_RELATIONSHIP_BACKREF_KEY,
+    DB_RELATIONSHIP_COL_KEY,
+    DB_RELATIONSHIP_NAME_KEY,
+    DB_RELATIONSHIP_TABLE_KEY,
+]
 
 # schema keys
 SCHEMA_PROP_KEY = "properties"
 SCHEMA_TYPE_KEY = "type"
+SCHEMA_DESC_KEY = "description"
 
 # DB column names
 ID = "id"
@@ -79,14 +92,6 @@
 
 RESERVED_COLNAMES = [ID, RECORD_ID]
 
-FIXED_COLUMNS = [f"{ID} BIGSERIAL PRIMARY KEY", f"{RECORD_ID} TEXT UNIQUE NOT NULL"]
-
-STATUS_TABLE_COLUMNS = [
-    f"{ID} BIGSERIAL PRIMARY KEY",
-    f"{RECORD_ID} TEXT UNIQUE NOT NULL",
-    f"{STATUS} TEXT",
-]
-# f"{STATUS} {STATUS}"]  # custom type 'status'
 CANONICAL_TYPES = {
     "image": {
         "type": "object",
@@ -127,9 +132,24 @@
     "boolean": bool,
 }
 
+SQL_CLASSES_BY_TYPE = {
+    "number": Float,
+    "integer": Integer,
+    "object": JSONB,
+    "image": JSONB,
+    "file": JSONB,
+    "string": String(500),
+    "array": JSONB,
+    "boolean": Boolean,
+}
+
 CFG_SCHEMA = os.path.join(
     os.path.dirname(os.path.abspath(__file__)), "schemas", "pipestat_config_schema.yaml"
 )
 STATUS_SCHEMA = os.path.join(
     os.path.dirname(os.path.abspath(__file__)), "schemas", "status_schema.yaml"
 )
+
+STATUS_TABLE_SCHEMA = os.path.join(
+    os.path.dirname(os.path.abspath(__file__)), "schemas", "status_table_schema.yaml"
+)
diff --git a/pipestat/exceptions.py b/pipestat/exceptions.py
index 8d4f4522..af1db58d 100644
--- a/pipestat/exceptions.py
+++ b/pipestat/exceptions.py
@@ -16,31 +16,34 @@
 
 
 class PipestatError(Exception):
-    """ Base exception type for this package """
+    """Base exception type for this package"""
 
     __metaclass__ = abc.ABCMeta
 
 
 class SchemaError(PipestatError):
-    """ Schema error """
+    """Schema error"""
 
     def __init__(self, msg):
         super(SchemaError, self).__init__(msg)
 
 
 class SchemaNotFoundError(SchemaError):
-    """ Schema not found error """
-
-    def __init__(self, msg):
-        txt = (
-            f"Results schema not found. The schema is required to {msg}. "
-            f"It needs to be supplied to the object constructor."
+    """Schema not found error"""
+
+    def __init__(self, msg, cli=False):
+        txt = f"Results schema not found. The schema is required to {msg}. "
+        txt += (
+            f"It needs to be supplied as an CLI argument"
+            if cli
+            else "It needs to be supplied to the object constructor"
         )
+        txt += f" or via '{ENV_VARS['schema']}' environment variable."
         super(SchemaNotFoundError, self).__init__(txt)
 
 
 class MissingConfigDataError(PipestatError):
-    """ Exception for invalid config file. """
+    """Exception for invalid config file."""
 
     def __init__(self, msg):
         spacing = " " if msg[-1] in ["?", ".", "\n"] else "; "
@@ -49,14 +52,14 @@ def __init__(self, msg):
 
 
 class PipestatDatabaseError(PipestatError):
-    """ Database error """
+    """Database error"""
 
     def __init__(self, msg):
         super(PipestatDatabaseError, self).__init__(msg)
 
 
 class InvalidTypeError(PipestatError):
-    """ Type of the reported value is not supported """
+    """Type of the reported value is not supported"""
 
     def __init__(self, type):
         super(InvalidTypeError, self).__init__(
@@ -66,7 +69,7 @@ def __init__(self, type):
 
 
 class IncompatibleClassError(PipestatError):
-    """ Class  of the reported value is not supported """
+    """Class  of the reported value is not supported"""
 
     def __init__(self, cls, req_cls, type):
         super(IncompatibleClassError, self).__init__(
diff --git a/pipestat/helpers.py b/pipestat/helpers.py
index 44af23a3..942f9d75 100644
--- a/pipestat/helpers.py
+++ b/pipestat/helpers.py
@@ -1,9 +1,12 @@
 import logging
 from re import findall
+from typing import Any, Dict, List, Optional, Tuple, Union
 
 import jsonschema
+import sqlalchemy.orm
 from oyaml import safe_load
 from psycopg2 import sql
+from sqlalchemy.orm import DeclarativeMeta, Query
 from ubiquerg import expandpath
 
 from .const import *
@@ -11,24 +14,21 @@
 _LOGGER = logging.getLogger(__name__)
 
 
-def schema_to_columns(schema):
+def get_status_table_schema(status_schema: Dict[str, Any]) -> Dict[str, Any]:
     """
-    Get a list of database table columns from a schema
+    Update and return a status_table_schema based on user-provided status schema
 
-    :param dict schema: schema to parse
-    :return list[str]: columns to inial ize database table with
+    :param Dict[str, Any] status_schema: status schema provided by the user
+    :return Dict[str, Any]: status_schema status table scheme
+        to use as a base for status table generation
     """
-    columns = []
-    for colname, col_dict in schema.items():
-        if col_dict[SCHEMA_TYPE_KEY] not in TABLE_COLS_BY_TYPE:
-            _LOGGER.warning(
-                f"'{col_dict[SCHEMA_TYPE_KEY]}' result type defined"
-                f" in schema is not supported"
-            )
-            continue
-        columns.append(TABLE_COLS_BY_TYPE[col_dict[SCHEMA_TYPE_KEY]].format(colname))
-    _LOGGER.info(f"Table columns created based on schema: {columns}")
-    return columns
+    defined_status_codes = list(status_schema.keys())
+    _, status_table_schema = read_yaml_data(
+        path=STATUS_TABLE_SCHEMA, what="status table schema"
+    )
+    status_table_schema["status"].update({"enum": defined_status_codes})
+    _LOGGER.debug(f"Updated status table schema: {status_table_schema}")
+    return status_table_schema
 
 
 def validate_type(value, schema, strict_type=False):
@@ -102,66 +102,71 @@ def mk_list_of_str(x):
     )
 
 
-def preprocess_condition_pair(condition, condition_val):
+def dynamic_filter(
+    ORM: DeclarativeMeta,
+    query: Query,
+    filter_conditions: Optional[List[Tuple[str, str, Union[str, List[str]]]]] = None,
+    json_filter_conditions: Optional[List[Tuple[str, str, str]]] = None,
+) -> sqlalchemy.orm.Query:
     """
-    Preprocess query condition and values to ensure sanity and compatibility
-
-    :param str condition: condition string
-    :param tuple condition_val: values to populate condition string with
-    :return (psycopg2.sql.SQL, tuple): condition pair
+    Return filtered query based on condition.
+
+    :param sqlalchemy.orm.DeclarativeMeta ORM:
+    :param sqlalchemy.orm.Query query: takes query
+    :param [(key,operator,value)] filter_conditions: e.g. [("id", "eq", 1)] operator list
+        - eq for ==
+        - lt for <
+        - ge for >=
+        - in for in_
+        - like for like
+    :param [(col,key,value)] json_filter_conditions: conditions for JSONB column to query.
+        Only '==' is supported e.g. [("other", "genome", "hg38")]
+    :return: query
     """
 
-    def _check_semicolon(x):
-        """
-        recursively check for semicolons in an object
-
-        :param aby x: object to inspect
-        :raises ValueError: if semicolon detected
-        """
-        if isinstance(x, str):
-            assert ";" not in x, ValueError(
-                f"semicolons are not permitted in condition values: '{str(x)}'"
+    def _unpack_tripartite(x):
+        try:
+            assert isinstance(x, List) or isinstance(x, Tuple), TypeError(
+                "Wrong filter class, a List or Tuple is required"
+            )
+            e1, e2, e3 = x
+            return e1, e2, e3
+        except Exception:
+            raise ValueError(
+                f"Invalid filter value: {x}. The filter must be a tripartite iterable"
             )
-        if isinstance(x, list):
-            list(map(lambda v: _check_semicolon(v), x))
-
-    if condition:
-        if not isinstance(condition, str):
-            raise TypeError("Condition has to be a string")
-        else:
-            _check_semicolon(condition)
-            placeholders = findall("%s", condition)
-            condition = sql.SQL(condition)
-        if not condition_val:
-            raise ValueError("condition provided but condition_val missing")
-        assert isinstance(condition_val, list), TypeError(
-            "condition_val has to be a list"
-        )
-        condition_val = tuple(condition_val)
-        assert len(placeholders) == len(condition_val), ValueError(
-            f"Number of condition ({len(condition_val)}) values not equal "
-            f"number of placeholders in: {condition}"
-        )
-    return condition, condition_val
-
-
-def paginate_query(query, offset, limit):
-    """
-    Apply offset and limit to the query string
 
-    :param sql.SQL query: query string to apply limit and offset to
-    :param int offset: offset to apply; no. of records to skip
-    :param int limit: limit to apply; max no. of records to return
-    :return sql.SQL: a possibly paginated query
-    """
-    if offset is not None:
-        assert isinstance(offset, int), TypeError(
-            f"Provided offset ({offset}) must be an int"
-        )
-        query += sql.SQL(f" OFFSET {offset}")
-    if limit is not None:
-        assert isinstance(limit, int), TypeError(
-            f"Provided limit ({limit}) must be an int"
-        )
-        query += sql.SQL(f" LIMIT {limit}")
+    if filter_conditions is not None:
+        for filter_condition in filter_conditions:
+            key, op, value = _unpack_tripartite(filter_condition)
+            column = getattr(ORM, key, None)
+            if column is None:
+                raise ValueError(f"Selected filter column does not exist: {key}")
+            if op == "in":
+                if isinstance(value, list):
+                    filt = column.in_(value)
+                else:
+                    filt = column.in_(value.split(","))
+            else:
+                try:
+                    attr = (
+                        list(
+                            filter(
+                                lambda e: hasattr(column, e % op),
+                                ["%s", "%s_", "__%s__"],
+                            )
+                        )[0]
+                        % op
+                    )
+                except IndexError:
+                    raise ValueError()(f"Invalid filter operator: {op}")
+                if value == "null":
+                    value = None
+                filt = getattr(column, attr)(value)
+            query = query.filter(filt)
+
+    if json_filter_conditions is not None:
+        for json_filter_condition in json_filter_conditions:
+            col, key, value = _unpack_tripartite(json_filter_condition)
+            query = query.filter(getattr(ORM, col)[key].astext == value)
     return query
diff --git a/pipestat/pipestat.py b/pipestat/pipestat.py
index f3f75262..8311e51c 100644
--- a/pipestat/pipestat.py
+++ b/pipestat/pipestat.py
@@ -1,13 +1,21 @@
 from contextlib import contextmanager
 from copy import deepcopy
 from logging import getLogger
-from typing import Any, Dict, List, Optional, Union
+from typing import Dict, List, Optional, Tuple, Union
+from urllib.parse import quote_plus
 
-import psycopg2
+import sqlalchemy.orm
 from attmap import PathExAttMap as PXAM
 from jsonschema import validate
-from psycopg2.extensions import connection
-from psycopg2.extras import DictCursor, Json
+from sqlalchemy import Column, ForeignKey, create_engine, text
+from sqlalchemy.ext.declarative import declarative_base
+from sqlalchemy.orm import (
+    DeclarativeMeta,
+    backref,
+    relationship,
+    scoped_session,
+    sessionmaker,
+)
 from ubiquerg import create_lock, remove_lock
 from yacman import YacAttMap
 
@@ -18,25 +26,6 @@
 _LOGGER = getLogger(PKG_NAME)
 
 
-class LoggingCursor(psycopg2.extras.DictCursor):
-    """
-    Logging db cursor
-    """
-
-    def execute(self, query, vars=None):
-        """
-        Execute a database operation (query or command) and issue a debug
-        and info level log messages
-
-        :param query:
-        :param vars:
-        :return:
-        """
-        _LOGGER.debug(f"Executing query: {self.mogrify(query, vars)}")
-        super(LoggingCursor, self).execute(query=query, vars=vars)
-        _LOGGER.debug(f"Executed query: {self.query}")
-
-
 class PipestatManager(dict):
     """
     Pipestat standardizes reporting of pipeline results and
@@ -45,19 +34,21 @@ class PipestatManager(dict):
     pipeline can easily and reliably become an input for downstream analyses.
     The object exposes API for interacting with the results and
     pipeline status and can be backed by either a YAML-formatted file
-    or a PostgreSQL database.
+    or a database.
     """
 
     def __init__(
         self,
-        namespace: str = None,
-        record_identifier: str = None,
-        schema_path: str = None,
-        results_file_path: str = None,
-        database_only: bool = False,
-        config: Union[str, dict] = None,
-        status_schema_path: str = None,
-        flag_file_dir: str = None,
+        namespace: Optional[str] = None,
+        record_identifier: Optional[str] = None,
+        schema_path: Optional[str] = None,
+        results_file_path: Optional[str] = None,
+        database_only: Optional[bool] = True,
+        config: Optional[Union[str, dict]] = None,
+        status_schema_path: Optional[str] = None,
+        flag_file_dir: Optional[str] = None,
+        custom_declarative_base: Optional[sqlalchemy.orm.DeclarativeMeta] = None,
+        show_db_logs: bool = False,
     ):
         """
         Initialize the object
@@ -77,6 +68,8 @@ def __init__(
             with the config file content
         :param str status_schema_path: path to the status schema that formalizes
             the status flags structure
+        :param sqlalchemy.orm.DeclarativeMeta custom_declarative_base: a declarative base to
+            use for ORMs creation a new instance will be created if not provided
         """
 
         def _check_cfg_key(cfg: dict, key: str) -> bool:
@@ -100,7 +93,8 @@ def _mk_abs_via_cfg(
                     os.path.dirname(rel_to_cwd), os.W_OK
                 ):
                     return rel_to_cwd
-                raise OSError(f"Could not make this path absolute: {path}")
+                else:
+                    raise OSError(f"File not found: {path}")
             joined = os.path.join(os.path.dirname(cfg_path), path)
             if os.path.isabs(joined):
                 return joined
@@ -187,6 +181,11 @@ def _select_value(
                     f"highlighted results specification "
                     f"({self[HIGHLIGHTED_KEY]}) has to be a list"
                 )
+        else:
+            _LOGGER.debug(
+                "Creating object with no results schema."
+                " The object can be used only for status management in this case."
+            )
         # read status schema
         status_schema_path = (
             _mk_abs_via_cfg(
@@ -217,10 +216,11 @@ def _select_value(
         )
         if results_file_path:
             if self[DB_ONLY_KEY]:
-                raise ValueError(
-                    "Running in database only mode does not make "
-                    "sense with a YAML file as a backend."
+                _LOGGER.debug(
+                    "Running in database only mode does not make sense with a YAML file as a backend. "
+                    "Changing back to using memory."
                 )
+                self[DB_ONLY_KEY] = not self[DB_ONLY_KEY]
             self[FILE_KEY] = results_file_path
             self._init_results_file()
             flag_file_dir = _select_value(
@@ -235,14 +235,17 @@ def _select_value(
                 ]
             ):
                 raise MissingConfigDataError(
-                    "Must specify all database login " "credentials or result_file_path"
+                    "Must specify all database login credentials or result_file_path"
                 )
+            self[DB_ORMS_KEY] = {}
+            self[DB_BASE_KEY] = custom_declarative_base or declarative_base()
             self[DATA_KEY] = YacAttMap()
-            self._init_postgres_table()
+            self._show_db_logs = show_db_logs
+            self._init_db_table()
             self._init_status_table()
         else:
             raise MissingConfigDataError(
-                "Must specify either database login " "credentials or a YAML file path"
+                "Must specify either database login credentials or a YAML file path"
             )
 
     def __str__(self):
@@ -253,7 +256,9 @@ def __str__(self):
         """
         res = f"{self.__class__.__name__} ({self.namespace})"
         res += "\nBackend: {}".format(
-            f"file ({self.file})" if self.file else "PostgreSQL"
+            f"File\n - results: {self.file}\n - status: {self[STATUS_FILE_DIR]}"
+            if self.file
+            else f"Database (dialect: {self[DB_ENGINE_KEY].dialect.name})"
         )
         res += f"\nResults schema source: {self.schema_path}"
         res += f"\nStatus schema source: {self.status_schema_source}"
@@ -262,33 +267,18 @@ def __str__(self):
             res += f"\nHighlighted results: {', '.join(self.highlighted_results)}"
         return res
 
-    def _get_flag_file(
-        self, record_identifier: str = None
-    ) -> Union[str, List[str], None]:
+    @property
+    def record_count(self) -> int:
         """
-        Get path to the status flag file for the specified record
+        Number of records reported
 
-        :param str record_identifier: unique record identifier
-        :return str | list[str] | None: path to the status flag file
+        :return int: number of records reported
         """
-        from glob import glob
-
-        r_id = self._strict_record_id(record_identifier)
-        if self.file is None:
-            return
-        if self.file is not None:
-            regex = os.path.join(
-                self[STATUS_FILE_DIR], f"{self.namespace}_{r_id}_*.flag"
-            )
-            file_list = glob(regex)
-            if len(file_list) > 1:
-                _LOGGER.warning("Multiple flag files found")
-                return file_list
-            elif len(file_list) == 1:
-                return file_list[0]
-            else:
-                _LOGGER.debug("No flag files found")
-                return None
+        return (
+            len(self.data[self.namespace])
+            if self.file
+            else self._count_rows(self.namespace)
+        )
 
     @property
     def highlighted_results(self) -> List[str]:
@@ -300,17 +290,53 @@ def highlighted_results(self) -> List[str]:
         return self._get_attr(HIGHLIGHTED_KEY) or []
 
     @property
-    def record_count(self) -> int:
+    def db_column_kwargs_by_result(self) -> Dict[str, Any]:
         """
-        Number of records reported
+        Database column key word arguments for every result,
+        sourced from the results schema in the `db_column` section
 
-        :return int: number of records reported
+        :return Dict[str, Any]: key word arguments for every result
         """
-        return (
-            len(self.data[self.namespace])
-            if self.file
-            else self._count_rows(self.namespace)
-        )
+        if self.schema is None:
+            return {}
+        return {
+            result_id: self.schema[result_id][DB_COLUMN_KEY]
+            for result_id in self.schema.keys()
+            if DB_COLUMN_KEY in self.schema[result_id]
+        }
+
+    @property
+    def db_column_relationships_by_result(self) -> Dict[str, str]:
+        """
+        Database column relationships for every result,
+        sourced from the results schema in the `relationship` section
+
+        *Note: this is an experimental feature*
+
+        :return Dict[str, Dict[str, str]]: relationships for every result
+        """
+        if self.schema is None:
+            return {}
+
+        def _validate_rel_section(result_id):
+            if not all(
+                [
+                    k in self.schema[result_id][DB_RELATIONSHIP_KEY].keys()
+                    for k in DB_RELATIONSHIP_ELEMENTS
+                ]
+            ):
+                PipestatDatabaseError(
+                    f"Not all required {DB_RELATIONSHIP_KEY} settings ({DB_RELATIONSHIP_ELEMENTS}) were "
+                    f"provided for result: {result_id}"
+                )
+            return True
+
+        return {
+            result_id: self.schema[result_id][DB_RELATIONSHIP_KEY]
+            for result_id in self.schema.keys()
+            if DB_RELATIONSHIP_KEY in self.schema[result_id]
+            and _validate_rel_section(result_id)
+        }
 
     @property
     def namespace(self) -> str:
@@ -406,259 +432,322 @@ def data(self) -> YacAttMap:
         return self._get_attr(DATA_KEY)
 
     @property
-    @contextmanager
-    def db_cursor(self):
+    def db_url(self) -> str:
         """
-        Establish connection and get a PostgreSQL database cursor,
-        commit and close the connection afterwards
+        Database URL, generated based on config credentials
 
-        :return LoggingCursor: Database cursor object
+        :return str: database URL
+        :raise PipestatDatabaseError: if the object is not backed by a database
         """
+        if self.file is not None:
+            raise PipestatDatabaseError(
+                "Can't determine database URL if the object is backed by a file"
+            )
         try:
-            if not self.check_connection():
-                self.establish_postgres_connection()
-            with self[DB_CONNECTION_KEY] as c, c.cursor(
-                cursor_factory=LoggingCursor
-            ) as cur:
-                yield cur
-        except Exception:
-            raise
-        finally:
-            self.close_postgres_connection()
+            creds = dict(
+                name=self[CONFIG_KEY][CFG_DATABASE_KEY][CFG_NAME_KEY],
+                user=self[CONFIG_KEY][CFG_DATABASE_KEY][CFG_USER_KEY],
+                passwd=self[CONFIG_KEY][CFG_DATABASE_KEY][CFG_PASSWORD_KEY],
+                host=self[CONFIG_KEY][CFG_DATABASE_KEY][CFG_HOST_KEY],
+                port=self[CONFIG_KEY][CFG_DATABASE_KEY][CFG_PORT_KEY],
+                dialect=self[CONFIG_KEY][CFG_DATABASE_KEY][CFG_DIALECT_KEY],
+                driver=self[CONFIG_KEY][CFG_DATABASE_KEY][CFG_DRIVER_KEY],
+            )
+        except (KeyError, AttributeError) as e:
+            raise PipestatDatabaseError(
+                f"Could not determine database URL. Caught error: {str(e)}"
+            )
+        parsed_creds = {k: quote_plus(str(v)) for k, v in creds.items()}
+        return "{dialect}+{driver}://{user}:{passwd}@{host}:{port}/{name}".format(
+            **parsed_creds
+        )
 
-    def get_status(self, record_identifier: str = None) -> Optional[str]:
+    @property
+    @contextmanager
+    def session(self):
         """
-        Get the current pipeline status
+        Provide a transactional scope around a series of query
+        operations.
+        """
+        if not self.is_db_connected():
+            self.establish_db_connection()
+        with self[DB_SESSION_KEY]() as session:
+            _LOGGER.debug("Created session")
+            yield session
+            _LOGGER.debug("Ending session")
 
-        :return str: status identifier, like 'running'
+    def _get_flag_file(
+        self, record_identifier: str = None
+    ) -> Union[str, List[str], None]:
+        """
+        Get path to the status flag file for the specified record
+
+        :param str record_identifier: unique record identifier
+        :return str | list[str] | None: path to the status flag file
         """
+        from glob import glob
+
         r_id = self._strict_record_id(record_identifier)
         if self.file is None:
-            with self.db_cursor as cur:
-                query = sql.SQL(
-                    f"SELECT {STATUS} "
-                    f"FROM {f'{self.namespace}_{STATUS}'} "
-                    f"WHERE {RECORD_ID}=%s"
-                )
-                cur.execute(query, (r_id,))
-                result = cur.fetchone()
-            return result[0] if result is not None else None
-        else:
-            flag_file = self._get_flag_file(record_identifier=r_id)
-            if flag_file is not None:
-                assert isinstance(flag_file, str), TypeError(
-                    "Flag file path is expected to be a str, were multiple flags found?"
-                )
-                with open(flag_file, "r") as f:
-                    status = f.read()
-                return status
-            _LOGGER.debug(
-                f"Could not determine status for '{r_id}' record. "
-                f"No flags found in: {self[STATUS_FILE_DIR]}"
+            return
+        if self.file is not None:
+            regex = os.path.join(
+                self[STATUS_FILE_DIR], f"{self.namespace}_{r_id}_*.flag"
             )
-            return None
+            file_list = glob(regex)
+            if len(file_list) > 1:
+                _LOGGER.warning("Multiple flag files found")
+                return file_list
+            elif len(file_list) == 1:
+                return file_list[0]
+            else:
+                _LOGGER.debug("No flag files found")
+                return None
 
-    def _get_attr(self, attr: str) -> Any:
+    def _strict_record_id(self, forced_value: str = None) -> str:
         """
-        Safely get the name of the selected attribute of this object
+        Get record identifier from the outer source or stored with this object
 
-        :param str attr: attr to select
-        :return:
+        :param str forced_value: return this value
+        :return str: record identifier
         """
-        return self[attr] if attr in self else None
+        if forced_value is not None:
+            return forced_value
+        if self.record_identifier is not None:
+            return self.record_identifier
+        raise PipestatError(
+            f"You must provide the record identifier you want to perform "
+            f"the action on. Either in the {self.__class__.__name__} "
+            f"constructor or as an argument to the method."
+        )
 
-    def _table_to_dict(self) -> None:
-        """
-        Create a dictionary from the database table data
+    def _create_table_orm(self, table_name: str, schema: Dict[str, Any]):
         """
-        with self.db_cursor as cur:
-            cur.execute(f"SELECT * FROM {self.namespace}")
-            data = cur.fetchall()
-        _LOGGER.debug(f"Reading data from database for '{self.namespace}' namespace")
-        for record in data:
-            record_id = record[RECORD_ID]
-            for res_id, val in record.items():
-                if val is not None:
-                    self._report_data_element(
-                        record_identifier=record_id, values={res_id: val}
-                    )
+        Create a table
 
-    def _init_postgres_table(self) -> bool:
+        :param str table_name: name of the table to create
+        :param Dict[str, Any] schema: schema to base table creation on
         """
-        Initialize a PostgreSQL table based on the provided schema,
-        if it does not exist. Read the data stored in the database into the
-        memory otherwise.
 
-        :return bool: whether the table has been created
-        """
-        if self.schema is None:
-            raise SchemaNotFoundError("initialize the database table")
-        if self._check_table_exists(table_name=self.namespace):
-            _LOGGER.debug(f"Table '{self.namespace}' already exists in the database")
-            if not self[DB_ONLY_KEY]:
-                self._table_to_dict()
-            return False
-        _LOGGER.info(f"Initializing '{self.namespace}' table in '{PKG_NAME}' database")
-        columns = FIXED_COLUMNS + schema_to_columns(schema=self.schema)
-        self._create_table(table_name=self.namespace, columns=columns)
-        return True
+        def _auto_repr(x: Any) -> str:
+            """
+            Auto-generated __repr__ fun
 
-    # def _create_status_type(self):
-    #     with self.db_cursor as cur:
-    #         s = sql.SQL(f"SELECT exists (SELECT 1 FROM pg_type WHERE typname = '{STATUS}');")
-    #         cur.execute(s)
-    #         if cur.fetchone()[0]:
-    #             return
-    #     with self.db_cursor as cur:
-    #         status_strs = [f"'{st_id}'" for st_id in self.status_schema.keys()]
-    #         status_str = ", ".join(status_strs)
-    #         s = sql.SQL(f"CREATE TYPE {STATUS} as enum({status_str});")
-    #         cur.execute(s)
+            :param Any x: object to generate __repr__ method for
+            :return str: string object representation
+            """
+            attr_strs = [
+                f"{k}={str(v)}" for k, v in x.__dict__.items() if not k.startswith("_")
+            ]
+            return "<{}: {}>".format(x.__class__.__name__, ", ".join(attr_strs))
 
-    def _init_status_table(self):
-        status_table_name = f"{self.namespace}_{STATUS}"
-        # self._create_status_type()
-        if not self._check_table_exists(table_name=status_table_name):
-            _LOGGER.info(
-                f"Initializing '{status_table_name}' table in " f"'{PKG_NAME}' database"
+        _LOGGER.debug(
+            f"Creating models for '{self.namespace}' table in '{PKG_NAME}' database"
+        )
+        tn = table_name or self.namespace
+        attr_dict = dict(
+            __tablename__=tn,
+            id=Column(Integer, primary_key=True),
+            record_identifier=Column(
+                SQL_CLASSES_BY_TYPE["string"],
+                unique=True,
+                doc="A unique identifier of the record",
+            ),
+            query=self[DB_SCOPED_SESSION_KEY].query_property(),
+        )
+        for result_id, result_metadata in schema.items():
+            col_type = SQL_CLASSES_BY_TYPE[result_metadata[SCHEMA_TYPE_KEY]]
+            _LOGGER.debug(f"Adding object: {result_id} of type: {str(col_type)}")
+
+            rel_info = self.db_column_relationships_by_result.get(result_id, {})
+            col_args = []
+            # if there is a relationship defined for this result, include it
+            if rel_info:
+                attr_dict.update(
+                    {
+                        rel_info["name"]: relationship(
+                            rel_info["table"].capitalize(),
+                            backref=backref(
+                                rel_info["backref"],
+                                uselist=True,
+                                cascade="delete,all",
+                            ),
+                        )
+                    }
+                )
+                col_args = [ForeignKey(f"{rel_info['table']}.{rel_info['column']}")]
+
+            attr_dict.update(
+                {
+                    result_id: Column(
+                        col_type,
+                        doc=result_metadata["description"],
+                        *col_args,
+                        **self.db_column_kwargs_by_result.get(result_id, {}),
+                    )
+                }
             )
-            self._create_table(status_table_name, STATUS_TABLE_COLUMNS)
+        attr_dict.update({"__repr__": _auto_repr})
+        _LOGGER.debug(f"Creating '{tn}' ORM with args: {attr_dict}")
+        self[DB_ORMS_KEY][tn] = type(tn.capitalize(), (self[DB_BASE_KEY],), attr_dict)
+        self[DB_BASE_KEY].metadata.create_all(bind=self[DB_ENGINE_KEY])
 
-    def _create_table(self, table_name: str, columns: List[str]):
+    def establish_db_connection(self) -> bool:
         """
-        Create a table
+        Establish DB connection using the config data
 
-        :param str table_name: name of the table to create
-        :param str | List[str] columns: columns definition list,
-            for instance: ['name VARCHAR(50) NOT NULL']
+        :return bool: whether the connection has been established successfully
         """
-        columns = mk_list_of_str(columns)
-        with self.db_cursor as cur:
-            s = sql.SQL(f"CREATE TABLE {table_name} ({','.join(columns)})")
-            cur.execute(s)
+        if self.is_db_connected():
+            raise PipestatDatabaseError("Connection is already established")
+        self[DB_ENGINE_KEY] = create_engine(self.db_url, echo=self._show_db_logs)
+        self[DB_SESSION_KEY] = sessionmaker(bind=self[DB_ENGINE_KEY])
+        self[DB_SCOPED_SESSION_KEY] = scoped_session(self[DB_SESSION_KEY])
+        return True
 
-    def _init_results_file(self) -> bool:
+    def is_db_connected(self) -> bool:
         """
-        Initialize YAML results file if it does not exist.
-        Read the data stored in the existing file into the memory otherwise.
+        Check whether a DB connection has been established
 
-        :return bool: whether the file has been created
+        :return bool: whether the connection has been established
         """
-        if not os.path.exists(self.file):
-            _LOGGER.info(f"Initializing results file '{self.file}'")
-            data = YacAttMap(entries={self.namespace: "{}"})
-            data.write(filepath=self.file)
-            data.make_readonly()
-            self[DATA_KEY] = data
-            return True
-        _LOGGER.debug(f"Reading data from '{self.file}'")
-        data = YacAttMap(filepath=self.file)
-        filtered = list(filter(lambda x: not x.startswith("_"), data.keys()))
-        if filtered and self.namespace not in filtered:
+        if self.file is not None:
             raise PipestatDatabaseError(
-                f"'{self.file}' is already used to report results for "
-                f"other namespace: {filtered[0]}"
+                f"The {self.__class__.__name__} object is not backed by a database"
             )
-        self[DATA_KEY] = data
+        if DB_SESSION_KEY in self and isinstance(self[DB_SESSION_KEY], sessionmaker):
+            return True
         return False
 
-    def _check_table_exists(self, table_name: str) -> bool:
+    def set_status(self, status_identifier: str, record_identifier: str = None) -> None:
         """
-        Check if the specified table exists
+        Set pipeline run status.
 
-        :param str table_name: table name to be checked
-        :return bool: whether the specified table exists
+        The status identifier needs to match one of identifiers specified in
+        the status schema. A basic, ready to use, status schema is shipped with
+         this package.
+
+        :param str status_identifier: status to set, one of statuses defined
+            in the status schema
+        :param str record_identifier: record identifier to set the
+            pipeline status for
         """
-        with self.db_cursor as cur:
-            cur.execute(
-                "SELECT EXISTS(SELECT * FROM information_schema.tables "
-                "WHERE table_name=%s)",
-                (table_name,),
+        r_id = self._strict_record_id(record_identifier)
+        known_status_identifiers = self.status_schema.keys()
+        if status_identifier not in known_status_identifiers:
+            raise PipestatError(
+                f"'{status_identifier}' is not a defined status identifier. "
+                f"These are allowed: {known_status_identifiers}"
+            )
+        prev_status = self.get_status(r_id)
+        if self.file is not None:
+            self._set_status_file(
+                status_identifier=status_identifier,
+                record_identifier=r_id,
+                prev_status=prev_status,
+            )
+        else:
+            self._set_status_db(
+                status_identifier=status_identifier,
+                record_identifier=r_id,
+            )
+        if prev_status:
+            _LOGGER.debug(
+                f"Changed status from '{prev_status}' to '{status_identifier}'"
             )
-            return cur.fetchone()[0]
 
-    def _check_record(
-        self, condition_col: str, condition_val: str, table_name: str
-    ) -> bool:
+    def get_status_flag_path(
+        self, status_identifier: str, record_identifier=None
+    ) -> str:
         """
-        Check if the record matching the condition is in the table
+        Get the path to the status file flag
 
-        :param str condition_col: column to base the check on
-        :param str condition_val: value in the selected column
-        :param str table_name: name of the table ot check the record in
-        :return bool: whether any record matches the provided condition
+        :param str status_identifier: one of the defined status IDs in schema
+        :param str record_identifier: unique record ID, optional if
+            specified in the object constructor
+        :return str: absolute path to the flag file or None if object is
+            backed by a DB
         """
-        with self.db_cursor as cur:
-            statement = (
-                f"SELECT EXISTS(SELECT 1 from {table_name} "
-                f"WHERE {condition_col}=%s)"
+        if self.file is None:
+            # DB as the backend
+            return
+        r_id = self._strict_record_id(record_identifier)
+        return os.path.join(
+            self[STATUS_FILE_DIR], f"{self.namespace}_{r_id}_{status_identifier}.flag"
+        )
+
+    def _set_status_file(
+        self,
+        status_identifier: str,
+        record_identifier: str,
+        prev_status: Optional[str] = None,
+    ) -> None:
+        if prev_status is not None:
+            prev_flag_path = self.get_status_flag_path(prev_status, record_identifier)
+            os.remove(prev_flag_path)
+        flag_path = self.get_status_flag_path(status_identifier, record_identifier)
+        create_lock(flag_path)
+        with open(flag_path, "w") as f:
+            f.write(status_identifier)
+        remove_lock(flag_path)
+
+    def _set_status_db(
+        self,
+        status_identifier: str,
+        record_identifier: str,
+    ) -> None:
+        try:
+            self._report_db(
+                values={STATUS: status_identifier},
+                record_identifier=record_identifier,
+                table_name=f"{self.namespace}_{STATUS}",
             )
-            cur.execute(statement, (condition_val,))
-            return cur.fetchone()[0]
+        except Exception as e:
+            _LOGGER.error(f"Could not insert into the status table. Exception: {e}")
+            raise
 
-    def _count_rows(self, table_name: str) -> int:
+    def get_status(self, record_identifier: str = None) -> Optional[str]:
         """
-        Count rows in a selected table
+        Get the current pipeline status
 
-        :param str table_name: table to count rows for
-        :return int: number of rows in the selected table
+        :return str: status identifier, like 'running'
         """
-        with self.db_cursor as cur:
-            statement = sql.SQL("SELECT COUNT(*) FROM {}").format(
-                sql.Identifier(table_name)
+        r_id = self._strict_record_id(record_identifier)
+        if self.file is None:
+            return self._get_status_db(record_identifier=r_id)
+        else:
+            return self._get_status_file(record_identifier=r_id)
+
+    def _get_status_file(self, record_identifier: str) -> Optional[str]:
+        r_id = self._strict_record_id(record_identifier)
+        flag_file = self._get_flag_file(record_identifier=record_identifier)
+        if flag_file is not None:
+            assert isinstance(flag_file, str), TypeError(
+                "Flag file path is expected to be a str, were multiple flags found?"
             )
-            cur.execute(statement)
-            return cur.fetchall()[0][0]
+            with open(flag_file, "r") as f:
+                status = f.read()
+            return status
+        _LOGGER.debug(
+            f"Could not determine status for '{r_id}' record. "
+            f"No flags found in: {self[STATUS_FILE_DIR]}"
+        )
+        return None
 
-    def _report_postgres(
-        self, value: Dict[str, Any], record_identifier: str, table_name: str = None
-    ) -> int:
-        """
-        Check if record with this record identifier in table, create new record
-         if not (INSERT), update the record if yes (UPDATE).
-
-        Currently supports just one column at a time.
-
-        :param str record_identifier: unique identifier of the record, value to
-            in 'record_identifier' column to look for to determine if the record
-            already exists in the table
-        :param dict value: a mapping of pair of table column names and
-            respective values to be inserted to the database
-        :return int: id of the row just inserted
-        """
-        table_name = table_name or self.namespace
-        if not self._check_record(
-            condition_col=RECORD_ID,
-            condition_val=record_identifier,
-            table_name=table_name,
-        ):
-            with self.db_cursor as cur:
-                cur.execute(
-                    f"INSERT INTO {table_name} ({RECORD_ID}) VALUES (%s)",
-                    (record_identifier,),
-                )
-        # prep a list of SQL objects with column-named value placeholders
-        columns = sql.SQL(",").join(
-            [
-                sql.SQL("{}=%({})s").format(sql.Identifier(k), sql.SQL(k))
-                for k in list(value.keys())
-            ]
-        )
-        # construct the query template to execute
-        query = sql.SQL("UPDATE {n} SET {c} WHERE {id}=%({id})s RETURNING id").format(
-            n=sql.Identifier(table_name), c=columns, id=sql.SQL(RECORD_ID)
-        )
-        # preprocess the values, dict -> Json
-        values = {k: Json(v) if isinstance(v, dict) else v for k, v in value.items()}
-        # add record_identifier column, which is specified outside of values
-        values.update({RECORD_ID: record_identifier})
-        with self.db_cursor as cur:
-            cur.execute(query, values)
-            return cur.fetchone()[0]
+    def _get_status_db(self, record_identifier: str) -> Optional[str]:
+        try:
+            result = self._retrieve_db(
+                result_identifier=STATUS,
+                record_identifier=record_identifier,
+                table_name=f"{self.namespace}_{STATUS}",
+            )
+        except PipestatDatabaseError:
+            return None
+        return result[STATUS]
 
     def clear_status(
         self, record_identifier: str = None, flag_names: List[str] = None
-    ) -> List[str]:
+    ) -> List[Union[str, None]]:
         """
         Remove status flags
 
@@ -669,123 +758,249 @@ def clear_status(
         """
         r_id = self._strict_record_id(record_identifier)
         if self.file is not None:
-            flag_names = flag_names or list(self.status_schema.keys())
-            if isinstance(flag_names, str):
-                flag_names = [flag_names]
-            removed = []
-            for f in flag_names:
-                path_flag_file = self.get_status_flag_path(
-                    status_identifier=f, record_identifier=r_id
-                )
-                try:
-                    os.remove(path_flag_file)
-                except:
-                    pass
-                else:
-                    _LOGGER.info(f"Removed existing flag: {path_flag_file}")
-                    removed.append(f)
-            return removed
+            return self._clear_status_file(
+                record_identifier=r_id, flag_names=flag_names
+            )
+        else:
+            return self._clear_status_db(record_identifier=r_id)
+
+    def _clear_status_file(
+        self, record_identifier: str = None, flag_names: List[str] = None
+    ) -> List[Union[str, None]]:
+        flag_names = flag_names or list(self.status_schema.keys())
+        if isinstance(flag_names, str):
+            flag_names = [flag_names]
+        removed = []
+        for f in flag_names:
+            path_flag_file = self.get_status_flag_path(
+                status_identifier=f, record_identifier=record_identifier
+            )
+            try:
+                os.remove(path_flag_file)
+            except:
+                pass
+            else:
+                _LOGGER.info(f"Removed existing flag: {path_flag_file}")
+                removed.append(f)
+        return removed
+
+    def _clear_status_db(self, record_identifier: str = None) -> List[Union[str, None]]:
+        removed = self.get_status(record_identifier)
+        try:
+            self._remove_db(
+                record_identifier=record_identifier,
+                table_name=f"{self.namespace}_{STATUS}",
+            )
+        except Exception as e:
+            _LOGGER.error(
+                f"Could not remove the status from the database. Exception: {e}"
+            )
+            return []
         else:
-            removed = self.get_status(r_id)
-            status_table_name = f"{self.namespace}_{STATUS}"
-            with self.db_cursor as cur:
-                try:
-                    cur.execute(
-                        f"DELETE FROM {status_table_name} WHERE "
-                        f"{RECORD_ID}='{r_id}'"
+            return [removed]
+
+    def validate_schema(self) -> None:
+        """
+        Check schema for any possible issues
+
+        :raises SchemaError: if any schema format issue is detected
+        """
+
+        def _recursively_replace_custom_types(s: dict) -> Dict:
+            """
+            Replace the custom types in pipestat schema with canonical types
+
+            :param dict s: schema to replace types in
+            :return dict: schema with types replaced
+            """
+            for k, v in s.items():
+                assert SCHEMA_TYPE_KEY in v, SchemaError(
+                    f"Result '{k}' is missing '{SCHEMA_TYPE_KEY}' key"
+                )
+                assert SCHEMA_DESC_KEY in v, SchemaError(
+                    f"Result '{k}' is missing '{SCHEMA_DESC_KEY}' key"
+                )
+                if v[SCHEMA_TYPE_KEY] == "object" and SCHEMA_PROP_KEY in s[k]:
+                    _recursively_replace_custom_types(s[k][SCHEMA_PROP_KEY])
+                if v[SCHEMA_TYPE_KEY] in CANONICAL_TYPES.keys():
+                    s.setdefault(k, {})
+                    s[k].setdefault(SCHEMA_PROP_KEY, {})
+                    s[k][SCHEMA_PROP_KEY].update(
+                        CANONICAL_TYPES[v[SCHEMA_TYPE_KEY]][SCHEMA_PROP_KEY]
                     )
-                except Exception as e:
-                    _LOGGER.error(
-                        f"Could not remove the status from the "
-                        f"database. Exception: {e}"
+                    s[k].setdefault("required", [])
+                    s[k]["required"].extend(
+                        CANONICAL_TYPES[v[SCHEMA_TYPE_KEY]]["required"]
                     )
-                    return []
-                else:
-                    return [removed]
+                    s[k][SCHEMA_TYPE_KEY] = CANONICAL_TYPES[v[SCHEMA_TYPE_KEY]][
+                        SCHEMA_TYPE_KEY
+                    ]
+            return s
 
-    def get_status_flag_path(
-        self, status_identifier: str, record_identifier=None
-    ) -> str:
+        schema = deepcopy(self.schema)
+        _LOGGER.debug(f"Validating input schema")
+        assert isinstance(schema, dict), SchemaError(
+            f"The schema has to be a {dict().__class__.__name__}"
+        )
+        for col_name in RESERVED_COLNAMES:
+            assert col_name not in schema.keys(), PipestatError(
+                f"'{col_name}' is an identifier reserved by pipestat"
+            )
+        self[RES_SCHEMAS_KEY] = {}
+        schema = _recursively_replace_custom_types(schema)
+        self[RES_SCHEMAS_KEY] = schema
+
+    def _init_results_file(self) -> bool:
         """
-        Get the path to the status file flag
+        Initialize YAML results file if it does not exist.
+        Read the data stored in the existing file into the memory otherwise.
 
-        :param str status_identifier: one of the defined status IDs in schema
-        :param str record_identifier: unique record ID, optional if
-            specified in the object constructor
-        :return str: absolute path to the flag file or None if object is
-            backed by a DB
+        :return bool: whether the file has been created
         """
-        if self.file is None:
-            # DB as the backend
-            return
-        r_id = self._strict_record_id(record_identifier)
-        return os.path.join(
-            self[STATUS_FILE_DIR], f"{self.namespace}_{r_id}_{status_identifier}.flag"
+        if not os.path.exists(self.file):
+            _LOGGER.info(f"Initializing results file '{self.file}'")
+            data = YacAttMap(entries={self.namespace: "{}"})
+            data.write(filepath=self.file)
+            data.make_readonly()
+            self[DATA_KEY] = data
+            return True
+        _LOGGER.debug(f"Reading data from '{self.file}'")
+        data = YacAttMap(filepath=self.file)
+        filtered = list(filter(lambda x: not x.startswith("_"), data.keys()))
+        if filtered and self.namespace not in filtered:
+            raise PipestatDatabaseError(
+                f"'{self.file}' is already used to report results for "
+                f"other namespace: {filtered[0]}"
+            )
+        self[DATA_KEY] = data
+        return False
+
+    def _init_db_table(self) -> bool:
+        """
+        Initialize a database table based on the provided schema,
+        if it does not exist. Read the data stored in the database into the
+        memory otherwise.
+
+        :return bool: whether the table has been created
+        """
+        if self.schema is None:
+            return False
+        if not self.is_db_connected():
+            self.establish_db_connection()
+        self._create_table_orm(table_name=self.namespace, schema=self.result_schemas)
+        if not self[DB_ONLY_KEY]:
+            self._table_to_dict()
+        return True
+
+    def _table_to_dict(self) -> None:
+        """
+        Create a dictionary from the database table data
+        """
+        with self.session as s:
+            records = s.query(self.get_orm(self.namespace)).all()
+        _LOGGER.debug(f"Reading data from database for '{self.namespace}' namespace")
+        for record in records:
+            record_id = getattr(record, RECORD_ID)
+            for column in record.__table__.columns:
+                val = getattr(record, column.name, None)
+                if val is not None:
+                    self._report_data_element(
+                        record_identifier=record_id, values={column.name: val}
+                    )
+
+    def _init_status_table(self):
+        status_table_name = f"{self.namespace}_{STATUS}"
+        if not self.is_db_connected():
+            self.establish_db_connection()
+        # if not self._check_table_exists(table_name=status_table_name):
+        _LOGGER.debug(f"Initializing '{status_table_name}' table")
+        self._create_table_orm(
+            table_name=status_table_name,
+            schema=get_status_table_schema(status_schema=self.status_schema),
         )
 
-    def set_status(self, status_identifier: str, record_identifier: str = None) -> None:
+    def _get_attr(self, attr: str) -> Any:
         """
-        Set pipeline run status.
+        Safely get the name of the selected attribute of this object
 
-        The status identifier needs to match one of identifiers specified in
-        the status schema. A basic, ready to use, status schema is shipped with
-         this package.
+        :param str attr: attr to select
+        :return:
+        """
+        return self[attr] if attr in self else None
 
-        :param str status_identifier: status to set, one of statuses defined
-            in the status schema
-        :param str record_identifier: record identifier to set the
-            pipeline status for
+    def _check_table_exists(self, table_name: str) -> bool:
         """
-        r_id = self._strict_record_id(record_identifier)
-        known_status_identifiers = self.status_schema.keys()
-        if status_identifier not in known_status_identifiers:
-            raise PipestatError(
-                f"'{status_identifier}' is not a defined status identifier. "
-                f"These are allowed: {known_status_identifiers}"
+        Check if the specified table exists
+
+        :param str table_name: table name to be checked
+        :return bool: whether the specified table exists
+        """
+        from sqlalchemy import inspect
+
+        with self.session as s:
+            return inspect(s.bind).has_table(table_name=table_name)
+
+    def _count_rows(self, table_name: str) -> int:
+        """
+        Count rows in a selected table
+
+        :param str table_name: table to count rows for
+        :return int: number of rows in the selected table
+        """
+        with self.session as s:
+            return s.query(self[DB_ORMS_KEY][table_name].id).count()
+
+    def get_orm(self, table_name: str = None) -> Any:
+        """
+        Get an object relational mapper class
+
+        :param str table_name: table name to get a class for
+        :return Any: Object relational mapper class
+        """
+        if DB_ORMS_KEY not in self:
+            raise PipestatDatabaseError("Object relational mapper classes not defined")
+        tn = f"{table_name or self.namespace}"
+        if tn not in self[DB_ORMS_KEY]:
+            raise PipestatDatabaseError(
+                f"No object relational mapper class defined for table: {tn}"
             )
-        prev_status = self.get_status(r_id)
-        if self.file is not None:
-            if prev_status:
-                prev_flag_path = self.get_status_flag_path(prev_status, r_id)
-                os.remove(prev_flag_path)
-            flag_path = self.get_status_flag_path(status_identifier, r_id)
-            create_lock(flag_path)
-            with open(flag_path, "w") as f:
-                f.write(status_identifier)
-            remove_lock(flag_path)
-        else:
-            try:
-                self._report_postgres(
-                    value={STATUS: status_identifier},
-                    record_identifier=r_id,
-                    table_name=f"{self.namespace}_{STATUS}",
-                )
-            except Exception as e:
-                _LOGGER.error(
-                    f"Could not insert into the status table. " f"Exception: {e}"
-                )
-                raise
-        if prev_status:
-            _LOGGER.debug(
-                f"Changed status from '{prev_status}' to '{status_identifier}'"
+        if not isinstance(self[DB_ORMS_KEY][tn], DeclarativeMeta):
+            raise PipestatDatabaseError(
+                f"Object relational mapper class for table '{tn}' is invalid"
             )
+        return self[DB_ORMS_KEY][tn]
 
-    def check_result_exists(self, result_identifier, record_identifier=None):
+    def check_record_exists(
+        self, record_identifier: str, table_name: str = None
+    ) -> bool:
         """
-        Check if the result has been reported
+        Check if the specified record exists in the table
 
-        :param str record_identifier: unique identifier of the record
-        :param str result_identifier: name of the result to check
-        :return bool: whether the specified result has been reported for the
-            indicated record in current namespace
+        :param str record_identifier: record to check for
+        :param str table_name: table name to check
+        :return bool: whether the record exists in the table
         """
-        record_identifier = self._strict_record_id(record_identifier)
-        return self._check_which_results_exist(
-            results=[result_identifier], rid=record_identifier
-        )
+        if self.file is None:
+            with self.session as s:
+                return (
+                    s.query(self.get_orm(table_name).id)
+                    .filter_by(record_identifier=record_identifier)
+                    .first()
+                    is not None
+                )
+        else:
+            if (
+                self.namespace in self.data
+                and record_identifier in self.data[table_name]
+            ):
+                return True
+            return False
 
-    def _check_which_results_exist(
-        self, results: List[str], rid: str = None
+    def check_which_results_exist(
+        self,
+        results: List[str],
+        rid: Optional[str] = None,
+        table_name: Optional[str] = None,
     ) -> List[str]:
         """
         Check which results have been reported
@@ -796,52 +1011,254 @@ def _check_which_results_exist(
             indicated record in current namespace
         """
         rid = self._strict_record_id(rid)
-        existing = []
-        for r in results:
-            if not self[DB_ONLY_KEY]:
+        if self.file is None:
+            existing = self._check_which_results_exist_db(
+                results=results, rid=rid, table_name=table_name
+            )
+        else:
+            existing = []
+            for r in results:
                 if (
                     self.namespace in self.data
                     and rid in self.data[self.namespace]
                     and r in self.data[self.namespace][rid]
                 ):
                     existing.append(r)
-            else:
-                with self.db_cursor as cur:
-                    try:
-                        cur.execute(
-                            f"SELECT {r} FROM {self.namespace} WHERE {RECORD_ID}=%s",
-                            (rid,),
-                        )
-                    except Exception:
-                        continue
-                    else:
-                        res = cur.fetchone()
-                        if res is not None and res[0] is not None:
-                            existing.append(r)
         return existing
 
-    def check_record_exists(self, record_identifier: str = None) -> bool:
+    def _check_which_results_exist_db(
+        self, results: List[str], rid: str = None, table_name: str = None
+    ) -> List[str]:
+        """
+        Check if the specified results exist in the table
+
+        :param str rid: record to check for
+        :param List[str] results: results identifiers to check for
+        :param str table_name: name of the table to search for results in
+        :return List[str]: results identifiers that exist
         """
-        Check if the record exists
+        table_name = table_name or self.namespace
+        rid = self._strict_record_id(rid)
+        with self.session as s:
+            record = (
+                s.query(self.get_orm(table_name))
+                .filter_by(record_identifier=rid)
+                .first()
+            )
+        return [r for r in results if getattr(record, r, None) is not None]
+
+    def check_result_exists(
+        self,
+        result_identifier: str,
+        record_identifier: str = None,
+    ) -> bool:
+        """
+        Check if the result has been reported
 
         :param str record_identifier: unique identifier of the record
-        :return bool: whether the record exists
+        :param str result_identifier: name of the result to check
+        :return bool: whether the specified result has been reported for the
+            indicated record in current namespace
         """
         record_identifier = self._strict_record_id(record_identifier)
-        if self[DB_ONLY_KEY]:
-            with self.db_cursor as cur:
-                cur.execute(
-                    f"SELECT exists(SELECT 1 from {self.namespace} "
-                    f"WHERE {RECORD_ID}=%s)",
-                    (record_identifier,),
+        return (
+            len(
+                self.check_which_results_exist(
+                    results=[result_identifier],
+                    rid=record_identifier,
                 )
-                return cur.fetchone()
-        if (
-            self.namespace in self.data
-            and record_identifier in self.data[self.namespace]
-        ):
-            return True
-        return False
+            )
+            > 0
+        )
+
+    def select(
+        self,
+        table_name: Optional[str] = None,
+        columns: Optional[List[str]] = None,
+        filter_conditions: Optional[
+            List[Tuple[str, str, Union[str, List[str]]]]
+        ] = None,
+        json_filter_conditions: Optional[List[Tuple[str, str, str]]] = None,
+        offset: Optional[int] = None,
+        limit: Optional[int] = None,
+    ) -> List[Any]:
+        """
+        Perform a `SELECT` on the table
+
+        :param str table_name: name of the table to SELECT from
+        :param List[str] columns: columns to include in the result
+        :param [(key,operator,value)] filter_conditions: e.g. [("id", "eq", 1)], operator list:
+            - eq for ==
+            - lt for <
+            - ge for >=
+            - in for in_
+            - like for like
+        :param [(col,key,value)] json_filter_conditions: conditions for JSONB column to
+            query that include JSON column name, key withing the JSON object in that
+            column and the value to check the identity against. Therefore only '==' is
+            supported in non-nested checks, e.g. [("other", "genome", "hg38")]
+        :param int offset: skip this number of rows
+        :param int limit: include this number of rows
+        """
+
+        ORM = self.get_orm(table_name or self.namespace)
+        with self.session as s:
+            if columns is not None:
+                query = s.query(*[getattr(ORM, column) for column in columns])
+            else:
+                query = s.query(ORM)
+            query = dynamic_filter(
+                ORM=ORM,
+                query=query,
+                filter_conditions=filter_conditions,
+                json_filter_conditions=json_filter_conditions,
+            )
+            if isinstance(offset, int):
+                query = query.offset(offset)
+            if isinstance(limit, int):
+                query = query.limit(limit)
+            result = query.all()
+        return result
+
+    def retrieve(
+        self,
+        record_identifier: Optional[str] = None,
+        result_identifier: Optional[str] = None,
+    ) -> Union[Any, Dict[str, Any]]:
+        """
+        Retrieve a result for a record.
+
+        If no result ID specified, results for the entire record will
+        be returned.
+
+        :param str record_identifier: unique identifier of the record
+        :param str result_identifier: name of the result to be retrieved
+        :return any | Dict[str, any]: a single result or a mapping with all the
+            results reported for the record
+        """
+        r_id = self._strict_record_id(record_identifier)
+        if self.file is None:
+            results = self._retrieve_db(
+                result_identifier=result_identifier, record_identifier=r_id
+            )
+            if result_identifier is not None:
+                return results[result_identifier]
+            return results
+        else:
+            if r_id not in self.data[self.namespace]:
+                raise PipestatDatabaseError(f"Record '{r_id}' not found")
+            if result_identifier is None:
+                return self.data[self.namespace][r_id].to_dict()
+            if result_identifier not in self.data[self.namespace][r_id]:
+                raise PipestatDatabaseError(
+                    f"Result '{result_identifier}' not found for record '{r_id}'"
+                )
+            return self.data[self.namespace][r_id][result_identifier]
+
+    def _retrieve_db(
+        self,
+        result_identifier: str = None,
+        record_identifier: str = None,
+        table_name: str = None,
+    ) -> Dict[str, Any]:
+        """
+        Retrieve a result for a record.
+
+        If no result ID specified, results for the entire record will
+        be returned.
+
+        :param str record_identifier: unique identifier of the record
+        :param str result_identifier: name of the result to be retrieved
+        :param str table_name: name of the table to search for results in
+        :return Dict[str, any]: a single result or a mapping with all the results
+            reported for the record
+        """
+        table_name = table_name or self.namespace
+        record_identifier = self._strict_record_id(record_identifier)
+        if result_identifier is not None:
+            existing = self.check_which_results_exist(
+                results=[result_identifier],
+                rid=record_identifier,
+                table_name=table_name,
+            )
+            if not existing:
+                raise PipestatDatabaseError(
+                    f"Result '{result_identifier}' not found for record "
+                    f"'{record_identifier}'"
+                )
+
+        with self.session as s:
+            record = (
+                s.query(self.get_orm(table_name))
+                .filter_by(record_identifier=record_identifier)
+                .first()
+            )
+
+        if record is not None:
+            if result_identifier is not None:
+                return {result_identifier: getattr(record, result_identifier)}
+            return {
+                column: getattr(record, column)
+                for column in [c.name for c in record.__table__.columns]
+                if getattr(record, column, None) is not None
+            }
+        raise PipestatDatabaseError(f"Record '{record_identifier}' not found")
+
+    def select_txt(
+        self,
+        filter_templ: Optional[str] = "",
+        filter_params: Optional[Dict[str, Any]] = {},
+        table_name: Optional[str] = None,
+        offset: Optional[int] = None,
+        limit: Optional[int] = None,
+    ) -> List[Any]:
+        """
+        Execute a query with a textual filter. Returns all results.
+
+        To retrieve all table contents, leave the filter arguments out.
+        Table name defaults to the namespace
+
+        :param str filter_templ: filter template with value placeholders,
+             formatted as follows `id<:value and name=:name`
+        :param Dict[str, Any] filter_params: a mapping keys specified in the `filter_templ`
+            to parameters that are supposed to replace the placeholders
+        :param str table_name: name of the table to query
+        :param int offset: skip this number of rows
+        :param int limit: include this number of rows
+        :return List[Any]: a list of matched records
+        """
+        if self.file:
+            raise PipestatDatabaseError(
+                f"The {self.__class__.__name__} object is not backed by a database. "
+                f"This operation is not supported for file backend."
+            )
+        with self.session as s:
+            q = (
+                s.query(self.get_orm(table_name or self.namespace))
+                .filter(text(filter_templ))
+                .params(**filter_params)
+            )
+            if isinstance(offset, int):
+                q = q.offset(offset)
+            if isinstance(limit, int):
+                q = q.limit(limit)
+            results = q.all()
+        return results
+
+    def assert_results_defined(self, results: List[str]) -> None:
+        """
+        Assert provided list of results is defined in the schema
+
+        :param List[str] results: list of results to
+            check for existence in the schema
+        :raises SchemaError: if any of the results is not defined in the schema
+        """
+        known_results = self.result_schemas.keys()
+        for r in results:
+            assert r in known_results, SchemaError(
+                f"'{r}' is not a known result. Results defined in the "
+                f"schema are: {list(known_results)}."
+            )
 
     def report(
         self,
@@ -873,21 +1290,22 @@ def report(
                 "There is no way to return the updated object ID while using "
                 "results file as the object backend"
             )
-        updated_ids = False
         if self.schema is None:
             raise SchemaNotFoundError("report results")
+        updated_ids = False
         result_identifiers = list(values.keys())
         self.assert_results_defined(results=result_identifiers)
-        existing = self._check_which_results_exist(
+        existing = self.check_which_results_exist(
             rid=record_identifier, results=result_identifiers
         )
         if existing:
+            existing_str = ", ".join(existing)
             _LOGGER.warning(
-                f"These results exist for '{record_identifier}': {existing}"
+                f"These results exist for '{record_identifier}': {existing_str}"
             )
             if not force_overwrite:
                 return False
-            _LOGGER.info(f"Overwriting existing results: {existing}")
+            _LOGGER.info(f"Overwriting existing results: {existing_str}")
         for r in result_identifiers:
             validate_type(
                 value=values[r], schema=self.result_schemas[r], strict_type=strict_type
@@ -903,12 +1321,12 @@ def report(
             self.data.make_readonly()
         else:
             try:
-                updated_ids = self._report_postgres(
-                    record_identifier=record_identifier, value=values
+                updated_ids = self._report_db(
+                    record_identifier=record_identifier, values=values
                 )
             except Exception as e:
                 _LOGGER.error(
-                    f"Could not insert the result into the database. " f"Exception: {e}"
+                    f"Could not insert the result into the database. Exception: {e}"
                 )
                 if not self[DB_ONLY_KEY]:
                     for r in result_identifiers:
@@ -922,6 +1340,41 @@ def report(
         )
         return True if not return_id else updated_ids
 
+    def _report_db(
+        self, values: Dict[str, Any], record_identifier: str, table_name: str = None
+    ) -> int:
+        """
+        Report a result to a database
+
+        :param Dict[str, Any] values: values to report
+        :param str record_identifier: record to report the result for
+        :param str table_name: name of the table to report the result in
+        :return int: updated/inserted row
+        """
+        record_identifier = self._strict_record_id(record_identifier)
+        ORMClass = self.get_orm(table_name)
+        values.update({RECORD_ID: record_identifier})
+        if not self.check_record_exists(
+            record_identifier=record_identifier, table_name=table_name
+        ):
+            new_record = ORMClass(**values)
+            with self.session as s:
+                s.add(new_record)
+                s.commit()
+                returned_id = new_record.id
+        else:
+            with self.session as s:
+                record_to_update = (
+                    s.query(ORMClass)
+                    .filter(getattr(ORMClass, RECORD_ID) == record_identifier)
+                    .first()
+                )
+                for result_id, result_value in values.items():
+                    setattr(record_to_update, result_id, result_value)
+                s.commit()
+                returned_id = record_to_update.id
+        return returned_id
+
     def _report_data_element(
         self, record_identifier: str, values: Dict[str, Any]
     ) -> None:
@@ -932,7 +1385,7 @@ def _report_data_element(
          hierarchical mapping structure if needed.
 
         :param str record_identifier: unique identifier of the record
-        :param Dict[str,Any] values: dict of results identifiers and values
+        :param Dict[str, Any] values: dict of results identifiers and values
             to be reported
         """
         self[DATA_KEY].setdefault(self.namespace, PXAM())
@@ -940,104 +1393,10 @@ def _report_data_element(
         for res_id, val in values.items():
             self[DATA_KEY][self.namespace][record_identifier][res_id] = val
 
-    def select(
-        self,
-        columns: Union[str, List[str]] = None,
-        condition: str = None,
-        condition_val: str = None,
-        offset: int = None,
-        limit: int = None,
-    ) -> List[psycopg2.extras.DictRow]:
-        """
-        Get all the contents from the selected table, possibly restricted by
-        the provided condition.
-
-        :param str | List[str] columns: columns to select
-        :param str condition: condition to restrict the results
-            with, will be appended to the end of the SELECT statement and
-            safely populated with 'condition_val',
-            for example: `"id=%s"`
-        :param list condition_val: values to fill the placeholder
-            in 'condition' with
-        :param int offset: number of records to be skipped
-        :param int limit: max number of records to be returned
-        :return List[psycopg2.extras.DictRow]: all table contents
-        """
-        if self.file:
-            raise NotImplementedError(
-                "Selection is not supported on objects backed by results files."
-                " Use 'retrieve' method instead."
-            )
-        condition, condition_val = preprocess_condition_pair(condition, condition_val)
-        if not columns:
-            columns = sql.SQL("*")
-        else:
-            columns = sql.SQL(",").join(
-                [sql.Identifier(x) for x in mk_list_of_str(columns)]
-            )
-        statement = sql.SQL("SELECT {} FROM {}").format(
-            columns, sql.Identifier(self.namespace)
-        )
-        if condition:
-            statement += sql.SQL(" WHERE ")
-            statement += condition
-        statement = paginate_query(statement, offset, limit)
-        with self.db_cursor as cur:
-            cur.execute(query=statement, vars=condition_val)
-            result = cur.fetchall()
-        return result
-
-    def retrieve(
-        self, record_identifier: str = None, result_identifier: str = None
-    ) -> Union[Any, Dict[str, Any]]:
-        """
-        Retrieve a result for a record.
-
-        If no result ID specified, results for the entire record will
-        be returned.
-
-        :param str record_identifier: unique identifier of the record
-        :param str result_identifier: name of the result to be retrieved
-        :return any | Dict[str, any]: a single result or a mapping with all the
-            results reported for the record
-        """
-        record_identifier = self._strict_record_id(record_identifier)
-        if self[DB_ONLY_KEY]:
-            if result_identifier is not None:
-                existing = self._check_which_results_exist(
-                    results=[result_identifier], rid=record_identifier
-                )
-                if not existing:
-                    raise PipestatDatabaseError(
-                        f"Result '{result_identifier}' not found for record "
-                        f"'{record_identifier}'"
-                    )
-            with self.db_cursor as cur:
-                query = sql.SQL(
-                    f"SELECT {result_identifier or '*'} "
-                    f"FROM {self.namespace} WHERE {RECORD_ID}=%s"
-                )
-                cur.execute(query, (record_identifier,))
-                result = cur.fetchall()
-            if len(result) > 0:
-                if result_identifier is None:
-                    return {k: v for k, v in dict(result[0]).items() if v is not None}
-                return dict(result[0])[result_identifier]
-            raise PipestatDatabaseError(f"Record '{record_identifier}' not found")
-        else:
-            if record_identifier not in self.data[self.namespace]:
-                raise PipestatDatabaseError(f"Record '{record_identifier}' not found")
-            if result_identifier is None:
-                return self.data[self.namespace][record_identifier].to_dict()
-            if result_identifier not in self.data[self.namespace][record_identifier]:
-                raise PipestatDatabaseError(
-                    f"Result '{result_identifier}' not found for record "
-                    f"'{record_identifier}'"
-                )
-            return self.data[self.namespace][record_identifier][result_identifier]
-
     def remove(
-        self, record_identifier: str = None, result_identifier: str = None
+        self,
+        record_identifier: str = None,
+        result_identifier: str = None,
     ) -> bool:
         """
         Remove a result.
@@ -1050,221 +1409,96 @@ def remove(
              if the record should be removed.
         :return bool: whether the result has been removed
         """
-        record_identifier = self._strict_record_id(record_identifier)
+        r_id = self._strict_record_id(record_identifier)
         rm_record = True if result_identifier is None else False
-        if not self.check_record_exists(record_identifier):
-            _LOGGER.error(f"Record '{record_identifier}' not found")
-            return False
-        if result_identifier and not self.check_result_exists(
-            result_identifier, record_identifier
+        if not self.check_record_exists(
+            record_identifier=r_id, table_name=self.namespace
         ):
-            _LOGGER.error(
-                f"'{result_identifier}' has not been reported for "
-                f"'{record_identifier}'"
-            )
+            _LOGGER.error(f"Record '{r_id}' not found")
+            return False
+        if result_identifier and not self.check_result_exists(result_identifier, r_id):
+            _LOGGER.error(f"'{result_identifier}' has not been reported for '{r_id}'")
             return False
         if self.file:
             self.data.make_writable()
         if not self[DB_ONLY_KEY]:
             if rm_record:
-                _LOGGER.info(f"Removing '{record_identifier}' record")
-                del self[DATA_KEY][self.namespace][record_identifier]
+                _LOGGER.info(f"Removing '{r_id}' record")
+                del self[DATA_KEY][self.namespace][r_id]
             else:
-                val_backup = self[DATA_KEY][self.namespace][record_identifier][
-                    result_identifier
-                ]
-                del self[DATA_KEY][self.namespace][record_identifier][result_identifier]
+                val_backup = self[DATA_KEY][self.namespace][r_id][result_identifier]
+                del self[DATA_KEY][self.namespace][r_id][result_identifier]
                 _LOGGER.info(
                     f"Removed result '{result_identifier}' for record "
-                    f"'{record_identifier}' from '{self.namespace}' namespace"
+                    f"'{r_id}' from '{self.namespace}' namespace"
                 )
-                if not self[DATA_KEY][self.namespace][record_identifier]:
+                if not self[DATA_KEY][self.namespace][r_id]:
                     _LOGGER.info(
-                        f"Last result removed for '{record_identifier}'. "
-                        f"Removing the record"
+                        f"Last result removed for '{r_id}'. " f"Removing the record"
                     )
-                    del self[DATA_KEY][self.namespace][record_identifier]
+                    del self[DATA_KEY][self.namespace][r_id]
                     rm_record = True
         if self.file:
             self.data.write()
             self.data.make_readonly()
         if self.file is None:
-            if rm_record:
-                try:
-                    with self.db_cursor as cur:
-                        cur.execute(
-                            f"DELETE FROM {self.namespace} WHERE "
-                            f"{RECORD_ID}='{record_identifier}'"
-                        )
-                except Exception as e:
-                    _LOGGER.error(
-                        f"Could not remove the result from the "
-                        f"database. Exception: {e}"
-                    )
-                    self[DATA_KEY][self.namespace].setdefault(record_identifier, PXAM())
-                    raise
-                return True
             try:
-                with self.db_cursor as cur:
-                    cur.execute(
-                        f"UPDATE {self.namespace} SET {result_identifier}=null "
-                        f"WHERE {RECORD_ID}='{record_identifier}'"
-                    )
+                self._remove_db(
+                    record_identifier=r_id,
+                    result_identifier=None if rm_record else result_identifier,
+                )
             except Exception as e:
                 _LOGGER.error(
-                    f"Could not remove the result from the database. " f"Exception: {e}"
+                    f"Could not remove the result from the database. Exception: {e}"
                 )
-                if not self[DB_ONLY_KEY]:
-                    self[DATA_KEY][self.namespace][record_identifier][
-                        result_identifier
-                    ] = val_backup
+                if not self[DB_ONLY_KEY] and not rm_record:
+                    self[DATA_KEY][self.namespace][r_id][result_identifier] = val_backup
                 raise
         return True
 
-    def validate_schema(self) -> None:
-        """
-        Check schema for any possible issues
-
-        :raises SchemaError: if any schema format issue is detected
-        """
-
-        def _recursively_replace_custom_types(s: dict) -> Dict:
-            """
-            Replace the custom types in pipestat schema with canonical types
-
-            :param dict s: schema to replace types in
-            :return dict: schema with types replaced
-            """
-            for k, v in s.items():
-                assert SCHEMA_TYPE_KEY in v, SchemaError(
-                    f"Result '{k}' is missing '{SCHEMA_TYPE_KEY}' key"
-                )
-                if v[SCHEMA_TYPE_KEY] == "object" and SCHEMA_PROP_KEY in s[k]:
-                    _recursively_replace_custom_types(s[k][SCHEMA_PROP_KEY])
-                if v[SCHEMA_TYPE_KEY] in CANONICAL_TYPES.keys():
-                    s.setdefault(k, {})
-                    s[k].setdefault(SCHEMA_PROP_KEY, {})
-                    s[k][SCHEMA_PROP_KEY].update(
-                        CANONICAL_TYPES[v[SCHEMA_TYPE_KEY]][SCHEMA_PROP_KEY]
-                    )
-                    s[k].setdefault("required", [])
-                    s[k]["required"].extend(
-                        CANONICAL_TYPES[v[SCHEMA_TYPE_KEY]]["required"]
-                    )
-                    s[k][SCHEMA_TYPE_KEY] = CANONICAL_TYPES[v[SCHEMA_TYPE_KEY]][
-                        SCHEMA_TYPE_KEY
-                    ]
-            return s
-
-        schema = deepcopy(self.schema)
-        _LOGGER.debug(f"Validating input schema")
-        assert isinstance(schema, dict), SchemaError(
-            f"The schema has to be a {dict().__class__.__name__}"
-        )
-        for col_name in RESERVED_COLNAMES:
-            assert col_name not in schema.keys(), PipestatError(
-                f"'{col_name}' is an identifier reserved by pipestat"
-            )
-        self[RES_SCHEMAS_KEY] = {}
-        schema = _recursively_replace_custom_types(schema)
-        self[RES_SCHEMAS_KEY] = schema
-
-    def assert_results_defined(self, results: List[str]) -> None:
-        """
-        Assert provided list of results is defined in the schema
-
-        :param List[str] results: list of results to
-            check for existence in the schema
-        :raises SchemaError: if any of the results is not defined in the schema
+    def _remove_db(
+        self,
+        record_identifier: str = None,
+        result_identifier: str = None,
+        table_name: str = None,
+    ) -> bool:
         """
-        known_results = self.result_schemas.keys()
-        for r in results:
-            assert r in known_results, SchemaError(
-                f"'{r}' is not a known result. Results defined in the "
-                f"schema are: {list(known_results)}."
-            )
+        Remove a result.
 
-    def check_connection(self) -> bool:
-        """
-        Check whether a PostgreSQL connection has been established
+        If no result ID specified or last result is removed, the entire record
+        will be removed.
 
-        :return bool: whether the connection has been established
+        :param str record_identifier: unique identifier of the record
+        :param str result_identifier: name of the result to be removed or None
+             if the record should be removed.
+        :param str table_name: name of the table to report the result in
+        :return bool: whether the result has been removed
+        :raise PipestatDatabaseError: if either record or result specified are not found
         """
-        if self.file is not None:
-            raise PipestatDatabaseError(
-                f"The {self.__class__.__name__} object " f"is not backed by a database"
-            )
-        if DB_CONNECTION_KEY in self and isinstance(
-            self[DB_CONNECTION_KEY], psycopg2.extensions.connection
+        table_name = table_name or self.namespace
+        record_identifier = self._strict_record_id(record_identifier)
+        ORMClass = self.get_orm(table_name=table_name)
+        if self.check_record_exists(
+            record_identifier=record_identifier, table_name=table_name
         ):
-            return True
-        return False
-
-    def establish_postgres_connection(self, suppress: bool = False) -> bool:
-        """
-        Establish PostgreSQL connection using the config data
-
-        :param bool suppress: whether to suppress any connection errors
-        :return bool: whether the connection has been established successfully
-        """
-        if self.check_connection():
-            raise PipestatDatabaseError(
-                f"Connection is already established: "
-                f"{self[DB_CONNECTION_KEY].info.host}"
-            )
-        try:
-            self[DB_CONNECTION_KEY] = psycopg2.connect(
-                dbname=self[CONFIG_KEY][CFG_DATABASE_KEY][CFG_NAME_KEY],
-                user=self[CONFIG_KEY][CFG_DATABASE_KEY][CFG_USER_KEY],
-                password=self[CONFIG_KEY][CFG_DATABASE_KEY][CFG_PASSWORD_KEY],
-                host=self[CONFIG_KEY][CFG_DATABASE_KEY][CFG_HOST_KEY],
-                port=self[CONFIG_KEY][CFG_DATABASE_KEY][CFG_PORT_KEY],
-            )
-        except psycopg2.Error as e:
-            _LOGGER.error(
-                f"Could not connect to: "
-                f"{self[CONFIG_KEY][CFG_DATABASE_KEY][CFG_HOST_KEY]}"
-            )
-            _LOGGER.info(f"Caught error: {e}")
-            if suppress:
-                return False
-            raise
+            with self.session as s:
+                records = s.query(ORMClass).filter(
+                    getattr(ORMClass, RECORD_ID) == record_identifier
+                )
+                if result_identifier is None:
+                    # delete row
+                    records.delete()
+                else:
+                    # set the value to None
+                    if not self.check_result_exists(
+                        record_identifier=record_identifier,
+                        result_identifier=result_identifier,
+                    ):
+                        raise PipestatDatabaseError(
+                            f"Result '{result_identifier}' not found for record "
+                            f"'{record_identifier}'"
+                        )
+                    setattr(records.first(), result_identifier, None)
+                s.commit()
         else:
-            _LOGGER.debug(
-                f"Established connection with PostgreSQL: "
-                f"{self[CONFIG_KEY][CFG_DATABASE_KEY][CFG_HOST_KEY]}"
-            )
-            return True
-
-    def close_postgres_connection(self) -> None:
-        """
-        Close connection and remove client bound
-        """
-        if not self.check_connection():
-            raise PipestatDatabaseError(
-                f"The connection has not been established: "
-                f"{self[CONFIG_KEY][CFG_DATABASE_KEY][CFG_HOST_KEY]}"
-            )
-        self[DB_CONNECTION_KEY].close()
-        del self[DB_CONNECTION_KEY]
-        _LOGGER.debug(
-            f"Closed connection with PostgreSQL: "
-            f"{self[CONFIG_KEY][CFG_DATABASE_KEY][CFG_HOST_KEY]}"
-        )
-
-    def _strict_record_id(self, forced_value: str = None) -> str:
-        """
-        Get record identifier from the outer source or stored with this object
-
-        :param str forced_value: return this value
-        :return str: record identifier
-        """
-        if forced_value is not None:
-            return forced_value
-        if self.record_identifier is not None:
-            return self.record_identifier
-        raise PipestatError(
-            f"You must provide the record identifier you want to perform "
-            f"the action on. Either in the {self.__class__.__name__} "
-            f"constructor or as an argument to the method."
-        )
+            raise PipestatDatabaseError(f"Record '{record_identifier}' not found")
diff --git a/pipestat/schemas/pipestat_config_schema.yaml b/pipestat/schemas/pipestat_config_schema.yaml
index ee11bd51..03670227 100644
--- a/pipestat/schemas/pipestat_config_schema.yaml
+++ b/pipestat/schemas/pipestat_config_schema.yaml
@@ -1,6 +1,6 @@
 description: "Pipestat configuration file schema; docs: http://pipestat.databio.org/en/latest/config/"
 properties:
-  name: 
+  name:
     type: string
     pattern: "^\\S*$"
     description: "Namespace identifier with no whitespace"
@@ -17,6 +17,10 @@ properties:
   database:
     type: object
     properties:
+      dialect:
+        type: string
+        enum: ["sqlite", "mysql", "postgresql", "oracle", "mssql"]
+        description: "Dialect names include the identifying name of the SQLAlchemy dialect, a name such as sqlite, mysql, postgresql, oracle, or mssql"
       name:
         type: string
         description: "DB name"
diff --git a/pipestat/schemas/status_schema.yaml b/pipestat/schemas/status_schema.yaml
index 0a7cf280..492e496d 100644
--- a/pipestat/schemas/status_schema.yaml
+++ b/pipestat/schemas/status_schema.yaml
@@ -12,4 +12,4 @@ waiting:
   color: [240, 230, 140] # khaki
 partial:
   description: "the pipeline stopped before completion point"
-  color: [169, 169, 169] # darkgray
\ No newline at end of file
+  color: [169, 169, 169] # darkgray
diff --git a/pipestat/schemas/status_table_schema.yaml b/pipestat/schemas/status_table_schema.yaml
new file mode 100644
index 00000000..530dfc07
--- /dev/null
+++ b/pipestat/schemas/status_table_schema.yaml
@@ -0,0 +1,4 @@
+status:
+  # this is updated with an 'enum' based on the status_schema provided by the user
+  type: string
+  description: "status code, only statuses defined in the status_schema are defined"
diff --git a/requirements/requirements-all.txt b/requirements/requirements-all.txt
index e0d427df..ab2db6b7 100644
--- a/requirements/requirements-all.txt
+++ b/requirements/requirements-all.txt
@@ -3,5 +3,6 @@ jsonschema
 logmuse>=0.2.5
 oyaml
 psycopg2-binary
+sqlalchemy>=1.4.7
 ubiquerg>=0.6.1
-yacman>=0.8.0
+yacman>=0.8.1
diff --git a/requirements/requirements-doc.txt b/requirements/requirements-doc.txt
index 307edf2e..320b6050 100644
--- a/requirements/requirements-doc.txt
+++ b/requirements/requirements-doc.txt
@@ -1,5 +1,5 @@
-mkdocs>=1.0
+https://github.com/databio/mkdocs-databio/archive/master.zip
+https://github.com/pepkit/pipestat/archive/master.zip
 markdown-include
+mkdocs>=1.0
 pydoc-markdown
-https://github.com/pepkit/pipestat/archive/master.zip
-https://github.com/databio/mkdocs-databio/archive/master.zip
diff --git a/requirements/requirements-test.txt b/requirements/requirements-test.txt
index 61196936..a1303c85 100644
--- a/requirements/requirements-test.txt
+++ b/requirements/requirements-test.txt
@@ -1,3 +1,3 @@
+coveralls
 pytest>=4.6.9
 pytest-cov>=2.8.1
-coveralls
\ No newline at end of file
diff --git a/tests/data/config.yaml b/tests/data/config.yaml
index 1538ae9f..7385e630 100644
--- a/tests/data/config.yaml
+++ b/tests/data/config.yaml
@@ -2,9 +2,11 @@ namespace: test
 record_identifier: sample1
 schema_path: sample_output_schema.yaml #$HOME/Desktop/sample_output_schema.yaml
 database:
+  dialect: postgresql
+  driver: psycopg2
   name: pipestat-test
   user: postgres
   password: pipestat-password
-  host: localhost
+  host: 127.0.0.1
   port: 5432
 #results_file_path: results_file.yaml #$HOME/Desktop/results.yaml
diff --git a/tests/data/config_no_schema.yaml b/tests/data/config_no_schema.yaml
index a82d0c92..0248ec5a 100644
--- a/tests/data/config_no_schema.yaml
+++ b/tests/data/config_no_schema.yaml
@@ -2,6 +2,8 @@ namespace: test
 record_identifier: sample1
 #schema_path: sample_output_schema.yaml #$HOME/Desktop/sample_output_schema.yaml
 database:
+  dialect: postgresql
+  driver: psycopg2
   name: pipestat-test
   user: postgres
   password: pipestat-password
diff --git a/tests/data/custom_status_schema.yaml b/tests/data/custom_status_schema.yaml
index 460e410a..3630d0ea 100644
--- a/tests/data/custom_status_schema.yaml
+++ b/tests/data/custom_status_schema.yaml
@@ -6,4 +6,4 @@ completed_custom:
   color: [50, 205, 50] # limegreen
 failed_custom:
   description: "the pipeline has failed"
-  color: [220, 20, 60] # crimson
\ No newline at end of file
+  color: [220, 20, 60] # crimson
diff --git a/tests/data/sample_output_schema.yaml b/tests/data/sample_output_schema.yaml
index 392bb832..38341c95 100644
--- a/tests/data/sample_output_schema.yaml
+++ b/tests/data/sample_output_schema.yaml
@@ -21,4 +21,8 @@ output_file:
   description: "This a path to the output file"
 output_image:
   type: image
-  description: "This a path to the output image"
\ No newline at end of file
+  description: "This a path to the output image"
+md5sum:
+  type: string
+  description: "MD5SUM of an object"
+  highlight: true
diff --git a/tests/data/sample_output_schema_highlight.yaml b/tests/data/sample_output_schema_highlight.yaml
index e51fd0bd..32b63c02 100644
--- a/tests/data/sample_output_schema_highlight.yaml
+++ b/tests/data/sample_output_schema_highlight.yaml
@@ -38,4 +38,4 @@ commands:
 version:
   type: string
   highlight: true
-  description: "Pipeline version"
\ No newline at end of file
+  description: "Pipeline version"
diff --git a/tests/data/sample_output_schema_recursive.yaml b/tests/data/sample_output_schema_recursive.yaml
index f398275d..74a281c8 100644
--- a/tests/data/sample_output_schema_recursive.yaml
+++ b/tests/data/sample_output_schema_recursive.yaml
@@ -7,8 +7,10 @@ output_file_in_object:
   type: object
   properties:
     prop1:
+      description: "This is an example file"
       type: file
     prop2:
+      description: "This is an example image"
       type: image
   description: "Object output"
 output_file:
@@ -16,4 +18,4 @@ output_file:
   description: "This a path to the output file"
 output_image:
   type: image
-  description: "This a path to the output image"
\ No newline at end of file
+  description: "This a path to the output image"
diff --git a/tests/data/test_results_1.yaml b/tests/data/test_results_1.yaml
new file mode 100644
index 00000000..b43bdf32
--- /dev/null
+++ b/tests/data/test_results_1.yaml
@@ -0,0 +1,3 @@
+pipeline_name:
+  sample_name:
+    percentage_of_things: 12
diff --git a/tests/test_db_only_mode.py b/tests/test_db_only_mode.py
new file mode 100644
index 00000000..31a6e653
--- /dev/null
+++ b/tests/test_db_only_mode.py
@@ -0,0 +1,124 @@
+import pytest
+
+from pipestat import PipestatManager
+from pipestat.const import *
+
+
+class TestDatabaseOnly:
+    @pytest.mark.parametrize(
+        "val",
+        [
+            {"name_of_something": "test_name"},
+            {"number_of_things": 1},
+            {"percentage_of_things": 10.1},
+        ],
+    )
+    def test_report(
+        self,
+        val,
+        config_file_path,
+        schema_file_path,
+    ):
+        REC_ID = "constant_record_id"
+        psm = PipestatManager(
+            schema_path=schema_file_path,
+            namespace="test",
+            record_identifier=REC_ID,
+            database_only=True,
+            config=config_file_path,
+        )
+        psm.report(values=val)
+        assert len(psm.data) == 0
+        val_name = list(val.keys())[0]
+        assert psm.select(filter_conditions=[(val_name, "eq", str(val[val_name]))])
+
+    @pytest.mark.parametrize(["rec_id", "res_id"], [("sample2", "number_of_things")])
+    def test_select_invalid_filter_column(
+        self,
+        rec_id,
+        res_id,
+        config_file_path,
+        schema_file_path,
+    ):
+        args = dict(
+            schema_path=schema_file_path, namespace="test", config=config_file_path
+        )
+        psm = PipestatManager(**args)
+        with pytest.raises(ValueError):
+            psm.select(
+                filter_conditions=[("bogus_column", "eq", rec_id)],
+                columns=[res_id],
+            )
+
+    @pytest.mark.parametrize("res_id", ["number_of_things"])
+    @pytest.mark.parametrize("filter", [("column", "eq", 1), "a", [1, 2, 3]])
+    def test_select_invalid_filter_structure(
+        self,
+        res_id,
+        config_file_path,
+        schema_file_path,
+        filter,
+    ):
+        args = dict(
+            schema_path=schema_file_path, namespace="test", config=config_file_path
+        )
+        psm = PipestatManager(**args)
+        with pytest.raises((ValueError, TypeError)):
+            psm.select(
+                filter_conditions=[filter],
+                columns=[res_id],
+            )
+
+    @pytest.mark.parametrize(["rec_id", "res_id"], [("sample2", "number_of_things")])
+    @pytest.mark.parametrize("limit", [1, 2, 3, 15555])
+    def test_select_limit(
+        self,
+        rec_id,
+        res_id,
+        config_file_path,
+        schema_file_path,
+        limit,
+    ):
+        args = dict(
+            schema_path=schema_file_path, namespace="test", config=config_file_path
+        )
+        psm = PipestatManager(**args)
+        result = psm.select(
+            filter_conditions=[(RECORD_ID, "eq", rec_id)],
+            columns=[res_id],
+            limit=limit,
+        )
+        assert len(result) <= limit
+
+    @pytest.mark.parametrize("offset", [0, 1, 2, 3, 15555])
+    def test_select_offset(
+        self,
+        config_file_path,
+        schema_file_path,
+        offset,
+    ):
+        args = dict(
+            schema_path=schema_file_path, namespace="test", config=config_file_path
+        )
+        psm = PipestatManager(**args)
+        result = psm.select(offset=offset)
+        print(result)
+        assert len(result) == max((psm.record_count - offset), 0)
+
+    @pytest.mark.parametrize(
+        ["offset", "limit"], [(0, 0), (0, 1), (0, 2), (0, 11111), (1, 1), (1, 0)]
+    )
+    def test_select_pagination(
+        self,
+        config_file_path,
+        schema_file_path,
+        offset,
+        limit,
+    ):
+        args = dict(
+            schema_path=schema_file_path, namespace="test", config=config_file_path
+        )
+        psm = PipestatManager(**args)
+        result = psm.select(offset=offset, limit=limit)
+        print(result)
+        assert len(result) == min(max((psm.record_count - offset), 0), limit)
diff --git a/tests/test_init.py b/tests/test_init.py
new file mode 100644
index 00000000..e614c52e
--- /dev/null
+++ b/tests/test_init.py
@@ -0,0 +1,146 @@
+from tempfile import mkdtemp
+
+import pytest
+from yaml import dump
+
+from pipestat import PipestatManager
+from pipestat.const import *
+from pipestat.exceptions import *
+
+
+class TestConnection:
+    def test_connection_checker(self, config_file_path, schema_file_path):
+        pm = PipestatManager(
+            config=config_file_path,
+            database_only=True,
+            schema_path=schema_file_path,
+            namespace="test",
+        )
+        assert pm.is_db_connected()
+
+    def test_connection_overwrite_error(self, config_file_path, schema_file_path):
+        pm = PipestatManager(
+            config=config_file_path,
+            database_only=True,
+            schema_path=schema_file_path,
+            namespace="test",
+        )
+        with pytest.raises(PipestatDatabaseError):
+            pm.establish_db_connection()
+
+
+class TestPipestatManagerInstantiation:
+    def test_obj_creation_file(self, schema_file_path, results_file_path):
+        """Object constructor works with file as backend"""
+        assert isinstance(
+            PipestatManager(
+                namespace="test",
+                results_file_path=results_file_path,
+                schema_path=schema_file_path,
+            ),
+            PipestatManager,
+        )
+
+    def test_obj_creation_db(self, config_file_path):
+        """Object constructor works with database as backend"""
+        assert isinstance(PipestatManager(config=config_file_path), PipestatManager)
+
+    @pytest.mark.xfail(reason="schema is no longer required to init the object")
+    def test_schema_req(self, results_file_path):
+        """
+        Object constructor raises exception if schema is not provided
+        """
+        with pytest.raises(PipestatError):
+            PipestatManager(namespace="test", results_file_path=results_file_path)
+
+    def test_schema_recursive_custom_type_conversion(
+        self, recursive_schema_file_path, results_file_path
+    ):
+        psm = PipestatManager(
+            namespace="test",
+            results_file_path=results_file_path,
+            schema_path=recursive_schema_file_path,
+        )
+        assert (
+            "path"
+            in psm.result_schemas["output_file_in_object"]["properties"]["prop1"][
+                "properties"
+            ]
+        )
+        assert (
+            "thumbnail_path"
+            in psm.result_schemas["output_file_in_object"]["properties"]["prop2"][
+                "properties"
+            ]
+        )
+
+    def test_missing_cfg_data(self, schema_file_path):
+        """Object constructor raises exception if cfg is missing data"""
+        tmp_pth = os.path.join(mkdtemp(), "res.yml")
+        with open(tmp_pth, "w") as file:
+            dump({"database": {"host": "localhost"}}, file)
+        with pytest.raises(MissingConfigDataError):
+            PipestatManager(
+                namespace="test", config=tmp_pth, schema_path=schema_file_path
+            )
+
+    def test_unknown_backend(self, schema_file_path):
+        """Either db config or results file path needs to be provided"""
+        with pytest.raises(MissingConfigDataError):
+            PipestatManager(namespace="test", schema_path=schema_file_path)
+
+    def test_create_results_file(self, schema_file_path):
+        """Results file is created if a nonexistent path provided"""
+        tmp_res_file = os.path.join(mkdtemp(), "res.yml")
+        print(f"Temporary results file: {tmp_res_file}")
+        assert not os.path.exists(tmp_res_file)
+        PipestatManager(
+            namespace="test",
+            results_file_path=tmp_res_file,
+            schema_path=schema_file_path,
+        )
+        assert os.path.exists(tmp_res_file)
+
+    def test_use_other_namespace_file(self, schema_file_path):
+        """Results file can be used with just one namespace"""
+        tmp_res_file = os.path.join(mkdtemp(), "res.yml")
+        print(f"Temporary results file: {tmp_res_file}")
+        assert not os.path.exists(tmp_res_file)
+        PipestatManager(
+            namespace="test",
+            results_file_path=tmp_res_file,
+            schema_path=schema_file_path,
+        )
+        assert os.path.exists(tmp_res_file)
+        with pytest.raises(PipestatDatabaseError):
+            PipestatManager(
+                namespace="new_test",
+                results_file_path=tmp_res_file,
+                schema_path=schema_file_path,
+            )
+
+    @pytest.mark.parametrize("pth", [["/$HOME/path.yaml"], 1])
+    def test_wrong_class_results_file(self, schema_file_path, pth):
+        """Input string that is not a file path raises an informative error"""
+        with pytest.raises((TypeError, AssertionError)):
+            PipestatManager(
+                namespace="test", results_file_path=pth, schema_path=schema_file_path
+            )
+
+    def test_results_file_contents_loaded(self, results_file_path, schema_file_path):
+        """Contents of the results file are present after loading"""
+        psm = PipestatManager(
+            namespace="test",
+            results_file_path=results_file_path,
+            schema_path=schema_file_path,
+        )
+        assert "test" in psm.data
+
+    def test_str_representation(self, results_file_path, schema_file_path):
+        """Test string representation identifies number of records"""
+        psm = PipestatManager(
+            namespace="test",
+            results_file_path=results_file_path,
+            schema_path=schema_file_path,
+        )
+        assert f"Records count: {len(psm.data[psm.namespace])}" in str(psm)
diff --git a/tests/test_pipestat.py b/tests/test_pipestat.py
index b8eef8df..f67df065 100644
--- a/tests/test_pipestat.py
+++ b/tests/test_pipestat.py
@@ -1,12 +1,7 @@
-import os
-from collections import Mapping
-from tempfile import mkdtemp
+from collections.abc import Mapping
 
 import pytest
-from _pytest.monkeypatch import monkeypatch
 from jsonschema import ValidationError
-from psycopg2 import Error as psycopg2Error
-from yaml import dump
 
 from pipestat import PipestatManager
 from pipestat.const import *
@@ -31,185 +26,6 @@ def is_in_file(fs, s, reverse=False):
                 assert s in fh.read()
 
 
-class TestConnection:
-    def test_connection_checker(self, config_file_path, schema_file_path):
-        pm = PipestatManager(
-            config=config_file_path,
-            database_only=True,
-            schema_path=schema_file_path,
-            namespace="test",
-        )
-        assert not pm.check_connection()
-        pm.establish_postgres_connection()
-        assert pm.check_connection()
-        pm.close_postgres_connection()
-
-    def test_connection_overwrite_error(self, config_file_path, schema_file_path):
-        pm = PipestatManager(
-            config=config_file_path,
-            database_only=True,
-            schema_path=schema_file_path,
-            namespace="test",
-        )
-        pm.establish_postgres_connection()
-        with pytest.raises(PipestatDatabaseError):
-            pm.establish_postgres_connection()
-        pm.close_postgres_connection()
-
-    @pytest.mark.parametrize("suppress", [True, False])
-    def test_connection_error(self, config_file_path, schema_file_path, suppress):
-        pm = PipestatManager(
-            config=config_file_path,
-            database_only=True,
-            schema_path=schema_file_path,
-            namespace="test",
-        )
-        pm[CONFIG_KEY][CFG_DATABASE_KEY][CFG_HOST_KEY] = "bogus_host"
-        if suppress:
-            assert not pm.establish_postgres_connection(suppress=suppress)
-        else:
-            with pytest.raises(psycopg2Error):
-                pm.establish_postgres_connection(suppress=suppress)
-
-    def test_connection_closing(self, config_file_path, schema_file_path):
-        pm = PipestatManager(
-            config=config_file_path,
-            database_only=True,
-            schema_path=schema_file_path,
-            namespace="test",
-        )
-        pm.establish_postgres_connection()
-        pm.close_postgres_connection()
-        assert not pm.check_connection()
-
-    def test_connection_closing_closed(self, config_file_path, schema_file_path):
-        pm = PipestatManager(
-            config=config_file_path,
-            database_only=True,
-            schema_path=schema_file_path,
-            namespace="test",
-        )
-        with pytest.raises(PipestatDatabaseError):
-            pm.close_postgres_connection()
-
-
-class TestPipestatManagerInstantiation:
-    def test_obj_creation_file(self, schema_file_path, results_file_path):
-        """ Object constructor works with file as backend"""
-        assert isinstance(
-            PipestatManager(
-                namespace="test",
-                results_file_path=results_file_path,
-                schema_path=schema_file_path,
-            ),
-            PipestatManager,
-        )
-
-    def test_obj_creation_db(self, config_file_path):
-        """ Object constructor works with database as backend"""
-        assert isinstance(PipestatManager(config=config_file_path), PipestatManager)
-
-    @pytest.mark.xfail(reason="schema is no longer required to init the object")
-    def test_schema_req(self, results_file_path):
-        """
-        Object constructor raises exception if schema is not provided
-        """
-        with pytest.raises(PipestatError):
-            PipestatManager(namespace="test", results_file_path=results_file_path)
-
-    def test_schema_recursive_custom_type_conversion(
-        self, recursive_schema_file_path, results_file_path
-    ):
-        psm = PipestatManager(
-            namespace="test",
-            results_file_path=results_file_path,
-            schema_path=recursive_schema_file_path,
-        )
-        assert (
-            "path"
-            in psm.result_schemas["output_file_in_object"]["properties"]["prop1"][
-                "properties"
-            ]
-        )
-        assert (
-            "thumbnail_path"
-            in psm.result_schemas["output_file_in_object"]["properties"]["prop2"][
-                "properties"
-            ]
-        )
-
-    def test_missing_cfg_data(self, schema_file_path):
-        """ Object constructor raises exception if cfg is missing data """
-        tmp_pth = os.path.join(mkdtemp(), "res.yml")
-        with open(tmp_pth, "w") as file:
-            dump({"database": {"host": "localhost"}}, file)
-        with pytest.raises(MissingConfigDataError):
-            PipestatManager(
-                namespace="test", config=tmp_pth, schema_path=schema_file_path
-            )
-
-    def test_unknown_backend(self, schema_file_path):
-        """ Either db config or results file path needs to be provided """
-        with pytest.raises(MissingConfigDataError):
-            PipestatManager(namespace="test", schema_path=schema_file_path)
-
-    def test_create_results_file(self, schema_file_path):
-        """ Results file is created if a nonexistent path provided """
-        tmp_res_file = os.path.join(mkdtemp(), "res.yml")
-        print(f"Temporary results file: {tmp_res_file}")
-        assert not os.path.exists(tmp_res_file)
-        PipestatManager(
-            namespace="test",
-            results_file_path=tmp_res_file,
-            schema_path=schema_file_path,
-        )
-        assert os.path.exists(tmp_res_file)
-
-    def test_use_other_namespace_file(self, schema_file_path):
-        """ Results file can be used with just one namespace """
-        tmp_res_file = os.path.join(mkdtemp(), "res.yml")
-        print(f"Temporary results file: {tmp_res_file}")
-        assert not os.path.exists(tmp_res_file)
-        PipestatManager(
-            namespace="test",
-            results_file_path=tmp_res_file,
-            schema_path=schema_file_path,
-        )
-        assert os.path.exists(tmp_res_file)
-        with pytest.raises(PipestatDatabaseError):
-            PipestatManager(
-                namespace="new_test",
-                results_file_path=tmp_res_file,
-                schema_path=schema_file_path,
-            )
-
-    @pytest.mark.parametrize("pth", [["/$HOME/path.yaml"], 1])
-    def test_wrong_class_results_file(self, schema_file_path, pth):
-        """ Input string that is not a file path raises an informative error """
-        with pytest.raises((TypeError, AssertionError)):
-            PipestatManager(
-                namespace="test", results_file_path=pth, schema_path=schema_file_path
-            )
-
-    def test_results_file_contents_loaded(self, results_file_path, schema_file_path):
-        """ Contents of the results file are present after loading """
-        psm = PipestatManager(
-            namespace="test",
-            results_file_path=results_file_path,
-            schema_path=schema_file_path,
-        )
-        assert "test" in psm.data
-
-    def test_str_representation(self, results_file_path, schema_file_path):
-        """ Test string representation identifies number of records """
-        psm = PipestatManager(
-            namespace="test",
-            results_file_path=results_file_path,
-            schema_path=schema_file_path,
-        )
-        assert f"Records count: {len(psm.data[psm.namespace])}" in str(psm)
-
-
 class TestReporting:
     @pytest.mark.parametrize(
         ["rec_id", "val"],
@@ -232,7 +48,7 @@ def test_report_basic(
         results_file_path,
         backend,
     ):
-        args = dict(schema_path=schema_file_path, namespace="test")
+        args = dict(schema_path=schema_file_path, namespace="test", database_only=False)
         backend_data = (
             {"config": config_file_path}
             if backend == "db"
@@ -276,11 +92,7 @@ def test_report_requires_schema(
             else {"results_file_path": results_file_path}
         )
         args.update(backend_data)
-        if backend == "db":
-            with pytest.raises(SchemaNotFoundError):
-                psm = PipestatManager(**args)
-        else:
-            psm = PipestatManager(**args)
+        psm = PipestatManager(**args)
         if backend == "file":
             with pytest.raises(SchemaNotFoundError):
                 psm.report(record_identifier=rec_id, values=val)
@@ -299,7 +111,7 @@ def test_report_overwrite(
         results_file_path,
         backend,
     ):
-        args = dict(schema_path=schema_file_path, namespace="test")
+        args = dict(schema_path=schema_file_path, namespace="test", database_only=False)
         backend_data = (
             {"config": config_file_path}
             if backend == "db"
@@ -447,7 +259,7 @@ def test_remove_basic(
         schema_file_path,
         backend,
     ):
-        args = dict(schema_path=schema_file_path, namespace="test")
+        args = dict(schema_path=schema_file_path, namespace="test", database_only=False)
         backend_data = (
             {"config": config_file_path}
             if backend == "db"
@@ -463,7 +275,7 @@ def test_remove_basic(
     def test_remove_record(
         self, rec_id, schema_file_path, config_file_path, results_file_path, backend
     ):
-        args = dict(schema_path=schema_file_path, namespace="test")
+        args = dict(schema_path=schema_file_path, namespace="test", database_only=False)
         backend_data = (
             {"config": config_file_path}
             if backend == "db"
@@ -523,7 +335,7 @@ def test_last_result_removal_removes_record(
         results_file_path,
         backend,
     ):
-        args = dict(schema_path=schema_file_path, namespace="test")
+        args = dict(schema_path=schema_file_path, namespace="test", database_only=False)
         backend_data = (
             {"config": config_file_path}
             if backend == "db"
@@ -550,7 +362,10 @@ def test_report(
     ):
         REC_ID = "constant_record_id"
         args = dict(
-            schema_path=schema_file_path, namespace="test", record_identifier=REC_ID
+            schema_path=schema_file_path,
+            namespace="test",
+            record_identifier=REC_ID,
+            database_only=False,
         )
         backend_data = (
             {"config": config_file_path}
@@ -617,91 +432,6 @@ def test_remove(
         assert psm.remove(result_identifier=list(val.keys())[0])
 
 
-class TestDatabaseOnly:
-    @pytest.mark.parametrize(
-        "val",
-        [
-            {"name_of_something": "test_name"},
-            {"number_of_things": 1},
-            {"percentage_of_things": 10.1},
-        ],
-    )
-    def test_report(self, val, config_file_path, schema_file_path, results_file_path):
-        REC_ID = "constant_record_id"
-        psm = PipestatManager(
-            schema_path=schema_file_path,
-            namespace="test",
-            record_identifier=REC_ID,
-            database_only=True,
-            config=config_file_path,
-        )
-        psm.report(values=val)
-        assert len(psm.data) == 0
-        val_name = list(val.keys())[0]
-        assert psm.select(
-            condition=val_name + "=%s", condition_val=[str(val[val_name])]
-        )
-
-    @pytest.mark.parametrize(["rec_id", "res_id"], [("sample2", "number_of_things")])
-    @pytest.mark.parametrize("backend", ["db"])
-    @pytest.mark.parametrize("limit", [1, 2, 3, 15555])
-    def test_select_limit(
-        self,
-        rec_id,
-        res_id,
-        config_file_path,
-        results_file_path,
-        schema_file_path,
-        backend,
-        limit,
-    ):
-        args = dict(
-            schema_path=schema_file_path, namespace="test", config=config_file_path
-        )
-        psm = PipestatManager(**args)
-        result = psm.select(
-            condition=f"{RECORD_ID}=%s",
-            condition_val=[rec_id],
-            columns=[res_id],
-            limit=limit,
-        )
-        assert len(result) <= limit
-
-    @pytest.mark.parametrize("backend", ["db"])
-    @pytest.mark.parametrize("offset", [0, 1, 2, 3, 15555])
-    def test_select_offset(
-        self, config_file_path, results_file_path, schema_file_path, backend, offset
-    ):
-        args = dict(
-            schema_path=schema_file_path, namespace="test", config=config_file_path
-        )
-        psm = PipestatManager(**args)
-        result = psm.select(offset=offset)
-        print(result)
-        assert len(result) == max((psm.record_count - offset), 0)
-
-    @pytest.mark.parametrize("backend", ["db"])
-    @pytest.mark.parametrize(
-        ["offset", "limit"], [(0, 0), (0, 1), (0, 2), (0, 11111), (1, 1), (1, 0)]
-    )
-    def test_select_pagination(
-        self,
-        config_file_path,
-        results_file_path,
-        schema_file_path,
-        backend,
-        offset,
-        limit,
-    ):
-        args = dict(
-            schema_path=schema_file_path, namespace="test", config=config_file_path
-        )
-        psm = PipestatManager(**args)
-        result = psm.select(offset=offset, limit=limit)
-        print(result)
-        assert len(result) == min(max((psm.record_count - offset), 0), limit)
-
-
 class TestHighlighting:
     def test_highlighting_works(self, highlight_schema_file_path, results_file_path):
         """the highlighted results are sourced from the schema and only ones
@@ -718,64 +448,6 @@ def test_highlighting_works(self, highlight_schema_file_path, results_file_path)
         assert psm.highlighted_results == schema_highlighted_results
 
 
-class TestStatus:
-    def test_status_file_defult_location(self, schema_file_path, results_file_path):
-        """status file location is set to the results file dir
-        if not specified"""
-        psm = PipestatManager(
-            namespace="test",
-            results_file_path=results_file_path,
-            schema_path=schema_file_path,
-        )
-        assert psm[STATUS_FILE_DIR] == os.path.dirname(psm.file)
-
-    @pytest.mark.parametrize("backend", ["file", "db"])
-    @pytest.mark.parametrize("status_id", ["running", "failed", "completed"])
-    def test_status_not_configured(
-        self, schema_file_path, config_file_path, results_file_path, backend, status_id
-    ):
-        """ status management works even in case it has not been configured"""
-        args = dict(schema_path=schema_file_path, namespace="test")
-        backend_data = (
-            {"config": config_file_path}
-            if backend == "db"
-            else {"results_file_path": results_file_path}
-        )
-        args.update(backend_data)
-        psm = PipestatManager(**args)
-        psm.set_status(record_identifier="sample1", status_identifier=status_id)
-        assert psm.get_status(record_identifier="sample1") == status_id
-
-    @pytest.mark.parametrize("backend", ["file", "db"])
-    @pytest.mark.parametrize(
-        "status_id", ["running_custom", "failed_custom", "completed_custom"]
-    )
-    def test_custom_status_schema(
-        self,
-        schema_file_path,
-        config_file_path,
-        results_file_path,
-        backend,
-        status_id,
-        custom_status_schema,
-    ):
-        """ status management works even in case it has not been configured"""
-        args = dict(
-            schema_path=schema_file_path,
-            namespace="test",
-            status_schema_path=custom_status_schema,
-        )
-        backend_data = (
-            {"config": config_file_path}
-            if backend == "db"
-            else {"results_file_path": results_file_path}
-        )
-        args.update(backend_data)
-        psm = PipestatManager(**args)
-        psm.set_status(record_identifier="sample1", status_identifier=status_id)
-        assert psm.get_status(record_identifier="sample1") == status_id
-
-
 class TestEnvVars:
     def test_no_config(self, monkeypatch, results_file_path, schema_file_path):
         """
diff --git a/tests/test_status.py b/tests/test_status.py
new file mode 100644
index 00000000..58fd3f86
--- /dev/null
+++ b/tests/test_status.py
@@ -0,0 +1,62 @@
+import pytest
+
+from pipestat import PipestatManager
+from pipestat.const import *
+
+
+class TestStatus:
+    def test_status_file_defult_location(self, schema_file_path, results_file_path):
+        """status file location is set to the results file dir
+        if not specified"""
+        psm = PipestatManager(
+            namespace="test",
+            results_file_path=results_file_path,
+            schema_path=schema_file_path,
+        )
+        assert psm[STATUS_FILE_DIR] == os.path.dirname(psm.file)
+
+    @pytest.mark.parametrize("backend", ["file", "db"])
+    @pytest.mark.parametrize("status_id", ["running", "failed", "completed"])
+    def test_status_not_configured(
+        self, schema_file_path, config_file_path, results_file_path, backend, status_id
+    ):
+        """status management works even in case it has not been configured"""
+        args = dict(schema_path=schema_file_path, namespace="test")
+        backend_data = (
+            {"config": config_file_path}
+            if backend == "db"
+            else {"results_file_path": results_file_path}
+        )
+        args.update(backend_data)
+        psm = PipestatManager(**args)
+        psm.set_status(record_identifier="sample1", status_identifier=status_id)
+        assert psm.get_status(record_identifier="sample1") == status_id
+
+    @pytest.mark.parametrize("backend", ["file", "db"])
+    @pytest.mark.parametrize(
+        "status_id", ["running_custom", "failed_custom", "completed_custom"]
+    )
+    def test_custom_status_schema(
+        self,
+        schema_file_path,
+        config_file_path,
+        results_file_path,
+        backend,
+        status_id,
+        custom_status_schema,
+    ):
+        """status management works even in case it has not been configured"""
+        args = dict(
+            schema_path=schema_file_path,
+            namespace="test",
+            status_schema_path=custom_status_schema,
+        )
+        backend_data = (
+            {"config": config_file_path}
+            if backend == "db"
+            else {"results_file_path": results_file_path}
+        )
+        args.update(backend_data)
+        psm = PipestatManager(**args)
+        psm.set_status(record_identifier="sample1", status_identifier=status_id)
+        assert psm.get_status(record_identifier="sample1") == status_id
diff --git a/update_api_docs.sh b/update_api_docs.sh
index 0eec075d..ef1083f4 100755
--- a/update_api_docs.sh
+++ b/update_api_docs.sh
@@ -1,2 +1,2 @@
 #!/bin/bash
-lucidoc pipestat -P rst > docs/api_docs.md
\ No newline at end of file
+lucidoc pipestat -P rst > docs/api_docs.md
diff --git a/update_usage_docs.sh b/update_usage_docs.sh
new file mode 100755
index 00000000..10aba076
--- /dev/null
+++ b/update_usage_docs.sh
@@ -0,0 +1,25 @@
+#!/bin/bash
+
+# This little bash script just updates the docs/usage.md file with
+# latest usage, for the installed version.
+# Run this when updating version to update the usage docs.
+cp docs/usage.template usage.template
+
+for cmd in "--help" "report --help" "inspect --help" "remove --help" "retrieve --help" "status --help" "status get --help" "status set --help"; do
+	echo $cmd
+	echo -e "## \`pipestat $cmd\`" > USAGE_header.temp
+	pipestat $cmd --help > USAGE.temp 2>&1
+	# sed -i 's/^/\t/' USAGE.temp
+	sed -i.bak '1s;^;\`\`\`console\
+;' USAGE.temp
+#	sed -i '1s/^/\n\`\`\`console\n/' USAGE.temp
+	echo -e "\`\`\`\n" >> USAGE.temp
+	#sed -i -e "/\`looper $cmd\`/r USAGE.temp" -e '$G' usage.template  # for -in place inserts
+	cat USAGE_header.temp USAGE.temp >> usage.template # to append to the end
+done
+rm USAGE.temp
+rm USAGE_header.temp
+rm USAGE.temp.bak
+mv usage.template  docs/usage.md
+cat docs/usage.md
+#rm USAGE.temp