Feat release flow

.github/workflows/cicd.yml

@@ -4,6 +4,8 @@ on:
   push:
     branches:
       - "*"
+  release:
+    types: [published]
 
 permissions:
   contents: read
@@ -71,3 +73,31 @@ jobs:
 
       - name: Run tests
         run: python -m pytest -vv -s --timeout=600 --timeout-method=thread ${{ matrix.test_file }}
+
+  publish:
+    name: Publish to PyPI
+    needs: tests
+    runs-on: ubuntu-latest
+    if: github.event_name == 'release' && github.event.action == 'published'
+    environment:
+      name: pypi
+      url: https://pypi.org/p/py-dockerdb
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build package
+        run: |
+          python -m pip install build
+          python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

.gitignore

@@ -1,11 +1,15 @@
 env/
 venv/
 .venv
+.claude
 ztrash
 debug.log
 config.yaml
 chromedriver.log
 .skill*
+experiments/
+tmp/
+
 
 
 # Created by https://www.gitignore.io/api/python
@@ -131,4 +135,4 @@ message.txt
 # End of https://www.gitignore.io/api/python
 /logs
 /pgdata
-entrypoint.log
+entrypoint.log

README.md

@@ -5,57 +5,110 @@
 [![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)
+[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://amadou-6e.github.io/py-docker/introduction.html)
 
-`py-dockerdb` gives you easy Docker database setup in Python for PostgreSQL, MySQL, MongoDB, Microsoft SQL Server, Redis, Cassandra, Neo4j, OpenSearch, Qdrant, and Ollama. It is built for people who teach, demo, and prototype with notebooks or scripts and need repeatable local databases in minutes.
+```bash
+pip install py-dockerdb
+```
+
+`py-dockerdb` gives you one Python API to create, connect, and clean up Docker
+databases: PostgreSQL, MySQL, MongoDB, MSSQL, Redis, Neo4j, and Ollama. It is built
+for people who teach, demo, and prototype with notebooks and need repeatable local
+databases in seconds.
+
+Switch from PostgreSQL to MongoDB without changing a line of connection code. Test
+a pgvector RAG pipeline, then swap to Neo4j for GraphRAG with one config change.
+Or hand every student a pre-seeded database at the start of class without touching
+Docker on their machine.
 
 ## When to use this
 
-- **Teaching workshops**: every learner starts from the same environment.
-- **Comparing databases for an MVP**: switch backends with minimal code changes.
-- **Local RAG / GraphRAG prototyping**: run vector and graph backends locally.
-- **Local LLM experiments**: use Ollama in Docker for model-serving workflows.
+- **Teaching a SQL workshop:** two lines give every learner a working, pre-seeded
+  database, identical across Windows/Mac/Linux.
+- **Comparing databases for an MVP:** run Postgres, MongoDB, Redis, and Neo4j
+  through the same interface and pick based on behaviour, not setup time.
+- **Local RAG prototype:** spin up pgvector, validate retrieval, swap to another
+  backend in one config change without touching orchestration code.
+- **GraphRAG with Neo4j:** `Neo4jDB.connection` returns a `neo4j.Driver` that
+  plugs directly into LlamaIndex's `Neo4jGraphStore` and LangChain's `Neo4jGraph`.
 
 ## Supported Databases
 
-- PostgreSQL
-- MySQL
-- MongoDB
-- Microsoft SQL Server
-- Redis
-- Cassandra
-- Neo4j
-- OpenSearch
-- Qdrant
-- Ollama
+[![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/)
+[![Redis](https://img.shields.io/badge/Redis-DC382D?logo=redis&logoColor=white)](https://redis.io/docs/)
+[![Neo4j](https://img.shields.io/badge/Neo4j-008CC1?logo=neo4j&logoColor=white)](https://neo4j.com/docs/)
+[![Ollama](https://img.shields.io/badge/Ollama-000000?logo=ollama&logoColor=white)](https://ollama.com/library)
 
 ## Prerequisites
 
-- Python 3.10+
-- Docker installed and running
+- Python 3.10+ · Docker running
 
 ## Installation
 
 ```bash
-# Core
-pip install py-dockerdb
-
-# Graph/RAG extras
-pip install "py-dockerdb[graph,rag]"
+pip install py-dockerdb                # core
+pip install "py-dockerdb[graph]"       # + Neo4j / LlamaIndex / LangChain
+pip install "py-dockerdb[rag]"         # + pgvector / LlamaIndex
 ```
 
 ## Usage
 
-The API is consistent across engines: define a config, call `create_db()`, run your workload, then tear down with `delete_db()`.
+Define a config, call `create_db()`, run your workload, tear down with `delete_db()`.
+
+### PostgreSQL
+
+```python
+from docker_db.dbs.postgres_db import PostgresConfig, PostgresDB
+
+db = PostgresDB(PostgresConfig(user="u", password="p", database="d", project_name="demo"))
+db.create_db()
+conn = db.connection          # psycopg2 connection
+cur = conn.cursor()
+cur.execute("SELECT version();")
+print(cur.fetchone())
+db.delete_db(running_ok=True)
+```
+
+
+### Neo4j / GraphRAG
+
+```python
+from docker_db.dbs.neo4j_db import Neo4jConfig, Neo4jDB
+
+db = Neo4jDB(Neo4jConfig(password="p", project_name="demo"))
+db.create_db()
+driver = db.connection        # neo4j.Driver -> hand to Neo4jGraphStore or Neo4jGraph
+with driver.session() as s:
+    s.run("CREATE (n:Person {name: 'Alice'})")
+    print(s.run("MATCH (n:Person) RETURN n.name").single()[0])
+db.delete_db(running_ok=True)
+```
+
+### Ollama
+
+```python
+from docker_db.dbs.ollama_db import OllamaConfig, OllamaDB
+
+db = OllamaDB(OllamaConfig(project_name="demo"))
+db.create_db()
+session = db.connection       # requests.Session
+db.pull_model("llama3")
+resp = session.post(f"{db.base_url}/api/generate", json={"model": "llama3", "prompt": "Hello", "stream": False})
+print(resp.json()["response"])
+db.delete_db(running_ok=True)
+```
+
+### More examples
 
-See runnable notebooks in [`usage/`](./usage/):
+Full runnable notebooks are in [`usage/`](./usage/):
 
-- `postgres_example.ipynb`
-- `mysql_example.ipynb`
-- `mongo_example.ipynb`
-- `mssql_example.ipynb`
-- `redis_example.ipynb`
-- `neo4j_example.ipynb`
-- `ollama_example.ipynb`
+[PostgreSQL](./usage/postgres_example.ipynb) · [MySQL](./usage/mysql_example.ipynb)
+· [MongoDB](./usage/mongo_example.ipynb) · [MSSQL](./usage/mssql_example.ipynb)
+· [Redis](./usage/redis_example.ipynb) · [Neo4j / GraphRAG](./usage/neo4j_example.ipynb)
+· [pgvector RAG](./usage/pgvector_rag_example.ipynb) · [Lifecycle](./usage/db_management_example.ipynb)
 
 ## Roadmap
 
@@ -71,7 +124,7 @@ See runnable notebooks in [`usage/`](./usage/):
 ```bash
 git clone https://github.com/amadou-6e/docker-db.git
 cd docker-db
-python -m pip install -e ".[test]"
+pip install -e ".[test]"
 ```
 
 ## Testing
@@ -94,7 +147,7 @@ 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 `usage/` notebooks when applicable.
+PRs welcome. Include tests for behaviour changes and keep notebooks runnable.
 
 ## License
 

docs/introduction.rst

@@ -12,7 +12,7 @@ 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, Microsoft SQL Server, Redis, and Neo4j. 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.
+``py-dockerdb`` gives you easy Docker database setup in Python for PostgreSQL, MySQL, MongoDB, Microsoft SQL Server, Redis, Neo4j, and Ollama. It is built for people who teach, demo, and prototype with notebooks or scripts and need repeatable local databases in seconds. 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 and GraphRAG experiments where you want to test one storage backend, then swap it out without rewriting environment glue.
 

docs/quick_start.rst

@@ -6,7 +6,7 @@ By the end of this page, you will have a running PostgreSQL container managed fr
 Prerequisites
 -------------
 
-- Python 3.7+
+- Python 3.10+
 - Docker installed and running
 - Database drivers (installed automatically with package dependencies):
   - ``psycopg2-binary`` for PostgreSQL
@@ -19,7 +19,9 @@ Installation
 
 .. code-block:: bash
 
-   pip install py-dockerdb
+   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
 -------------------------------
@@ -83,4 +85,8 @@ Next Steps
   Redis key-value store and caching examples.
 - `neo4j_example.ipynb <https://github.com/amadou-6e/docker-db/blob/main/usage/neo4j_example.ipynb>`_:
   Neo4j knowledge graph setup, node/relationship queries, and GraphRAG with LlamaIndex.
+- `pgvector_rag_example.ipynb <https://github.com/amadou-6e/docker-db/blob/main/usage/pgvector_rag_example.ipynb>`_:
+  pgvector RAG pipeline with LlamaIndex vector store.
+- `ollama_example.ipynb <https://github.com/amadou-6e/docker-db/blob/main/usage/ollama_example.ipynb>`_:
+  Ollama local LLM container setup and model inference.
 - API reference: :doc:`source/modules`

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "py-dockerdb"
-version = "0.9.0"
+version = "1.0.0"
 description = "Provision Docker databases in Python — Postgres, Neo4j, MongoDB, MySQL, MSSQL with a unified one-call API"
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.10"

usage/mongo_example.ipynb

@@ -123,15 +123,7 @@
    "id": "cb34a6dc",
    "metadata": {},
    "outputs": [],
-   "source": [
-    "import tempfile\n",
-    "import os\n",
-    "temp_dir = Path(\"tmp\")\n",
-    "temp_dir.mkdir(exist_ok=True)\n",
-    "container_name = f\"demo-mongodb-{uuid.uuid4().hex[:8]}\"\n",
-    "init_script_path = Path(\"configs\", \"mongodb\", \"init.js\")\n",
-    "init_script_path.exists()"
-   ]
+   "source": "import tempfile\ntemp_dir = Path(tempfile.mkdtemp())\ncontainer_name = f\"demo-mongodb-{uuid.uuid4().hex[:8]}\"\ninit_script_path = Path(\"configs\", \"mongodb\", \"init.js\")\ninit_script_path.exists()"
   },
   {
    "cell_type": "markdown",
@@ -629,4 +621,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 5
-}
+}

usage/mssql_example.ipynb

@@ -127,15 +127,7 @@
    "id": "fbf5b274",
    "metadata": {},
    "outputs": [],
-   "source": [
-    "import tempfile\n",
-    "import os\n",
-    "temp_dir = Path(\"tmp\").absolute()\n",
-    "temp_dir.mkdir(exist_ok=True)\n",
-    "container_name = f\"demo-mssql-{uuid.uuid4().hex[:8]}\"\n",
-    "init_script_path = Path(\"configs\", \"mssql\", \"initdb.sql\")\n",
-    "init_script_path.exists()"
-   ]
+   "source": "import tempfile\ntemp_dir = Path(tempfile.mkdtemp())\ncontainer_name = f\"demo-mssql-{uuid.uuid4().hex[:8]}\"\ninit_script_path = Path(\"configs\", \"mssql\", \"initdb.sql\")\ninit_script_path.exists()"
   },
   {
    "cell_type": "markdown",
@@ -543,4 +535,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 5
-}
+}