Docs deploy sphinx

.github/workflows/docs.yml

@@ -0,0 +1,61 @@
+name: Docs
+
+on:
+  push:
+    branches:
+      - main
+      - docs*
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: |
+            pyproject.toml
+            docs/requirements.txt
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e .
+          python -m pip install -r docs/requirements.txt
+
+      - name: Build docs
+        run: sphinx-build -b html docs docs/_build/html
+
+      - name: Configure Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/_build/html
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -5,6 +5,7 @@ ztrash
 debug.log
 config.yaml
 chromedriver.log
+.skills
 
 
 # Created by https://www.gitignore.io/api/python

.skill-planning/README.generated.md

@@ -0,0 +1,239 @@
+# py-dockerdb
+
+*Pythonic Docker database management for notebooks, tutorials, and fast MVPs.*
+
+[![Build](https://img.shields.io/github/actions/workflow/status/amadou-6e/docker-db/cicd.yml?branch=main&label=tests)](https://github.com/amadou-6e/docker-db/actions/workflows/cicd.yml)
+[![PyPI](https://img.shields.io/pypi/v/py-dockerdb)](https://pypi.org/project/py-dockerdb/)
+[![License](https://img.shields.io/badge/license-MIT-lightgrey)](./LICENSE)
+
+`py-dockerdb` gives you easy Docker database setup in Python for PostgreSQL, MySQL, MongoDB, and Microsoft SQL Server. It is built for people who teach, demo, and prototype with notebooks or scripts and need repeatable local databases in minutes. Instead of writing Docker commands and per-engine setup code, you use one API to create, start, connect, and clean up containers.
+
+Switch from PostgreSQL to MongoDB and back without changing a line of connection code. This makes side-by-side database comparison a first-class workflow - useful for MVPs where the right engine isn't decided yet, and for RAG experiments where you want to test one storage backend, then swap it out without rewriting environment glue.
+
+If you teach SQL or data workflows, it removes the environment-setup section from your slides entirely: every student runs the same two lines and gets a working database.
+
+`py-dockerdb` is designed for instructors and demo authors who need classroom-ready environments that start consistently on student machines. The same workflow also supports learners and MVP builders who want to compare databases quickly, plus local RAG prototype builders who need to swap backends without reworking setup scripts. You focus on teaching, experimenting, and comparing outcomes while the library handles container lifecycle and connection setup.
+
+## When to use this
+
+- **Teaching a SQL workshop or notebook tutorial** - use easy docker database setup in Python so every learner starts from the same environment with minimal setup friction.
+- **Comparing databases for an MVP** - run a quick mvp database comparison in python across PostgreSQL, MySQL, MongoDB, and MSSQL with one pythonic docker database management flow.
+- **Building a local RAG prototype** - do local rag database setup python-first, then swap from a rag prototype postgres docker setup to rag prototype mongodb docker without changing your orchestration style.
+
+## Prerequisites
+
+- Python 3.7+
+- 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
+
+```bash
+pip install py-dockerdb
+```
+
+For development:
+
+```bash
+python -m pip install -e ".[test]"
+```
+
+## Usage
+
+If you are teaching, demoing, or doing an MVP database comparison in python, start with the same pattern for each engine: define config, `create_db()`, run your workload, then teardown.
+
+### PostgreSQL notebook workflow
+
+```python
+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)
+```
+
+### MySQL notebook workflow
+
+```python
+import uuid
+from pathlib import Path
+from docker_db.dbs.mysql_db import MySQLConfig, MySQLDB
+
+container_name = f"demo-mysql-{uuid.uuid4().hex[:8]}"
+temp_dir = Path("tmp")
+temp_dir.mkdir(exist_ok=True)
+
+config = MySQLConfig(
+    user="demouser",
+    password="demopass",
+    database="demodb",
+    root_password="rootpass",
+    project_name="demo",
+    workdir=temp_dir,
+    container_name=container_name,
+    retries=20,
+    delay=3,
+)
+
+db_manager = MySQLDB(config)
+db_manager.create_db()
+
+conn = db_manager.connection
+cur = conn.cursor()
+cur.execute("SELECT 1;")
+print(cur.fetchone())
+
+cur.close()
+conn.close()
+db_manager.delete_db(running_ok=True)
+```
+
+### MongoDB notebook workflow
+
+```python
+import uuid
+from pathlib import Path
+from docker_db.dbs.mongo_db import MongoDBConfig, MongoDB
+
+container_name = f"demo-mongodb-{uuid.uuid4().hex[:8]}"
+temp_dir = Path("tmp")
+temp_dir.mkdir(exist_ok=True)
+
+config = MongoDBConfig(
+    user="demouser",
+    password="demopass",
+    database="demodb",
+    root_username="admin",
+    root_password="adminpass",
+    project_name="demo",
+    workdir=temp_dir,
+    container_name=container_name,
+    retries=20,
+    delay=3,
+)
+
+db_manager = MongoDB(config)
+db_manager.create_db()
+
+client = db_manager.connection
+db = client[config.database]
+print(db.list_collection_names())
+
+client.close()
+db_manager.delete_db(running_ok=True)
+```
+
+### MSSQL notebook workflow
+
+```python
+import uuid
+from pathlib import Path
+from docker_db.dbs.mssql_db import MSSQLConfig, MSSQLDB
+
+container_name = f"demo-mssql-{uuid.uuid4().hex[:8]}"
+temp_dir = Path("tmp").absolute()
+temp_dir.mkdir(exist_ok=True)
+
+config = MSSQLConfig(
+    user="demouser",
+    host="127.0.0.1",
+    password="Demo_Pass123",
+    database="demodb",
+    sa_password="StrongPass123!",
+    project_name="demo",
+    workdir=temp_dir,
+    container_name=container_name,
+    retries=20,
+    delay=3,
+)
+
+db_manager = MSSQLDB(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)
+```
+
+### Initialization scripts for seeded demos
+
+Use `init_script` to preload tables or documents for lessons and live demos.
+
+```python
+from pathlib import Path
+from docker_db.dbs.postgres_db import PostgresConfig
+
+config = PostgresConfig(
+    user="demouser",
+    password="demopass",
+    database="demodb",
+    init_script=Path("./configs/postgres/initdb.sh"),
+)
+```
+
+### SQL magic or client integration
+
+Notebook examples include connection string helpers for SQL magic workflows.
+
+```python
+conn_string = db_manager.connection_string(sql_magic=True)
+```
+
+## Development
+
+```bash
+python -m pip install -e ".[test]"
+```
+
+## Testing
+
+```bash
+python -m pytest -vv -s tests/test_manager.py
+python -m pytest -vv -s tests/test_postgres.py
+python -m pytest -vv -s tests/test_mysql.py
+python -m pytest -vv -s tests/test_mongodb.py
+python -m pytest -vv -s tests/test_mssql.py
+python -m pytest -vv -s tests/test_notebooks.py
+```
+
+## Contributing
+
+Pull requests are welcome. Please include tests for behavior changes and keep examples runnable in the `usage/` notebooks when applicable.
+
+## License
+
+MIT License. See `LICENSE`.

.skill-planning/repo_marketing_prose.md

@@ -0,0 +1,77 @@
+# Marketing Prose: py-dockerdb
+
+**Target audience:** Python instructors and demo authors (primary), learners and MVP builders comparing databases (secondary)
+**Keyword targets:** python notebook docker database, jupyter database tutorial, easy docker database setup python, pythonic sql database setup, pythonic docker database management, mvp database comparison python, compare postgres mysql mongodb mssql, local rag database setup python, rag prototype postgres docker, rag prototype mongodb docker
+
+---
+
+## 1. README Hero Section
+
+# py-dockerdb
+
+*Pythonic Docker database management for notebooks, tutorials, and fast MVPs.*
+
+[![Build](https://img.shields.io/badge/build-passing-brightgreen)](https://github.com/your-org/py-dockerdb/actions)
+[![PyPI](https://img.shields.io/badge/pypi-v0.8.0-blue)](https://pypi.org/project/py-dockerdb/)
+[![License](https://img.shields.io/badge/license-MIT-lightgrey)](./LICENSE)
+
+`py-dockerdb` gives you easy Docker database setup in Python for PostgreSQL, MySQL, MongoDB, and Microsoft SQL Server. It is built for people who teach, demo, and prototype with notebooks or scripts and need repeatable local databases in minutes. Instead of writing Docker commands and per-engine setup code, you use one API to create, start, connect, and clean up containers.
+
+Switch from PostgreSQL to MongoDB and back without changing a line of connection code. This makes side-by-side database comparison a first-class workflow - useful for MVPs where the right engine isn't decided yet, and for RAG experiments where you want to test one storage backend, then swap it out without rewriting environment glue.
+
+If you teach SQL or data workflows, it removes the environment-setup section from your slides entirely: every student runs the same two lines and gets a working database.
+
+---
+
+## 2. PyPI Long Description Intro
+
+py-dockerdb is a Python package for easy Docker database setup across PostgreSQL, MySQL, MongoDB, and Microsoft SQL Server. It gives you a pythonic SQL database setup workflow for notebooks, tutorials, and MVPs: define a config, create the containerized database, connect, and tear it down with the same interface. For instructors and demo authors, this removes repetitive environment prep and makes sessions reproducible on local machines and CI. For learners and builders, it simplifies side-by-side database comparison and rapid prototyping, including local RAG database setup in Python when you want to test different storage options quickly.
+
+---
+
+## 3. GitHub "About" One-Liner
+
+Spin up PostgreSQL, MySQL, MongoDB, or MSSQL from a notebook in two lines - no Docker commands, no per-engine setup code.
+
+---
+
+## 4. Social Share Blurb
+
+If you teach SQL or run data workshops, `py-dockerdb` lets you drop the environment setup section from your slides entirely - every student runs two lines and gets a working database. It also handles side-by-side engine comparison and local RAG prototypes across PostgreSQL, MySQL, MongoDB, and MSSQL. One interface, no Docker commands, no per-engine glue.
+
+---
+
+## 5. Documentation Meta Description
+
+py-dockerdb provides easy Docker database setup in Python for notebooks, tutorials, MVP database comparison, and quick local RAG prototypes across SQL and NoSQL.
+
+---
+
+## Audience Cards Considered
+
+> These were the candidate audiences evaluated in Phase 1. Preserved here so you can
+> revisit targeting without starting from scratch.
+
+### Audience: Python instructors and demo authors
+**Who they are:** Developers and educators who teach SQL, data engineering, or backend workflows via notebooks, workshops, or recorded tutorials. They spend significant prep time on environment setup before a session even starts.
+**Their pain point:** Every student has a different machine. Docker commands differ by OS, per-engine setup varies, and one broken environment derails a class. They need something reproducible that doesn't require a Docker explanation mid-lesson.
+**Why this framing works:** py-dockerdb removes the environment section from the lesson plan entirely. That's a tangible time saving with a clear before/after.
+**Where they gather:** Real Python, YouTube (Corey Schafer, Tech With Tim), PyData conferences, r/learnpython, Jupyter community forum, O'Reilly learning platform.
+**Elevator pitch:** Stop writing Docker setup instructions in your README. py-dockerdb gives every student a running PostgreSQL, MySQL, MongoDB, or MSSQL instance in two lines of Python - same result, every machine.
+**Keywords they search for:** jupyter database tutorial, python classroom database setup, reproducible notebook database, docker database python teaching
+
+### Audience: Learners and MVP builders comparing databases
+**Who they are:** Developers building early-stage products or working through database selection. They know Python but may not have deep Docker or DBA experience. They want to test PostgreSQL vs MongoDB vs MSSQL without provisioning cloud infrastructure.
+**Their pain point:** Comparing databases locally means learning each engine's Docker image, port conventions, and connection string format separately. The comparison work drowns in environment work.
+**Why this framing works:** A single interface across all four engines turns a multi-day yak-shave into an afternoon experiment.
+**Where they gather:** Hacker News (Show HN), r/Python, r/dataengineering, Indie Hackers, Dev.to, Discord servers for FastAPI / SQLAlchemy.
+**Elevator pitch:** Switch from PostgreSQL to MongoDB and back without changing a line of connection code. py-dockerdb makes database comparison a one-afternoon experiment instead of a multi-engine setup project.
+**Keywords they search for:** compare postgres mysql mongodb python, local database comparison python, mvp database setup python, easy docker database python
+
+### Audience: RAG and AI prototype builders
+**Who they are:** ML engineers and applied AI developers spinning up retrieval-augmented generation prototypes. They need a vector-capable or document store backend fast, want to swap it out if it doesn't fit, and don't want to manage infrastructure while the architecture is still fluid.
+**Their pain point:** Setting up and tearing down database backends during prototyping is friction that interrupts the actual experiment. Cloud databases add latency and cost during iteration.
+**Why this framing works:** Local, disposable, swappable databases are exactly what RAG prototyping needs. py-dockerdb frames this as a feature, not a workaround.
+**Where they gather:** LangChain Discord, LlamaIndex community, Hugging Face forums, r/LocalLLaMA, AI-focused newsletters (The Batch, TLDR AI).
+**Elevator pitch:** Run your RAG prototype against PostgreSQL with pgvector, then swap to MongoDB Atlas-compatible local storage in one config change. py-dockerdb keeps your local AI experiments clean and reproducible without touching cloud infrastructure.
+**Keywords they search for:** local rag database setup python, rag prototype postgres docker, pgvector local python, mongodb rag prototype local