========
Database
========

Module: `thinkiq.database`
===========================

.. automodule:: thinkiq.database
.. currentmodule:: thinkiq.database

:class:`Database`
-----------------

.. autoclass:: Database
   :members:
   :undoc-members:
   :show-inheritance:

Description
-----------

The :class:`Database` class provides a single access point to PostgreSQL:

- **Connection management**
  - Persistent or per-call connection modes
  - Health-check and auto-reconnect
- **Centralized query helpers**
  - ``query_one`` – fetch a single row as a dict
  - ``query_all`` – fetch multiple rows as a list of dicts
  - ``execute_non_query`` – execute INSERT/UPDATE/DELETE/DDL
- **Caching**
  - Built-in TTL cache for SELECT queries
  - Automatic invalidation on writes
- **Profiling and logging**
  - Logs queries and execution time with optional tags

Example
-------

.. code-block:: python

    from thinkiq.database import Database

    # Create a database access object
    db = Database(persist_connection=True)

    # Get a connection (auto-reconnect enabled)
    conn = db.get_connection()

    # Run queries
    row = db.query_one("SELECT * FROM users WHERE id=%s", (123,))
    rows = db.query_all("SELECT * FROM users")

    # Insert/update
    db.execute_non_query("UPDATE users SET name=%s WHERE id=%s", ("Alice", 123))

    # Disconnect safely
    db.disconnect()