Quickstart

By the end of this page, you will have a running PostgreSQL container managed from Python, execute a query, and cleanly tear everything down.

Prerequisites

  • Python 3.10+

  • Docker installed and running

  • Database drivers (installed automatically with package dependencies): - psycopg2-binary for PostgreSQL - mysql-connector-python for MySQL - pymongo for MongoDB - pyodbc for MSSQL

Installation

pip install py-dockerdb                # core
pip install "py-dockerdb[graph]"       # + Neo4j / LlamaIndex / LangChain
pip install "py-dockerdb[rag]"         # + pgvector / LlamaIndex

Your First py-dockerdb Workflow

This example uses the canonical README workflow for instructors, learners, and MVP builders: configure a database, create it, run a query, then clean up so your machine and class environment stay reproducible.

import uuid
from pathlib import Path
from docker_db.dbs.postgres_db import PostgresConfig, PostgresDB

container_name = f"demo-postgres-{uuid.uuid4().hex[:8]}"
temp_dir = Path("tmp")
temp_dir.mkdir(exist_ok=True)

config = PostgresConfig(
    user="demouser",
    password="demopass",
    database="demodb",
    project_name="demo",
    container_name=container_name,
    workdir=temp_dir.absolute(),
    retries=20,
    delay=3,
)

db_manager = PostgresDB(config)
db_manager.create_db()

conn = db_manager.connection
cur = conn.cursor()
cur.execute("SELECT version();")
print(cur.fetchone())

cur.close()
conn.close()
db_manager.delete_db(running_ok=True)

The script provisions the containerized database, connects with the configured user, runs a real SQL query, prints the result, and removes the running container at the end.

What Just Happened

You used the core lifecycle pattern visible across the library: define a config object, call create_db() to provision and wait for readiness, use the connection for your workload, then call teardown (delete_db(running_ok=True) in this example). This pattern keeps workshop and MVP environments reproducible because setup and cleanup are explicit in the same script.

Next Steps