feat: add stats command

.copier-answers.yml

@@ -4,10 +4,11 @@ _src_path: https://github.com/trobz/trobz-python-template.git
 author_email: moncoeur2k1@gmail.com
 author_username: duydoanh
 enable_docs_site: false
-enable_github_action: false
+enable_github_action: true
 package_name: odoo_db
 project_description: Odoo databases management CLI tool
 project_name: odoo-db
 project_type: cli
+publish_to_pypi: false
 repository_name: odoo-db
 repository_namespace: trobz

.github/actions/setup-python-env/action.yaml

@@ -0,0 +1,28 @@
+name: "Setup Python Environment"
+
+inputs:
+  python-version:
+    description: "Python version to use"
+    required: true
+    default: "3.12"
+  uv-version:
+    description: "uv version to use"
+    required: true
+
+runs:
+  using: "composite"
+  steps:
+    - uses: actions/setup-python@v6
+      with:
+        python-version: ${{ inputs.python-version }}
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v6
+      with:
+        version: ${{ inputs.uv-version }}
+        enable-cache: 'true'
+        cache-suffix: ${{ matrix.python-version }}
+
+    - name: Install Python dependencies
+      run: uv sync --frozen
+      shell: bash

.github/workflows/pre-commit.yaml

@@ -0,0 +1,26 @@
+name: pre-commit
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+  push:
+    branches:
+      - main
+
+jobs:
+  pre-commit:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out
+        uses: actions/checkout@v6
+
+      - uses: actions/cache@v5
+        with:
+          path: ~/.cache/pre-commit
+          key: pre-commit-${{ hashFiles('.pre-commit-config.yaml') }}
+
+      - name: Set up the environment
+        uses: ./.github/actions/setup-python-env
+
+      - name: Run checks
+        run: make check

.github/workflows/release.yaml

@@ -0,0 +1,40 @@
+name: release
+
+on:
+  push:
+    branches:
+      - main
+
+
+permissions:
+  contents: read
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write
+
+    outputs:
+      released: ${{ steps.release.outputs.released }}
+      tag: ${{ steps.release.outputs.tag }}
+
+    steps:
+
+      - name: Checkout Repository on Release Branch
+        uses: actions/checkout@v6
+        with:
+          ref: ${{ github.ref_name }}
+
+      - name: Force release branch to be at workflow sha
+        run: |
+          git reset --hard ${{ github.sha }}
+
+      - name: Semantic Version Release
+        id: release
+        uses: python-semantic-release/python-semantic-release@v10.5.2
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          git_committer_name: "github-actions"
+          git_committer_email: "actions@users.noreply.github.com"

.github/workflows/test.yaml

@@ -0,0 +1,30 @@
+name: test
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+  push:
+    branches:
+      - main
+
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+      fail-fast: false
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - name: Check out
+        uses: actions/checkout@v6
+
+      - name: Set up the environment
+        uses: ./.github/actions/setup-python-env
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Run tests
+        run: make test

.gitignore

@@ -218,3 +218,6 @@ __marimo__/
 
 # Plans (local planning files)
 plans/
