Logging in PostgreSQL¶

PostgreSQL is a powerful, open-source relational database system with a strong reputation for reliability, feature robustness, and performance.

TruLens can write and read from a PostgreSQL database using SQLAlchemy. This allows you to read, write, persist and share TruLens logs in a PostgreSQL database.

Here is a guide to logging in PostgreSQL.

Prerequisites¶

Install PostgreSQL Driver¶

TruLens requires a synchronous PostgreSQL driver. Install one of the following:

Install using pip

# Recommended: psycopg2-binary (includes compiled binaries)
pip install psycopg2-binary

# Alternative: psycopg2 (requires PostgreSQL dev libraries)
pip install psycopg2

# Alternative: psycopg v3
pip install psycopg

Do NOT use asyncpg

asyncpg is not supported. It is an async-only driver and is incompatible with TruLens's synchronous SQLAlchemy operations. Using asyncpg will result in a MissingGreenlet error.

Start PostgreSQL (Optional: Docker)¶

If you don't have a PostgreSQL instance, you can start one using Docker:

docker run -d \
    --name trulens-postgres \
    -e POSTGRES_DB=trulens \
    -e POSTGRES_USER=trulensuser \
    -e POSTGRES_PASSWORD=password \
    -p 5432:5432 \
    postgres:15-alpine

Connect TruLens to PostgreSQL¶

Using a Database URL¶

The simplest way to connect is with a database URL in the format: postgresql://username:password@host:port/database

Connect TruLens to PostgreSQL

from trulens.core import TruSession

session = TruSession(
    database_url="postgresql://trulensuser:password@localhost:5432/trulens"
)

After which you should see:

🦑 Initialized with db url postgresql://trulensuser:***@localhost:5432/trulens.

Using a Database Engine¶

For more control over the connection (e.g., SSL settings, connection pooling), create a SQLAlchemy engine:

Connect TruLens to PostgreSQL with SSL

from trulens.core import TruSession
from sqlalchemy import create_engine

engine = create_engine(
    "postgresql://trulensuser:password@localhost:5432/trulens",
    connect_args={"sslmode": "require"},
)

session = TruSession(database_engine=engine)

Using Environment Variables (Recommended for Production)¶

Connect using environment variables

import os
from trulens.core import TruSession

session = TruSession(
    database_url=os.environ["DATABASE_URL"],
    database_redact_keys=True,  # Recommended: redact sensitive data
)

Connection URL Formats¶

TruLens supports various PostgreSQL connection URL formats:

Format	Example
Basic	`postgresql://user:pass@host:port/db`
With psycopg2	`postgresql+psycopg2://user:pass@host:port/db`
With psycopg v3	`postgresql+psycopg://user:pass@host:port/db`
With SSL	`postgresql://user:pass@host:port/db?sslmode=require`

Full Example¶

For a complete working example, see the Log in PostgreSQL notebook.