Quickstart

1. Load up your VirtualEnvironment of choice and run:

   pip install py-dbcn
   

   Alternatively, add py-dbcn to your respective project requirements file, and then follow the standard package installation method for your project (requirements.txt, pipenv, poetry, etc).

2. Install your database connection of choice:

   The py-dbcn package does not inherently install the associated pip libraries for each database. This is so the local installation only installs the bare minimum needed for your specific use case.

   Use the below packages to connect to the database type of choice:

   • Python package for MySQL:

     mysqlclient
     

   • Python package for PostgreSQL:

     psycopg2-binary
     

3. Create a new Python project (or load an existing one) and establish one or more database connections. For example, to connect with MySQL:

   # Here we initialize a single MySQL connection.
   from py_dbcn.connectors import MysqlDbConnector
   
   # Import config values from some other file.
   from .settings import mysql_config
   
   ...
   
   connector = MysqlDbConnector(
       mysql_config['db_host'],
       mysql_config['db_port'],
       mysql_config['db_user'],
       mysql_config['db_user_password'],
       mysql_config['db_name'],
   )
   

   Important

   With the above code, we’re specifically importing the database settings from some outside location. In this case, we import these values as a dictionary format.

   Depending on who can access this project and how it’s stored, it’s often much more secure to avoid committing database settings to the project.

   Instead, add some file to the project’s .gitignore and read in config values from there. It can also be helpful to make an example_config.py file, to show the expected format of how these settings should be provided (but without committing the actual database credentials).

4. Optionally set up logging for py-dbcn, in order to get additional helpful logging output.

   We recommend follow logging setup as discussed in the `Django Docs <>`_. Yes, this project doesn’t require Django, but the Django docs provide thorough documentation for what we believe is the best Python logging format.

   Once logging is set up, add the py-dbcn package to your logging namespace, similar to shown:

   'loggers': {
   
       ...
   
       'py_dbcn': {
           'handlers': [<handlers_here>],
           'level': 'NOTSET',
       },
   }
   

   Where <handlers_here> is replaced by your project’s actual logging handlers.

5. Install optional packages for extra functionality.

   This package offers support for the colorama Python package.

   Colorama is not necessary to use py-dbcn, but adding it will provide helpful coloring output to log messages, to help separate what kind of calls are being made.

6. Run database queries as desired. See <link-here>.

   Note

   Closing the database is not necessary, as py-dbcn will automatically take care of it on program termination.

   However, if desired, you can still manually close the database connection mid-program.

   The py-dbcn library also has no built-in limitations. You are free to open and close as many simultaneous connections as you wish.