{"id":25616611,"url":"https://github.com/julmon/pg_activity","last_synced_at":"2025-02-22T04:01:17.467Z","repository":{"id":38084866,"uuid":"6432337","full_name":"dalibo/pg_activity","owner":"dalibo","description":"pg_activity is a top like application for PostgreSQL server activity monitoring.","archived":false,"fork":false,"pushed_at":"2024-10-08T13:35:45.000Z","size":2999,"stargazers_count":2473,"open_issues_count":11,"forks_count":178,"subscribers_count":45,"default_branch":"master","last_synced_at":"2024-10-29T11:31:51.844Z","etag":null,"topics":["activity","cli","monitoring","postgresql","sql","top"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"postgresql","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dalibo.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS.md","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2012-10-28T21:34:42.000Z","updated_at":"2024-10-28T23:23:11.000Z","dependencies_parsed_at":"2023-02-18T16:40:17.522Z","dependency_job_id":"57efd7c7-4877-4738-8b6e-24af58b9eb44","html_url":"https://github.com/dalibo/pg_activity","commit_stats":{"total_commits":841,"total_committers":42,"mean_commits":"20.023809523809526","dds":"0.38287752675386444","last_synced_commit":"56fb9b70a56cd8f8cb8c60d08ecdca280b49cca3"},"previous_names":["julmon/pg_activity"],"tags_count":55,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dalibo%2Fpg_activity","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dalibo%2Fpg_activity/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dalibo%2Fpg_activity/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dalibo%2Fpg_activity/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dalibo","download_url":"https://codeload.github.com/dalibo/pg_activity/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240122591,"owners_count":19751143,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["activity","cli","monitoring","postgresql","sql","top"],"created_at":"2025-02-22T04:01:06.898Z","updated_at":"2025-02-22T04:01:17.461Z","avatar_url":"https://github.com/dalibo.png","language":"Python","readme":"![pg_activity](https://github.com/dalibo/pg_activity/raw/master/docs/imgs/logo-horizontal.png)\n\nCommand line tool for PostgreSQL server activity monitoring.\n\n[![Latest PyPI version](https://img.shields.io/pypi/v/pg_activity.svg)](https://pypi.python.org/pypi/pg_activity)\n[![Lint](https://github.com/dalibo/pg_activity/actions/workflows/lint.yml/badge.svg)](https://github.com/dalibo/pg_activity/actions/workflows/lint.yml)\n[![Tests](https://github.com/dalibo/pg_activity/actions/workflows/tests.yml/badge.svg)](https://github.com/dalibo/pg_activity/actions/workflows/tests.yml)\n\n![pg_activity screenshot](https://raw.github.com/dalibo/pg_activity/master/docs/imgs/screenshot.png)\n\n# Installation\n\n## From distribution packages\n\nThe simplest way to install pg\\_activity is through the package manager of your\nLinux distribution, if it ships with a package. E.g., on Debian-based\ndistributions (e.g. Debian, Ubuntu, Mint...):\n\n    $ sudo apt install pg-activity\n\n(on Debian bullseye, the current stable version, a backport is available: `apt\ninstall pg-activity/bullseye-backports`).\n\nThe PostgreSQL Global Development Group (PGDG) also provides packages for\nRPM-based (https://yum.postgresql.org/) and Debian-based distributions\n(https://wiki.postgresql.org/wiki/Apt).\n\n**Note:** distribution packages may not be up to date with the latest\npg\\_activity releases. Before submitting a bug report here:\n-   check the package version, compare that to our latest release and then\n    review the [change log][changelog] to see if the bug has been fixed;\n-   if the issue is about packaging, e.g. missing dependencies, reach out\n    the package maintainer (or PGDG) first.\n\n## From PyPI\n\npg\\_activity can be installed using pip on Python 3.8 or later along with\npsycopg:\n\n    $ python3 -m pip install \"pg_activity[psycopg]\"\n\nAlternatively, [pipx](https://pypi.org/project/pipx/) can be used to install\nand run pg\\_activity in an isolated environment:\n\n    $ pipx install \"pg_activity[psycopg]\"\n\nIn case your `$PATH` does not already contain it, the full path is:\n\n    $ ~/.local/bin/pg_activity\n\n## From source, using git\n\nThis is only necessary to test development versions. First, clone the repository:\n\n    $ git clone https://github.com/dalibo/pg_activity.git\n\nChange the branch if necessary. Then create a dedicated environment,\nand install pg\\_activity with the psycopg database driver:\n\n    $ cd pg_activity\n    $ python3 -m venv .venv\n    $ . .venv/bin/activate\n    (.venv) $ pip install \".[psycopg]\"\n    (.venv) $ pg_activity\n\nTo quit this env and destroy it:\n\n    $ deactivate\n    $ rm -r .venv\n\n# Usage\n\n`pg_activity` works locally or remotely. In local execution context, to obtain\nsufficient rights to display system information, the system user running\n`pg_activity` must be the same user running postgresql server (`postgres` by\ndefault), or have more rights like `root`. The PostgreSQL user used to connect\nto the database must be super-user in order to get as much data as possible.\nOtherwise, `pg_activity` can fall back to a degraded mode where some data like\nsystem information or temporary file data are not displayed.\n\nex:\n\n    sudo -u postgres pg_activity -U postgres\n\n## Options\n\n    pg_activity [options] [connection string]\n\n    Configuration:\n      -P, --profile PROFILE\n                            Configuration profile matching a PROFILE.conf file in\n                            ${XDG_CONFIG_HOME:~/.config}/pg_activity/ or\n                            /etc/pg_activity/, or a built-in profile.\n\n    Options:\n      --blocksize BLOCKSIZE\n                            Filesystem blocksize (default: 4096).\n      --rds                 Enable support for AWS RDS (implies --no-tempfiles and\n                            filters out the rdsadmin database from space\n                            calculation).\n      --output FILEPATH     Store running queries as CSV.\n      --db-size, --no-db-size\n                            Enable/disable total size of DB.\n      --tempfiles, --no-tempfiles\n                            Enable/disable tempfile count and size.\n      --walreceiver, --no-walreceiver\n                            Enable/disable walreceiver checks.\n      -w, --wrap-query      Wrap query column instead of truncating.\n      --duration-mode DURATION_MODE\n                            Duration mode. Values: 1-QUERY(default),\n                            2-TRANSACTION, 3-BACKEND.\n      --min-duration SECONDS\n                            Don't display queries with smaller than specified\n                            duration (in seconds).\n      --filter FIELD:REGEX  Filter activities with a (case insensitive) regular\n                            expression applied on selected fields. Known fields\n                            are: dbname.\n      --debug-file DEBUG_FILE\n                            Enable debug and write it to DEBUG_FILE.\n      --version             show program's version number and exit.\n      --help                Show this help message and exit.\n\n    Connection Options:\n      connection string     A valid connection string to the database, e.g.:\n                            'host=HOSTNAME port=PORT user=USER dbname=DBNAME'.\n      -h, --host HOSTNAME   Database server host or socket directory.\n      -p, --port PORT       Database server port.\n      -U, --username USERNAME\n                            Database user name.\n      -d, --dbname DBNAME   Database name to connect to.\n\n    Process table display options:\n      These options may be used hide some columns from the processes table.\n\n      --pid, --no-pid       Enable/disable PID.\n      --database, --no-database\n                            Enable/disable DATABASE.\n      --user, --no-user     Enable/disable USER.\n      --client, --no-client\n                            Enable/disable CLIENT.\n      --cpu, --no-cpu       Enable/disable CPU%.\n      --mem, --no-mem       Enable/disable MEM%.\n      --read, --no-read     Enable/disable READ/s.\n      --write, --no-write   Enable/disable WRITE/s.\n      --time, --no-time     Enable/disable TIME+.\n      --wait, --no-wait     Enable/disable W.\n      --app-name, --no-app-name\n                            Enable/disable APP.\n\n    Header display options:\n      --no-inst-info        Display instance information.\n      --no-sys-info         Display system information.\n      --no-proc-info        Display workers process information.\n\n    Other display options:\n      --hide-queries-in-logs\n                            Disable log_min_duration_statements and\n                            log_min_duration_sample for pg_activity.\n      --refresh REFRESH     Refresh rate. Values: 0.5, 1, 2, 3, 4, 5 (default: 2).\n\n## Configuration\n\n`pg_activity` may be configured through a configuration file, in [INI format][],\nread from `${XDG_CONFIG_HOME:~/.config}/pg_activity.conf` or\n`/etc/pg_activity.conf` in that order. Command-line options may override\nconfiguration file settings.\nThis is used to control how columns in the processes table are rendered or which\nitems of the header should be displayed, e.g.:\n```ini\n[header]\nshow_instance = yes\nshow_system = yes\nshow_workers = no\n\n[client]\nhidden = yes\n\n[database]\nwidth = 9\n```\n\nAlternatively, the user might define *configuration profiles* in the form of\nfiles located at `${XDG_CONFIG_HOME:~/.config}/pg_activity/\u003cmy-profile\u003e.conf` or\n`/etc/pg_activity/\u003cmy-profile\u003e.conf`; these can then be used through the\n`--profile \u003cmy-profile\u003e` command-line option. The format of these files is the\nsame as the main configuration file.\n\n`pg_activity` ships with a few built-in profiles:\n\n- `narrow`, providing a narrow user interface with most non-essential\n  columns in the process table hidden,\n- `wide`, providing a wide user interface (the inverse of `narrow`), and,\n- `minimal`, providing an even more minimal user interface with header\n  information hidden\n\nColumns of the process table in pg\\_activity user interface can be assigned a\ncustom color in the configuration file, e.g.:\n```ini\n[client]\ncolor = magenta\n\n[relation]\ncolor = red\n```\n\nThe `color` option illustrated above defines the color used to render the cell\nindependently of its value, i.e. the \"normal\" color. Some columns may be\ncolorized differently depending on the value of their cells; for example, the\n`time` column can handle tree colors depending on whether the time value is\n*high*, *medium* or *low*. The color of such columns cannot be currently\ncustomized and attempting to do so will result in pg\\_activity to exit early\nwith an error message.\n\n[INI format]: https://docs.python.org/3/library/configparser.html#supported-ini-file-structure\n\n## Notes\n\nLength of SQL query text that `pg_activity` reports relies on PostgreSQL\nparameter `track_activity_query_size`. Default value is `1024` (expressed in\nbytes). If your SQL query text look truncated, you should increase\n`track_activity_query_size`.\n\n\n## Interactives commands\n\n| Key       | Action                                                           |\n|-----------|------------------------------------------------------------------|\n| `r`       | Sort by READ/s, descending                                       |\n| `w`       | Sort by WRITE/s, descending                                      |\n| `c`       | Sort by CPU%, descending                                         |\n| `m`       | Sort by MEM%, descending                                         |\n| `t`       | Sort by TIME+, descending                                        |\n| `y`       | Copy focused query to clipboard                                  |\n| `T`       | Change duration mode: query, transaction, backend                |\n| `Space`   | Pause on/off                                                     |\n| `v`       | Change queries display mode: full, indented, truncated           |\n| `UP/DOWN` | Scroll processes list                                            |\n| `k/j`     | Scroll processes list                                            |\n| `q`       | Quit                                                             |\n| `+`       | Increase refresh time. Maximum value: 5s                         |\n| `-`       | Decrease refresh time. Minimum Value: 0.5s                       |\n| `F1/1`    | Running queries list                                             |\n| `F2/2`    | Waiting queries list                                             |\n| `F3/3`    | Blocking queries list                                            |\n| `h`       | Help page                                                        |\n| `R`       | Refresh                                                          |\n| `D`       | Refresh Database Size (including when --no-dbzise option applied)|\n| `s`       | Display system information in header                             |\n| `i`       | Display general instance information in header                   |\n| `o`       | Display worker information in header                             |\n\n## Navigation mode\n\n| Key        | Action                                        |\n|------------|-----------------------------------------------|\n| `UP`/`k`   | Move up the cursor                            |\n| `DOWN`/`j` | Move down the cursor                          |\n| `K`        | Terminate the current backend/tagged backends |\n| `C`        | Cancel the current backend/tagged backends    |\n| `Space`    | Tag or untag the process                      |\n| `q`        | Quit                                          |\n| `Other`    | Back to activity                              |\n\n## FAQ\n\n**I can't see my queries only TPS is shown**\n\n`pg_activity` scans the view `pg_stat_activity` with a user defined refresh\ntime comprised between 0.5 and 5 seconds. It can be modified in the interface\nwith the `+` and `-` keys. Any query executed between two scans won't be\ndisplayed.\n\n\nWhat is more, `pg_activity` uses different queries to get:\n\n*    settings from `pg_settings`\n*    version info using `version()`\n*    queries and number of connections from `pg_stat_activity`\n*    locks from `pg_locks`\n*    tps from `pg_database` using `pg_stat_get_db_xact_commit()` and\n     `pg_stat_get_db_xact_rollback()`\n*    and more (e.g.: `pg_cancel_backend()` and `pg_terminate_backend()`)\n\nThose queries cannot be seen in the query tab because all queries issued from\nthe `pg_activity` backend are considered as noise and are not displayed . On\nthe other hand, the transactions used to get the info for `pg_activity`'s\nreporting are still accounted for by postgres in `pg_stat_get_db_xact_commit()`\nand `pg_stat_get_db_xact_commit()`. Therefore `pg_activity` will display a non\nzero TPS even with no activity on the database, and/or no activity displayed on\nscreen.\n\n**How can I specify a password for authentication?**\n\npg_activity uses libpq to access to PostgreSQL therefore all the traditional\nmethods are available.\n\nYou can pass the password for the database connection in a password file.\nInformation can also be given via PostgreSQL's environment variables\n(PGPASSFILE or PGPASSWORD) or via the connection string parameters.\n\nThe password file is preferred since it's more secure (security is deferred to\nthe OS). Please avoid password in connection strings at all cost.\n\n**How to copy/paste the query of focused process?**\n\nThe `y` shortcut will copy the query of focused process to system clipboard\nusing OSC 52 escape sequence. This requires the terminal emulator to support\nthis escape sequence and set the clipboard accordingly. If so, the copy even\nworks across remote connections (SSH). In general, terminal emulators supporting\nthis would use `CTRL+SHIFT+V` to paste from this clipboard.\n\n# Hacking\n\nIn order to work on pg\\_activity source code, in particular to run the tests\nsuite, a temporary PostgreSQL database cluster will be created; accordingly,\nPostgreSQL server binaries (e.g. `initdb`, `pg_ctl`) need to be available. For\ninstance, on a Debian system, this means simply having the `postgresql` package\ninstalled.\n\nTo set up a development environment, get the source repository:\n\n    $ git clone https://github.com/dalibo/pg_activity\n    $ cd pg_activity\n\nand then create a [virtual environment][venv], activate it and install the\nproject along with development dependencies:\n\n    $ python3 -m venv .venv\n    $ .venv/bin/activate\n    (.venv) $ pip install -e \".[dev]\"\n\nThe source code is formatted with [black][] and [isort][] and typed checked with\n[mypy][] (all those are included in the development environment). Make sure to\nrespect this, e.g. by configuring your editor, before committing changes.\nAlternatively, you can install [pre-commit][] hooks so that this will be checked\nautomatically:\n\n    (.venv) $ pre-commit install\n\n[venv]: https://docs.python.org/3/library/venv.html\n[black]: https://black.readthedocs.io/\n[isort]: https://pycqa.github.io/isort/\n[mypy]: https://mypy.readthedocs.io/\n[pre-commit]: https://pre-commit.com/\n\nTo run the tests suite, simply invoke:\n\n    (.venv) $ pytest\n    ================================ test session starts =================================\n    platform linux -- Python 3.11.2, pytest-7.3.1, pluggy-1.0.0\n    psycopg: 3.1.8\n    configfile: pytest.ini\n    plugins: cov-4.0.0, accept-0.1.9, postgresql-4.1.1\n    collected 70 items\n\n    pgactivity/activities.py ..                                                    [  2%]\n    pgactivity/config.py ..                                                        [  5%]\n    pgactivity/data.py ..                                                          [  8%]\n    pgactivity/handlers.py .....                                                   [ 15%]\n    pgactivity/keys.py .                                                           [ 17%]\n    pgactivity/types.py ..............                                             [ 37%]\n    pgactivity/utils.py .........                                                  [ 50%]\n    pgactivity/views.py .....                                                      [ 57%]\n    tests/test_activities.py ...                                                   [ 61%]\n    tests/test_config.py ..                                                        [ 64%]\n    tests/test_data.py ................                                            [ 87%]\n    tests/test_scroll.txt .                                                        [ 88%]\n    tests/test_types.py .                                                          [ 90%]\n    tests/test_ui.txt .                                                            [ 91%]\n    tests/test_views.py ....                                                       [ 97%]\n    tests/test_views.txt .                                                         [ 98%]\n    tests/test_widgets.txt .                                                       [100%]\n\n    ================================ 70 passed in 11.89s =================================\n\n# Change log\n\nSee [CHANGELOG.md][changelog].\n\n[changelog]: https://github.com/dalibo/pg_activity/blob/master/CHANGELOG.md\n","funding_links":[],"categories":["Python","CLI"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjulmon%2Fpg_activity","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjulmon%2Fpg_activity","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjulmon%2Fpg_activity/lists"}