{"id":13626139,"url":"https://github.com/MarketSquare/Robotframework-Database-Library","last_synced_at":"2025-04-16T11:31:18.292Z","repository":{"id":2719300,"uuid":"1118374","full_name":"MarketSquare/Robotframework-Database-Library","owner":"MarketSquare","description":"The Database Library for Robot Framework allows you to query a database and verify the results using different Python DB modules (installed separately).","archived":false,"fork":false,"pushed_at":"2025-02-20T10:22:34.000Z","size":2771,"stargazers_count":165,"open_issues_count":9,"forks_count":178,"subscribers_count":27,"default_branch":"master","last_synced_at":"2025-04-10T07:21:34.304Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://marketsquare.github.io/Robotframework-Database-Library/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MarketSquare.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2010-11-28T04:37:50.000Z","updated_at":"2025-04-07T08:45:13.000Z","dependencies_parsed_at":"2024-01-06T22:53:34.771Z","dependency_job_id":"6d978cdb-235b-4783-a5d6-0b2ce95f1e0a","html_url":"https://github.com/MarketSquare/Robotframework-Database-Library","commit_stats":null,"previous_names":["franz-see/Robotframework-Database-Library","franz-see/robotframework-database-library"],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MarketSquare%2FRobotframework-Database-Library","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MarketSquare%2FRobotframework-Database-Library/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MarketSquare%2FRobotframework-Database-Library/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MarketSquare%2FRobotframework-Database-Library/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MarketSquare","download_url":"https://codeload.github.com/MarketSquare/Robotframework-Database-Library/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249235052,"owners_count":21235137,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T21:02:10.977Z","updated_at":"2025-04-16T11:31:18.283Z","avatar_url":"https://github.com/MarketSquare.png","language":"Python","funding_links":[],"categories":["Libraries","Python"],"sub_categories":["Database"],"readme":"# Robot Framework Database Library\n\nThe Database Library for [Robot Framework](https://robotframework.org) allows you to query a database and verify the results.\nIt requires an appropriate **Python module to be installed separately** - depending on your database, like e.g. `oracledb` or `pymysql`. \n\nThe library consists of some keywords designed to perform different checks on your database.\nHere you can find the [keyword docs](http://marketsquare.github.io/Robotframework-Database-Library/).\n\nWath the [talk at Robocon 2024 about the Database Library update](https://youtu.be/A96NTUps8sU).\n\n[![Talk at Robocon 2024 about the Database Library update](http://img.youtube.com/vi/A96NTUps8sU/0.jpg)](https://youtu.be/A96NTUps8sU)\n\n# Requirements\n- Python\n- Robot Framework\n- Python database module you're going to use - e.g. `oracledb`\n# Installation\n```\npip install robotframework-databaselibrary\n```\n# Basic usage examples\n```RobotFramework\n*** Settings ***\nLibrary       DatabaseLibrary\nTest Setup    Connect To My Oracle DB\n\n*** Keywords ***\nConnect To My Oracle DB\n    Connect To Database\n    ...    oracledb\n    ...    db_name=db\n    ...    db_user=my_user\n    ...    db_password=my_pass\n    ...    db_host=127.0.0.1\n    ...    db_port=1521\n\n*** Test Cases ***\nGet All Names\n    ${Rows}=    Query    select FIRST_NAME, LAST_NAME from person\n    Should Be Equal    ${Rows}[0][0]    Franz Allan\n    Should Be Equal    ${Rows}[0][1]    See\n    Should Be Equal    ${Rows}[1][0]    Jerry\n    Should Be Equal    ${Rows}[1][1]    Schneider\n\nPerson Table Contains Expected Records\n    ${sql}=    Catenate    select LAST_NAME from person\n    Check Query Result    ${sql}    contains    See\n    Check Query Result    ${sql}    equals      Schneider    row=1\n\nWait Until Table Gets New Record\n    ${sql}=    Catenate    select LAST_NAME from person\n    Check Row Count    ${sql}    \u003e    2    retry_timeout=5s\n\nPerson Table Contains No Joe\n    ${sql}=    Catenate    SELECT id FROM person\n    ...                    WHERE FIRST_NAME= 'Joe'\n    Check Row Count    ${sql}   ==    0\n```\nSee more examples in the folder `tests`.\n\n# Handling multiple database connections\nThe library can handle multiple connections to different databases using *aliases*.\nAn alias is set while creating a connection and can be passed to library keywords in a corresponding argument.\n## Example\n```RobotFramework\n*** Settings ***\nLibrary          DatabaseLibrary\nTest Setup       Connect To All Databases\nTest Teardown    Disconnect From All Databases\n\n*** Keywords ***\nConnect To All Databases\n    Connect To Database\n    ...    psycopg2\n    ...    db_name=db\n    ...    db_user=db_user\n    ...    db_password=pass\n    ...    db_host=127.0.0.1\n    ...    db_port=5432\n    ...    alias=postgres\n    Connect To Database\n    ...    pymysql\n    ...    db_name=db\n    ...    db_user=db_user\n    ...    db_password=pass\n    ...    db_host=127.0.0.1\n    ...    db_port=3306\n    ...    alias=mysql\n\n*** Test Cases ***\nUsing Aliases\n    ${names}=    Query    select LAST_NAME from person    alias=postgres\n    Execute Sql String    drop table XYZ                  alias=mysql\n\nSwitching Default Alias\n    Switch Database    postgres\n    ${names}=    Query    select LAST_NAME from person\n    Switch Database    mysql\n    Execute Sql String    drop table XYZ\n```\n\n# Connection examples for different DB modules\n\u003cdetails\u003e\n\u003csummary\u003eOracle (oracle_db)\u003c/summary\u003e\n\n```RobotFramework\n# Thin mode is used by default\nConnect To Database\n...    oracledb\n...    db_name=db\n...    db_user=db_user\n...    db_password=pass\n...    db_host=127.0.0.1\n...    db_port=1521\n\n# Thick mode with default location of the Oracle Instant Client\nConnect To Database\n...    oracledb\n...    db_name=db\n...    db_user=db_user\n...    db_password=pass\n...    db_host=127.0.0.1\n...    db_port=1521\n...    oracle_driver_mode=thick\n    \n# Thick mode with custom location of the Oracle Instant Client\nConnect To Database\n...    oracledb\n...    db_name=db\n...    db_user=db_user\n...    db_password=pass\n...    db_host=127.0.0.1\n...    db_port=1521\n...    oracle_driver_mode=thick,lib_dir=C:/instant_client_23_5\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e PostgreSQL (psycopg2) \u003c/summary\u003e\n\n```RobotFramework\nConnect To Database\n...    psycopg2\n...    db_name=db\n...    db_user=db_user\n...    db_password=pass\n...    db_host=127.0.0.1\n...    db_port=5432\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eMicrosoft SQL Server (pymssql)\u003c/summary\u003e\n\n```RobotFramework\n# UTF-8 charset is used by default\nConnect To Database\n...    pymssql\n...    db_name=db\n...    db_user=db_user\n...    db_password=pass\n...    db_host=127.0.0.1\n...    db_port=1433\n\n# Specifying a custom charset\nConnect To Database\n...    pymssql\n...    db_name=db\n...    db_user=db_user\n...    db_password=pass\n...    db_host=127.0.0.1\n...    db_port=1433\n...    db_charset=cp1252\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eMySQL (pymysql)\u003c/summary\u003e\n\n```RobotFramework\n# UTF-8 charset is used by default\nConnect To Database\n...    pymysql\n...    db_name=db\n...    db_user=db_user\n...    db_password=pass\n...    db_host=127.0.0.1\n...    db_port=3306\n    \n# Specifying a custom charset\nConnect To Database\n...    pymysql\n...    db_name=db\n...    db_user=db_user\n...    db_password=pass\n...    db_host=127.0.0.1\n...    db_port=3306\n...    db_charset=cp1252\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eIBM DB2 (ibm_db_dbi)\u003c/summary\u003e\n\n```RobotFramework\nConnect To Database\n...    ibm_db_dbi\n...    db_name=db\n...    db_user=db_user\n...    db_password=pass\n...    db_host=127.0.0.1\n...    db_port=50000\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eMySQL via ODBC (pyodbc)\u003c/summary\u003e\n\n```RobotFramework\n# ODBC driver name is required\n# ODBC driver itself has to be installed\nConnect To Database\n...    pyodbc\n...    db_name=db\n...    db_user=db_user\n...    db_password=pass\n...    db_host=127.0.0.1\n...    db_port=3306\n...    odbc_driver={MySQL ODBC 9.2 ANSI Driver}\n    \n# Specifying a custom charset if needed\nConnect To Database\n...    pyodbc\n...    db_name=db\n...    db_user=db_user\n...    db_password=pass\n...    db_host=127.0.0.1\n...    db_port=3306\n...    odbc_driver={MySQL ODBC 9.2 ANSI Driver}\n...    db_charset=latin1 \n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eOracle via JDBC (jaydebeapi)\u003c/summary\u003e\n\n```RobotFramework\n# Username and password must be set as a dictionary\nVAR    \u0026{CREDENTIALS}    user=db_user    password=pass\n\n# JAR file with Oracle JDBC driver is required\n# Jaydebeapi is not \"natively\" supported by the Database Library,\n# so using the custom parameters\nConnect To Database\n...    jaydebeapi\n...    jclassname=oracle.jdbc.driver.OracleDriver\n...    url=jdbc:oracle:thin:@127.0.0.1:1521/db\n...    driver_args=${CREDENTIALS}\n...    jars=C:/ojdbc17.jar    \n\n# Set if getting error 'Could not commit/rollback with auto-commit enabled'\nSet Auto Commit    False    \n\n# Set for automatically removing trailing ';' (might be helpful for Oracle)\nSet Omit Trailing Semicolon    True    \n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eSQLite (sqlite3)\u003c/summary\u003e\n\n```RobotFramework\n# Using custom parameters required\nConnect To Database  \n...    sqlite3\n...    database=./my_database.db\n...    isolation_level=${None}\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eTeradata (teradata)\u003c/summary\u003e\n\n```RobotFramework\nConnect To Database\n...    teradata\n...    db_name=db\n...    db_user=db_user\n...    db_password=pass\n...    db_host=127.0.0.1\n...    db_port=1025\n```\n\u003c/details\u003e\n\n# Using configuration file\nThe `Connect To Database` keyword allows providing the connection parameters in two ways:\n- As keyword arguments\n- In a configuration file - a simple list of _key=value_ pairs, set inside an _alias_ section.\n\nYou can use only one way or you can combine them:\n- The keyword arguments are taken by default\n- If no keyword argument is provided, a parameter value is searched in the config file\n\nAlong with commonly used connection parameters, named exactly as keyword arguments, a config file\ncan contain any other DB module specific parameters as key/value pairs.\nIf same custom parameter is provided both as a keyword argument *and* in config file,\nthe *keyword argument value takes precedence*.\n\nThe path to the config file is set by default to `./resources/db.cfg`.\nYou can change it using an according parameter in the `Connect To Database` keyword.\n\nA config file *must* contain at least one section name -\nthe connection alias, if used (see [Handling multiple database connections](#handling-multiple-database-connections)), or\n`[default]` if no aliases are used.\n\n## Config file examples \n### Config file with default alias (equal to using no aliases at all)\n```\n[default]\ndb_module=psycopg2\ndb_name=yourdbname\ndb_user=yourusername\ndb_password=yourpassword\ndb_host=yourhost\ndb_port=yourport\n```\n### Config file with a specific alias\n```\n[myoracle]\ndb_module=oracledb\ndb_name=yourdbname\ndb_user=yourusername\ndb_password=yourpassword\ndb_host=yourhost\ndb_port=yourport\n```\n\n### Config file with some params only\n```\n[default]\ndb_password=mysecret\n```\n### Config file with some custom DB module specific params\n```\n[default]\nmy_custom_param=value\n```\n\n# Inline assertions\nKeywords, that accept arguments ``assertion_operator`` and ``expected_value``,\nperform a check according to the specified condition - using the [Assertion Engine](https://github.com/MarketSquare/AssertionEngine).\n\n## Examples\n```RobotFramework\nCheck Row Count     SELECT id FROM person          ==        2\nCheck Query Result  SELECT first_name FROM person  contains  Allan\n```\n\n# Retry mechanism\nAssertion keywords, that accept arguments ``retry_timeout`` and ``retry_pause``, support waiting for assertion to pass.\n\nSetting the ``retry_timeout`` argument enables the mechanism -\nin this case the SQL request and the assertion are executed in a loop,\nuntil the assertion is passed or the ``retry_timeout`` is reached.\nThe pause between the loop iterations is set using the ``retry_pause`` argument.\n\nThe argument values are set in [Robot Framework time format](http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#time-format) - e.g. ``5 seconds``.\n\nThe retry mechanism is disabled by default - ``retry_timeout`` is set to ``0``.\n\n## Examples\n```RobotFramework\n${sql}=   Catenate    SELECT first_name FROM person\nCheck Row Count     ${sql}  ==        2      retry_timeout=10 seconds\nCheck Query Result  ${sql}  contains  Allan  retry_timeout=5s  retry_pause=1s\n```\n\n# Logging query results\nKeywords, that fetch results of a SQL query, print the result rows as a table in RF log.\n- A log head limit of *50 rows* is applied, other table rows are truncated in the log message.\n- The limit and the logging in general can be adjusted any time in your tests using the Keyword `Set Logging Query Results`.\n\nYou can also setup the limit or disable the logging during the library import.\n## Examples\n```RobotFramework\n*** Settings ***\n# Default behavior - logging of query results is enabled, log head is 50 rows.\nLibrary    DatabaseLibrary\n\n# Logging of query results is disabled, log head is 50 rows (default).\nLibrary    DatabaseLibrary    log_query_results=False\n\n# Logging of query results is enabled (default), log head is 10 rows.\nLibrary    DatabaseLibrary    log_query_results_head=10\n\n# Logging of query results is enabled (default), log head limit is disabled (log all rows).\nLibrary    DatabaseLibrary    log_query_results_head=0\n```\n\n# Commit behavior\nWhile creating a database connection, the library doesn't explicitly set the _autocommit_ behavior -\nso the default value of the Python DB module is used.\nAccording to Python DB API specification it should be disabled by default -\nwhich means each SQL transaction (even a simple _SELECT_) must contain a dedicated commit statement, if necessary.\n\nThe library manages it for you - keywords like `Query` or `Execute SQL String`\nperform automatically a commit after running the query (or a rollback in case of error).\n\nYou can turn off this automatic commit/rollback behavior using the ``no_transaction`` parameter.\nSee docs of a particular keyword.\n\nIt's also possible to explicitly set the _autocommit_ behavior on the Python DB module level -\nusing the `Set Auto Commit` keyword.\nThis has no impact on the automatic commit/rollback behavior in library keywords (described above).\n\n# Omitting trailing semicolon behavior\nSome databases (e.g. Oracle) throw an exception, if you leave a semicolon (;) at the SQL string end.     \nHowever, there are exceptional cases, when you need it even for Oracle - e.g. at the end of a PL/SQL block.\n\nThe library can handle it for you and remove the semicolon at the end of the SQL string.\nBy default, it's decided based on the current database module in use:\n- For `oracle_db` and `cx_Oracle`, the trailing semicolon is removed\n- For other modules, the trailing semicolon is left as it is\n\nYou can also set this behavior explicitly:\n- Using the `Set Omit Trailing Semicolon` keyword\n- Using the `omit_trailing_semicolon` parameter in the `Execute SQL String` keyword.\n\n# Database modules compatibility\n\u003e Looking for [Connection examples for different DB modules](#connection-examples-for-different-db-modules)?   \n\nThe library is basically compatible with any [Python Database API Specification 2.0](https://peps.python.org/pep-0249/) module.\n\nHowever, the actual implementation in existing Python modules is sometimes quite different, which requires custom handling in the library.\nTherefore there are some modules, which are \"natively\" supported in the library - and others, which may work and may not.\n\n## Python modules currently \"natively\" supported\n### Oracle\n- [oracledb](https://oracle.github.io/python-oracledb/)\n    - Both thick and thin client modes are supported - you can select one using the `oracle_driver_mode` parameter.\n    - 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.\n- [cx_Oracle](https://oracle.github.io/python-cx_Oracle/)\n### MySQL\n- [pymysql](https://github.com/PyMySQL/PyMySQL)\n- [MySQLdb](https://mysqlclient.readthedocs.io/index.html)\n### PostgreSQL\n- [psycopg2](https://www.psycopg.org/docs/)\n### MS SQL Server\n- [pymssql](https://github.com/pymssql/pymssql)\n### SQLite\n- [sqlite3](https://docs.python.org/3/library/sqlite3.html)\n### Teradata\n- [teradata](https://github.com/teradata/PyTd)\n### IBM DB2\n- 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`.   \n- *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).\n### ODBC\n- [pyodbc](https://github.com/mkleehammer/pyodbc)\n- [pypyodbc](https://github.com/pypyodbc/pypyodbc)\n### Kingbase\n- ksycopg2\n\n# Further references (partly outdated)\n- [List of Python DB interfaces](https://wiki.python.org/moin/DatabaseInterfaces)\n- [Python DB programming](https://wiki.python.org/moin/DatabaseProgramming)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMarketSquare%2FRobotframework-Database-Library","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FMarketSquare%2FRobotframework-Database-Library","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMarketSquare%2FRobotframework-Database-Library/lists"}