{"id":14029999,"url":"https://github.com/dcgadmin/pg_sqltxplain","last_synced_at":"2025-04-14T08:53:53.085Z","repository":{"id":251222495,"uuid":"836410494","full_name":"dcgadmin/pg_sqltxplain","owner":"dcgadmin","description":"pg_sqltxplain - Simplifying PostgreSQL Execution Plan Analysis by curating underlying stats in a single html report.","archived":false,"fork":false,"pushed_at":"2024-10-06T06:59:22.000Z","size":269,"stargazers_count":25,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-27T22:23:28.237Z","etag":null,"topics":["analysis","analyze","buffers","database","execution","explain","performance","perv2","plan","postgres","postgresql","report","report-generator","sql","sqltuning","statistics","tuning"],"latest_commit_sha":null,"homepage":"http://www.datacloudgaze.com","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dcgadmin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"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}},"created_at":"2024-07-31T19:40:13.000Z","updated_at":"2025-03-15T18:35:25.000Z","dependencies_parsed_at":"2024-08-07T12:06:14.337Z","dependency_job_id":"3bba371f-24f7-4e10-8321-d6965d120148","html_url":"https://github.com/dcgadmin/pg_sqltxplain","commit_stats":null,"previous_names":["dcgadmin/statsviaexplainanalyze","dcgadmin/pg_sqltxplain"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dcgadmin%2Fpg_sqltxplain","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dcgadmin%2Fpg_sqltxplain/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dcgadmin%2Fpg_sqltxplain/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dcgadmin%2Fpg_sqltxplain/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dcgadmin","download_url":"https://codeload.github.com/dcgadmin/pg_sqltxplain/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248852109,"owners_count":21171839,"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":["analysis","analyze","buffers","database","execution","explain","performance","perv2","plan","postgres","postgresql","report","report-generator","sql","sqltuning","statistics","tuning"],"created_at":"2024-08-11T22:00:19.704Z","updated_at":"2025-04-14T08:53:53.063Z","avatar_url":"https://github.com/dcgadmin.png","language":"HTML","readme":"# pg_sqltxplain - Simplifying PostgreSQL Execution Plan Analysis.\n\nAnalyzing execution plans is made easier with curating execution plan, statistics of database objects such as tables, indexes, or columns involved in the actual runtime execution plan, all within a single report. This makes it easier to share among team members or external forum and reduces the need for additional information requests.\n\nThis tool automates the curation of object statistics when analyzing problematic execution plans in PostgreSQL using an HTML template embded in sql file and the `psql` command line.\n\n### How it Works?\nExecution plan is generated either by `Explain Analyze Buffers` or only with `Explain` and stored in a plantable.\n\nUsing the `psql` command line, the current statistics of all database objects involved in Execution plan are fetched and included in the HTML output. The output can also be integrated with the [PEV2 visualiser](https://github.com/dalibo/pev2).\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/user-attachments/assets/6ab56914-2158-44eb-b663-062b861e153b\" alt=\"Screen Recording\" width=\"600\" height=\"450\"/\u003e\n\u003c/div\u003e\n\n###  Installation \nSetup Databases with necessary wrappers code that generate execution plan and stored it in plantable.\n\n#### Extension Dependency \nThis tool uses the `pg_stat_statements` view to extract runtime information of problematic SQL using `queryid`. It can also be used as filters to gather Generic Plan from `pg_stat_statements`. The `pgstattuple` extension is used to extract bloat-related information, though it is optional.\n\n```\n        Name        |                              Description\n--------------------+------------------------------------------------------------------------\n pg_stat_statements | track planning and execution statistics of all SQL statements executed\n pgstattuple        | show tuple-level statistics\n\n```\n\n#### Creating planstats schema\nGathering statistics requires traversing all execution plan steps and extracting the objects involved. We have built all necessary wrappers with functions and views within the `planstats` schema. You need to set it up on the concerned databases.\n\n```bash\nPGPASSWORD=******** psql -h \u003c\u003cPostgresHost\u003e\u003e -U \u003c\u003cSuperUser\u003e\u003e -d \u003c\u003cDatabases\u003e\u003e -f pg_sqltxplan/initialsetup.sql\n```\n\n### Generating Report including underlying stats on objects and execution plan.\nWe have multiple options to generate report either directly from pg_stat_statements using GENERIC_PLAN supported since PostgreSQL 16 or run SQL within wrapper functions `(run_plan_analyze/run_plan_explain)`\n\n#### Option 1 - Running Problematic SQL using `run_plan_analyze` Wrapper\n\nUsing Dollar Quoting enclosed problematic SQL as input and run it using function `run_plan_analyze` defined in `planstats` schema.\n\n```sql\nplantest=# select planstats.run_plan_analyze($$select count(1) from emp$$);\n    run_plan_analyze\n-------------------------\n (1,7335632667878063635)\n(1 row)\n```\nIt will return internal planid and queryid for further references.\n\nIn next steps, we will generate pg_sqltxplain report using `psql` command line.If no Filter is provided by default it will generate report on last plan analyzed(max-planid).\n\n```bash\nPGPASSWORD=********* psql -h \u003c\u003cPostgresHost\u003e\u003e -U \u003c\u003cPGuser\u003e\u003e -d \u003c\u003cDatabases\u003e\u003e  -q -v ON_ERROR_STOP=1 -v query_id=7335632667878063635 -f pg_sqltxplain.sql\nGathering Database Object Stats for Query ID(7335632667878063635)\nUnderlying Statistics curated for Query(7335632667878063635) - Output File Stats_Via_Explain_Analyze_7335632667878063635.html\n```\n\nPlease note - Replace Host, DBname and Password as per your DB instances.\n\n####  Option 2 - Running Only Explain on Problematic SQL using Wrapper\n\nUsing Dollar Quoting enclosed problematic SQL as input and run it using function `run_plan_explain` defined in `planstats` schema.\n\n```sql\nplantest=# select planstats.run_plan_explain($$select count(1) from emp$$);\n    run_plan_analyze\n-------------------------\n (1,7335632667878063635)\n(1 row)\n```\n\nIn next steps, we will generate pg_sqltxplain report using `psql` command line.If no Filter is provided by default it will generate report on last plan analyzed(max-planid).\n\n```bash\nPGPASSWORD=********* psql -h \u003c\u003cPostgresHost\u003e\u003e -U \u003c\u003cPGuser\u003e\u003e -d \u003c\u003cDatabases\u003e\u003e  -q -v ON_ERROR_STOP=1 -v query_id=7335632667878063635 -f pg_sqltxplain.sql\nGathering Database Object Stats for Query ID(7335632667878063635)\nUnderlying Statistics curated for Query(7335632667878063635) - Output File pg_sqltxplain_7335632667878063635.html\n```\n\n####  Option 3 - Running using `pg_stat_statements` performance views (Preferably for PostgreSQL 16 onwards)\nUsing -v option of `psql`, we can pass `queryid` filters along with `pg_stat_statements` to use internal performance views to extract query metadata. It internally used `GENERIC_PLAN` plan options to generate underlying explain plan using `query` column.\n\n```bash\nPGPASSWORD=********* psql -h \u003c\u003cPostgresHost\u003e\u003e -U \u003c\u003cPGuser\u003e\u003e -d \u003c\u003cDatabases\u003e\u003e  -q -v ON_ERROR_STOP=1 -v query_id=8192079375982646892 -v pg_stat_statements= -f pg_sqltxplain.sql\n```\n\n### Integrations with `Pev2 Visualiser`\nIntegrate Execution plan objects statistics with [PEV2 visualiser](https://github.com/dalibo/pev2) a graphical vizualization of a PostgreSQL execution plan.\n\nWith any of the options mentioned previously, we can choose to get underlying stats of Objects with auto integrated it with PEV2. \nInternally it use two sql file to generate couple of html report as we are using iframe html tag to take care of different stylesheet. \n\nPlease note that we will need to share both generated HTML files.\n\n```bash\nPGPASSWORD=********* psql -h \u003c\u003cPostgresHost\u003e\u003e -U \u003c\u003cPGuser\u003e\u003e -d \u003c\u003cDatabases\u003e\u003e  -q -v ON_ERROR_STOP=1 -f explain_dalibo.sql -f pg_sqltxplain_with_dalibo.sql\n```\n\n### Sample Report \nCheck out sample html report created using  pg_sqltxplan utility.\n1. [Sample 1 - pg_sqltxplain](https://htmlpreview.github.io/?https://github.com/dcgadmin/pg_sqltxplain/blob/main/samplereport/pg_sqltxplain_8388037885303713885.html)\n2. [Sample 2 - pg_sqltxplain](https://htmlpreview.github.io/?https://github.com/dcgadmin/pg_sqltxplain/blob/main/samplereport/pg_sqltxplain_1545576602608240663.html)\n3. [Sample 3 - pg_sqltxplainDalibo](https://github.com/dcgadmin/pg_sqltxplain/blob/main/samplereport/StatsViaExplainAnalyze_With_dalibo.pdf)\n\n### Contact Details.\nFeel free to mail us(`contact@datacloudgaze.com`) for any issues or consulting on PostgreSQL performance Tuning.\n\n[www.datacloudgaze.com](www.datacloudgaze.com)\n","funding_links":[],"categories":["HTML","PLpgSQL"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdcgadmin%2Fpg_sqltxplain","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdcgadmin%2Fpg_sqltxplain","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdcgadmin%2Fpg_sqltxplain/lists"}