<!-- doc/src/sgml/pgstatstatements.sgml -->

<sect1 id="pgstatstatements" xreflabel="pg_stat_statements">
 <title>pg_stat_statements &mdash; track statistics of SQL planning and execution</title>

 <indexterm zone="pgstatstatements">
  <primary>pg_stat_statements</primary>
 </indexterm>

 <para>
  The <filename>pg_stat_statements</filename> module provides a means for
  tracking planning and execution statistics of all SQL statements executed by
  a server.
 </para>

 <para>
  The module must be loaded by adding <literal>pg_stat_statements</literal> to
  <xref linkend="guc-shared-preload-libraries"/> in
  <filename>postgresql.conf</filename>, because it requires additional shared memory.
  This means that a server restart is needed to add or remove the module.
  In addition, query identifier calculation must be enabled in order for the
  module to be active, which is done automatically if <xref linkend="guc-compute-query-id"/>
  is set to <literal>auto</literal> or <literal>on</literal>, or any third-party
  module that calculates query identifiers is loaded.
 </para>

 <para>
   When <filename>pg_stat_statements</filename> is active, it tracks
   statistics across all databases of the server.  To access and manipulate
   these statistics, the module provides views
   <structname>pg_stat_statements</structname> and
   <structname>pg_stat_statements_info</structname>,
   and the utility functions <function>pg_stat_statements_reset</function> and
   <function>pg_stat_statements</function>.  These are not available globally but
   can be enabled for a specific database with
   <command>CREATE EXTENSION pg_stat_statements</command>.
 </para>

 <sect2 id="pgstatstatements-pg-stat-statements">
  <title>The <structname>pg_stat_statements</structname> View</title>

  <para>
   The statistics gathered by the module are made available via a
   view named <structname>pg_stat_statements</structname>.  This view
   contains one row for each distinct combination of database ID, user
   ID, query ID and whether it's a top-level statement or not (up to
   the maximum number of distinct statements that the module can track).
   The columns of the view are shown in
   <xref linkend="pgstatstatements-columns"/>.
  </para>

  <table id="pgstatstatements-columns">
   <title><structname>pg_stat_statements</structname> Columns</title>
   <tgroup cols="1">
    <thead>
     <row>
      <entry role="catalog_table_entry"><para role="column_definition">
       Column Type
      </para>
      <para>
       Description
      </para></entry>
     </row>
    </thead>

    <tbody>
     <row>
      <entry role="catalog_table_entry"><para role="column_definition">
       <structfield>userid</structfield> <type>oid</type>
       (references <link linkend="catalog-pg-authid"><structname>pg_authid</structname></link>.<structfield>oid</structfield>)
      </para>
      <para>
       OID of user who executed the statement
      </para></entry>
     </row>

     <row>
      <entry role="catalog_table_entry"><para role="column_definition">
       <structfield>dbid</structfield> <type>oid</type>
       (references <link linkend="catalog-pg-database"><structname>pg_database</structname></link>.<structfield>oid</structfield>)
      </para>
      <para>
       OID of database in which the statement was executed
      </para></entry>
     </row>

     <row>
      <entry role="catalog_table_entry"><para role="column_definition">
       <structfield>toplevel</structfield> <type>bool</type>
      </para>
      <para>
       True if the query was executed as a top-level statement
       (always true if <varname>pg_stat_statements.track</varname> is set to
       <literal>top</literal>)
      </para></entry>
     </row>

     <row>
      <entry role="catalog_table_entry"><para role="column_definition">
       <structfield>queryid</structfield> <type>bigint</type>
      </para>
      <para>
       Hash code to identify identical normalized queries.
      </para></entry>
     </row>