Package: scrippy-db
scrippy-dbGeneric database client for theScrippyframework.RequirementsPython modulesList of required modulesThe modules listed below will be installed automatically.psycopg2-binarycx-Oraclemysql-connector-pythonInstallationWithpippipinstallscrippy-dbManual installationgitclonehttps://codeberg.org/scrippy/scrippy-db.gitcdscrippy-db
python-mpipinstall-rrequirements.txt
makeinstallUsageThescrippy_db.dbmodule provides theDatabaseobject, which is intended to offer database usage functionality.Connection to a database can be done either by directly providing connection parameters (db_type,username,host,database,port,password) to the constructor, or by providing the name of theserviceto connect to.Thedb_typeparameter allows you to specify the type of database (sqlite3,postgres,mysqlororacle).Note thatOracledatabase is not tested as much as the other types of database.Simple queryQuery execution is performed with theDatabase.execute()method, which accepts the following parameters:query: The query itself (required)params: The query parameters in the exact order of appearance within the query (optional)verbose: Boolean. If set toTrue, each query, parameter and result will be sent to the logger.commit: Boolean. When set toTrue, a commit statement will be sent to the database immediately after the query execution. default toFalse.exit_on_error: Boolean. If set toTrue, any error encountered while query execution will raise an error and exit the script after query rollback. Default toTrue.A query may contain one or more variable parameters requiring the query to be adapted to these parameters.In conformance toPython Database API v2.0, parameters may be provided as sequence or mapping and will be bound to variables in the operation. If error occurs while query execution, the query will berollbacked.The query format depends on the database type. See thequery formatting sectionbelow for further details.For security reasons,nevertry to manage the interpolation of parameters inside the query yourself.Multiple queriesA single query can be executed multiple times with multiple set of parameters using theDatabase.multi_query()method, which accepts the following parameters:query: The query itself as a string with placeholders for parameters (required)paramlist: A mandatory list of dictionaries specifying the needed parameters to be mapped on each execution of thequerystring.verbose: Boolean. If set toTrue, each query, parameter and result will be sent to the logger.commit: Boolean. When set toTrue, a commit statement will be sent to the database immediately after each query execution. default toFalse.exit_on_error: Boolean. If set toTrue, any error encountered while query execution will raise an error and exit the script after query rollback. Default toTrue.In conformance toPython Database API v2.0, parameters may be provided as sequence or mapping and will be bound to variables in the operation. If error occurs while query execution, the query will berollbacked.This method is intended to insert data or update the database. It is not intended to retrieve data.The query format depends on the database type. See thequery formatting sectionbelow for further details.For security reasons,nevertry to manage the interpolation of parameters inside the query yourself.TransactionsTransactions can be performed withe theDatabase.transaction()method, which accpets the following parmeters:queries: A list of dictionaries specifying all queries and needed parameters to be executed within the transaction. The SQL query to execute. The string query should use thenamed paramstyle(seehttps://peps.python.org/pep-0249/#paramstyle) for parameters mapping.verbose: Boolean. If set toTrue, each query, parameter and result will be sent to the logger.exit_on_error: Boolean. If set toTrue, any error encountered while query execution will raise an error and exit the script after query rollback. Default toFalse.The whole transaction is committed only if all queries specified in thequeriesargument are executed without error. If an error occurs within the transaction, the whole transaction isrollbacked.This method is intended to insert data or update the database. It is not intended to retrieve data.Each dictionary in thequerieslist must provide at least aqueryitem specifying a query to execute. It may also provide aparamsitem which is a dictionary of parameters to be mapped onto the correspondingquerystring (see thequery()method for further details).The query format depends on the database type. See thequery formatting sectionbelow for further details.Query formattingIn order to prevent SQL injection, SQL queries must use placeholders for data binding.While the principe is the same amongst the different supported database types, the placeholder formats vary.PostgresandMySQLPlaceholders are identified by%(placeholder)s. The name of the placeholders can then be utilized to transmit data to the query through a dictionary with keys matching the query parameter names.Exemples:query="INSERT INTO people VALUES(%(firstname)s,%(lastname)s,%(age)s)"data={"firstname":"Luiggi","lastname":"Vercotti","age":42}query="select * from people where age =%(age)s"data={"age":42}sqlite3andOraclePlaceholders are identified by a colon followed by the name of the placeholder. The name of the placeholders can then be utilized to transmit data to the query through a dictionary with keys matching the query parameter names.Exemples:query="INSERT INTO people VALUES(:firstname, :lastname, :age)"data={"firstname":"Luiggi","lastname":"Vercotti","age":42}query="select * from people where age = :age"data={"age":42}Examplesfromscrippy_dbimportScrippyDbError,loggerfromscrippy_db.dbimportDatabase# Simple querywithDatabase(db_type="pgsql",username="luiggi.vercotti",password="D3ADP4ARR0T",host="db.flying.circus",port="5432",database="monty_python")asdb:query="INSERT INTO people VALUES(:firstname, :lastname, :age)"data={"firstname":"Harry","lastname":"Fink","age":42}db.query(query=query,params=data,commit=True,exit_on_error=True)# Multiple querieswithDatabase(db_type="pgsql",username="luiggi.vercotti",password="d34dP4rr0t",host="db.flying.circus",port="5432",database="monty_python")asdb:query="INSERT INTO people VALUES(:firstname, :lastname, :age)"data=[{"firstname":"Harry","lastname":"Fink","age":42},{"firstname":"Eric","lastname":"Parline","age":50},{"firstname":None,"lastname":"Gumby","age":36}]db.multi_query(query=query,params=data,commit=True,exit_on_error=True,verbose=True)# transactionwithDatabase(db_type="pgsql",username="luiggi.vercotti",password="d34dP4rr0t",host="db.flying.circus",port="5432",database="monty_python")asdb:queries=[{"query":"INSERT INTO people VALUES(:firstname, :lastname, :age)","params":{"firstname":"Harry","lastname":"Fink","age":42}},{"query":"delete from people where age > :age","params":30}]db.transaction(queries=queries,exit_on_error=True)