{"id":17526868,"url":"https://github.com/vyruss/pg_statviz","last_synced_at":"2026-01-16T03:26:19.040Z","repository":{"id":65694833,"uuid":"592527300","full_name":"vyruss/pg_statviz","owner":"vyruss","description":"A minimalist extension and utility pair for time series analysis and visualization of PostgreSQL internal statistics.","archived":false,"fork":false,"pushed_at":"2026-01-12T01:21:01.000Z","size":1004,"stargazers_count":85,"open_issues_count":1,"forks_count":7,"subscribers_count":3,"default_branch":"master","last_synced_at":"2026-01-12T01:22:26.634Z","etag":null,"topics":["data-visualization","database","database-administration","database-management","dataviz","hacktoberfest","open-source","opensource","performance-analysis","postgres","postgresql","postgresql-database","postgresql-extension","time-series","time-series-analysis"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vyruss.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-01-23T23:06:27.000Z","updated_at":"2025-12-30T06:04:44.000Z","dependencies_parsed_at":"2023-10-05T02:03:48.672Z","dependency_job_id":"b6fb8c1e-e583-48e9-b5f9-bf4b1a2b7f9d","html_url":"https://github.com/vyruss/pg_statviz","commit_stats":{"total_commits":2,"total_committers":1,"mean_commits":2.0,"dds":0.0,"last_synced_commit":"7f98b1f4dfcf9c329510e745372bcb3a1706e9c9"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/vyruss/pg_statviz","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vyruss%2Fpg_statviz","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vyruss%2Fpg_statviz/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vyruss%2Fpg_statviz/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vyruss%2Fpg_statviz/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vyruss","download_url":"https://codeload.github.com/vyruss/pg_statviz/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vyruss%2Fpg_statviz/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28477203,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T03:13:13.607Z","status":"ssl_error","status_checked_at":"2026-01-16T03:11:47.863Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["data-visualization","database","database-administration","database-management","dataviz","hacktoberfest","open-source","opensource","performance-analysis","postgres","postgresql","postgresql-database","postgresql-extension","time-series","time-series-analysis"],"created_at":"2024-10-20T15:02:34.743Z","updated_at":"2026-01-16T03:26:19.026Z","avatar_url":"https://github.com/vyruss.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"![pg_statviz](src/pg_statviz/libs/pg_statviz_readme.png)\n\n# pg_statviz\n\n`pg_statviz` is a minimalist extension and utility pair for time series analysis and visualization\nof PostgreSQL internal statistics.\n\nCreated for capturing PostgreSQL's cumulative and dynamic statistics, `pg_statviz` enables deeper\ntime series analysis than the standard PostgreSQL statistics views. The included utility generates\nvisualizations for selected time ranges from the stored statistic snapshots, helping users track\nPostgreSQL performance over time and potentially aiding in performance tuning and troubleshooting.\n\n## Design Philosophy\n\nDesigned with the [K.I.S.S.](https://en.wikipedia.org/wiki/KISS_principle) and\n[UNIX](https://en.wikipedia.org/wiki/Unix_philosophy) philosophies in mind, `pg_statviz` aims to be\na modular, minimal and unobtrusive tool that does only what it's meant for: create snapshots\nof PostgreSQL statistics for visualization and analysis. To this end, a utility is provided for\nretrieving and creating simple visualizations with the stored snapshots, by using\n[pandas](https://pandas.pydata.org/) and [Matplotlib](https://github.com/matplotlib/matplotlib).\n\n## Installing the extension\n\n### Debian (12+) / Ubuntu (22.04+)\n\n1. Configure the PostgreSQL Deb repository for your Linux distribution, as\n[explained here for Debian](https://www.postgresql.org/download/linux/debian/) and\n[here for Ubuntu](https://www.postgresql.org/download/linux/ubuntu/).\n2. Use `apt` to install the extension for your PostgreSQL version:\n\n        sudo apt install postgresql-\u003cpg_version\u003e-statviz        \n\n### Red Hat Enterprise Linux (v8.0+) / Fedora (37+)\n\n1. Configure the PostgreSQL Yum repository for your Linux distribution, as\n[explained here](https://www.postgresql.org/download/linux/redhat).\n2. Use `dnf` or `yum` to install the extension for your PostgreSQL version:\n\n        sudo dnf install pg_statviz_extension-\u003cpg_version\u003e\n        OR\n        sudo yum install pg_statviz_extension-\u003cpg_version\u003e\n\n### PGXN (PostgreSQL Extension Network)\n\nThe extension is available on [PGXN](https://pgxn.org/dist/pg_statviz/).\n\nTo install from PGXN, either download the zip file and install manually or use the\n[PGXN Client](https://pgxn.github.io/pgxnclient/) to install:\n\n    pgxn install pg_statviz\n\n### Manual installation\n\nTo install manually, clone this repository locally:\n\n    git clone https://github.com/vyruss/pg_statviz.git\n\nThis will install the extension in the appropriate location for your system (`$SHAREDIR/extension`):\n\n    cd pg_statviz\n    sudo make install\n\n### Enabling the extension\n\nThe extension can now be enabled inside the appropriate database like this, e.g. from `psql`:\n\n    \\c mydatabase\n    CREATE EXTENSION pg_statviz;\n\nThis will create the needed tables and functions under schema `pgstatviz` (note the lack of\nunderscore in the schema name).\n\n## Installing the utility\n\nThe visualization utility can be installed from [PyPi](https://pypi.org/project/pg_statviz/):\n\n    pip install pg_statviz\n\nThe utility is also available in the [Debian](https://www.postgresql.org/download/linux/debian/) and\n[Ubuntu](https://www.postgresql.org/download/linux/ubuntu/) PostgreSQL Deb Repositories, and can be installed\nusing `apt`:\n\n    sudo apt install pg-statviz\n\nFinally, it can be found in the\n[PostgreSQL Yum Repository](https://www.postgresql.org/download/linux/redhat/) and can be installed\nusing `dnf` or `yum`:\n\n    sudo dnf install pg_statviz\n    OR\n    sudo yum install pg_statviz\n\n### Requirements\n\nPython 3.11+ is required for the visualization utility.\nAny recent PostgreSQL version up to and including 18 is supported.\n\n## Usage\n\nThe extension can be used by superusers or any user that has `pg_monitor` role privileges. To take\na snapshot, e.g. from `psql`:\n\n    SELECT pgstatviz.snapshot();\n\n[comment]::\n\n    NOTICE:  created pg_statviz snapshot\n               snapshot\n    -------------------------------\n     2026-01-01 11:04:58.055453+00\n    (1 row)\n\nOlder snapshots and their associated data can be removed using any time expression. For example, to\nremove data more than 90 days old:\n\n    DELETE FROM pgstatviz.snapshots\n    WHERE snapshot_tstamp \u003c CURRENT_DATE - 90;\n\nOr all snapshots can be removed like this:\n\n    SELECT pgstatviz.delete_snapshots();\n\n[comment]::\n\n    NOTICE:  truncating table \"snapshots\"\n    NOTICE:  truncate cascades to table \"buf\"\n    NOTICE:  truncate cascades to table \"conf\"\n    NOTICE:  truncate cascades to table \"conn\"\n    NOTICE:  truncate cascades to table \"db\"\n    NOTICE:  truncate cascades to table \"io\"\n    NOTICE:  truncate cascades to table \"lock\"\n    NOTICE:  truncate cascades to table \"repl\"\n    NOTICE:  truncate cascades to table \"slru\"\n    NOTICE:  truncate cascades to table \"wait\"\n    NOTICE:  truncate cascades to table \"wal\"\n     delete_snapshots\n    ------------------\n\n    (1 row)\n\nThe `pg_monitor` role can be assigned to any user:\n\n    GRANT pg_monitor TO myuser;\n\n## Scheduling\n\nPeriodic snapshots can be set up with any job scheduler. For example with `cron`:\n\n    crontab -e -u postgres\n\nInside the `postgres` user's crontab, add this line to take a snapshot every 15 minutes:\n\n    */15 * * * * psql -c -d mydatabase \"SELECT pgstatviz.snapshot()\" \u003e/dev/null 2\u003e\u00261\n\n## Visualization\n\nPotentially very large numbers of data points can be visualized with the aid of pandas resampling,\ndisplaying the mean value over 100 plot points as a default.\n\nThe visualization utility can be called like a PostgreSQL command line tool:\n\n    pg_statviz --help\n\n[comment]::\n\n    usage: pg_statviz [--help] [--version] [-d DBNAME] [-h HOSTNAME] [-p PORT]\n                      [-U USERNAME] [-W] [-D FROM TO] [-O OUTPUTDIR]\n                      {analyze,buf,cache,checkp,checksum,conn,io,lock,repl,slru,tuple,wait,wal,xact} ...\n\n    run all analysis modules\n\n    positional arguments:\n      {analyze,buf,cache,checkp,checksum,conf,conn,io,lock,repl,slru,tuple,wait,wal,xact}\n        analyze             run all analysis modules\n        buf                 run buffers written analysis module\n        cache               run cache hit ratio analysis module\n        checkp              run checkpoint analysis module\n        checksum            run checksum failure analysis module\n        conf                run configuration changes analysis module\n        conn                run connection count analysis module\n        io                  run I/O analysis module\n        lock                run locks analysis module\n        repl                run replication analysis module\n        slru                run SLRU analysis module\n        tuple               run tuple count analysis module\n        wait                run wait events analysis module\n        wal                 run WAL generation analysis module\n        xact                run transaction count analysis module\n\n    options:\n      --help\n      --version             show program's version number and exit\n      -d DBNAME, --dbname DBNAME\n                            database name to analyze (default: 'myuser')\n      -h HOSTNAME, --host HOSTNAME\n                            database server host or socket directory (default: '/var/run/postgresql')\n      -p PORT, --port PORT  database server port (default: '5432')\n      -U USERNAME, --username USERNAME\n                            database user name (default: 'myuser')\n      -W, --password        force password prompt (should happen automatically) (default: False)\n      -D FROM TO, --daterange FROM TO\n                            date range to be analyzed in ISO 8601 format e.g. 2026-01-01T00:00\n                            2026-01-01T23:59 (default: [])\n      -O OUTPUTDIR, --outputdir OUTPUTDIR\n                            output directory (default: -)\n\n### Specific module usage\n\n    pg_statviz conn --help\n\n[comment]::\n\n    usage: pg_statviz conn [-h] [-d DBNAME] [--host HOSTNAME] [-p PORT] [-U USERNAME] [-W]\n                           [-D FROM TO] [-O OUTPUTDIR] [-u [USERS ...]]\n\n    run connection count analysis module\n\n    options:\n      -h, --help            show this help message and exit\n      -d DBNAME, --dbname DBNAME\n                            database name to analyze (default: 'myuser')\n      --host HOSTNAME       database server host or socket directory (default: '/var/run/postgresql')\n      -p PORT, --port PORT  database server port (default: '5432')\n      -U USERNAME, --username USERNAME\n                            database user name (default: 'myuser')\n      -W, --password        force password prompt (should happen automatically) (default: False)\n      -D FROM TO, --daterange FROM TO\n                            date range to be analyzed in ISO 8601 format e.g. 2026-01-01T00:00\n                            2026-01-01T23:59 (default: [])\n      -O OUTPUTDIR, --outputdir OUTPUTDIR\n                            output directory (default: -)\n      -u [USERS ...], --users [USERS ...]\n                            user name(s) to plot in analysis (default: [])\n\n### Example:\n\n    pg_statviz buf --host localhost -d postgres -U postgres -D 2026-01-01T00:00 2026-01-01T23:59\n\n### Produces:\n![buf output sample](src/pg_statviz/libs/pg_statviz_localhost_5432_buf.png)\n\n[comment]::\n\n![buf output sample (rate)](src/pg_statviz/libs/pg_statviz_localhost_5432_buf_rate.png)\n\n![conf output sample](src/pg_statviz/libs/pg_statviz_localhost_5432_conf.png)\n\n\n## Schema\n\nThe `pg_statviz` extension stores its data in the following tables:\n\nTable | Description\n--- | ---\n`pgstatviz.snapshots` | Timestamped snapshots\n`pgstatviz.buf` | Buffer, checkpointer and background writer data\n`pgstatviz.conf` | PostgreSQL server configuration data\n`pgstatviz.conn` | Connection data\n`pgstatviz.db` | PostgreSQL server and database statistics\n`pgstatviz.io` | I/O stats data\n`pgstatviz.lock` | Locks data\n`pgstatviz.repl` | Replication stats data\n`pgstatviz.slru` | SLRU cache stats data\n`pgstatviz.wait` | Wait events data\n`pgstatviz.wal` | WAL generation data\n\n## Export data\n\nTo dump the captured data, e.g. for analysis on a different machine, run:\n\n    pg_dump -d \u003cdbname\u003e -a -O -t pgstatviz.* \u003e pg_statviz_data.dump\n\nLoad it like this on the target database (which should have `pg_statviz` installed) :\n\n    psql -d \u003cother_dbname\u003e -f pg_statviz_data.dump\n\nAlternatively, `pg_statviz` internal tables can also be exported to a tab separated values (TSV) file\nfor use by other tools:\n\n    psql -d \u003cdbname\u003e -c \"COPY pgstatviz.conn TO STDOUT CSV HEADER DELIMITER E'\\t'\" \u003e conn.tsv\n\nThese can then be loaded into another database like this, provided the tables exist (installing the extension will create them):\n\n    psql -d \u003cother_dbname\u003e -c \"COPY pgstatviz.conn FROM STDIN CSV HEADER DELIMITER E'\\t'\" \u003c conn.tsv\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvyruss%2Fpg_statviz","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvyruss%2Fpg_statviz","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvyruss%2Fpg_statviz/lists"}