{"id":20491704,"url":"https://github.com/dalibo/pgshark","last_synced_at":"2025-04-13T16:55:18.023Z","repository":{"id":139466939,"uuid":"1388151","full_name":"dalibo/pgshark","owner":"dalibo","description":"Messing with PostgreSQL network traffic to make some usefull things","archived":false,"fork":false,"pushed_at":"2021-01-29T17:11:13.000Z","size":485,"stargazers_count":91,"open_issues_count":2,"forks_count":11,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-03-27T07:51:32.333Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://dalibo.github.io/pgshark","language":"Perl","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/dalibo.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":"2011-02-20T02:25:12.000Z","updated_at":"2025-03-20T22:04:13.000Z","dependencies_parsed_at":null,"dependency_job_id":"8c7d268f-14a0-4fb5-8bc7-33a3d9957ec5","html_url":"https://github.com/dalibo/pgshark","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dalibo%2Fpgshark","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dalibo%2Fpgshark/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dalibo%2Fpgshark/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dalibo%2Fpgshark/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dalibo","download_url":"https://codeload.github.com/dalibo/pgshark/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248750011,"owners_count":21155682,"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":[],"created_at":"2024-11-15T17:25:37.996Z","updated_at":"2025-04-13T16:55:18.006Z","avatar_url":"https://github.com/dalibo.png","language":"Perl","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n    \n    pgShark is a Perl module able to mess with PostgreSQL network\n    traffic\n\nSynopsis\n==================\n\nA simple example to count the number of connections and disconnections on localhost, live version:\n\n```perl\n        use pgShark;\n\n        my ($cnx, $dcnx) = (0, 0);\n        my $dev = 'lo';\n        my $err;\n\n        $shark = pgShark-\u003enew({\n            'procs' =\u003e {\n                'AuthenticationOk' =\u003e sub {$cnx++},\n                'Terminate' =\u003e sub {$dcnx++},\n            },\n            'host' =\u003e '127.0.0.1',\n            'port' =\u003e 5432\n        });\n\n        die \"Can not open interface $dev:\\n$err\" if $shark-\u003elive($dev, \\$err);\n\n        # on live capture, a ctrl-c interrupt the loop\n        $shark-\u003eprocess_all();\n\n        $shark-\u003eclose();\n\n        printf \"Number of connections/disconnections: %u/%u\\n\", $cnx, $dcnx;\n```\n\nDescription\n=========================\n\nThis Perl module is able to study PostgreSQL traffic captured from a\nnetwork interface and call various functions for each messages of the\nprotocol. The network dump could be live or from a pcap file (using\ntcpdump as instance).\n\npgShark comes with various sample scripts able to do various things with\nthese network dumps. See help page of each of them for more\ninformations.\n\nMethods\n================================\n\n    *   new (\\%settings)\n\n        Static method.\n\n        Creates a new pgShark object and returns it. It takes a hash as\n        parameter with the following settings:\n\n            {\n                'host' =\u003e IP address of the server\n                'port' =\u003e Port of the PostgreSQL server\n                'protocol' =\u003e the protocol version, ie. 2 or 3\n                'procs' =\u003e {\n                    # Hash of callbacks for each messages.\n                    'message name' =\u003e \\\u0026callback\n                    ...\n                }\n                'debug' =\u003e $level\n            }\n\n        When 'host' key is not given, pgShark will wait for a message coming\n        from the backend or the frontend with no doubt before calling user\n        callbacks. Depending on the network activity, it can takes more or\n        less time and messages might be lost (usually, COPY related ones).\n        If you really need *ALL* messages, set the 'host' key explicitly.\n\n        pgShark is not able to detect which port the server is listening.\n        Default is PostgreSQL's ones, ie. 5432. Make sure to always set the\n        proper port or pgShark will just filter out your PostgreSQL traffic\n        if it's not on 5432.\n\n        If not defined, the protocol version by default is 3.\n\n        The 'procs' hash associate a callback to each messages of the\n        PostgreSQL protocol you are interested in. See the following link\n        about available message names and definitions:\n\n          http://www.postgresql.org/docs/current/static/protocol-message-formats.html\n\n        One messages type has been added to both protocols: SSLAnswer.\n\n        The 'debug' key in settings can be set between 0 and 6, 0 is the\n        default with no debug message, 6 is the most verbose. Because of\n        internal performance consideration, you MUST set the environment\n        variable DEBUG to '1' to actually activate the debugging messages.\n\n    *   live ($interface, \\$err)\n\n        Open a live capture on given interface from first parameter. The\n        second parameter is a reference to a string. It will be filled with\n        the error message if the method fails.\n\n        Returns 0 on success, 1 on failure\n\n    *   open ($file, \\$err)\n\n        Open a given pcap file from first parameter. The second parameter is\n        a reference to a string. It will be filled with the error message if\n        the method fails.\n\n        Returns 0 on success, 1 on failure.\n\n    *   close ()\n\n        Close the pcap handle previously opened with this object using\n        either pgShark::live() or pgShark::open() methods.\n\n    *   process_all ()\n\n        Loop over all available packets from the previously opened pcap\n        handle.\n\n    *   dec2dot ($ip_addr)\n\n        Static method.\n\n        Convert a decimal IP address representation given as first parameter\n        to the human notation \"ww.xx.yy.zz\".\n\n    *   normalize_query ($query)\n\n        Static method.\n\n        Returns the normalized version of the query given as first\n        parameter.\n\nBinaries\n==================\n\n    For details, see the output of parameter \"--help\" for each of them.\n\n    *   pgs-badger\n\n        This script analyse the pcap traffics and outputs various statistics\n        about what was found in PostgreSQL protocol.\n\n        The report contains most popular queries, slowest cumulated ones,\n        slowest queries ever, classification of queries by type, sessions\n        time, number of connexion, errors, notices, etc.\n\n        The network dump could be live or from a pcap file (using tcpdump\n        for instance).\n\n        In a futur version this script is supposed to talk with pgbadger\n        directly !\n\n    *   pgs-debug\n\n        Outputs the PostgreSQL messages in human readable format. Useful to\n        analyze what is in a network dump before using pgshark on some other\n        duties.\n\n    *   pgs-normalize\n\n        The \"pgs-normalize\" script tries to normalize queries and prepared\n        statements and output them to stdout. Its purpose is to give you a\n        list of unique queries, whatever the number of time they have been\n        sent by clients and whatever their parameters were.\n\n    *   pgs-record\n\n        \"pgs-record\" filters network traffic and dump PostgreSQL related\n        activity to a pcap file. The pcap file can then be processed with\n        all available pgShark tools.\n\n        \"pgs-record\" rely on perl Net::Pcap module. However, unlike\n        Net::Pcap, \"tcpdump\" is able to set a bigger capture buffer using\n        recent libpcap. Default buffer size is often too small to be able to\n        dump all tcp datagram quickly enough. Because of this buffer size\n        (1MB), on high loaded systems, you might loose packets. Therefor, by\n        default, \"pgs-record\" will try to act as a wrapper around c\u003ctcpdump\u003e\n        if it is available on the system and set the buffer to \"32M\".\n\n        Capturing high throughput traffic, make sure your CPU, disks and\n        memory are good enough to deal with the amount of data. You might\n        want to set the capture buffer to 256MB or more and redirect\n        directly to a file for future use.\n\n    *   pgs-replay\n\n        \u003cpgs-replay\u003e send the PostgreSQL messages to a given PostgreSQL\n        cluster. The network dump could be live or from a pcap file (using\n        tcpdump for instance).\n\n        This script only supports protocol v3, making it compatilible with\n        versions 7.4 to 9.2 of PostgreSQL.\n\n        This script currently does not support any kind of authentication on\n        the remote PostgreSQL cluster where messages are send. Make sure it\n        can connect using ident, peer or trust.\n\n    *   pgs-sql\n\n        Writes captured queries on stdout. Because of the SQL language\n        doesn't support unnamed prepared statement, this script actually try\n        to names them. Presently, this script doesn't support cursors nor\n        COPY messages.\n\n    *   pgs-stat\n\n        Outputs various informations about PostgreSQL activity on the\n        network on a given sampling period.\n\nSee also\n===========\n\n    This module rely on two modules to parse message of protocols v2 and v3:\n    pgShark::protocol_2 and pgShark::protocol_3.\n\nLICENSING\n================\n\n    This program is open source, licensed under the simplified BSD license.\n    For license terms, see the LICENSE provided with the sources.\n\nAUTHORS\n============\n\n    Jehan-Guillaume de Rorthais \u003cjgdr@dalibo.com\u003e\n\n    Nicolas Thauvin \u003cnicolas.thauvin@dalibo.com\u003e\n\n    Guillaume Lelarge \u003cguillaume.lelarge@dalibo.com\u003e\n\n    Copyright: (C) 2012-2014 Jehan-Guillaume de Rorthais - All rights\n    reserved.\n\n    Dalibo's team. http://www.dalibo.org\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdalibo%2Fpgshark","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdalibo%2Fpgshark","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdalibo%2Fpgshark/lists"}