{"id":7480,"library":"oslo-db","title":"Oslo Database Library","description":"oslo.db is an OpenStack project library that provides database connectivity and common utilities for interacting with various SQL database backends (e.g., PostgreSQL, MySQL, SQLite). It simplifies database session management, model definition, and migration processes for OpenStack components. The library is actively maintained, with version 18.0.0 being the latest stable release, and follows the OpenStack release cadence.","status":"active","version":"18.0.0","language":"en","source_language":"en","source_url":"https://opendev.org/openstack/oslo.db","tags":["OpenStack","database","SQLAlchemy","ORM","utility","MySQL","PostgreSQL","SQLite"],"install":[{"cmd":"pip install oslo.db","lang":"bash","label":"Base installation"},{"cmd":"pip install PyMySQL","lang":"bash","label":"For MySQL/MariaDB backend (example)"},{"cmd":"sudo apt-get install libpq-dev && pip install psycopg2","lang":"bash","label":"For PostgreSQL backend on Debian/Ubuntu"}],"dependencies":[{"reason":"Runtime environment","package":"Python","min_version":"3.10"},{"reason":"Core ORM functionality","package":"SQLAlchemy","optional":false},{"reason":"MySQL/MariaDB database driver","package":"PyMySQL","optional":true},{"reason":"PostgreSQL database driver","package":"psycopg2","optional":true},{"reason":"SQLite database driver","package":"pysqlite","optional":true}],"imports":[{"note":"Used for managing database sessions and connections.","symbol":"enginefacade","correct":"from oslo_db.sqlalchemy import enginefacade"},{"note":"Provides base classes for SQLAlchemy models, including TimestampMixin.","symbol":"models","correct":"from oslo_db.sqlalchemy import models"},{"note":"The `db_api` module is typically imported with an alias and used for database operations.","wrong":"from oslo_db.api import DBAPI","symbol":"db_api","correct":"from oslo_db import api as db_api"}],"quickstart":{"code":"import os\nfrom sqlalchemy import Column, Integer, String\nfrom oslo_db.sqlalchemy import enginefacade, models\n\n# Configure a simple SQLite database for demonstration\nos.environ['OSLO_DB_CONNECTION'] = 'sqlite:///./test.sqlite'\n\n# Initialize the enginefacade\nenginefacade.configure(\n    sqlite_synchronous=False # For better performance in SQLite, though less safe\n)\n\n# Define a base model for our application\nclass MyModelBase(models.ModelBase, models.TimestampMixin):\n    __abstract__ = True\n\nclass User(MyModelBase):\n    __tablename__ = 'users'\n    id = Column(Integer, primary_key=True, autoincrement=True)\n    name = Column(String(255), nullable=False)\n    email = Column(String(255), unique=True, nullable=False)\n\n    def __repr__(self):\n        return f\"<User(id='{self.id}', name='{self.name}', email='{self.email}')>\"\n\n# Create tables (usually done via migration tools like Alembic in production)\n# For quickstart, we'll create directly if not exists\nwith enginefacade.transaction() as session:\n    MyModelBase.metadata.create_all(session.bind)\n\n# Example usage: adding and querying data\nclass MyContext:\n    pass\n\n@enginefacade.transaction_context_manager\ndef add_user(context, name, email):\n    new_user = User(name=name, email=email)\n    context.session.add(new_user)\n    print(f\"Added user: {new_user}\")\n    return new_user\n\n@enginefacade.reader_context_manager\ndef get_users(context):\n    users = context.session.query(User).all()\n    print(\"All users:\")\n    for user in users:\n        print(f\"- {user}\")\n    return users\n\nif __name__ == '__main__':\n    # Use a dummy context object, as oslo_db often expects one\n    ctx = MyContext()\n\n    add_user(ctx, \"Alice\", \"alice@example.com\")\n    add_user(ctx, \"Bob\", \"bob@example.com\")\n\n    get_users(ctx)\n\n    # Clean up test.sqlite if it exists\n    if os.path.exists('./test.sqlite'):\n        os.remove('./test.sqlite')\n        print(\"Cleaned up test.sqlite\")\n","lang":"python","description":"This quickstart demonstrates how to configure oslo.db with a SQLite backend, define a basic SQLAlchemy model using `oslo_db.sqlalchemy.models.ModelBase` and `TimestampMixin`, and perform basic CRUD operations using `oslo_db.sqlalchemy.enginefacade.transaction_context_manager` and `reader_context_manager`."},"warnings":[{"fix":"Ensure all database interactions leverage `oslo_db.sqlalchemy.enginefacade.transaction()`, `transaction_context_manager`, or `reader_context_manager`.","message":"oslo.db tightly integrates with SQLAlchemy, and direct manipulation of SQLAlchemy session/engine objects outside of oslo.db's `enginefacade` can lead to unexpected behavior or resource leaks. Always use the provided context managers or decorators.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Update `oslo.db` configuration files (e.g., `oslo.conf`) to use the `[database]` section for connection and backend settings. Refer to the specific release notes for your OpenStack version.","message":"The `[DEFAULT]/sql_connection` and `[DEFAULT]/db_backend` configuration options have been deprecated in favor of `[database]/connection` and `[database]/backend` respectively. Using the old options may result in unapplied configurations or future errors.","severity":"breaking","affected_versions":"Introduced in OpenStack Mitaka (oslo.db 4.x), fully deprecated/removed in later versions."},{"fix":"Install the necessary system-level development packages for your chosen database backend before attempting to `pip install` the Python driver (e.g., `sudo apt-get install libpq-dev` for PostgreSQL on Ubuntu).","message":"When using `psycopg2` (PostgreSQL) or `PyMySQL` (MySQL) as backends, system-level development packages (e.g., `libpq-dev` for PostgreSQL, `libmysqlclient-dev` for MySQL) are often required before `pip install` can succeed for the Python packages.","severity":"gotcha","affected_versions":"All versions when installing backend drivers."},{"fix":"Configure `[database]pool_recycle` in your `oslo.db` configuration to be less than your database server's `wait_timeout`. Also, ensure optimistic disconnect handling is enabled or properly managed by the backend driver if applicable. For MySQL, using TCP protocol (`all_tcp = true`) can also mitigate issues.","message":"Handling database connection loss (`DBConnectionError`, 'MySQL server has gone away') requires careful configuration of connection pooling, including `pool_recycle` and `wait_timeout` settings, to ensure idle connections are properly reaped and re-established.","severity":"gotcha","affected_versions":"All versions."}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Adjust the `[database]pool_recycle` option in your `oslo.db` configuration to a value (in seconds) less than the database's `wait_timeout` setting. For example, `pool_recycle = 3600` if `wait_timeout` is 7200 seconds. Also, ensure `all_tcp = true` in relevant service configurations if using MySQL/Designate.","cause":"The database connection was idle for too long and was closed by the MySQL server, or a network issue occurred.","error":"oslo_db.exception.DBConnectionError: (pymysql.err.OperationalError) (2006, \"MySQL server has gone away (BrokenPipeError(32, 'Broken pipe'))\")"},{"fix":"The correct import path for `enginefacade` is `from oslo_db.sqlalchemy import enginefacade`. Ensure `oslo.db` and its dependencies are correctly installed.","cause":"Attempting to import `enginefacade` directly from the top-level `oslo_db` package, or an incorrect `oslo.db` installation.","error":"ImportError: cannot import name 'enginefacade' from 'oslo_db'"},{"fix":"Review application logic for potential deadlock scenarios. Consider optimizing database queries, implementing finer-grained locking, or adjusting transaction isolation levels. In OpenStack, this often indicates a need to scale database resources or optimize service configurations.","cause":"Concurrent database operations led to a deadlock, and oslo.db's retry mechanism was exhausted. This is common in high-concurrency environments, especially during resource-intensive operations like instance creation/deletion in OpenStack services.","error":"oslo_db.exception.DBDeadlock: DB exceeded retry limit."}]}