odoo-dev 0.3.3__tar.gz → 0.4.0__tar.gz

odoo_dev-0.4.0/.github/workflows/release-please.yml

@@ -0,0 +1,43 @@
+name: Release
+
+on:
+  push:
+    branches: [master]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+      tag_name: ${{ steps.release.outputs.tag_name }}
+    steps:
+      # Maintains a release PR from Conventional Commits; when that PR is merged
+      # it creates the git tag + GitHub release and sets release_created=true.
+      - uses: googleapis/release-please-action@v4
+        id: release
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          # release-please-config.json and .release-please-manifest.json are
+          # read from the repo root by default.
+
+  publish:
+    needs: release-please
+    if: ${{ needs.release-please.outputs.release_created == 'true' }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write   # OIDC: mint a short-lived token for PyPI Trusted Publishing
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - name: Build sdist + wheel
+        run: uv build
+      - name: Publish to PyPI (Trusted Publishing / OIDC)
+        run: uv publish --trusted-publishing always

odoo_dev-0.4.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.4.0"
+}

odoo_dev-0.4.0/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## [0.4.0](https://github.com/bemade/odoo-dev/compare/v0.3.3...v0.4.0) (2026-06-11)
+
+
+### Features
+
+* configurable DB connection + connectivity preflight ([#3](https://github.com/bemade/odoo-dev/issues/3)) ([632738e](https://github.com/bemade/odoo-dev/commit/632738e37c1d22d79ec4a03cba72a28ca580f7c8))

{odoo_dev-0.3.3 → odoo_dev-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: odoo-dev
-Version: 0.3.3
+Version: 0.4.0
 Summary: Odoo Development Environment Helper
 Project-URL: Homepage, https://git.bemade.org/bemade/odoo-dev
 Project-URL: Repository, https://git.bemade.org/bemade/odoo-dev
@@ -55,9 +55,10 @@ Docker at the end — answer "no" if you only want the local venv workflow.
 ## Database setup (read this before your first `run`/`test`)
 
 The generated `conf/odoo.conf` connects as PostgreSQL user **`odoo`** over the local
-socket. You need a running PostgreSQL server and a matching role. `setup` installs
-PostgreSQL but does **not** start it or create the role, so on a fresh machine do this
-once:
+socket. You need a running PostgreSQL server and a matching role. `setup` never creates
+the role, and what it installs differs by OS — on **macOS** it installs the server (but
+does **not** start it); on **Linux** it installs only the PostgreSQL *client* (so you
+supply the server yourself). On a fresh machine do this once:
 
 **macOS (Homebrew):**
 
@@ -68,14 +69,23 @@ createuser -s odoo                         # create the role odoo.conf expects
 #   export PATH="$(brew --prefix postgresql@18)/bin:$PATH"
 ```
 
-**Debian/Ubuntu:**
+**Debian/Ubuntu:** install a server if you don't already have one (or point
+`conf/odoo.conf` at an existing / remote / Docker PostgreSQL):
 
 ```bash
+sudo apt-get install postgresql     # if you don't already have a server
 sudo systemctl start postgresql
 sudo -u postgres createuser -s odoo
 ```
 
-You can change the DB user/password in `conf/odoo.conf` if you prefer a different role.
+**Using a different / remote / Docker PostgreSQL:** set `DB_HOST`, `DB_PORT`,
+`DB_USER`, `DB_PASSWORD` in `.env` before running `setup` (it writes them into
+`conf/odoo.conf`), or edit `conf/odoo.conf` directly. With no `DB_HOST`, odoo-dev
+connects over the local socket as the `odoo` role.
+
+Before launching, `run`/`test`/`shell`/`update` run a quick connection preflight: if
+the server is unreachable, the role is missing, or authentication fails, you get a
+specific one-line fix instead of a stack trace.
 
 ## Commands
 
@@ -152,6 +162,14 @@ Create a `.env` file in your project root:
 ```bash
 ODOO_VERSION=19.0
 PYTHON_VERSION=3.12
+
+# Optional — DB connection, written into conf/odoo.conf by `setup`.
+# Omit DB_HOST/DB_PORT to use the local socket (the default). Set these to
+# point at a remote / Docker / non-default PostgreSQL:
+# DB_HOST=localhost
+# DB_PORT=5432
+# DB_USER=odoo
+# DB_PASSWORD=odoo
 ```
 
 ## Requirements

{odoo_dev-0.3.3 → odoo_dev-0.4.0}/README.md

@@ -41,9 +41,10 @@ Docker at the end — answer "no" if you only want the local venv workflow.
 ## Database setup (read this before your first `run`/`test`)
 
 The generated `conf/odoo.conf` connects as PostgreSQL user **`odoo`** over the local
-socket. You need a running PostgreSQL server and a matching role. `setup` installs
-PostgreSQL but does **not** start it or create the role, so on a fresh machine do this
-once:
+socket. You need a running PostgreSQL server and a matching role. `setup` never creates
+the role, and what it installs differs by OS — on **macOS** it installs the server (but
+does **not** start it); on **Linux** it installs only the PostgreSQL *client* (so you
+supply the server yourself). On a fresh machine do this once:
 
 **macOS (Homebrew):**
 
@@ -54,14 +55,23 @@ createuser -s odoo                         # create the role odoo.conf expects
 #   export PATH="$(brew --prefix postgresql@18)/bin:$PATH"
 ```
 
-**Debian/Ubuntu:**
+**Debian/Ubuntu:** install a server if you don't already have one (or point
+`conf/odoo.conf` at an existing / remote / Docker PostgreSQL):
 
 ```bash
+sudo apt-get install postgresql     # if you don't already have a server
 sudo systemctl start postgresql
 sudo -u postgres createuser -s odoo
 ```
 
-You can change the DB user/password in `conf/odoo.conf` if you prefer a different role.
+**Using a different / remote / Docker PostgreSQL:** set `DB_HOST`, `DB_PORT`,
+`DB_USER`, `DB_PASSWORD` in `.env` before running `setup` (it writes them into
+`conf/odoo.conf`), or edit `conf/odoo.conf` directly. With no `DB_HOST`, odoo-dev
+connects over the local socket as the `odoo` role.
+
+Before launching, `run`/`test`/`shell`/`update` run a quick connection preflight: if
+the server is unreachable, the role is missing, or authentication fails, you get a
+specific one-line fix instead of a stack trace.
 
 ## Commands
 
@@ -138,6 +148,14 @@ Create a `.env` file in your project root:
 ```bash
 ODOO_VERSION=19.0
 PYTHON_VERSION=3.12
+
+# Optional — DB connection, written into conf/odoo.conf by `setup`.
+# Omit DB_HOST/DB_PORT to use the local socket (the default). Set these to
+# point at a remote / Docker / non-default PostgreSQL:
+# DB_HOST=localhost
+# DB_PORT=5432
+# DB_USER=odoo
+# DB_PASSWORD=odoo
 ```
 
 ## Requirements

{odoo_dev-0.3.3 → odoo_dev-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "odoo-dev"
-version = "0.3.3"
+version = "0.4.0"
 description = "Odoo Development Environment Helper"
 readme = "README.md"
 requires-python = ">=3.12"

odoo_dev-0.4.0/release-please-config.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
+  "packages": {
+    ".": {
+      "release-type": "python",
+      "package-name": "odoo-dev",
+      "changelog-path": "CHANGELOG.md",
+      "include-component-in-tag": false,
+      "extra-files": ["src/odoo_dev/__init__.py"]
+    }
+  }
+}

odoo_dev-0.4.0/src/odoo_dev/__init__.py

@@ -0,0 +1,3 @@
+"""Odoo Development Environment Helper."""
+
+__version__ = "0.4.0"  # x-release-please-version

{odoo_dev-0.3.3 → odoo_dev-0.4.0}/src/odoo_dev/commands/run.py

@@ -10,6 +10,7 @@ from typing import Annotated
 import typer
 
 from odoo_dev.config import load_config
+from odoo_dev.preflight import require_db
 from odoo_dev.utils.console import error, info, success, warning
 
 
@@ -53,6 +54,8 @@ def run(
         error("Run 'odoo-dev setup' first to clone Odoo repositories.")
         raise typer.Exit(1)
 
+    require_db(cfg)
+
     venv_python = cfg.venv_path / "bin" / "python"
 
     # Build command
@@ -114,6 +117,8 @@ def shell(
         error("Run 'odoo-dev setup' first.")
         raise typer.Exit(1)
 
+    require_db(cfg)
+
     venv_python = cfg.venv_path / "bin" / "python"
 
     success(f"Opening Odoo shell with database {db_name}...")
@@ -148,6 +153,8 @@ def update(
         error("Run 'odoo-dev setup' first.")
         raise typer.Exit(1)
 
+    require_db(cfg)
+
     venv_python = cfg.venv_path / "bin" / "python"
 
     success(f"Updating modules: {modules} on database {db_name}...")
@@ -192,7 +199,8 @@ def test(
         bool, typer.Option("--coverage/--no-coverage", help="Enable coverage reporting")
     ] = True,
     keep_db: Annotated[
-        bool, typer.Option("--keep-db/--no-keep-db", help="Keep test database after tests")
+        bool,
+        typer.Option("--keep-db/--no-keep-db", help="Keep test database after tests"),
     ] = False,
     exclude: Annotated[
         str | None,
@@ -254,6 +262,8 @@ def test(
     if db_name is None:
         db_name = f"test_{int(time.time())}"
 
+    require_db(cfg)
+
     venv_python = cfg.venv_path / "bin" / "python"
 
     # Determine modules to test
@@ -291,7 +301,15 @@ def test(
                 if not clone_dir.exists():
                     branch = os.environ.get("ODOO_VERSION", cfg.odoo_version)
                     result = subprocess.run(
-                        ["git", "clone", "--depth=1", "-b", branch, repo_url, str(clone_dir)],
+                        [
+                            "git",
+                            "clone",
+                            "--depth=1",
+                            "-b",
+                            branch,
+                            repo_url,
+                            str(clone_dir),
+                        ],
                         capture_output=True,
                     )
                     if result.returncode != 0:
@@ -370,7 +388,9 @@ def test(
 
         if coverage:
             # Build coverage source paths
-            coverage_source = ",".join(str(cfg.addons_dir / m) for m in modules.split(","))
+            coverage_source = ",".join(
+                str(cfg.addons_dir / m) for m in modules.split(",")
+            )
 
             test_cmd = [
                 str(venv_python),
@@ -512,9 +532,12 @@ def _drop_database(cfg, db_name: str) -> None:
     result = subprocess.run(
         [
             "dropdb",
-            "-h", db_config["host"],
-            "-p", db_config["port"],
-            "-U", db_config["user"],
+            "-h",
+            db_config["host"],
+            "-p",
+            db_config["port"],
+            "-U",
+            db_config["user"],
             "--if-exists",
             db_name,
         ],
@@ -534,10 +557,14 @@ def _terminate_connections(db_name: str, db_config: dict[str, str]) -> None:
     subprocess.run(
         [
             "psql",
-            "-h", db_config["host"],
-            "-p", db_config["port"],
-            "-U", db_config["user"],
-            "-d", "postgres",
+            "-h",
+            db_config["host"],
+            "-p",
+            db_config["port"],
+            "-U",
+            db_config["user"],
+            "-d",
+            "postgres",
             "-c",
             f"SELECT pg_terminate_backend(pid) FROM pg_stat_activity "
             f"WHERE datname = '{db_name}' AND pid <> pg_backend_pid()",
@@ -547,6 +574,7 @@ def _terminate_connections(db_name: str, db_config: dict[str, str]) -> None:
         env=env,
     )
 
+
 def _get_addons_path(config_file) -> str:
     """Extract addons_path from odoo.conf."""
     for line in config_file.read_text().splitlines():

{odoo_dev-0.3.3 → odoo_dev-0.4.0}/src/odoo_dev/commands/setup.py

@@ -309,12 +309,28 @@ def _setup_odoo_config(cfg, community_only: bool = False) -> None:
     # Filter to only existing paths
     addons_paths = [p for p in addons_paths if Path(p).exists()]
 
-    config_content = f"""[options]
-addons_path = {",".join(addons_paths)}
-admin_passwd = admin
-db_user = odoo
-db_password = odoo
-"""
+    # DB connection is configurable via .env (loaded into the environment by
+    # load_config). Host/port are written only when set, so the default is the
+    # local socket — matching odoo-bin's behavior when db_host is absent.
+    db_user = os.getenv("DB_USER", "odoo")
+    db_password = os.getenv("DB_PASSWORD", "odoo")
+    db_host = os.getenv("DB_HOST", "")
+    db_port = os.getenv("DB_PORT", "")
+
+    db_lines = []
+    if db_host:
+        db_lines.append(f"db_host = {db_host}")
+    if db_port:
+        db_lines.append(f"db_port = {db_port}")
+    db_lines.append(f"db_user = {db_user}")
+    db_lines.append(f"db_password = {db_password}")
+
+    config_content = (
+        "[options]\n"
+        f"addons_path = {','.join(addons_paths)}\n"
+        "admin_passwd = admin\n"
+        f"{chr(10).join(db_lines)}\n"
+    )
 
     conf_file.write_text(config_content)
     conf_file.chmod(0o600)

{odoo_dev-0.3.3 → odoo_dev-0.4.0}/src/odoo_dev/config.py

@@ -9,6 +9,56 @@ DEFAULT_ODOO_VERSION = "19.0"
 DEFAULT_PYTHON_VERSION = "3.12"
 
 
+@dataclass
+class DbConfig:
+    """PostgreSQL connection settings, as odoo-bin will use them.
+
+    An empty ``host``/``port`` means "use the libpq defaults" (i.e. the local
+    Unix socket), which is exactly what odoo-bin does when ``db_host`` is absent
+    from odoo.conf. The preflight check must mirror that, so we keep them empty
+    rather than substituting ``localhost``/``5432`` (which would force TCP and
+    can spuriously fail on socket/peer-auth setups).
+    """
+
+    host: str = ""
+    port: str = ""
+    user: str = "odoo"
+    password: str = ""
+    name: str | None = None
+
+
+def read_db_config(config_file: Path) -> "DbConfig":
+    """Read DB connection settings from an odoo.conf file.
+
+    Args:
+        config_file: Path to odoo.conf. A missing file yields defaults.
+
+    Returns:
+        DbConfig reflecting the connection odoo-bin would make.
+    """
+    db = DbConfig()
+    if not config_file.exists():
+        return db
+
+    for line in config_file.read_text().splitlines():
+        line = line.strip()
+        if "=" not in line or line.startswith("#"):
+            continue
+        key, _, value = line.partition("=")
+        key, value = key.strip(), value.strip()
+        if key == "db_host":
+            db.host = value
+        elif key == "db_port":
+            db.port = value
+        elif key == "db_user":
+            db.user = value
+        elif key == "db_password":
+            db.password = value
+        elif key == "db_name":
+            db.name = value
+    return db
+
+
 @dataclass
 class ProjectConfig:
     """Configuration for an Odoo development project."""

odoo_dev-0.4.0/src/odoo_dev/preflight.py

@@ -0,0 +1,158 @@
+"""Fast PostgreSQL connectivity preflight for commands that need a database.
+
+odoo-dev does not own the PostgreSQL server lifecycle (you bring your own:
+a local service, Docker, or a remote/managed DB). Instead, commands that need
+a database call :func:`require_db` first, which connects exactly the way
+odoo-bin will and, on failure, prints a specific, actionable diagnostic rather
+than letting Odoo fail later with a noisy stack trace.
+"""
+
+import os
+import subprocess
+from dataclasses import dataclass
+
+import typer
+
+from odoo_dev.config import DbConfig, read_db_config
+from odoo_dev.utils.console import error, warning
+
+
+@dataclass
+class PreflightResult:
+    """Outcome of a connectivity check."""
+
+    ok: bool
+    category: str  # ok | client_missing | unreachable | auth | role_missing | db_missing | unknown
+    message: str  # raw stderr (or short note), for context
+
+
+def psql_argv(
+    db: DbConfig, dbname: str = "postgres", sql: str = "SELECT 1"
+) -> list[str]:
+    """Build a psql argv that connects the way odoo-bin would.
+
+    Host/port are only passed when set, so an unset host uses the local socket
+    (libpq default) rather than forcing TCP to localhost.
+    """
+    # -w / --no-password: never prompt interactively (would hang a preflight);
+    # fail fast instead so we can classify the failure.
+    argv = ["psql", "-w"]
+    if db.host:
+        argv += ["-h", db.host]
+    if db.port:
+        argv += ["-p", db.port]
+    argv += ["-U", db.user, "-d", dbname, "-tAc", sql]
+    return argv
+
+
+def classify_psql_failure(returncode: int, stderr: str) -> str:
+    """Map a failed psql attempt to a category for actionable guidance."""
+    s = stderr.lower()
+    # Order matters: the "does not exist" variants must be checked before the
+    # generic connection failures.
+    if "does not exist" in s and "role" in s:
+        return "role_missing"
+    if "does not exist" in s and "database" in s:
+        return "db_missing"
+    if "authentication failed" in s or "no password supplied" in s:
+        return "auth"
+    if (
+        "could not connect" in s
+        or "connection refused" in s
+        or "could not translate host" in s
+        or "no such file or directory" in s
+        or "is the server running" in s
+    ):
+        return "unreachable"
+    return "unknown"
+
+
+def check_db_connection(db: DbConfig, dbname: str = "postgres") -> PreflightResult:
+    """Attempt a trivial query and report whether (and why) it failed."""
+    env = os.environ.copy()
+    if db.password:
+        env["PGPASSWORD"] = db.password
+    try:
+        proc = subprocess.run(
+            psql_argv(db, dbname=dbname),
+            capture_output=True,
+            text=True,
+            env=env,
+        )
+    except FileNotFoundError:
+        return PreflightResult(
+            False,
+            "client_missing",
+            "psql executable not found on PATH",
+        )
+    if proc.returncode == 0:
+        return PreflightResult(True, "ok", "")
+    return PreflightResult(
+        False,
+        classify_psql_failure(proc.returncode, proc.stderr),
+        proc.stderr.strip(),
+    )
+
+
+def _target(db: DbConfig) -> str:
+    """Human-readable connection target for messages."""
+    where = f"{db.host}:{db.port or '5432'}" if db.host else "the local socket"
+    return f"PostgreSQL as user '{db.user}' on {where}"
+
+
+def _guidance(category: str, db: DbConfig) -> str:
+    """Actionable next step for a failure category."""
+    if category == "client_missing":
+        return (
+            "The psql client isn't on your PATH. Install the PostgreSQL client "
+            "(macOS: `brew install libpq` and add it to PATH; Debian/Ubuntu: "
+            "`sudo apt-get install postgresql-client`)."
+        )
+    if category == "unreachable":
+        return (
+            "Could not reach a PostgreSQL server. Start one (macOS: "
+            "`brew services start postgresql@18`; Debian/Ubuntu: "
+            "`sudo systemctl start postgresql`), or set db_host/db_port in "
+            "conf/odoo.conf (or DB_HOST/DB_PORT in .env) to point at an "
+            "existing / remote / Docker PostgreSQL."
+        )
+    if category == "auth":
+        return (
+            f"Authentication failed for role '{db.user}'. Check db_user/"
+            "db_password in conf/odoo.conf, or adjust the server's pg_hba.conf "
+            "(peer vs. password auth). A ~/.pgpass entry can supply the password."
+        )
+    if category == "role_missing":
+        return (
+            f"The role '{db.user}' does not exist. Create it once: "
+            f"`createuser -s {db.user}` (Debian/Ubuntu: prefix with "
+            "`sudo -u postgres`)."
+        )
+    if category == "db_missing":
+        return (
+            "The maintenance database is missing — unusual; your PostgreSQL "
+            "install may be incomplete."
+        )
+    return "See the PostgreSQL error above."
+
+
+def require_db(cfg, dbname: str = "postgres") -> None:
+    """Ensure the configured database server is reachable, or exit with guidance.
+
+    Args:
+        cfg: ProjectConfig (only ``config_file`` is used).
+        dbname: Database to connect to for the check (default: ``postgres``).
+
+    Raises:
+        typer.Exit: if the server cannot be reached / authenticated.
+    """
+    db = read_db_config(cfg.config_file)
+    result = check_db_connection(db, dbname=dbname)
+    if result.ok:
+        return
+
+    error(f"Cannot connect to {_target(db)}.")
+    if result.message:
+        warning(result.message)
+    error(_guidance(result.category, db))
+    raise typer.Exit(1)

odoo_dev-0.4.0/tests/test_db_config.py

@@ -0,0 +1,49 @@
+"""Tests for reading DB connection settings the way odoo-bin will use them."""
+
+from pathlib import Path
+
+from odoo_dev.config import DbConfig, read_db_config
+
+
+class TestReadDbConfig:
+    def test_parses_full_config(self, tmp_path: Path):
+        conf = tmp_path / "odoo.conf"
+        conf.write_text(
+            "[options]\n"
+            "db_host = db.example.com\n"
+            "db_port = 5544\n"
+            "db_user = appuser\n"
+            "db_password = secret\n"
+            "db_name = mydb\n"
+        )
+        db = read_db_config(conf)
+        assert db == DbConfig(
+            host="db.example.com",
+            port="5544",
+            user="appuser",
+            password="secret",
+            name="mydb",
+        )
+
+    def test_unset_host_port_stay_empty_for_socket(self, tmp_path: Path):
+        # odoo-bin with no db_host uses the local socket; preflight must mirror that
+        conf = tmp_path / "odoo.conf"
+        conf.write_text("[options]\ndb_user = odoo\ndb_password = odoo\n")
+        db = read_db_config(conf)
+        assert db.host == ""
+        assert db.port == ""
+        assert db.user == "odoo"
+        assert db.password == "odoo"
+        assert db.name is None
+
+    def test_defaults_when_file_missing(self, tmp_path: Path):
+        db = read_db_config(tmp_path / "nonexistent.conf")
+        assert db == DbConfig()
+        assert db.user == "odoo"
+
+    def test_handles_whitespace(self, tmp_path: Path):
+        conf = tmp_path / "odoo.conf"
+        conf.write_text("db_user =   spacey   \ndb_host=nospace\n")
+        db = read_db_config(conf)
+        assert db.user == "spacey"
+        assert db.host == "nospace"