lightoracle

A lightweight Oracle database connection handler. Reads credentials automatically, and can execute queries with Pandas or produce a SQLAlchemy engine so you can use your tool of choice.

Installation

pip install git+https://github.com/GSU-Analytics/lightoracle.git

To pin a version:

pip install git+https://github.com/GSU-Analytics/lightoracle.git@v0.3.0

Configuration

Configuration File Support

lightoracle supports at least 5 different configuration approaches.

• See the configuration guide for details on where to place your configuration files.
• See the structure guide for details on the structure of the configuration file.

Configuration File Structure

A minimal configuration file looks like this.

• Place it anywhere specified in the configuration guide.
• Full details on the expected file structure can be found in the structure guide.

default:
  user: developer
  dsn: my-dsn:port/SID

If you like, lightoracle.credentials contains a function which will create a starting configuration template for you.

from lightoracle import credentials
from pathlib import Path
# This will get you started
credentials.write_config_template(Path('oracle_config.yaml'))

Password Management

Your password is loaded in priority order:

1. (NOT RECOMMENDED) Get the ORACLE_PASSWORD passed to .env or set as an environment variable.
   • This is to support backwards compatibility. We do not suggest you do this!
2. From the system keyring. The password will be selected based on the value of credential_account.
   • You may provide any credential_account name to store your password in the keyring.
   • By default, your user name will be used.
   • For example, if your .yaml file specifies credential_account: db_admin, the keyring password for LightOracleConnection associated with the name db_admin will be used.
3. If no keyring value is found for the given credential_account value, you will be interactively prompted to provide one.

To reset a stored keyring password:

conn.reset_password()

Usage

Executing with Pandas

Import LightOracleConnection and create an instance. Credentials will be loaded automatically.

from lightoracle import LightOracleConnection

conn = LightOracleConnection()
df = conn.execute_query("SELECT * FROM my_table FETCH FIRST 10 ROWS ONLY")
df.to_csv('output.csv', index=False)

SQLAlchemy Engine Support

Some libraries, like polars and ibis, are most easily interfaced with if you have an SQLAlchemy engine instance.

Use LightOracleConnection.create_engine() to get an engine instance pre-configured for you.

conn = LightOracleConnection()
engine = conn.create_engine()

Dynamic Connection Support

If you have entries in a connections block in your configuration file, you can change your credentials by using the LightOracleConnection().with_profile() method. Pass a profile name to use the credentials in that block.

Here's an example configuration scheme:

# Imagine we have the following blocks
connections:
  DB-development:
    user: ???
    dsn: ???
    lib_dir: null
  DB-production:
    user: ???
    dsn: ???
    lib_dir: null

We can switch between these parameters at runtime.

# We start by using the development server
conn = LightOracleConnection(profile='DB-development')
# At some point, we decide to switch to the production server
# NOTE! Your connection won't change until you explicitly call `.connect()`!
conn.with_profile(profile='DB-production').connect()

Thin mode vs. thick mode

By default, lightoracle uses thin mode — no Oracle Instant Client required.

To use thick mode (Oracle Instant Client), set the lib_dir:

# thick mode — explicit library path
# Note: You can also specify `lib_dir` in your config file
conn = LightOracleConnection(lib_dir="/path/to/oracle/client")

lib_dir can also be set via ORACLE_LIB_DIR in your .env file.