+
+# Logs
+logs/*.log

AGENTS.md

@@ -2,6 +2,17 @@
 
 > Quick reference for AI coding agents.
 
+## Agent Discipline
+
+**After every change, always:**
+1. Update `README.md` and `AGENTS.md` to reflect changes (new flags, commands, behavior).
+2. Run `make check` (lint + format + type-check) before committing.
+3. Run pre-commit: `uv run pre-commit run -a` or via `make check`.
+
+Never skip these steps. They catch regressions and keep docs in sync.
+
+---
+
 ## Project
 
 `odoo-db` — CLI tool for Odoo database management. Connects to local PostgreSQL
@@ -15,16 +26,20 @@ Odoo locally.
 ## Entry Points
 
 - `odoo_db/main.py` — CLI entry point (`odoo-db` command)
+- `odoo_db/db.py` — all DB queries (psycopg3)
+- `odoo_db/output.py` — output formatting (text/json/prometheus)
 
 ## CLI Structure
 
 ```
-odoo-db [--output-file FILE] [--output-format FORMAT] COMMAND [ARGS]
+odoo-db [--output-file FILE] [--output-format FORMAT] [--log-level LEVEL] [--log-file FILE] COMMAND [ARGS]
 ```
 
 **Global flags:**
 - `--output-file` — default `-` (stdout)
 - `--output-format` — `text` (default), `json`, `prometheus`
+- `--log-level` — `DEBUG`, `INFO`, `WARNING` (default), `ERROR`
+- `--log-file` — default `logs/odoo-db.log` (auto-created, gitignored)
 
 **Commands:**
 
@@ -33,9 +48,10 @@ odoo-db [--output-file FILE] [--output-format FORMAT] COMMAND [ARGS]
 | `list` | All local Odoo DBs: name, version, neutralized status. `--verbose`: + module count, user count |
 | `modules <db>` | Installed modules with version |
 | `crons <db>` | Active scheduled actions |
-| `jobs <db>` | Queue jobs (pg_queue_job) |
-| `users <db>` | Users list |
-| `locks <db>` | Active DB locks |
+| `jobs <db>` | Queue job counts by state (returns message if queue_job not installed) |
+| `users <db>` | Active users with connection status (via bus_presence if available) |
+| `locks <db>` | Active DB locks (blocked/blocking PIDs + queries) |
+| `stats <db>` | Per-table record counts and sizes by year; `--years N` (default 3), `--top N` (default 20) |
 
 **Key SQL for `list`:**
 ```sql
@@ -56,6 +72,12 @@ Connect via psycopg3 (Unix socket, peer auth):
 psycopg.connect(dbname=db_name)  # no host/user needed for local socket
 ```
 
+## Logging
+
+- Console handler always active.
+- File handler writes to `--log-file` (default `logs/odoo-db.log`), parent dir auto-created.
+- `logs/*.log` is gitignored; `logs/.gitkeep` tracks the directory.
+
 ## Dev Commands
 
 Run `make help` for all commands. Key ones:
@@ -71,4 +93,5 @@ make test      # Run pytest
 - `Makefile` — Project commands
 - `pyproject.toml` — Dependencies and build config
 - `ruff.toml` — Linter/formatter rules
+- `logs/` — Log output directory (`.gitkeep` tracked, `*.log` gitignored)
 - `tests/` — Test suite (pytest)

Makefile

@@ -50,6 +50,3 @@ help:
 	[[print(f'\033[36m{m[0]:<20}\033[0m {m[1]}') for m in re.findall(r'^([a-zA-Z_-]+):.*?## (.*)$$', open(makefile).read(), re.M)] for makefile in ('$(MAKEFILE_LIST)').strip().split()]"
 
 .DEFAULT_GOAL := help
-
-
-

README.md

@@ -1,18 +1,86 @@
 # odoo-db
 
-Odoo databases management CLI tool
-
-This is where you should write a short paragraph that describes what your module does,
-how it does it, and why people should use it.
+CLI tool for Odoo database management. Connects to local PostgreSQL via Unix
+socket (peer auth — no credentials needed). Designed for developers running
+Odoo locally.
 
 ## Installation
 
 ```bash
-pip install odoo-db
+uv tool install git+https://github.com/trobz/odoo-db
+```
+
+Or for development:
+
+```bash
+git clone https://github.com/trobz/odoo-db
+cd odoo-db
+make install                       # install deps + pre-commit hooks
+uv tool install --editable .       # make `odoo-db` available globally
+```
+
+## Usage
+
+```
+odoo-db [OPTIONS] COMMAND [DB]
+```
+
+**Global options:**
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--output-file` | `-` (stdout) | Write output to file |
+| `--output-format` | `text` | Output format: `text`, `json`, `prometheus` |
+| `--log-level` | `WARNING` | Logging level: `DEBUG`, `INFO`, `WARNING`, `ERROR` |
+| `--log-file` | `logs/odoo-db.log` | Log file path (auto-created) |
+
+**Commands:**
+
+| Command | Description |
+|---------|-------------|
+| `list` | List all Odoo DBs with version and neutralization status |
+| `modules <db>` | List installed modules with version |
+| `crons <db>` | List active scheduled actions |
+| `jobs <db>` | Queue job counts by state (requires `queue_job` module) |
+| `users <db>` | List active users with connection status |
+| `locks <db>` | Show active PostgreSQL locks |
+| `stats <db>` | Per-table record counts and sizes by year (`--years N`, `--top N`) |
+
+## Examples
+
+```bash
+# List all local Odoo databases
+odoo-db list
+
+# Verbose: also show module count and user count
+odoo-db list --verbose
+
+# Output as JSON
+odoo-db --output-format json list
+
+# Export prometheus metrics to file
+odoo-db --output-format prometheus --output-file /tmp/odoo.prom list
+
+# Show installed modules for a specific database
+odoo-db modules my_db
+
+# Show queue jobs
+odoo-db jobs my_db
+
+# Per-table stats: record counts and sizes for last 3 years
+odoo-db stats my_db
+
+# Top 10 tables, last 5 years
+odoo-db stats my_db --top 10 --years 5
+
+# Debug mode with full logging
+odoo-db --log-level debug list
 ```
 
-With [`uv`](https://docs.astral.sh/uv/):
+## Dev
 
 ```bash
-uv tool install odoo-db
+make install   # Install deps + pre-commit hooks
+make check     # Lint, format, type-check
+make test      # Run tests
 ```