Getting Started with sqlalchemy-config

version: 0.4.7b0

The sqlalchemy-config package is a toolkit to handle database configuration parameters that are stored in a config file. This can locate, read, and extract the config parameters and create a sessionmaker object from them that is bound to the engine object.

There is online documentation for sqlalchemy-config.

Installation instructions

sqlalchemy-config can be installed via pypi or conda.

Installation using pip

pip install sqlalchemy-config

Installation using conda

I maintain a conda package in my personal conda channel. To install this please run:

conda install -c cfin -c conda-forge sqlalchemy-config

Usage TL;DR

sqlalchemy-config is designed to handle database connection inputs coming from different sources. For example: a URL or SQLite file path on the command line, a config file path from a command-line argument, an environment variable, or a default file in the home directory.

The config files used in the example below have a similar structure to this see SQLAlchemy engine from config:

[mydb_mysql]
# Make sure this is only readable by you
# Make sure password is URL encoded, see: sqlalchemy_config.encode_password
db.url = mysql+pymysql://user:password@127.0.0.1:3306/db_cfg_arg

>>> import sqlalchemy_config as sqlc
>>> import os

>>> # Input from the command line (SQLite file path)
>>> dbarg = "mydb.db"

>>> # Prefix used for SQLAlchemy parameters in config sections
>>> conn_prefix = "db."

>>> # This represents a default location for config files containing parameters
>>> config_file = os.path.join(os.environ['HOME'], "mydbs_def.cnf")

>>> # dbarg is treated as SQLite file path
>>> sqlc.get_new_sessionmaker(dbarg, conn_prefix=conn_prefix, config_arg=config_file)
>>> sessionmaker(class_='Session', bind=Engine(sqlite:///mydb.db), autoflush=True, autocommit=False, expire_on_commit=True)

>>> # dbarg can also be a fully formed SQLAlchemy URL
>>> dbarg = "mysql+pymysql://user:password@127.0.0.1:3306/db_url_arg"
>>> sqlc.get_new_sessionmaker(dbarg)
>>> sessionmaker(class_='Session', bind=Engine(mysql+pymysql://user:***@127.0.0.1:3306/db_url_arg), autoflush=True, autocommit=False, expire_on_commit=True)

See the API documentation for lower level functions.

Development

To set up a development environment, install the package with development dependencies:

pip install -e ".[dev]"

Run the test suite:

pytest tests/ -v

Run tests with coverage reporting:

pytest --cov=sqlalchemy_config --cov-report=term-missing tests/

Verify the coverage threshold (80%) is met:

pytest --cov=sqlalchemy_config --cov-fail-under=80 tests/

Lint and format code before committing:

ruff check --fix . && ruff format .

Change log

See CHANGELOG.md for the full change log.