Skip to content

docs: Update Database Library page with proper database modules #89

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
manykarim merged 3 commits into from
May 28, 2025
Merged

docs: Update Database Library page with proper database modules #89

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
0a23df3
docs: Update Database Library page with proper database modules
manykarim May 28, 2025
50f2fb6
docs: Add link to keyword documentation
manykarim May 28, 2025
2c223f4
Merge branch 'main' into docs/update_databaselibrary_page
manykarim May 28, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
225 changes: 67 additions & 158 deletions website/docs/different_libraries/database.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,14 +3,14 @@ sidebar_label: Database Library
title: Database Library
---

**Database Library** is a [Robot Framework](https://robotframework.org/) library that provides keywords for interacting with databases.
[**Database Library**](https://github.com/MarketSquare/Robotframework-Database-Library) is a [Robot Framework](https://robotframework.org/) library that provides keywords for interacting with databases.
It offers keywords to e.g.
- connect to a database
- execute SQL queries
- fetch results from the database
- assert table contents and result sets

For specifics, please refer to the library's [Keyword documentation](https://marketsquare.github.io/Robotframework-Database-Library/#library-documentation-top).
For specifics, please refer to the library's [Keyword documentation](https://marketsquare.github.io/Robotframework-Database-Library/).

## Installation

Expand All @@ -20,171 +20,80 @@ For specifics, please refer to the library's [Keyword documentation](https://mar
pip install robotframework-databaselibrary
```

To connect to a database, you also need to install a Python Module adhearing to the [Python Database API Specification v2.0](https://www.python.org/dev/peps/pep-0249/).
You can find a list of supported database modules [here](https://wiki.python.org/moin/DatabaseInterfaces).

Examples are:
- [psycopg2](https://pypi.org/project/psycopg2/) for PostgreSQL
- [cx_Oracle](https://pypi.org/project/cx-Oracle/) for Oracle
- [pymysql](https://pypi.org/project/PyMySQL/) for MySQL
- [pyodbc](https://pypi.org/project/pyodbc/) for Microsoft SQL Server

## Examples

Check out the [tests](https://github.com/MarketSquare/Robotframework-Database-Library/tree/master/test) folder in the repository for examples.

Example for a PostgreSQL database:
### Basic Usage Example

```robotframework
*** Settings ***
Suite Setup Connect To Database psycopg2 ${DBName} ${DBUser} ${DBPass} ${DBHost} ${DBPort}
Suite Teardown Disconnect From Database
Library DatabaseLibrary
Library OperatingSystem
Library Collections

*** Variables ***
${DBHost} localhost
${DBName} travis_ci_test
${DBPass} ""
${DBPort} 5432
${DBUser} postgres
Library DatabaseLibrary
Test Setup Connect To My Oracle DB

*** Keywords ***
Connect To My Oracle DB
Connect To Database
... oracledb
... db_name=db
... db_user=my_user
... db_password=my_pass
... db_host=127.0.0.1
... db_port=1521

*** Test Cases ***
Create person table
${output} = Execute SQL String CREATE TABLE person (id integer unique,first_name varchar,last_name varchar);
Log ${output}
Should Be Equal As Strings ${output} None

Execute SQL Script - Insert Data person table
Comment ${output} = Execute SQL Script ./${DBName}_insertData.sql
${output} = Execute SQL Script ./my_db_test_insertData.sql
Log ${output}
Should Be Equal As Strings ${output} None

Execute SQL String - Create Table
${output} = Execute SQL String create table foobar (id integer primary key, firstname varchar unique)
Log ${output}
Should Be Equal As Strings ${output} None

Check If Exists In DB - Franz Allan
Check If Exists In Database SELECT id FROM person WHERE first_name = 'Franz Allan';

Check If Not Exists In DB - Joe
Check If Not Exists In Database SELECT id FROM person WHERE first_name = 'Joe';

Table Must Exist - person
Table Must Exist person

Verify Row Count is 0
Row Count is 0 SELECT * FROM person WHERE first_name = 'NotHere';

Verify Row Count is Equal to X
Row Count is Equal to X SELECT id FROM person; 2

Verify Row Count is Less Than X
Row Count is Less Than X SELECT id FROM person; 3

Verify Row Count is Greater Than X
Row Count is Greater Than X SELECT * FROM person; 1

Retrieve Row Count
${output} = Row Count SELECT id FROM person;
Log ${output}
Should Be Equal As Strings ${output} 2

Retrieve records from person table
${output} = Execute SQL String SELECT * FROM person;
Log ${output}
Should Be Equal As Strings ${output} None

Verify person Description
[Tags] db smoke
Comment Query db for table column descriptions
@{queryResults} = Description SELECT * FROM person LIMIT 1;
Log Many @{queryResults}
${output} = Set Variable ${queryResults[0]}
Should Be Equal As Strings ${output} Column(name='id', type_code=23, display_size=None, internal_size=4, precision=None, scale=None, null_ok=None)
${output} = Set Variable ${queryResults[1]}
Should Be Equal As Strings ${output} Column(name='first_name', type_code=1043, display_size=None, internal_size=-1, precision=None, scale=None, null_ok=None)
${output} = Set Variable ${queryResults[2]}
Should Be Equal As Strings ${output} Column(name='last_name', type_code=1043, display_size=None, internal_size=-1, precision=None, scale=None, null_ok=None)
${NumColumns} = Get Length ${queryResults}
Should Be Equal As Integers ${NumColumns} 3

Verify foobar Description
[Tags] db smoke
Comment Query db for table column descriptions
@{queryResults} = Description SELECT * FROM foobar LIMIT 1;
Log Many @{queryResults}
${output} = Set Variable ${queryResults[0]}
Should Be Equal As Strings ${output} Column(name='id', type_code=23, display_size=None, internal_size=4, precision=None, scale=None, null_ok=None)
${output} = Set Variable ${queryResults[1]}
Should Be Equal As Strings ${output} Column(name='firstname', type_code=1043, display_size=None, internal_size=-1, precision=None, scale=None, null_ok=None)
${NumColumns} = Get Length ${queryResults}
Should Be Equal As Integers ${NumColumns} 2

Verify Query - Row Count person table
${output} = Query SELECT COUNT(*) FROM person;
Log ${output}
${val}= Get from list ${output} 0
${val}= Convert to list ${val}
${val}= Get from list ${val} 0
Should be equal as Integers ${val} 2

Verify Query - Row Count foobar table
${output} = Query SELECT COUNT(*) FROM foobar;
Log ${output}
${val}= Get from list ${output} 0
${val}= Convert to list ${val}
${val}= Get from list ${val} 0
Should be equal as Integers ${val} 0

Verify Query - Get results as a list of dictionaries
[Tags] db smoke
${output} = Query SELECT * FROM person; \ True
Log ${output}
Should Be Equal As Strings &{output[0]}[first_name] Franz Allan
Should Be Equal As Strings &{output[1]}[first_name] Jerry

Verify Execute SQL String - Row Count person table
${output} = Execute SQL String SELECT COUNT(*) FROM person;
Log ${output}
Should Be Equal As Strings ${output} None

Verify Execute SQL String - Row Count foobar table
${output} = Execute SQL String SELECT COUNT(*) FROM foobar;
Log ${output}
Should Be Equal As Strings ${output} None

Insert Data Into Table foobar
${output} = Execute SQL String INSERT INTO foobar VALUES(1,'Jerry');
Log ${output}
Should Be Equal As Strings ${output} None

Verify Query - Row Count foobar table 1 row
${output} = Query SELECT COUNT(*) FROM foobar;
Log ${output}
${val}= Get from list ${output} 0
${val}= Convert to list ${val}
${val}= Get from list ${val} 0
Should be equal as Integers ${val} 1

Verify Delete All Rows From Table - foobar
Delete All Rows From Table foobar
Comment Sleep 2s

Verify Query - Row Count foobar table 0 row
Row Count Is 0 SELECT * FROM foobar;
Comment ${output} = Query SELECT COUNT(*) FROM foobar;
Comment Log ${output}
Comment Should Be Equal As Strings ${output} [(0,)]

Drop person and foobar tables
${output} = Execute SQL String DROP TABLE IF EXISTS person,foobar;
Log ${output}
Should Be Equal As Strings ${output} None
Get All Names
${Rows}= Query select FIRST_NAME, LAST_NAME from person
Should Be Equal ${Rows}[0][0] Franz Allan
Should Be Equal ${Rows}[0][1] See
Should Be Equal ${Rows}[1][0] Jerry
Should Be Equal ${Rows}[1][1] Schneider

Person Table Contains Expected Records
${sql}= Catenate select LAST_NAME from person
Check Query Result ${sql} contains See
Check Query Result ${sql} equals Schneider row=1

Wait Until Table Gets New Record
${sql}= Catenate select LAST_NAME from person
Check Row Count ${sql} > 2 retry_timeout=5s

Person Table Contains No Joe
${sql}= Catenate SELECT id FROM person
... WHERE FIRST_NAME= 'Joe'
Check Row Count ${sql} == 0
```



## Database modules compatibility

The library is basically compatible with any [Python Database API Specification 2.0](https://peps.python.org/pep-0249/) module.

However, the actual implementation in existing Python modules is sometimes quite different, which requires custom handling in the library.
Therefore there are some modules, which are "natively" supported in the library - and others, which may work and may not.

### Python modules currently "natively" supported
#### Oracle
- [oracledb](https://oracle.github.io/python-oracledb/)
- Both thick and thin client modes are supported - you can select one using the `oracle_driver_mode` parameter.
- However, due to current limitations of the oracledb module, **it's not possible to switch between thick and thin modes during a test execution session** - even in different suites.
- [cx_Oracle](https://oracle.github.io/python-cx_Oracle/)
#### MySQL
- [pymysql](https://github.com/PyMySQL/PyMySQL)
- [MySQLdb](https://mysqlclient.readthedocs.io/index.html)
#### PostgreSQL
- [psycopg2](https://www.psycopg.org/docs/)
#### MS SQL Server
- [pymssql](https://github.com/pymssql/pymssql)
#### SQLite
- [sqlite3](https://docs.python.org/3/library/sqlite3.html)
#### Teradata
- [teradata](https://github.com/teradata/PyTd)
#### IBM DB2
- The Python package to be installed is [ibm_db](https://github.com/ibmdb/python-ibmdb). It includes two modules - `ibm_db` and `ibm_db_dbi`.
- *Using `ibm_db_dbi` is highly recommended* as only this module is Python DB API 2.0 compatible. See [official docs](https://www.ibm.com/docs/en/db2/12.1?topic=applications-python-sqlalchemy-django-framework).
#### ODBC
- [pyodbc](https://github.com/mkleehammer/pyodbc)
- [pypyodbc](https://github.com/pypyodbc/pypyodbc)
#### Kingbase
- ksycopg2