diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..a640834 --- /dev/null +++ b/.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 diff --git a/.gitignore b/.gitignore index 1543b28..58f8d14 100644 --- a/.gitignore +++ b/.gitignore @@ -5,6 +5,7 @@ ztrash debug.log config.yaml chromedriver.log +.skills # Created by https://www.gitignore.io/api/python diff --git a/.skill-planning/README.generated.md b/.skill-planning/README.generated.md new file mode 100644 index 0000000..79b583b --- /dev/null +++ b/.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`. diff --git a/.skill-planning/repo_marketing_prose.md b/.skill-planning/repo_marketing_prose.md new file mode 100644 index 0000000..f16edae --- /dev/null +++ b/.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 \ No newline at end of file diff --git a/README.md b/README.md index b8f6fb5..9641e64 100644 --- a/README.md +++ b/README.md @@ -1,175 +1,135 @@ -# Docker-DB +# py-dockerdb -A Python library for managing containerized databases through Docker. This library provides a simple interface for creating, configuring, and managing database containers for development and testing environments, from within python. +*Pythonic Docker database management for notebooks, tutorials, and fast MVPs.* -## Features +[![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) -The following features are supported: +`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. -- Easy setup and management of database containers -- Automated container lifecycle management -- Standardized configuration interfaces -- Connection management and health checking -- Volume persistence capabilities -- Initialization script support +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. -The following features are implemented but not tested: -- Enable/Disable error if already created -- startdb -- restartdb -- init scripts to examples +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. -The following databases are supported: - - MongoDB - - Microsoft SQL Server - - PostgreSQL - - MySQL +## When to use this -These databases might be added in the future: -- Cassandra +- **Teaching a SQL workshop or notebook tutorial** - every learner starts from the same environment with no per-machine Docker setup required. +- **Comparing databases for an MVP** - run PostgreSQL, MySQL, MongoDB, and MSSQL under the same Python interface and switch engines without rewriting connection code. +- **Building a local RAG prototype** - spin up a backing store, test your retrieval pipeline, then swap from PostgreSQL to MongoDB in one config change without touching orchestration code. -## Installation +## Supported Databases -```bash -pip install py-dockerdb -``` +[![PostgreSQL](https://img.shields.io/badge/PostgreSQL-4169E1?logo=postgresql&logoColor=white)](https://www.postgresql.org/docs/) +[![MySQL](https://img.shields.io/badge/MySQL-4479A1?logo=mysql&logoColor=white)](https://dev.mysql.com/doc/) +[![MongoDB](https://img.shields.io/badge/MongoDB-47A248?logo=mongodb&logoColor=white)](https://www.mongodb.com/docs/) +[![SQL Server](https://img.shields.io/badge/SQL_Server-CC2927?logo=microsoftsqlserver&logoColor=white)](https://learn.microsoft.com/en-us/sql/sql-server/) -## Requirements +## Prerequisites - Python 3.7+ - Docker installed and running -- Database-specific Python drivers: - - `pymongo` for MongoDB - - `pyodbc` for Microsoft SQL Server - - `psycopg2` for PostgreSQL +- Database drivers (installed automatically with package dependencies): + - `psycopg2-binary` for PostgreSQL - `mysql-connector-python` for MySQL + - `pymongo` for MongoDB + - `pyodbc` for MSSQL -## Basic Usage - -Check out the following usage examples: - -### MongoDB Example - -```python -from docker_db.mongodb import MongoDBConfig, MongoDB - -# Create configuration -config = MongoDBConfig( - user="testuser", - password="testpass", - database="testdb", - root_username="admin", - root_password="adminpass", - container_name="test-mongodb" -) - -# Create and start MongoDB container -db = MongoDB(config) -db.create_db() +## Installation -# Connect to database -client = db.connection -# Use the database... +```bash +pip install py-dockerdb +``` -# Stop the container when done -db.stop_db() +## Usage -# Completely remove the container -db.delete_db() -``` +The API is consistent across all four engines: define a config, call `create_db()`, run your workload, then tear down with `delete_db()`. -### PostgreSQL Example +### PostgreSQL example ```python -from docker_db.postgres import PostgresConfig, PostgresDB +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) -# Create configuration config = PostgresConfig( - user="testuser", - password="testpass", - database="testdb", - container_name="test-postgres" + user="demouser", + password="demopass", + database="demodb", + project_name="demo", + container_name=container_name, + workdir=temp_dir.absolute(), + retries=20, + delay=3, ) -# Create and start PostgreSQL container -db = PostgresDB(config) -db.create_db() - -# Connect to the database -conn = db.connection +db_manager = PostgresDB(config) +db_manager.create_db() -# Create a cursor and execute a query -cursor = conn.cursor() -cursor.execute("SELECT version();") -version = cursor.fetchone() -print(f"PostgreSQL version: {version[0]}") +conn = db_manager.connection +cur = conn.cursor() +cur.execute("SELECT version();") +print(cur.fetchone()) -# Clean up -cursor.close() -db.stop_db() +cur.close() +conn.close() +db_manager.delete_db(running_ok=True) ``` -### Working with Initialization Scripts +### More examples -All database managers support initialization scripts that can be executed when the container is created: +Full runnable notebooks for each engine are in the [`usage/`](./usage/) directory: -```python -from pathlib import Path -from docker_db.mongodb import MongoDBConfig, MongoDB - -config = MongoDBConfig( - user="testuser", - password="testpass", - database="testdb", - root_username="admin", - root_password="adminpass", - container_name="test-mongodb", - init_script=Path("./path/to/init_script.js") -) -``` +- [PostgreSQL](./usage/postgres_example.ipynb) +- [MySQL](./usage/mysql_example.ipynb) +- [MongoDB](./usage/mongo_example.ipynb) +- [MSSQL](./usage/mssql_example.ipynb) +- [Container lifecycle and management](./usage/db_management_example.ipynb) -### Custom Volume Paths +### Seeding data for demos and workshops -You can specify custom volume paths to persist data between container restarts: +Use `init_script` to preload tables or documents before handing the environment to students or running a live demo. ```python -from pathlib import Path -from docker_db.mssql import MSSQLConfig, MSSQLDB - -config = MSSQLConfig( - user="testuser", - password="testpass", - database="testdb", - sa_password="StrongPassword123!", - container_name="test-mssql", - volume_path=Path("./data/mssql") +config = PostgresConfig( + ... + init_script=Path("./configs/postgres/initdb.sh"), ) ``` -### Network Mode and Optional Port Mapping - -You can now run containers with explicit Docker network settings and optionally skip host port publishing. +### SQL magic and client tool integration ```python -from docker_db.postgres_db import PostgresConfig, PostgresDB +conn_string = db_manager.connection_string(sql_magic=True) +``` -config = PostgresConfig( - user="testuser", - password="testpass", - database="testdb", - network_mode="host", # Linux native host networking - port=None, # no host port mapping -) +## Development -db = PostgresDB(config) -db.create_db() +```bash +git clone https://github.com/amadou-6e/docker-db.git +cd docker-db +python -m pip install -e ".[test]" ``` -Notes: -- `network_mode="host"` works natively on Linux. -- On Windows/macOS, host mode falls back to bridge mode. -- If `port=None`, the manager skips host port mapping. +## 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 -This project is licensed under the MIT License - see the LICENSE file for details. +MIT License. See `LICENSE`. \ No newline at end of file diff --git a/docs/Makefile b/docs/Makefile index d4bb2cb..64f5c6c 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -18,3 +18,22 @@ help: # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). %: Makefile @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + + +# Push your branch with these files: +# docs.yml +# requirements.txt +# docs updates +# In GitHub repo: +# Settings → Pages +# Under Build and deployment, set Source to GitHub Actions +# Save +# Merge/push to main (workflow is configured for main pushes), or run manually: +# Actions → Docs → Run workflow +# Wait for both jobs in Docs workflow: +# build +# deploy +# Open deployed site: +# https://.github.io// +# Or use the URL shown in the deploy job output (page_url). +# If you want it to deploy from every branch push, I can adjust docs.yml trigger from main to *. diff --git a/docs/conf.py b/docs/conf.py index 0e6302a..98f30aa 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -7,8 +7,11 @@ # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information import os import sys +from pathlib import Path -sys.path.insert(0, os.path.abspath('../..')) +DOCS_DIR = Path(__file__).resolve().parent +REPO_ROOT = DOCS_DIR.parent +sys.path.insert(0, str(REPO_ROOT)) project = 'py-dockerdb' copyright = '2025, Amadou Wolfgang Cisse' diff --git a/docs/index.rst b/docs/index.rst index 684c956..5012398 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -15,5 +15,7 @@ documentation for details. :maxdepth: 4 :caption: Contents: + introduction + quick_start source/modules.rst diff --git a/docs/introduction.rst b/docs/introduction.rst new file mode 100644 index 0000000..898ecdd --- /dev/null +++ b/docs/introduction.rst @@ -0,0 +1,53 @@ +py-dockerdb +============ + +*Pythonic Docker database management for notebooks, tutorials, and fast MVPs.* + +|Build| |PyPI| |License| + +.. |Build| image:: https://img.shields.io/github/actions/workflow/status/amadou-6e/docker-db/cicd.yml?branch=main&label=tests + :target: https://github.com/amadou-6e/docker-db/actions/workflows/cicd.yml +.. |PyPI| image:: https://img.shields.io/pypi/v/py-dockerdb + :target: https://pypi.org/project/py-dockerdb/ +.. |License| image:: https://img.shields.io/badge/license-MIT-lightgrey + :target: ../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 is not 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. + +Who Is This For +--------------- + +Python instructors and demo authors who need a classroom-ready, reproducible setup across machines and operating systems. The goal is to spend time teaching SQL, workflow design, and experimentation instead of debugging Docker setup in front of learners. + +Learners and MVP builders who want to compare databases quickly with the same Pythonic workflow. You can test PostgreSQL, MySQL, MongoDB, and MSSQL under one lifecycle pattern and decide based on behavior instead of setup overhead. + +RAG and AI prototype builders who need fast local backend swaps during iteration. This workflow supports testing one database option, then changing engines without rebuilding your orchestration from scratch. + +What You Can Do With py-dockerdb +-------------------------------- + +For teaching and workshops, you can provision a real database container from a notebook, run seeded examples, and clean up at the end of class with the same script every learner can run. This keeps lesson flow focused on SQL and data concepts. + +For MVP database comparison, you can run equivalent workflows against multiple engines and evaluate tradeoffs with less glue code. The same lifecycle methods reduce per-engine setup complexity during early product decisions. + +For local RAG prototypes, you can start with one backing database, validate retrieval behavior, then switch to another engine without redesigning your setup process. This keeps experimentation fast when architecture is still changing. + +Where To Go Next +---------------- + +.. toctree:: + :maxdepth: 1 + + quick_start + source/modules + +- Usage notebooks: + `db_management_example.ipynb `_ + `postgres_example.ipynb `_ + `mysql_example.ipynb `_ + `mongo_example.ipynb `_ + `mssql_example.ipynb `_ diff --git a/docs/quick_start.rst b/docs/quick_start.rst new file mode 100644 index 0000000..a4866ef --- /dev/null +++ b/docs/quick_start.rst @@ -0,0 +1,82 @@ +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.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 +------------ + +.. code-block:: bash + + pip install py-dockerdb + +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. + +.. code-block:: 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) + +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 +---------- + +- `db_management_example.ipynb `_: + container lifecycle behavior and restart patterns. +- `postgres_example.ipynb `_: + PostgreSQL setup with SQL notebook flow and seeded data. +- `mysql_example.ipynb `_: + MySQL setup and SQL workflow examples. +- `mongo_example.ipynb `_: + MongoDB CRUD and collection examples. +- `mssql_example.ipynb `_: + MSSQL setup and query workflow. +- API reference: :doc:`source/modules` diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..b46fa87 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,3 @@ +sphinx>=7.0 +sphinx-rtd-theme>=2.0 +sphinx-autodoc-typehints>=2.0 diff --git a/docs/source/docker_db.rst b/docs/source/docker_db.rst index 1e9be32..7ef74a7 100644 --- a/docs/source/docker_db.rst +++ b/docs/source/docker_db.rst @@ -4,58 +4,66 @@ docker\_db package Submodules ---------- -docker\_db.cassandra\_db module +docker\_db.dbs.cassandra\_db module +----------------------------------- + +.. automodule:: docker_db.dbs.cassandra_db + :members: + :show-inheritance: + :undoc-members: + +docker\_db.dbs.mongo\_db module ------------------------------- -.. automodule:: docker_db.cassandra_db +.. automodule:: docker_db.dbs.mongo_db :members: :show-inheritance: :undoc-members: -docker\_db.containers module ----------------------------- +docker\_db.dbs.mssql\_db module +------------------------------- -.. automodule:: docker_db.containers +.. automodule:: docker_db.dbs.mssql_db :members: :show-inheritance: :undoc-members: -docker\_db.mongo\_db module ---------------------------- +docker\_db.dbs.mysql\_db module +------------------------------- -.. automodule:: docker_db.mongo_db +.. automodule:: docker_db.dbs.mysql_db :members: :show-inheritance: :undoc-members: -docker\_db.mssql\_db module ---------------------------- +docker\_db.dbs.postgres\_db module +---------------------------------- -.. automodule:: docker_db.mssql_db +.. automodule:: docker_db.dbs.postgres_db :members: :show-inheritance: :undoc-members: -docker\_db.mysql\_db module ---------------------------- +docker\_db.docker.manager module +-------------------------------- -.. automodule:: docker_db.mysql_db +.. automodule:: docker_db.docker.manager :members: :show-inheritance: :undoc-members: -docker\_db.postgres\_db module +docker\_db.docker.model module ------------------------------ -.. automodule:: docker_db.postgres_db +.. automodule:: docker_db.docker.model :members: :show-inheritance: :undoc-members: -docker\_db.utils module ------------------------ +docker\_db.docker.utils module +------------------------------ -.. automodule:: docker_db.utils +.. automodule:: docker_db.docker.utils :members: :show-inheritance: :undoc-members: diff --git a/etc/dev_requirements.txt b/etc/dev_requirements.txt deleted file mode 100644 index 55b033e..0000000 --- a/etc/dev_requirements.txt +++ /dev/null @@ -1 +0,0 @@ -pytest \ No newline at end of file diff --git a/requirements.txt b/requirements.txt deleted file mode 100644 index da11b5f..0000000 --- a/requirements.txt +++ /dev/null @@ -1,10 +0,0 @@ -psycopg2-binary -docker -pytest -pymongo -pydantic -setuptools -docker -pyodbc -mysql-connector-python -pydos2unix \ No newline at end of file diff --git a/setup.py b/setup.py index 0c04f33..b19530b 100644 --- a/setup.py +++ b/setup.py @@ -1,35 +1,5 @@ -from pathlib import Path -from setuptools import setup, find_packages +from setuptools import setup -curr_file = Path(__file__).parent.resolve() - -def parse_requirements(filename): - return [ - line for line in Path(filename).read_text().splitlines() - if line and not line.startswith("#") - ] - - -setup( - name="py-dockerdb", - version="0.8.0", - author="Amadou Wolfgang Cisse", - author_email="amadou.6e@googlemail.com", - description="Python package for working with databases in Docker containers", - long_description_content_type="text/markdown", - url="https://github.com/amadou-6e/docker-db.git", - packages=find_packages(), - classifiers=[ - "Programming Language :: Python :: 3", - "Operating System :: OS Independent", - "Topic :: Database", - "Topic :: Software Development :: Libraries :: Python Modules", - ], - python_requires=">=3.6", - install_requires=parse_requirements("requirements.txt"), - include_package_data=True, - package_data={ - "docker_db": ["tests/data/configs/*/*"], - }, -) +# Use metadata from pyproject.toml (PEP 621). +setup()