odoo-db

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

uv tool install git+https://github.com/trobz/odoo-db

Or for development:

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)
--include-sensitive-information off PII master switch: unmask identifying data (e.g. attachment filenames) in any command that redacts it by default

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 (--all also includes inactive ones). --running shows crons currently held by an Odoo worker (RowShareLock on ir_cron) — transient debug data, not bundled into prepare-audit. --include-code adds the python source of each state='code' cron (ignored with --running, which already always shows it)
jobs <db> Queue job counts by state (requires queue_job module)
params <db> [pattern] Show ir_config_parameter keys and values. Optional pattern narrows to keys containing it (case-insensitive substring). Values of secret-bearing keys are masked ******** by default; the global --include-sensitive-information reveals them
users <db> List active users with connection status
groups <db> List res.groups (category, name, share flag). --include-users adds each group's member logins. --include-acls adds per-group model access rights and record rules, plus top-level global_acls/global_rules for rows with no group at all (apply to every user — excluded from prior output, now the highest-value rows in a permission audit)
roles <db> List res.users.role (requires OCA base_user_role; prints a message if not installed). --include-users adds currently-enabled assigned users' logins. --include-groups adds the role's full resolved group set (its own group plus all directly and transitively implied groups)
role-drift <db> Detect drift between assigned res.users.role and actual res.groups membership (requires OCA base_user_role). Reports missing_groups (role grants a group the user doesn't actually have — sync gap) and extra_groups (user physically holds a role's own marker group but no role assignment — active or via another assigned role's implied closure — explains it: stale privilege from a removed/expired role, or a group granted by hand), per user. Baseline groups implied by roles but not exclusive to any of them (e.g. "Internal User") never count as drift. Each user is keyed by user_id; login (PII) is included only with the global --include-sensitive-information flag. --output-format prometheus exposes a odoo_db_role_drift_users gauge for alerting
locks <db> Show active PostgreSQL locks
stats <db> Per-table record counts and sizes by year (--years N, --top N). Tables with 0-byte heap are reported as empty without running count(*)
bloat <db> Estimate table + index bloat — space reclaimable by VACUUM FULL / REINDEX / a dump+restore migration (autovacuum never returns it). Uses pgstattuple for exact figures when the extension is installed and the relation fits under --exact-max-scan (MB), else a cheap statistical estimate; each row is tagged exact/est. Also flags high dead-tuple ratios, stale autovacuum, and unused indexes (idx_scan = 0)
studio <db> Show Studio customizations: custom models, models extended with Studio fields, and studio-flagged record counts by type
not-odoo <db> Show non-Odoo database objects: custom views, triggers, functions, and stored procedures. Triggers/functions are tagged recognized (known infra: unaccent, queue_job_notify, …) or custom
attachments <db> Read-only ir.attachment storage audit: repartition (storage location, by-model, mimetype family, size distribution, growth by year, largest files) plus cleanup/archive candidates (uninstalled-model orphans, regenerable asset bundles, duplicate checksums, aged transient, DB-stored bulk). --validate-orphans adds dead-res_id detection for the heaviest models. Sizes are file_size sums (reliable on any backend; payloads never read). Filenames are redacted by default — pass --include-individual-filenames (or the global --include-sensitive-information) to show them
prepare-audit <db> Bundle summary + modules + model_owners + orphan_tables + users_by_year + stats + not-odoo + studio_customizations into <db>.json (in the current directory) for /odoo-dev:audit-db (--years N, --top N; --top 0 means all tables). orphan_tables flags tables not owned by any installed module (reason: uninstalled_module or no_ownership_data). Every table in stats.tables and orphan_tables carries functional_group (first underscore component) for display-time grouping by functional area. users_by_year is an aggregate {year: count} of active users by create_date year — zero PII so the file can ship without an NDA. studio_customizations includes custom model list, extended model list, and studio-flagged record counts by type. The deep attachment audit is intentionally a separate command (attachments), not bundled here

Examples

# 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

# Show all config parameters
odoo-db params my_db

# Show config parameters with "mail" in the key
odoo-db params my_db mail

# Reveal masked secret values (database.secret, api keys, ...)
odoo-db --include-sensitive-information params my_db

# List access groups, with members and ACLs
odoo-db groups my_db --include-users --include-acls

# List user roles (base_user_role), with resolved group sets
odoo-db --output-format json roles my_db --include-users --include-groups

# 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

# Estimate table + index bloat (reclaimable space)
odoo-db bloat my_db

# Debug mode with full logging
odoo-db --log-level debug list

# Show Studio customizations (custom models, extended models, flagged records)
odoo-db studio my_db

# Show non-Odoo objects: custom views, triggers, functions, stored procedures
odoo-db not-odoo my_db

# Export not-odoo report as JSON
odoo-db --output-format json not-odoo my_db

# Audit ir.attachment storage (repartition + cleanup candidates)
odoo-db attachments my_db

# Also validate dead-record orphans, and show real filenames (PII)
odoo-db --include-sensitive-information attachments my_db --validate-orphans

# Full attachment audit as JSON
odoo-db --output-format json attachments my_db

# Prepare an audit bundle (writes ./my_db.json in the current directory)
odoo-db prepare-audit my_db

# Custom output path
odoo-db --output-file /tmp/audit.json prepare-audit my_db

Dev

make install   # Install deps + pre-commit hooks
make check     # Lint, format, type-check
make test      # Run tests
make docs      # Build the Zensical documentation site (site-docs/)
make docs-serve  # Serve the docs locally

Project links

Data verified by PyPI on Aug 14, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (1.24.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for trobz from gravatar.com trobz

Credits

Author: Do Anh Duy

GitHub Statistics

Data verified by PyPI on Aug 14, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

AGPL-3.0
View SPDX License List

Requires

Python >=3.10

Provides Extra

build

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

odoo_db-1.19.0.tar.gz (58.3 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

odoo_db-1.19.0-py3-none-any.whl (57.1 kB view details)

Uploaded Python 3

File details

Details for the file odoo_db-1.19.0.tar.gz.

File metadata

  • Download URL: odoo_db-1.19.0.tar.gz
  • Upload date:
  • Size: 58.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for odoo_db-1.19.0.tar.gz
Algorithm Hash digest
SHA256 a0a65e9ca7e8dc4cd3b193c3a45f06f0ab9c731d022c82761c7a95c6ca1a791e
MD5 be28bb0b37320df75a89a0e358cf714f
BLAKE2b-256 c6d705f6b5fefa20ce475ed0fc385cf0d6aa973dadaabe0b820977651c317d94

See more details on using hashes here.

Provenance

The following attestation bundles were made for odoo_db-1.19.0.tar.gz:

Publisher: release.yaml on trobz/odoo-db

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file odoo_db-1.19.0-py3-none-any.whl.

File metadata

  • Download URL: odoo_db-1.19.0-py3-none-any.whl
  • Upload date:
  • Size: 57.1 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for odoo_db-1.19.0-py3-none-any.whl
Algorithm Hash digest
SHA256 bd84f6fb0832699d79baf4712d6828537c542d6b3913cb658e742f1338d5e85b
MD5 0201f89cfb737bf9350a7ad6d481ae97
BLAKE2b-256 d7cde1e07600313aa15215e84ad0e0dcdb14ba863e537ffc0912dc832b3c1eb2

See more details on using hashes here.

Provenance

The following attestation bundles were made for odoo_db-1.19.0-py3-none-any.whl:

Publisher: release.yaml on trobz/odoo-db

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

1.24.0

2 files

1.23.0

2 files

1.22.0

2 files

1.21.0

2 files

1.20.0

2 files

This release

1.19.0 This release

2 files

1.18.0

2 files

1.17.0

2 files

1.16.0

2 files

1.15.0

2 files

1.14.1

2 files

1.14.0

2 files

1.13.0

2 files

1.12.1

2 files

1.12.0

2 files

1.11.1

2 files

1.11.0

2 files

1.10.0

2 files

1.9.2

2 files

1.9.1

2 files

1.9.0

2 files

1.8.0

2 files

1.7.0

2 files

1.6.0

2 files

1.5.0

2 files

1.4.0

2 files

1.3.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page