From 0a23df3c93b1505370f139bf8d750c03aa6bc30f Mon Sep 17 00:00:00 2001 From: Many Kasiriha Date: Wed, 28 May 2025 07:27:22 +0000 Subject: [PATCH 1/2] docs: Update Database Library page with proper database modules --- website/docs/different_libraries/database.md | 223 ++++++------------- 1 file changed, 66 insertions(+), 157 deletions(-) diff --git a/website/docs/different_libraries/database.md b/website/docs/different_libraries/database.md index 8b042f1c..9923c156 100644 --- a/website/docs/different_libraries/database.md +++ b/website/docs/different_libraries/database.md @@ -3,7 +3,7 @@ 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 @@ -18,171 +18,80 @@ It offers keywords to e.g. 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 \ No newline at end of file From 50f2fb60b34c5b898fc1c4f9d226b778f0132281 Mon Sep 17 00:00:00 2001 From: Many Kasiriha Date: Wed, 28 May 2025 07:35:36 +0000 Subject: [PATCH 2/2] docs: Add link to keyword documentation --- website/docs/different_libraries/database.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/website/docs/different_libraries/database.md b/website/docs/different_libraries/database.md index 9923c156..af650023 100644 --- a/website/docs/different_libraries/database.md +++ b/website/docs/different_libraries/database.md @@ -10,6 +10,8 @@ It offers keywords to e.g. - 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/). + ## Installation ### Install from PyPI