Skip to content

Commit fc64627

Browse files
manykarimmanykarim
authored
Merge pull request #89 from MarketSquare/docs/update_databaselibrary_page
docs: Update Database Library page with proper database modules
2 parents 8595aa4 + 2c223f4 commit fc64627

1 file changed

Lines changed: 67 additions & 158 deletions

File tree

‎website/docs/different_libraries/database.md‎

Lines changed: 67 additions & 158 deletions
Original file line numberDiff line numberDiff line change
@@ -3,14 +3,14 @@ sidebar_label: Database Library
33
title: Database Library
44
---
55

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

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

1515
## Installation
1616

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

23-
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/).
24-
You can find a list of supported database modules [here](https://wiki.python.org/moin/DatabaseInterfaces).
25-
26-
Examples are:
27-
- [psycopg2](https://pypi.org/project/psycopg2/) for PostgreSQL
28-
- [cx_Oracle](https://pypi.org/project/cx-Oracle/) for Oracle
29-
- [pymysql](https://pypi.org/project/PyMySQL/) for MySQL
30-
- [pyodbc](https://pypi.org/project/pyodbc/) for Microsoft SQL Server
31-
3223
## Examples
3324

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

36-
Example for a PostgreSQL database:
27+
### Basic Usage Example
3728

3829
```robotframework
3930
*** Settings ***
40-
Suite Setup Connect To Database psycopg2 ${DBName} ${DBUser} ${DBPass} ${DBHost} ${DBPort}
41-
Suite Teardown Disconnect From Database
42-
Library DatabaseLibrary
43-
Library OperatingSystem
44-
Library Collections
45-
46-
*** Variables ***
47-
${DBHost} localhost
48-
${DBName} travis_ci_test
49-
${DBPass} ""
50-
${DBPort} 5432
51-
${DBUser} postgres
31+
Library DatabaseLibrary
32+
Test Setup Connect To My Oracle DB
33+
34+
*** Keywords ***
35+
Connect To My Oracle DB
36+
Connect To Database
37+
... oracledb
38+
... db_name=db
39+
... db_user=my_user
40+
... db_password=my_pass
41+
... db_host=127.0.0.1
42+
... db_port=1521
5243
5344
*** Test Cases ***
54-
Create person table
55-
${output} = Execute SQL String CREATE TABLE person (id integer unique,first_name varchar,last_name varchar);
56-
Log ${output}
57-
Should Be Equal As Strings ${output} None
58-
59-
Execute SQL Script - Insert Data person table
60-
Comment ${output} = Execute SQL Script ./${DBName}_insertData.sql
61-
${output} = Execute SQL Script ./my_db_test_insertData.sql
62-
Log ${output}
63-
Should Be Equal As Strings ${output} None
64-
65-
Execute SQL String - Create Table
66-
${output} = Execute SQL String create table foobar (id integer primary key, firstname varchar unique)
67-
Log ${output}
68-
Should Be Equal As Strings ${output} None
69-
70-
Check If Exists In DB - Franz Allan
71-
Check If Exists In Database SELECT id FROM person WHERE first_name = 'Franz Allan';
72-
73-
Check If Not Exists In DB - Joe
74-
Check If Not Exists In Database SELECT id FROM person WHERE first_name = 'Joe';
75-
76-
Table Must Exist - person
77-
Table Must Exist person
78-
79-
Verify Row Count is 0
80-
Row Count is 0 SELECT * FROM person WHERE first_name = 'NotHere';
81-
82-
Verify Row Count is Equal to X
83-
Row Count is Equal to X SELECT id FROM person; 2
84-
85-
Verify Row Count is Less Than X
86-
Row Count is Less Than X SELECT id FROM person; 3
87-
88-
Verify Row Count is Greater Than X
89-
Row Count is Greater Than X SELECT * FROM person; 1
90-
91-
Retrieve Row Count
92-
${output} = Row Count SELECT id FROM person;
93-
Log ${output}
94-
Should Be Equal As Strings ${output} 2
95-
96-
Retrieve records from person table
97-
${output} = Execute SQL String SELECT * FROM person;
98-
Log ${output}
99-
Should Be Equal As Strings ${output} None
100-
101-
Verify person Description
102-
[Tags] db smoke
103-
Comment Query db for table column descriptions
104-
@{queryResults} = Description SELECT * FROM person LIMIT 1;
105-
Log Many @{queryResults}
106-
${output} = Set Variable ${queryResults[0]}
107-
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)
108-
${output} = Set Variable ${queryResults[1]}
109-
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)
110-
${output} = Set Variable ${queryResults[2]}
111-
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)
112-
${NumColumns} = Get Length ${queryResults}
113-
Should Be Equal As Integers ${NumColumns} 3
114-
115-
Verify foobar Description
116-
[Tags] db smoke
117-
Comment Query db for table column descriptions
118-
@{queryResults} = Description SELECT * FROM foobar LIMIT 1;
119-
Log Many @{queryResults}
120-
${output} = Set Variable ${queryResults[0]}
121-
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)
122-
${output} = Set Variable ${queryResults[1]}
123-
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)
124-
${NumColumns} = Get Length ${queryResults}
125-
Should Be Equal As Integers ${NumColumns} 2
126-
127-
Verify Query - Row Count person table
128-
${output} = Query SELECT COUNT(*) FROM person;
129-
Log ${output}
130-
${val}= Get from list ${output} 0
131-
${val}= Convert to list ${val}
132-
${val}= Get from list ${val} 0
133-
Should be equal as Integers ${val} 2
134-
135-
Verify Query - Row Count foobar table
136-
${output} = Query SELECT COUNT(*) FROM foobar;
137-
Log ${output}
138-
${val}= Get from list ${output} 0
139-
${val}= Convert to list ${val}
140-
${val}= Get from list ${val} 0
141-
Should be equal as Integers ${val} 0
142-
143-
Verify Query - Get results as a list of dictionaries
144-
[Tags] db smoke
145-
${output} = Query SELECT * FROM person; \ True
146-
Log ${output}
147-
Should Be Equal As Strings &{output[0]}[first_name] Franz Allan
148-
Should Be Equal As Strings &{output[1]}[first_name] Jerry
149-
150-
Verify Execute SQL String - Row Count person table
151-
${output} = Execute SQL String SELECT COUNT(*) FROM person;
152-
Log ${output}
153-
Should Be Equal As Strings ${output} None
154-
155-
Verify Execute SQL String - Row Count foobar table
156-
${output} = Execute SQL String SELECT COUNT(*) FROM foobar;
157-
Log ${output}
158-
Should Be Equal As Strings ${output} None
159-
160-
Insert Data Into Table foobar
161-
${output} = Execute SQL String INSERT INTO foobar VALUES(1,'Jerry');
162-
Log ${output}
163-
Should Be Equal As Strings ${output} None
164-
165-
Verify Query - Row Count foobar table 1 row
166-
${output} = Query SELECT COUNT(*) FROM foobar;
167-
Log ${output}
168-
${val}= Get from list ${output} 0
169-
${val}= Convert to list ${val}
170-
${val}= Get from list ${val} 0
171-
Should be equal as Integers ${val} 1
172-
173-
Verify Delete All Rows From Table - foobar
174-
Delete All Rows From Table foobar
175-
Comment Sleep 2s
176-
177-
Verify Query - Row Count foobar table 0 row
178-
Row Count Is 0 SELECT * FROM foobar;
179-
Comment ${output} = Query SELECT COUNT(*) FROM foobar;
180-
Comment Log ${output}
181-
Comment Should Be Equal As Strings ${output} [(0,)]
182-
183-
Drop person and foobar tables
184-
${output} = Execute SQL String DROP TABLE IF EXISTS person,foobar;
185-
Log ${output}
186-
Should Be Equal As Strings ${output} None
45+
Get All Names
46+
${Rows}= Query select FIRST_NAME, LAST_NAME from person
47+
Should Be Equal ${Rows}[0][0] Franz Allan
48+
Should Be Equal ${Rows}[0][1] See
49+
Should Be Equal ${Rows}[1][0] Jerry
50+
Should Be Equal ${Rows}[1][1] Schneider
51+
52+
Person Table Contains Expected Records
53+
${sql}= Catenate select LAST_NAME from person
54+
Check Query Result ${sql} contains See
55+
Check Query Result ${sql} equals Schneider row=1
56+
57+
Wait Until Table Gets New Record
58+
${sql}= Catenate select LAST_NAME from person
59+
Check Row Count ${sql} > 2 retry_timeout=5s
60+
61+
Person Table Contains No Joe
62+
${sql}= Catenate SELECT id FROM person
63+
... WHERE FIRST_NAME= 'Joe'
64+
Check Row Count ${sql} == 0
18765
```
18866

18967

190-
68+
## Database modules compatibility
69+
70+
The library is basically compatible with any [Python Database API Specification 2.0](https://peps.python.org/pep-0249/) module.
71+
72+
However, the actual implementation in existing Python modules is sometimes quite different, which requires custom handling in the library.
73+
Therefore there are some modules, which are "natively" supported in the library - and others, which may work and may not.
74+
75+
### Python modules currently "natively" supported
76+
#### Oracle
77+
- [oracledb](https://oracle.github.io/python-oracledb/)
78+
- Both thick and thin client modes are supported - you can select one using the `oracle_driver_mode` parameter.
79+
- 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.
80+
- [cx_Oracle](https://oracle.github.io/python-cx_Oracle/)
81+
#### MySQL
82+
- [pymysql](https://github.com/PyMySQL/PyMySQL)
83+
- [MySQLdb](https://mysqlclient.readthedocs.io/index.html)
84+
#### PostgreSQL
85+
- [psycopg2](https://www.psycopg.org/docs/)
86+
#### MS SQL Server
87+
- [pymssql](https://github.com/pymssql/pymssql)
88+
#### SQLite
89+
- [sqlite3](https://docs.python.org/3/library/sqlite3.html)
90+
#### Teradata
91+
- [teradata](https://github.com/teradata/PyTd)
92+
#### IBM DB2
93+
- 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`.
94+
- *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).
95+
#### ODBC
96+
- [pyodbc](https://github.com/mkleehammer/pyodbc)
97+
- [pypyodbc](https://github.com/pypyodbc/pypyodbc)
98+
#### Kingbase
99+
- ksycopg2

0 commit comments

Comments
 (0)