doc/src/sgml/system-views.sgml

   1 <!-- doc/src/sgml/system-views.sgml -->
   2 <!--
   3  Documentation of the system views, directed toward PostgreSQL developers
   4  -->
   5
   6 <chapter id="views">
   7  <title>System Views</title>
   8
   9   <para>
  10    In addition to the system catalogs, <productname>PostgreSQL</productname>
  11    provides a number of built-in views.  Some system views provide convenient
  12    access to some commonly used queries on the system catalogs.  Other views
  13    provide access to internal server state.
  14   </para>
  15
  16   <para>
  17    The information schema (<xref linkend="information-schema"/>) provides
  18    an alternative set of views which overlap the functionality of the system
  19    views.  Since the information schema is SQL-standard whereas the views
  20    described here are <productname>PostgreSQL</productname>-specific,
  21    it's usually better to use the information schema if it provides all
  22    the information you need.
  23   </para>
  24
  25   <para>
  26    <xref linkend="view-table"/> lists the system views described here.
  27    More detailed documentation of each view follows below.
  28    There are some additional views that provide access to accumulated
  29    statistics; they are described in
  30    <xref linkend="monitoring-stats-views-table"/>.
  31   </para>
  32
  33  <sect1 id="views-overview">
  34   <title>Overview</title>
  35
  36   <para>
  37    <xref linkend="view-table"/> lists the system views.
  38    More detailed documentation of each catalog follows below.
  39    Except where noted, all the views described here are read-only.
  40   </para>
  41
  42   <table id="view-table">
  43    <title>System Views</title>
  44
  45    <tgroup cols="2">
  46     <thead>
  47      <row>
  48       <entry>View Name</entry>
  49       <entry>Purpose</entry>
  50      </row>
  51     </thead>
  52
  53     <tbody>
  54      <row>
  55       <entry><link linkend="view-pg-available-extensions"><structname>pg_available_extensions</structname></link></entry>
  56       <entry>available extensions</entry>
  57      </row>
  58
  59      <row>
  60       <entry><link linkend="view-pg-available-extension-versions"><structname>pg_available_extension_versions</structname></link></entry>
  61       <entry>available versions of extensions</entry>
  62      </row>
  63
  64      <row>
  65       <entry><link linkend="view-pg-backend-memory-contexts"><structname>pg_backend_memory_contexts</structname></link></entry>
  66       <entry>backend memory contexts</entry>
  67      </row>
  68
  69      <row>
  70       <entry><link linkend="view-pg-config"><structname>pg_config</structname></link></entry>
  71       <entry>compile-time configuration parameters</entry>
  72      </row>
  73
  74      <row>
  75       <entry><link linkend="view-pg-cursors"><structname>pg_cursors</structname></link></entry>
  76       <entry>open cursors</entry>
  77      </row>
  78
  79      <row>
  80       <entry><link linkend="view-pg-file-settings"><structname>pg_file_settings</structname></link></entry>
  81       <entry>summary of configuration file contents</entry>
  82      </row>
  83
  84      <row>
  85       <entry><link linkend="view-pg-group"><structname>pg_group</structname></link></entry>
  86       <entry>groups of database users</entry>
  87      </row>
  88
  89      <row>
  90       <entry><link linkend="view-pg-hba-file-rules"><structname>pg_hba_file_rules</structname></link></entry>
  91       <entry>summary of client authentication configuration file contents</entry>
  92      </row>
  93
  94      <row>
  95       <entry><link linkend="view-pg-ident-file-mappings"><structname>pg_ident_file_mappings</structname></link></entry>
  96       <entry>summary of client user name mapping configuration file contents</entry>
  97      </row>
  98
  99      <row>
 100       <entry><link linkend="view-pg-indexes"><structname>pg_indexes</structname></link></entry>
 101       <entry>indexes</entry>
 102      </row>
 103
 104      <row>
 105       <entry><link linkend="view-pg-locks"><structname>pg_locks</structname></link></entry>
 106       <entry>locks currently held or awaited</entry>
 107      </row>
 108
 109      <row>
 110       <entry><link linkend="view-pg-matviews"><structname>pg_matviews</structname></link></entry>
 111       <entry>materialized views</entry>
 112      </row>
 113
 114      <row>
 115       <entry><link linkend="view-pg-policies"><structname>pg_policies</structname></link></entry>
 116       <entry>policies</entry>
 117      </row>
 118
 119      <row>
 120       <entry><link linkend="view-pg-prepared-statements"><structname>pg_prepared_statements</structname></link></entry>
 121       <entry>prepared statements</entry>
 122      </row>
 123
 124      <row>
 125       <entry><link linkend="view-pg-prepared-xacts"><structname>pg_prepared_xacts</structname></link></entry>
 126       <entry>prepared transactions</entry>
 127      </row>
 128
 129      <row>
 130       <entry><link linkend="view-pg-publication-tables"><structname>pg_publication_tables</structname></link></entry>
 131       <entry>publications and information of their associated tables</entry>
 132      </row>
 133
 134      <row>
 135       <entry><link linkend="view-pg-replication-origin-status"><structname>pg_replication_origin_status</structname></link></entry>
 136       <entry>information about replication origins, including replication progress</entry>
 137      </row>
 138
 139      <row>
 140       <entry><link linkend="view-pg-replication-slots"><structname>pg_replication_slots</structname></link></entry>
 141       <entry>replication slot information</entry>
 142      </row>
 143
 144      <row>
 145       <entry><link linkend="view-pg-roles"><structname>pg_roles</structname></link></entry>
 146       <entry>database roles</entry>
 147      </row>
 148
 149      <row>
 150       <entry><link linkend="view-pg-rules"><structname>pg_rules</structname></link></entry>
 151       <entry>rules</entry>
 152      </row>
 153
 154      <row>
 155       <entry><link linkend="view-pg-seclabels"><structname>pg_seclabels</structname></link></entry>
 156       <entry>security labels</entry>
 157      </row>
 158
 159      <row>
 160       <entry><link linkend="view-pg-sequences"><structname>pg_sequences</structname></link></entry>
 161       <entry>sequences</entry>
 162      </row>
 163
 164      <row>
 165       <entry><link linkend="view-pg-settings"><structname>pg_settings</structname></link></entry>
 166       <entry>parameter settings</entry>
 167      </row>
 168
 169      <row>
 170       <entry><link linkend="view-pg-shadow"><structname>pg_shadow</structname></link></entry>
 171       <entry>database users</entry>
 172      </row>
 173
 174      <row>
 175       <entry><link linkend="view-pg-shmem-allocations"><structname>pg_shmem_allocations</structname></link></entry>
 176       <entry>shared memory allocations</entry>
 177      </row>
 178
 179      <row>
 180       <entry><link linkend="view-pg-stats"><structname>pg_stats</structname></link></entry>
 181       <entry>planner statistics</entry>
 182      </row>
 183
 184      <row>
 185       <entry><link linkend="view-pg-stats-ext"><structname>pg_stats_ext</structname></link></entry>
 186       <entry>extended planner statistics</entry>
 187      </row>
 188
 189      <row>
 190       <entry><link linkend="view-pg-stats-ext-exprs"><structname>pg_stats_ext_exprs</structname></link></entry>
 191       <entry>extended planner statistics for expressions</entry>
 192      </row>
 193
 194      <row>
 195       <entry><link linkend="view-pg-tables"><structname>pg_tables</structname></link></entry>
 196       <entry>tables</entry>
 197      </row>
 198
 199      <row>
 200       <entry><link linkend="view-pg-timezone-abbrevs"><structname>pg_timezone_abbrevs</structname></link></entry>
 201       <entry>time zone abbreviations</entry>
 202      </row>
 203
 204      <row>
 205       <entry><link linkend="view-pg-timezone-names"><structname>pg_timezone_names</structname></link></entry>
 206       <entry>time zone names</entry>
 207      </row>
 208
 209      <row>
 210       <entry><link linkend="view-pg-user"><structname>pg_user</structname></link></entry>
 211       <entry>database users</entry>
 212      </row>
 213
 214      <row>
 215       <entry><link linkend="view-pg-user-mappings"><structname>pg_user_mappings</structname></link></entry>
 216       <entry>user mappings</entry>
 217      </row>
 218
 219      <row>
 220       <entry><link linkend="view-pg-views"><structname>pg_views</structname></link></entry>
 221       <entry>views</entry>
 222      </row>
 223
 224      <row>
 225       <entry><link linkend="view-pg-wait-events"><structname>pg_wait_events</structname></link></entry>
 226       <entry>wait events</entry>
 227      </row>
 228
 229     </tbody>
 230    </tgroup>
 231   </table>
 232  </sect1>
 233
 234  <sect1 id="view-pg-available-extensions">
 235   <title><structname>pg_available_extensions</structname></title>
 236
 237   <indexterm zone="view-pg-available-extensions">
 238    <primary>pg_available_extensions</primary>
 239   </indexterm>
 240
 241   <para>
 242    The <structname>pg_available_extensions</structname> view lists the
 243    extensions that are available for installation.
 244    See also the
 245    <link linkend="catalog-pg-extension"><structname>pg_extension</structname></link>
 246    catalog, which shows the extensions currently installed.
 247   </para>
 248
 249   <table>
 250    <title><structname>pg_available_extensions</structname> Columns</title>
 251    <tgroup cols="1">
 252     <thead>
 253      <row>
 254       <entry role="catalog_table_entry"><para role="column_definition">
 255        Column Type
 256       </para>
 257       <para>
 258        Description
 259       </para></entry>
 260      </row>
 261     </thead>
 262
 263     <tbody>
 264      <row>
 265       <entry role="catalog_table_entry"><para role="column_definition">
 266        <structfield>name</structfield> <type>name</type>
 267       </para>
 268       <para>
 269        Extension name
 270       </para></entry>
 271      </row>
 272
 273      <row>
 274       <entry role="catalog_table_entry"><para role="column_definition">
 275        <structfield>default_version</structfield> <type>text</type>
 276       </para>
 277       <para>
 278        Name of default version, or <literal>NULL</literal> if none is
 279        specified
 280       </para></entry>
 281      </row>
 282
 283      <row>
 284       <entry role="catalog_table_entry"><para role="column_definition">
 285        <structfield>installed_version</structfield> <type>text</type>
 286       </para>
 287       <para>
 288        Currently installed version of the extension,
 289        or <literal>NULL</literal> if not installed
 290       </para></entry>
 291      </row>
 292
 293      <row>
 294       <entry role="catalog_table_entry"><para role="column_definition">
 295        <structfield>comment</structfield> <type>text</type>
 296       </para>
 297       <para>
 298        Comment string from the extension's control file
 299       </para></entry>
 300      </row>
 301     </tbody>
 302    </tgroup>
 303   </table>
 304
 305   <para>
 306    The <structname>pg_available_extensions</structname> view is read-only.
 307   </para>
 308  </sect1>
 309
 310  <sect1 id="view-pg-available-extension-versions">
 311   <title><structname>pg_available_extension_versions</structname></title>
 312
 313   <indexterm zone="view-pg-available-extension-versions">
 314    <primary>pg_available_extension_versions</primary>
 315   </indexterm>
 316
 317   <para>
 318    The <structname>pg_available_extension_versions</structname> view lists the
 319    specific extension versions that are available for installation.
 320    See also the <link
 321    linkend="catalog-pg-extension"><structname>pg_extension</structname></link>
 322    catalog, which shows the extensions currently installed.
 323   </para>
 324
 325   <table>
 326    <title><structname>pg_available_extension_versions</structname> Columns</title>
 327    <tgroup cols="1">
 328     <thead>
 329      <row>
 330       <entry role="catalog_table_entry"><para role="column_definition">
 331        Column Type
 332       </para>
 333       <para>
 334        Description
 335       </para></entry>
 336      </row>
 337     </thead>
 338
 339     <tbody>
 340      <row>
 341       <entry role="catalog_table_entry"><para role="column_definition">
 342        <structfield>name</structfield> <type>name</type>
 343       </para>
 344       <para>
 345        Extension name
 346       </para></entry>
 347      </row>
 348
 349      <row>
 350       <entry role="catalog_table_entry"><para role="column_definition">
 351        <structfield>version</structfield> <type>text</type>
 352       </para>
 353       <para>
 354        Version name
 355       </para></entry>
 356      </row>
 357
 358      <row>
 359       <entry role="catalog_table_entry"><para role="column_definition">
 360        <structfield>installed</structfield> <type>bool</type>
 361       </para>
 362       <para>
 363        True if this version of this extension is currently
 364        installed
 365       </para></entry>
 366      </row>
 367
 368      <row>
 369       <entry role="catalog_table_entry"><para role="column_definition">
 370        <structfield>superuser</structfield> <type>bool</type>
 371       </para>
 372       <para>
 373        True if only superusers are allowed to install this extension
 374        (but see <structfield>trusted</structfield>)
 375       </para></entry>
 376      </row>
 377
 378      <row>
 379       <entry role="catalog_table_entry"><para role="column_definition">
 380        <structfield>trusted</structfield> <type>bool</type>
 381       </para>
 382       <para>
 383        True if the extension can be installed by non-superusers
 384        with appropriate privileges
 385       </para></entry>
 386      </row>
 387
 388      <row>
 389       <entry role="catalog_table_entry"><para role="column_definition">
 390        <structfield>relocatable</structfield> <type>bool</type>
 391       </para>
 392       <para>
 393        True if extension can be relocated to another schema
 394       </para></entry>
 395      </row>
 396
 397      <row>
 398       <entry role="catalog_table_entry"><para role="column_definition">
 399        <structfield>schema</structfield> <type>name</type>
 400       </para>
 401       <para>
 402        Name of the schema that the extension must be installed into,
 403        or <literal>NULL</literal> if partially or fully relocatable
 404       </para></entry>
 405      </row>
 406
 407      <row>
 408       <entry role="catalog_table_entry"><para role="column_definition">
 409        <structfield>requires</structfield> <type>name[]</type>
 410       </para>
 411       <para>
 412        Names of prerequisite extensions,
 413        or <literal>NULL</literal> if none
 414       </para></entry>
 415      </row>
 416
 417      <row>
 418       <entry role="catalog_table_entry"><para role="column_definition">
 419        <structfield>comment</structfield> <type>text</type>
 420       </para>
 421       <para>
 422        Comment string from the extension's control file
 423       </para></entry>
 424      </row>
 425     </tbody>
 426    </tgroup>
 427   </table>
 428
 429   <para>
 430    The <structname>pg_available_extension_versions</structname> view is
 431    read-only.
 432   </para>
 433  </sect1>
 434
 435  <sect1 id="view-pg-backend-memory-contexts">
 436   <title><structname>pg_backend_memory_contexts</structname></title>
 437
 438   <indexterm zone="view-pg-backend-memory-contexts">
 439    <primary>pg_backend_memory_contexts</primary>
 440   </indexterm>
 441
 442   <para>
 443    The view <structname>pg_backend_memory_contexts</structname> displays all
 444    the memory contexts of the server process attached to the current session.
 445   </para>
 446   <para>
 447    <structname>pg_backend_memory_contexts</structname> contains one row
 448    for each memory context.
 449   </para>
 450
 451   <table>
 452    <title><structname>pg_backend_memory_contexts</structname> Columns</title>
 453    <tgroup cols="1">
 454     <thead>
 455      <row>
 456       <entry role="catalog_table_entry"><para role="column_definition">
 457        Column Type
 458       </para>
 459       <para>
 460        Description
 461       </para></entry>
 462      </row>
 463     </thead>
 464
 465     <tbody>
 466      <row>
 467       <entry role="catalog_table_entry"><para role="column_definition">
 468        <structfield>name</structfield> <type>text</type>
 469       </para>
 470       <para>
 471        Name of the memory context
 472       </para></entry>
 473      </row>
 474
 475      <row>
 476       <entry role="catalog_table_entry"><para role="column_definition">
 477        <structfield>ident</structfield> <type>text</type>
 478       </para>
 479       <para>
 480        Identification information of the memory context. This field is truncated at 1024 bytes
 481       </para></entry>
 482      </row>
 483
 484      <row>
 485       <entry role="catalog_table_entry"><para role="column_definition">
 486        <structfield>type</structfield> <type>text</type>
 487       </para>
 488       <para>
 489        Type of the memory context
 490       </para></entry>
 491      </row>
 492
 493      <row>
 494       <entry role="catalog_table_entry"><para role="column_definition">
 495        <structfield>level</structfield> <type>int4</type>
 496       </para>
 497       <para>
 498        The 1-based level of the context in the memory context hierarchy. The
 499        level of a context also shows the position of that context in the
 500        <structfield>path</structfield> column.
 501       </para></entry>
 502      </row>
 503
 504      <row>
 505       <entry role="catalog_table_entry"><para role="column_definition">
 506        <structfield>path</structfield> <type>int4[]</type>
 507       </para>
 508       <para>
 509        Array of transient numerical identifiers to describe the memory
 510        context hierarchy. The first element is for
 511        <literal>TopMemoryContext</literal>, subsequent elements contain
 512        intermediate parents and the final element contains the identifier for
 513        the current context.
 514       </para></entry>
 515      </row>
 516
 517      <row>
 518       <entry role="catalog_table_entry"><para role="column_definition">
 519        <structfield>total_bytes</structfield> <type>int8</type>
 520       </para>
 521       <para>
 522        Total bytes allocated for this memory context
 523       </para></entry>
 524      </row>
 525
 526      <row>
 527       <entry role="catalog_table_entry"><para role="column_definition">
 528        <structfield>total_nblocks</structfield> <type>int8</type>
 529       </para>
 530       <para>
 531        Total number of blocks allocated for this memory context
 532       </para></entry>
 533      </row>
 534
 535      <row>
 536       <entry role="catalog_table_entry"><para role="column_definition">
 537        <structfield>free_bytes</structfield> <type>int8</type>
 538       </para>
 539       <para>
 540        Free space in bytes
 541       </para></entry>
 542      </row>
 543
 544      <row>
 545       <entry role="catalog_table_entry"><para role="column_definition">
 546        <structfield>free_chunks</structfield> <type>int8</type>
 547       </para>
 548       <para>
 549        Total number of free chunks
 550       </para></entry>
 551      </row>
 552
 553      <row>
 554       <entry role="catalog_table_entry"><para role="column_definition">
 555        <structfield>used_bytes</structfield> <type>int8</type>
 556       </para>
 557       <para>
 558        Used space in bytes
 559       </para></entry>
 560      </row>
 561     </tbody>
 562    </tgroup>
 563   </table>
 564
 565   <para>
 566    By default, the <structname>pg_backend_memory_contexts</structname> view can be
 567    read only by superusers or roles with the privileges of the
 568    <literal>pg_read_all_stats</literal> role.
 569   </para>
 570
 571   <para>
 572    Since memory contexts are created and destroyed during the running of a
 573    query, the identifiers stored in the <structfield>path</structfield> column
 574    can be unstable between multiple invocations of the view in the same query.
 575    The example below demonstrates an effective usage of this column and
 576    calculates the total number of bytes used by
 577    <literal>CacheMemoryContext</literal> and all of its children:
 578
 579 <programlisting>
 580 WITH memory_contexts AS (
 581     SELECT * FROM pg_backend_memory_contexts
 582 )
 583 SELECT sum(c1.total_bytes)
 584 FROM memory_contexts c1, memory_contexts c2
 585 WHERE c2.name = 'CacheMemoryContext'
 586 AND c1.path[c2.level] = c2.path[c2.level];
 587 </programlisting>
 588
 589    The <link linkend="queries-with">Common Table Expression</link> is used
 590    to ensure the context IDs in the <structfield>path</structfield> column
 591    match between both evaluations of the view.
 592   </para>
 593  </sect1>
 594
 595  <sect1 id="view-pg-config">
 596   <title><structname>pg_config</structname></title>
 597
 598   <indexterm zone="view-pg-config">
 599    <primary>pg_config</primary>
 600   </indexterm>
 601
 602   <para>
 603    The view <structname>pg_config</structname> describes the
 604    compile-time configuration parameters of the currently installed
 605    version of <productname>PostgreSQL</productname>. It is intended, for example, to
 606    be used by software packages that want to interface to
 607    <productname>PostgreSQL</productname> to facilitate finding the required header
 608    files and libraries. It provides the same basic information as the
 609    <xref linkend="app-pgconfig"/> <productname>PostgreSQL</productname> client
 610    application.
 611   </para>
 612
 613   <para>
 614    By default, the <structname>pg_config</structname> view can be read
 615    only by superusers.
 616   </para>
 617
 618   <table>
 619    <title><structname>pg_config</structname> Columns</title>
 620    <tgroup cols="1">
 621     <thead>
 622      <row>
 623       <entry role="catalog_table_entry"><para role="column_definition">
 624        Column Type
 625       </para>
 626       <para>
 627        Description
 628       </para></entry>
 629      </row>
 630     </thead>
 631
 632     <tbody>
 633      <row>
 634       <entry role="catalog_table_entry"><para role="column_definition">
 635        <structfield>name</structfield> <type>text</type>
 636       </para>
 637       <para>
 638        The parameter name
 639       </para></entry>
 640      </row>
 641
 642      <row>
 643       <entry role="catalog_table_entry"><para role="column_definition">
 644        <structfield>setting</structfield> <type>text</type>
 645       </para>
 646       <para>
 647        The parameter value
 648       </para></entry>
 649      </row>
 650     </tbody>
 651    </tgroup>
 652   </table>
 653
 654  </sect1>
 655
 656  <sect1 id="view-pg-cursors">
 657   <title><structname>pg_cursors</structname></title>
 658
 659   <indexterm zone="view-pg-cursors">
 660    <primary>pg_cursors</primary>
 661   </indexterm>
 662
 663   <para>
 664    The <structname>pg_cursors</structname> view lists the cursors that
 665    are currently available. Cursors can be defined in several ways:
 666    <itemizedlist>
 667     <listitem>
 668      <para>
 669       via the <link linkend="sql-declare"><command>DECLARE</command></link>
 670       statement in SQL
 671      </para>
 672     </listitem>
 673
 674     <listitem>
 675      <para>
 676       via the Bind message in the frontend/backend protocol, as
 677       described in <xref linkend="protocol-flow-ext-query"/>
 678      </para>
 679     </listitem>
 680
 681     <listitem>
 682      <para>
 683       via the Server Programming Interface (SPI), as described in
 684       <xref linkend="spi-interface"/>
 685      </para>
 686     </listitem>
 687    </itemizedlist>
 688
 689    The <structname>pg_cursors</structname> view displays cursors
 690    created by any of these means. Cursors only exist for the duration
 691    of the transaction that defines them, unless they have been
 692    declared <literal>WITH HOLD</literal>. Therefore non-holdable
 693    cursors are only present in the view until the end of their
 694    creating transaction.
 695
 696    <note>
 697     <para>
 698      Cursors are used internally to implement some of the components
 699      of <productname>PostgreSQL</productname>, such as procedural languages.
 700      Therefore, the <structname>pg_cursors</structname> view might include cursors
 701      that have not been explicitly created by the user.
 702     </para>
 703    </note>
 704   </para>
 705
 706   <table>
 707    <title><structname>pg_cursors</structname> Columns</title>
 708    <tgroup cols="1">
 709     <thead>
 710      <row>
 711       <entry role="catalog_table_entry"><para role="column_definition">
 712        Column Type
 713       </para>
 714       <para>
 715        Description
 716       </para></entry>
 717      </row>
 718     </thead>
 719
 720     <tbody>
 721      <row>
 722       <entry role="catalog_table_entry"><para role="column_definition">
 723        <structfield>name</structfield> <type>text</type>
 724       </para>
 725       <para>
 726        The name of the cursor
 727       </para></entry>
 728      </row>
 729
 730      <row>
 731       <entry role="catalog_table_entry"><para role="column_definition">
 732        <structfield>statement</structfield> <type>text</type>
 733       </para>
 734       <para>
 735        The verbatim query string submitted to declare this cursor
 736       </para></entry>
 737      </row>
 738
 739      <row>
 740       <entry role="catalog_table_entry"><para role="column_definition">
 741        <structfield>is_holdable</structfield> <type>bool</type>
 742       </para>
 743       <para>
 744        <literal>true</literal> if the cursor is holdable (that is, it
 745        can be accessed after the transaction that declared the cursor
 746        has committed); <literal>false</literal> otherwise
 747       </para></entry>
 748      </row>
 749
 750      <row>
 751       <entry role="catalog_table_entry"><para role="column_definition">
 752        <structfield>is_binary</structfield> <type>bool</type>
 753       </para>
 754       <para>
 755        <literal>true</literal> if the cursor was declared
 756        <literal>BINARY</literal>; <literal>false</literal>
 757        otherwise
 758       </para></entry>
 759      </row>
 760
 761      <row>
 762       <entry role="catalog_table_entry"><para role="column_definition">
 763        <structfield>is_scrollable</structfield> <type>bool</type>
 764       </para>
 765       <para>
 766        <literal>true</literal> if the cursor is scrollable (that is, it
 767        allows rows to be retrieved in a nonsequential manner);
 768        <literal>false</literal> otherwise
 769       </para></entry>
 770      </row>
 771
 772      <row>
 773       <entry role="catalog_table_entry"><para role="column_definition">
 774        <structfield>creation_time</structfield> <type>timestamptz</type>
 775       </para>
 776       <para>
 777        The time at which the cursor was declared
 778       </para></entry>
 779      </row>
 780     </tbody>
 781    </tgroup>
 782   </table>
 783
 784   <para>
 785    The <structname>pg_cursors</structname> view is read-only.
 786   </para>
 787
 788  </sect1>
 789
 790  <sect1 id="view-pg-file-settings">
 791   <title><structname>pg_file_settings</structname></title>
 792
 793   <indexterm zone="view-pg-file-settings">
 794    <primary>pg_file_settings</primary>
 795   </indexterm>
 796
 797   <para>
 798    The view <structname>pg_file_settings</structname> provides a summary of
 799    the contents of the server's configuration file(s).  A row appears in
 800    this view for each <quote>name = value</quote> entry appearing in the files,
 801    with annotations indicating whether the value could be applied
 802    successfully.  Additional row(s) may appear for problems not linked to
 803    a <quote>name = value</quote> entry, such as syntax errors in the files.
 804   </para>
 805
 806   <para>
 807    This view is helpful for checking whether planned changes in the
 808    configuration files will work, or for diagnosing a previous failure.
 809    Note that this view reports on the <emphasis>current</emphasis> contents of the
 810    files, not on what was last applied by the server.  (The
 811    <link linkend="view-pg-settings"><structname>pg_settings</structname></link>
 812    view is usually sufficient to determine that.)
 813   </para>
 814
 815   <para>
 816    By default, the <structname>pg_file_settings</structname> view can be read
 817    only by superusers.
 818   </para>
 819
 820   <table>
 821    <title><structname>pg_file_settings</structname> Columns</title>
 822    <tgroup cols="1">
 823     <thead>
 824      <row>
 825       <entry role="catalog_table_entry"><para role="column_definition">
 826        Column Type
 827       </para>
 828       <para>
 829        Description
 830       </para></entry>
 831      </row>
 832     </thead>
 833
 834     <tbody>
 835      <row>
 836       <entry role="catalog_table_entry"><para role="column_definition">
 837        <structfield>sourcefile</structfield> <type>text</type>
 838       </para>
 839       <para>
 840        Full path name of the configuration file
 841       </para></entry>
 842      </row>
 843
 844      <row>
 845       <entry role="catalog_table_entry"><para role="column_definition">
 846        <structfield>sourceline</structfield> <type>int4</type>
 847       </para>
 848       <para>
 849        Line number within the configuration file where the entry appears
 850       </para></entry>
 851      </row>
 852
 853      <row>
 854       <entry role="catalog_table_entry"><para role="column_definition">
 855        <structfield>seqno</structfield> <type>int4</type>
 856       </para>
 857       <para>
 858        Order in which the entries are processed (1..<replaceable>n</replaceable>)
 859       </para></entry>
 860      </row>
 861
 862      <row>
 863       <entry role="catalog_table_entry"><para role="column_definition">
 864        <structfield>name</structfield> <type>text</type>
 865       </para>
 866       <para>
 867        Configuration parameter name
 868       </para></entry>
 869      </row>
 870
 871      <row>
 872       <entry role="catalog_table_entry"><para role="column_definition">
 873        <structfield>setting</structfield> <type>text</type>
 874       </para>
 875       <para>
 876        Value to be assigned to the parameter
 877       </para></entry>
 878      </row>
 879
 880      <row>
 881       <entry role="catalog_table_entry"><para role="column_definition">
 882        <structfield>applied</structfield> <type>bool</type>
 883       </para>
 884       <para>
 885        True if the value can be applied successfully
 886       </para></entry>
 887      </row>
 888
 889      <row>
 890       <entry role="catalog_table_entry"><para role="column_definition">
 891        <structfield>error</structfield> <type>text</type>
 892       </para>
 893       <para>
 894        If not null, an error message indicating why this entry could
 895        not be applied
 896       </para></entry>
 897      </row>
 898     </tbody>
 899    </tgroup>
 900   </table>
 901
 902   <para>
 903    If the configuration file contains syntax errors or invalid parameter
 904    names, the server will not attempt to apply any settings from it, and
 905    therefore all the <structfield>applied</structfield> fields will read as false.
 906    In such a case there will be one or more rows with
 907    non-null <structfield>error</structfield> fields indicating the
 908    problem(s).  Otherwise, individual settings will be applied if possible.
 909    If an individual setting cannot be applied (e.g., invalid value, or the
 910    setting cannot be changed after server start) it will have an appropriate
 911    message in the <structfield>error</structfield> field.  Another way that
 912    an entry might have <structfield>applied</structfield> = false is that it is
 913    overridden by a later entry for the same parameter name; this case is not
 914    considered an error so nothing appears in
 915    the <structfield>error</structfield> field.
 916   </para>
 917
 918   <para>
 919    See <xref linkend="config-setting"/> for more information about the various
 920    ways to change run-time parameters.
 921   </para>
 922
 923 </sect1>
 924
 925  <sect1 id="view-pg-group">
 926   <title><structname>pg_group</structname></title>
 927
 928   <indexterm zone="view-pg-group">
 929    <primary>pg_group</primary>
 930   </indexterm>
 931
 932   <!-- Unlike information_schema.applicable_roles, this shows no members for
 933        pg_database_owner.  The v8.1 catalog would have shown no members if
 934        that role had existed at the time. -->
 935   <para>
 936    The view <structname>pg_group</structname> exists for backwards
 937    compatibility: it emulates a catalog that existed in
 938    <productname>PostgreSQL</productname> before version 8.1.
 939    It shows the names and members of all roles that are marked as not
 940    <structfield>rolcanlogin</structfield>, which is an approximation to the set
 941    of roles that are being used as groups.
 942   </para>
 943
 944   <table>
 945    <title><structname>pg_group</structname> Columns</title>
 946    <tgroup cols="1">
 947     <thead>
 948      <row>
 949       <entry role="catalog_table_entry"><para role="column_definition">
 950        Column Type
 951       </para>
 952       <para>
 953        Description
 954       </para></entry>
 955      </row>
 956     </thead>
 957
 958     <tbody>
 959      <row>
 960       <entry role="catalog_table_entry"><para role="column_definition">
 961        <structfield>groname</structfield> <type>name</type>
 962        (references <link linkend="catalog-pg-authid"><structname>pg_authid</structname></link>.<structfield>rolname</structfield>)
 963       </para>
 964       <para>
 965        Name of the group
 966       </para></entry>
 967      </row>
 968
 969      <row>
 970       <entry role="catalog_table_entry"><para role="column_definition">
 971        <structfield>grosysid</structfield> <type>oid</type>
 972        (references <link linkend="catalog-pg-authid"><structname>pg_authid</structname></link>.<structfield>oid</structfield>)
 973       </para>
 974       <para>
 975        ID of this group
 976       </para></entry>
 977      </row>
 978
 979      <row>
 980       <entry role="catalog_table_entry"><para role="column_definition">
 981        <structfield>grolist</structfield> <type>oid[]</type>
 982        (references <link linkend="catalog-pg-authid"><structname>pg_authid</structname></link>.<structfield>oid</structfield>)
 983       </para>
 984       <para>
 985        An array containing the IDs of the roles in this group
 986       </para></entry>
 987      </row>
 988     </tbody>
 989    </tgroup>
 990   </table>
 991
 992  </sect1>
 993
 994  <sect1 id="view-pg-hba-file-rules">
 995   <title><structname>pg_hba_file_rules</structname></title>
 996
 997   <indexterm zone="view-pg-hba-file-rules">
 998    <primary>pg_hba_file_rules</primary>
 999   </indexterm>
1000
1001   <para>
1002    The view <structname>pg_hba_file_rules</structname> provides a summary of
1003    the contents of the client authentication configuration file,
1004    <link linkend="auth-pg-hba-conf"><filename>pg_hba.conf</filename></link>.
1005    A row appears in this view for each
1006    non-empty, non-comment line in the file, with annotations indicating
1007    whether the rule could be applied successfully.
1008   </para>
1009
1010   <para>
1011    This view can be helpful for checking whether planned changes in the
1012    authentication configuration file will work, or for diagnosing a previous
1013    failure.  Note that this view reports on the <emphasis>current</emphasis> contents
1014    of the file, not on what was last loaded by the server.
1015   </para>
1016
1017   <para>
1018    By default, the <structname>pg_hba_file_rules</structname> view can be read
1019    only by superusers.
1020   </para>
1021
1022   <table>
1023    <title><structname>pg_hba_file_rules</structname> Columns</title>
1024    <tgroup cols="1">
1025     <thead>
1026      <row>
1027       <entry role="catalog_table_entry"><para role="column_definition">
1028        Column Type
1029       </para>
1030       <para>
1031        Description
1032       </para></entry>
1033      </row>
1034     </thead>
1035
1036     <tbody>
1037      <row>
1038       <entry role="catalog_table_entry"><para role="column_definition">
1039        <structfield>rule_number</structfield> <type>int4</type>
1040       </para>
1041       <para>
1042        Number of this rule, if valid, otherwise <literal>NULL</literal>.
1043        This indicates the order in which each rule is considered
1044        until a match is found during authentication.
1045       </para></entry>
1046      </row>
1047
1048      <row>
1049       <entry role="catalog_table_entry"><para role="column_definition">
1050        <structfield>file_name</structfield> <type>text</type>
1051       </para>
1052       <para>
1053        Name of the file containing this rule
1054       </para></entry>
1055      </row>
1056
1057      <row>
1058       <entry role="catalog_table_entry"><para role="column_definition">
1059        <structfield>line_number</structfield> <type>int4</type>
1060       </para>
1061       <para>
1062        Line number of this rule in <literal>file_name</literal>
1063       </para></entry>
1064      </row>
1065
1066      <row>
1067       <entry role="catalog_table_entry"><para role="column_definition">
1068        <structfield>type</structfield> <type>text</type>
1069       </para>
1070       <para>
1071        Type of connection
1072       </para></entry>
1073      </row>
1074
1075      <row>
1076       <entry role="catalog_table_entry"><para role="column_definition">
1077        <structfield>database</structfield> <type>text[]</type>
1078       </para>
1079       <para>
1080        List of database name(s) to which this rule applies
1081       </para></entry>
1082      </row>
1083
1084      <row>
1085       <entry role="catalog_table_entry"><para role="column_definition">
1086        <structfield>user_name</structfield> <type>text[]</type>
1087       </para>
1088       <para>
1089        List of user and group name(s) to which this rule applies
1090       </para></entry>
1091      </row>
1092
1093      <row>
1094       <entry role="catalog_table_entry"><para role="column_definition">
1095        <structfield>address</structfield> <type>text</type>
1096       </para>
1097       <para>
1098        Host name or IP address, or one
1099        of <literal>all</literal>, <literal>samehost</literal>,
1100        or <literal>samenet</literal>, or null for local connections
1101       </para></entry>
1102      </row>
1103
1104      <row>
1105       <entry role="catalog_table_entry"><para role="column_definition">
1106        <structfield>netmask</structfield> <type>text</type>
1107       </para>
1108       <para>
1109        IP address mask, or null if not applicable
1110       </para></entry>
1111      </row>
1112
1113      <row>
1114       <entry role="catalog_table_entry"><para role="column_definition">
1115        <structfield>auth_method</structfield> <type>text</type>
1116       </para>
1117       <para>
1118        Authentication method
1119       </para></entry>
1120      </row>
1121
1122      <row>
1123       <entry role="catalog_table_entry"><para role="column_definition">
1124        <structfield>options</structfield> <type>text[]</type>
1125       </para>
1126       <para>
1127        Options specified for authentication method, if any
1128       </para></entry>
1129      </row>
1130
1131      <row>
1132       <entry role="catalog_table_entry"><para role="column_definition">
1133        <structfield>error</structfield> <type>text</type>
1134       </para>
1135       <para>
1136        If not null, an error message indicating why this
1137        line could not be processed
1138       </para></entry>
1139      </row>
1140     </tbody>
1141    </tgroup>
1142   </table>
1143
1144   <para>
1145    Usually, a row reflecting an incorrect entry will have values for only
1146    the <structfield>line_number</structfield> and <structfield>error</structfield> fields.
1147   </para>
1148
1149   <para>
1150    See <xref linkend="client-authentication"/> for more information about
1151    client authentication configuration.
1152   </para>
1153  </sect1>
1154
1155  <sect1 id="view-pg-ident-file-mappings">
1156   <title><structname>pg_ident_file_mappings</structname></title>
1157
1158   <indexterm zone="view-pg-ident-file-mappings">
1159    <primary>pg_ident_file_mappings</primary>
1160   </indexterm>
1161
1162   <para>
1163    The view <structname>pg_ident_file_mappings</structname> provides a summary
1164    of the contents of the client user name mapping configuration file,
1165    <link linkend="auth-username-maps"><filename>pg_ident.conf</filename></link>.
1166    A row appears in this view for each non-empty, non-comment line in the file,
1167    with annotations indicating whether the map could be applied successfully.
1168   </para>
1169
1170   <para>
1171    This view can be helpful for checking whether planned changes in the
1172    authentication configuration file will work, or for diagnosing a previous
1173    failure.  Note that this view reports on the <emphasis>current</emphasis>
1174    contents of the file, not on what was last loaded by the server.
1175   </para>
1176
1177   <para>
1178    By default, the <structname>pg_ident_file_mappings</structname> view can be
1179    read only by superusers.
1180   </para>
1181
1182   <table>
1183    <title><structname>pg_ident_file_mappings</structname> Columns</title> <tgroup
1184    cols="1">
1185     <thead>
1186      <row>
1187       <entry role="catalog_table_entry"><para role="column_definition">
1188        Column Type
1189       </para>
1190       <para>
1191        Description
1192       </para></entry>
1193      </row>
1194     </thead>
1195
1196     <tbody>
1197      <row>
1198       <entry role="catalog_table_entry"><para role="column_definition">
1199        <structfield>map_number</structfield> <type>int4</type>
1200       </para>
1201       <para>
1202        Number of this map, in priority order, if valid, otherwise
1203        <literal>NULL</literal>
1204       </para></entry>
1205      </row>
1206
1207      <row>
1208       <entry role="catalog_table_entry"><para role="column_definition">
1209        <structfield>file_name</structfield> <type>text</type>
1210       </para>
1211       <para>
1212        Name of the file containing this map
1213       </para></entry>
1214      </row>
1215
1216      <row>
1217       <entry role="catalog_table_entry"><para role="column_definition">
1218        <structfield>line_number</structfield> <type>int4</type>
1219       </para>
1220       <para>
1221        Line number of this map in <literal>file_name</literal>
1222       </para></entry>
1223      </row>
1224
1225      <row>
1226       <entry role="catalog_table_entry"><para role="column_definition">
1227        <structfield>map_name</structfield> <type>text</type>
1228       </para>
1229       <para>
1230        Name of the map
1231       </para></entry>
1232      </row>
1233
1234      <row>
1235       <entry role="catalog_table_entry"><para role="column_definition">
1236        <structfield>sys_name</structfield> <type>text</type>
1237       </para>
1238       <para>
1239        Detected user name of the client
1240       </para></entry>
1241      </row>
1242
1243      <row>
1244       <entry role="catalog_table_entry"><para role="column_definition">
1245        <structfield>pg_username</structfield> <type>text</type>
1246       </para>
1247       <para>
1248        Requested PostgreSQL user name
1249       </para></entry>
1250      </row>
1251
1252      <row>
1253       <entry role="catalog_table_entry"><para role="column_definition">
1254        <structfield>error</structfield> <type>text</type>
1255       </para>
1256       <para>
1257        If not <literal>NULL</literal>, an error message indicating why this
1258        line could not be processed
1259       </para></entry>
1260      </row>
1261     </tbody>
1262    </tgroup>
1263   </table>
1264
1265   <para>
1266    Usually, a row reflecting an incorrect entry will have values for only
1267    the <structfield>line_number</structfield> and <structfield>error</structfield> fields.
1268   </para>
1269
1270   <para>
1271    See <xref linkend="client-authentication"/> for more information about
1272    client authentication configuration.
1273   </para>
1274  </sect1>
1275
1276  <sect1 id="view-pg-indexes">
1277   <title><structname>pg_indexes</structname></title>
1278
1279   <indexterm zone="view-pg-indexes">
1280    <primary>pg_indexes</primary>
1281   </indexterm>
1282
1283   <para>
1284    The view <structname>pg_indexes</structname> provides access to
1285    useful information about each index in the database.
1286   </para>
1287
1288   <table>
1289    <title><structname>pg_indexes</structname> Columns</title>
1290    <tgroup cols="1">
1291     <thead>
1292      <row>
1293       <entry role="catalog_table_entry"><para role="column_definition">
1294        Column Type
1295       </para>
1296       <para>
1297        Description
1298       </para></entry>
1299      </row>
1300     </thead>
1301
1302     <tbody>
1303      <row>
1304       <entry role="catalog_table_entry"><para role="column_definition">
1305        <structfield>schemaname</structfield> <type>name</type>
1306        (references <link linkend="catalog-pg-namespace"><structname>pg_namespace</structname></link>.<structfield>nspname</structfield>)
1307       </para>
1308       <para>
1309        Name of schema containing table and index
1310       </para></entry>
1311      </row>
1312
1313      <row>
1314       <entry role="catalog_table_entry"><para role="column_definition">
1315        <structfield>tablename</structfield> <type>name</type>
1316        (references <link linkend="catalog-pg-class"><structname>pg_class</structname></link>.<structfield>relname</structfield>)
1317       </para>
1318       <para>
1319        Name of table the index is for
1320       </para></entry>
1321      </row>
1322
1323      <row>
1324       <entry role="catalog_table_entry"><para role="column_definition">
1325        <structfield>indexname</structfield> <type>name</type>
1326        (references <link linkend="catalog-pg-class"><structname>pg_class</structname></link>.<structfield>relname</structfield>)
1327       </para>
1328       <para>
1329        Name of index
1330       </para></entry>
1331      </row>
1332
1333      <row>
1334       <entry role="catalog_table_entry"><para role="column_definition">
1335        <structfield>tablespace</structfield> <type>name</type>
1336        (references <link linkend="catalog-pg-tablespace"><structname>pg_tablespace</structname></link>.<structfield>spcname</structfield>)
1337       </para>
1338       <para>
1339        Name of tablespace containing index (null if default for database)
1340       </para></entry>
1341      </row>
1342
1343      <row>
1344       <entry role="catalog_table_entry"><para role="column_definition">
1345        <structfield>indexdef</structfield> <type>text</type>
1346       </para>
1347       <para>
1348        Index definition (a reconstructed <xref linkend="sql-createindex"/>
1349        command)
1350       </para></entry>
1351      </row>
1352     </tbody>
1353    </tgroup>
1354   </table>
1355
1356  </sect1>
1357
1358  <sect1 id="view-pg-locks">
1359   <title><structname>pg_locks</structname></title>
1360
1361   <indexterm zone="view-pg-locks">
1362    <primary>pg_locks</primary>
1363   </indexterm>
1364
1365   <para>
1366    The view <structname>pg_locks</structname> provides access to
1367    information about the locks held by active processes within the
1368    database server.  See <xref linkend="mvcc"/> for more discussion
1369    of locking.
1370   </para>
1371
1372   <para>
1373    <structname>pg_locks</structname> contains one row per active lockable
1374    object, requested lock mode, and relevant process.  Thus, the same
1375    lockable object might
1376    appear many times, if multiple processes are holding or waiting
1377    for locks on it.  However, an object that currently has no locks on it
1378    will not appear at all.
1379   </para>
1380
1381   <para>
1382    There are several distinct types of lockable objects:
1383    whole relations (e.g., tables), individual pages of relations,
1384    individual tuples of relations,
1385    transaction IDs (both virtual and permanent IDs),
1386    and general database objects (identified by class OID and object OID,
1387    in the same way as in <link linkend="catalog-pg-description"><structname>pg_description</structname></link> or
1388    <link linkend="catalog-pg-depend"><structname>pg_depend</structname></link>).  Also, the right to extend a
1389    relation is represented as a separate lockable object, as is the right to
1390    update <structname>pg_database</structname>.<structfield>datfrozenxid</structfield>.
1391    Also, <quote>advisory</quote> locks can be taken on numbers that have
1392    user-defined meanings.
1393   </para>
1394
1395   <table>
1396    <title><structname>pg_locks</structname> Columns</title>
1397    <tgroup cols="1">
1398     <thead>
1399      <row>
1400       <entry role="catalog_table_entry"><para role="column_definition">
1401        Column Type
1402       </para>
1403       <para>
1404        Description
1405       </para></entry>
1406      </row>
1407     </thead>
1408
1409     <tbody>
1410      <row>
1411       <entry role="catalog_table_entry"><para role="column_definition">
1412        <structfield>locktype</structfield> <type>text</type>
1413       </para>
1414       <para>
1415        Type of the lockable object:
1416        <literal>relation</literal>,
1417        <literal>extend</literal>,
1418        <literal>frozenid</literal>,
1419        <literal>page</literal>,
1420        <literal>tuple</literal>,
1421        <literal>transactionid</literal>,
1422        <literal>virtualxid</literal>,
1423        <literal>spectoken</literal>,
1424        <literal>object</literal>,
1425        <literal>userlock</literal>,
1426        <literal>advisory</literal>, or
1427        <literal>applytransaction</literal>.
1428        (See also <xref linkend="wait-event-lock-table"/>.)
1429       </para></entry>
1430      </row>
1431
1432      <row>
1433       <entry role="catalog_table_entry"><para role="column_definition">
1434        <structfield>database</structfield> <type>oid</type>
1435        (references <link linkend="catalog-pg-database"><structname>pg_database</structname></link>.<structfield>oid</structfield>)
1436       </para>
1437       <para>
1438        OID of the database in which the lock target exists, or
1439        zero if the target is a shared object, or
1440        null if the target is a transaction ID
1441       </para></entry>
1442      </row>
1443
1444      <row>
1445       <entry role="catalog_table_entry"><para role="column_definition">
1446        <structfield>relation</structfield> <type>oid</type>
1447        (references <link linkend="catalog-pg-class"><structname>pg_class</structname></link>.<structfield>oid</structfield>)
1448       </para>
1449       <para>
1450        OID of the relation targeted by the lock, or null if the target is not
1451        a relation or part of a relation
1452       </para></entry>
1453      </row>
1454
1455      <row>
1456       <entry role="catalog_table_entry"><para role="column_definition">
1457        <structfield>page</structfield> <type>int4</type>
1458       </para>
1459       <para>
1460        Page number targeted by the lock within the relation,
1461        or null if the target is not a relation page or tuple
1462       </para></entry>
1463      </row>
1464
1465      <row>
1466       <entry role="catalog_table_entry"><para role="column_definition">
1467        <structfield>tuple</structfield> <type>int2</type>
1468       </para>
1469       <para>
1470        Tuple number targeted by the lock within the page,
1471        or null if the target is not a tuple
1472       </para></entry>
1473      </row>
1474
1475      <row>
1476       <entry role="catalog_table_entry"><para role="column_definition">
1477        <structfield>virtualxid</structfield> <type>text</type>
1478       </para>
1479       <para>
1480        Virtual ID of the transaction targeted by the lock,
1481        or null if the target is not a virtual transaction ID;  see
1482        <xref linkend="transactions"/>
1483       </para></entry>
1484      </row>
1485
1486      <row>
1487       <entry role="catalog_table_entry"><para role="column_definition">
1488        <structfield>transactionid</structfield> <type>xid</type>
1489       </para>
1490       <para>
1491        ID of the transaction targeted by the lock, or null if the target
1492        is not a transaction ID;  <xref linkend="transactions"/>
1493       </para></entry>
1494      </row>
1495
1496      <row>
1497       <entry role="catalog_table_entry"><para role="column_definition">
1498        <structfield>classid</structfield> <type>oid</type>
1499        (references <link linkend="catalog-pg-class"><structname>pg_class</structname></link>.<structfield>oid</structfield>)
1500       </para>
1501       <para>
1502        OID of the system catalog containing the lock target, or null if the
1503        target is not a general database object
1504       </para></entry>
1505      </row>
1506
1507      <row>
1508       <entry role="catalog_table_entry"><para role="column_definition">
1509        <structfield>objid</structfield> <type>oid</type>
1510        (references any OID column)
1511       </para>
1512       <para>
1513        OID of the lock target within its system catalog, or null if the
1514        target is not a general database object
1515       </para></entry>
1516      </row>
1517
1518      <row>
1519       <entry role="catalog_table_entry"><para role="column_definition">
1520        <structfield>objsubid</structfield> <type>int2</type>
1521       </para>
1522       <para>
1523        Column number targeted by the lock (the
1524        <structfield>classid</structfield> and <structfield>objid</structfield> refer to the
1525        table itself),
1526        or zero if the target is some other general database object,
1527        or null if the target is not a general database object
1528       </para></entry>
1529      </row>
1530
1531      <row>
1532       <entry role="catalog_table_entry"><para role="column_definition">
1533        <structfield>virtualtransaction</structfield> <type>text</type>
1534       </para>
1535       <para>
1536        Virtual ID of the transaction that is holding or awaiting this lock
1537       </para></entry>
1538      </row>
1539
1540      <row>
1541       <entry role="catalog_table_entry"><para role="column_definition">
1542        <structfield>pid</structfield> <type>int4</type>
1543       </para>
1544       <para>
1545        Process ID of the server process holding or awaiting this
1546        lock, or null if the lock is held by a prepared transaction
1547       </para></entry>
1548      </row>
1549
1550      <row>
1551       <entry role="catalog_table_entry"><para role="column_definition">
1552        <structfield>mode</structfield> <type>text</type>
1553       </para>
1554       <para>
1555        Name of the lock mode held or desired by this process (see <xref linkend="locking-tables"/> and <xref linkend="xact-serializable"/>)
1556       </para></entry>
1557      </row>
1558
1559      <row>
1560       <entry role="catalog_table_entry"><para role="column_definition">
1561        <structfield>granted</structfield> <type>bool</type>
1562       </para>
1563       <para>
1564        True if lock is held, false if lock is awaited
1565       </para></entry>
1566      </row>
1567
1568      <row>
1569       <entry role="catalog_table_entry"><para role="column_definition">
1570        <structfield>fastpath</structfield> <type>bool</type>
1571       </para>
1572       <para>
1573        True if lock was taken via fast path, false if taken via main
1574        lock table
1575       </para></entry>
1576      </row>
1577
1578      <row>
1579       <entry role="catalog_table_entry"><para role="column_definition">
1580        <structfield>waitstart</structfield> <type>timestamptz</type>
1581       </para>
1582       <para>
1583        Time when the server process started waiting for this lock,
1584        or null if the lock is held.
1585        Note that this can be null for a very short period of time after
1586        the wait started even though <structfield>granted</structfield>
1587        is <literal>false</literal>.
1588       </para></entry>
1589      </row>
1590     </tbody>
1591    </tgroup>
1592   </table>
1593
1594   <para>
1595    <structfield>granted</structfield> is true in a row representing a lock
1596    held by the indicated process.  False indicates that this process is
1597    currently waiting to acquire this lock, which implies that at least one
1598    other process is holding or waiting for a conflicting lock mode on the same
1599    lockable object.  The waiting process will sleep until the other lock is
1600    released (or a deadlock situation is detected).  A single process can be
1601    waiting to acquire at most one lock at a time.
1602   </para>
1603
1604   <para>
1605    Throughout running a transaction, a server process holds an exclusive lock
1606    on the transaction's virtual transaction ID.  If a permanent ID is assigned
1607    to the transaction (which normally happens only if the transaction changes
1608    the state of the database), it also holds an exclusive lock on the
1609    transaction's permanent transaction ID until it ends.  When a process finds
1610    it necessary to wait specifically for another transaction to end, it does
1611    so by attempting to acquire share lock on the other transaction's ID
1612    (either virtual or permanent ID depending on the situation). That will
1613    succeed only when the other transaction terminates and releases its locks.
1614   </para>
1615
1616   <para>
1617    Although tuples are a lockable type of object,
1618    information about row-level locks is stored on disk, not in memory,
1619    and therefore row-level locks normally do not appear in this view.
1620    If a process is waiting for a
1621    row-level lock, it will usually appear in the view as waiting for the
1622    permanent transaction ID of the current holder of that row lock.
1623   </para>
1624
1625   <para>
1626    A speculative insertion lock consists of a transaction ID and a speculative
1627    insertion token. The speculative insertion token is displayed in the
1628    <structfield>objid</structfield> column.
1629   </para>
1630
1631   <para>
1632    Advisory locks can be acquired on keys consisting of either a single
1633    <type>bigint</type> value or two integer values.
1634    A <type>bigint</type> key is displayed with its
1635    high-order half in the <structfield>classid</structfield> column, its low-order half
1636    in the <structfield>objid</structfield> column, and <structfield>objsubid</structfield> equal
1637    to 1. The original <type>bigint</type> value can be reassembled with the
1638    expression <literal>(classid::bigint &lt;&lt; 32) |
1639    objid::bigint</literal>. Integer keys are displayed with the
1640    first key in the
1641    <structfield>classid</structfield> column, the second key in the <structfield>objid</structfield>
1642    column, and <structfield>objsubid</structfield> equal to 2.  The actual meaning of
1643    the keys is up to the user.  Advisory locks are local to each database,
1644    so the <structfield>database</structfield> column is meaningful for an advisory lock.
1645   </para>
1646
1647   <para>
1648    Apply transaction locks are used in parallel mode to apply the transaction
1649    in logical replication. The remote transaction ID is displayed in the
1650    <structfield>transactionid</structfield> column. The <structfield>objsubid</structfield>
1651    displays the lock subtype which is 0 for the lock used to synchronize the
1652    set of changes, and 1 for the lock used to wait for the transaction to
1653    finish to ensure commit order.
1654   </para>
1655
1656   <para>
1657    <structname>pg_locks</structname> provides a global view of all locks
1658    in the database cluster, not only those relevant to the current database.
1659    Although its <structfield>relation</structfield> column can be joined
1660    against <link linkend="catalog-pg-class"><structname>pg_class</structname></link>.<structfield>oid</structfield> to identify locked
1661    relations, this will only work correctly for relations in the current
1662    database (those for which the <structfield>database</structfield> column
1663    is either the current database's OID or zero).
1664   </para>
1665
1666   <para>
1667    The <structfield>pid</structfield> column can be joined to the
1668    <structfield>pid</structfield> column of the
1669    <link linkend="monitoring-pg-stat-activity-view">
1670    <structname>pg_stat_activity</structname></link>
1671    view to get more
1672    information on the session holding or awaiting each lock,
1673    for example
1674 <programlisting>
1675 SELECT * FROM pg_locks pl LEFT JOIN pg_stat_activity psa
1676     ON pl.pid = psa.pid;
1677 </programlisting>
1678    Also, if you are using prepared transactions, the
1679    <structfield>virtualtransaction</structfield> column can be joined to the
1680    <structfield>transaction</structfield> column of the <link
1681    linkend="view-pg-prepared-xacts"><structname>pg_prepared_xacts</structname></link>
1682    view to get more information on prepared transactions that hold locks.
1683    (A prepared transaction can never be waiting for a lock,
1684    but it continues to hold the locks it acquired while running.)
1685    For example:
1686 <programlisting>
1687 SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx
1688     ON pl.virtualtransaction = '-1/' || ppx.transaction;
1689 </programlisting>
1690   </para>
1691
1692   <para>
1693    While it is possible to obtain information about which processes block
1694    which other processes by joining <structname>pg_locks</structname> against
1695    itself, this is very difficult to get right in detail.  Such a query would
1696    have to encode knowledge about which lock modes conflict with which
1697    others.  Worse, the <structname>pg_locks</structname> view does not expose
1698    information about which processes are ahead of which others in lock wait
1699    queues, nor information about which processes are parallel workers running
1700    on behalf of which other client sessions.  It is better to use
1701    the <function>pg_blocking_pids()</function> function
1702    (see <xref linkend="functions-info-session-table"/>) to identify which
1703    process(es) a waiting process is blocked behind.
1704   </para>
1705
1706   <para>
1707    The <structname>pg_locks</structname> view displays data from both the
1708    regular lock manager and the predicate lock manager, which are
1709    separate systems; in addition, the regular lock manager subdivides its
1710    locks into regular and <firstterm>fast-path</firstterm> locks.
1711    This data is not guaranteed to be entirely consistent.
1712    When the view is queried,
1713    data on fast-path locks (with <structfield>fastpath</structfield> = <literal>true</literal>)
1714    is gathered from each backend one at a time, without freezing the state of
1715    the entire lock manager, so it is possible for locks to be taken or
1716    released while information is gathered.  Note, however, that these locks are
1717    known not to conflict with any other lock currently in place.  After
1718    all backends have been queried for fast-path locks, the remainder of the
1719    regular lock manager is locked as a unit, and a consistent snapshot of all
1720    remaining locks is collected as an atomic action.  After unlocking the
1721    regular lock manager, the predicate lock manager is similarly locked and all
1722    predicate locks are collected as an atomic action.  Thus, with the exception
1723    of fast-path locks, each lock manager will deliver a consistent set of
1724    results, but as we do not lock both lock managers simultaneously, it is
1725    possible for locks to be taken or released after we interrogate the regular
1726    lock manager and before we interrogate the predicate lock manager.
1727   </para>
1728
1729   <para>
1730    Locking the regular and/or predicate lock manager could have some
1731    impact on database performance if this view is very frequently accessed.
1732    The locks are held only for the minimum amount of time necessary to
1733    obtain data from the lock managers, but this does not completely eliminate
1734    the possibility of a performance impact.
1735   </para>
1736
1737  </sect1>
1738
1739  <sect1 id="view-pg-matviews">
1740   <title><structname>pg_matviews</structname></title>
1741
1742   <indexterm zone="view-pg-matviews">
1743    <primary>pg_matviews</primary>
1744   </indexterm>
1745
1746   <indexterm zone="view-pg-matviews">
1747    <primary>materialized views</primary>
1748   </indexterm>
1749
1750   <para>
1751    The view <structname>pg_matviews</structname> provides access to
1752    useful information about each materialized view in the database.
1753   </para>
1754
1755   <table>
1756    <title><structname>pg_matviews</structname> Columns</title>
1757    <tgroup cols="1">
1758     <thead>
1759      <row>
1760       <entry role="catalog_table_entry"><para role="column_definition">
1761        Column Type
1762       </para>
1763       <para>
1764        Description
1765       </para></entry>
1766      </row>
1767     </thead>
1768
1769     <tbody>
1770      <row>
1771       <entry role="catalog_table_entry"><para role="column_definition">
1772        <structfield>schemaname</structfield> <type>name</type>
1773        (references <link linkend="catalog-pg-namespace"><structname>pg_namespace</structname></link>.<structfield>nspname</structfield>)
1774       </para>
1775       <para>
1776        Name of schema containing materialized view
1777       </para></entry>
1778      </row>
1779
1780      <row>
1781       <entry role="catalog_table_entry"><para role="column_definition">
1782        <structfield>matviewname</structfield> <type>name</type>
1783        (references <link linkend="catalog-pg-class"><structname>pg_class</structname></link>.<structfield>relname</structfield>)
1784       </para>
1785       <para>
1786        Name of materialized view
1787       </para></entry>
1788      </row>
1789
1790      <row>
1791       <entry role="catalog_table_entry"><para role="column_definition">
1792        <structfield>matviewowner</structfield> <type>name</type>
1793        (references <link linkend="catalog-pg-authid"><structname>pg_authid</structname></link>.<structfield>rolname</structfield>)
1794       </para>
1795       <para>
1796        Name of materialized view's owner
1797       </para></entry>
1798      </row>
1799
1800      <row>
1801       <entry role="catalog_table_entry"><para role="column_definition">
1802        <structfield>tablespace</structfield> <type>name</type>
1803        (references <link linkend="catalog-pg-tablespace"><structname>pg_tablespace</structname></link>.<structfield>spcname</structfield>)
1804       </para>
1805       <para>
1806        Name of tablespace containing materialized view (null if default for database)
1807       </para></entry>
1808      </row>
1809
1810      <row>
1811       <entry role="catalog_table_entry"><para role="column_definition">
1812        <structfield>hasindexes</structfield> <type>bool</type>
1813       </para>
1814       <para>
1815        True if materialized view has (or recently had) any indexes
1816       </para></entry>
1817      </row>
1818
1819      <row>
1820       <entry role="catalog_table_entry"><para role="column_definition">
1821        <structfield>ispopulated</structfield> <type>bool</type>
1822       </para>
1823       <para>
1824        True if materialized view is currently populated
1825       </para></entry>
1826      </row>
1827
1828      <row>
1829       <entry role="catalog_table_entry"><para role="column_definition">
1830        <structfield>definition</structfield> <type>text</type>
1831       </para>
1832       <para>
1833        Materialized view definition (a reconstructed <xref linkend="sql-select"/> query)
1834       </para></entry>
1835      </row>
1836     </tbody>
1837    </tgroup>
1838   </table>
1839
1840  </sect1>
1841
1842  <sect1 id="view-pg-policies">
1843   <title><structname>pg_policies</structname></title>
1844
1845   <indexterm zone="view-pg-policies">
1846    <primary>pg_policies</primary>
1847   </indexterm>
1848
1849   <para>
1850    The view <structname>pg_policies</structname> provides access to
1851    useful information about each row-level security policy in the database.
1852   </para>
1853
1854   <table>
1855    <title><structname>pg_policies</structname> Columns</title>
1856    <tgroup cols="1">
1857     <thead>
1858      <row>
1859       <entry role="catalog_table_entry"><para role="column_definition">
1860        Column Type
1861       </para>
1862       <para>
1863        Description
1864       </para></entry>
1865      </row>
1866     </thead>
1867
1868     <tbody>
1869      <row>
1870       <entry role="catalog_table_entry"><para role="column_definition">
1871        <structfield>schemaname</structfield> <type>name</type>
1872        (references <link linkend="catalog-pg-namespace"><structname>pg_namespace</structname></link>.<structfield>nspname</structfield>)
1873       </para>
1874       <para>
1875        Name of schema containing table policy is on
1876       </para></entry>
1877      </row>
1878
1879      <row>
1880       <entry role="catalog_table_entry"><para role="column_definition">
1881        <structfield>tablename</structfield> <type>name</type>
1882        (references <link linkend="catalog-pg-class"><structname>pg_class</structname></link>.<structfield>relname</structfield>)
1883       </para>
1884       <para>
1885        Name of table policy is on
1886       </para></entry>
1887      </row>
1888
1889      <row>
1890       <entry role="catalog_table_entry"><para role="column_definition">
1891        <structfield>policyname</structfield> <type>name</type>
1892        (references <link linkend="catalog-pg-policy"><structname>pg_policy</structname></link>.<structfield>polname</structfield>)
1893       </para>
1894       <para>
1895        Name of policy
1896       </para></entry>
1897      </row>
1898
1899      <row>
1900       <entry role="catalog_table_entry"><para role="column_definition">
1901        <structfield>permissive</structfield> <type>text</type>
1902       </para>
1903       <para>
1904        Is the policy permissive or restrictive?
1905       </para></entry>
1906      </row>
1907
1908      <row>
1909       <entry role="catalog_table_entry"><para role="column_definition">
1910        <structfield>roles</structfield> <type>name[]</type>
1911       </para>
1912       <para>
1913        The roles to which this policy applies
1914       </para></entry>
1915      </row>
1916
1917      <row>
1918       <entry role="catalog_table_entry"><para role="column_definition">
1919        <structfield>cmd</structfield> <type>text</type>
1920       </para>
1921       <para>
1922        The command type to which the policy is applied
1923       </para></entry>
1924      </row>
1925
1926      <row>
1927       <entry role="catalog_table_entry"><para role="column_definition">
1928        <structfield>qual</structfield> <type>text</type>
1929       </para>
1930       <para>
1931        The expression added to the security barrier qualifications for
1932        queries that this policy applies to
1933       </para></entry>
1934      </row>
1935
1936      <row>
1937       <entry role="catalog_table_entry"><para role="column_definition">
1938        <structfield>with_check</structfield> <type>text</type>
1939       </para>
1940       <para>
1941        The expression added to the WITH CHECK qualifications for
1942        queries that attempt to add rows to this table
1943       </para></entry>
1944      </row>
1945     </tbody>
1946    </tgroup>
1947   </table>
1948
1949  </sect1>
1950
1951  <sect1 id="view-pg-prepared-statements">
1952   <title><structname>pg_prepared_statements</structname></title>
1953
1954   <indexterm zone="view-pg-prepared-statements">
1955    <primary>pg_prepared_statements</primary>
1956   </indexterm>
1957
1958   <para>
1959    The <structname>pg_prepared_statements</structname> view displays
1960    all the prepared statements that are available in the current
1961    session. See <xref linkend="sql-prepare"/> for more information about prepared
1962    statements.
1963   </para>
1964
1965   <para>
1966    <structname>pg_prepared_statements</structname> contains one row
1967    for each prepared statement. Rows are added to the view when a new
1968    prepared statement is created and removed when a prepared statement
1969    is released (for example, via the <link linkend="sql-deallocate"><command>DEALLOCATE</command></link> command).
1970   </para>
1971
1972   <table>
1973    <title><structname>pg_prepared_statements</structname> Columns</title>
1974    <tgroup cols="1">
1975     <thead>
1976      <row>
1977       <entry role="catalog_table_entry"><para role="column_definition">
1978        Column Type
1979       </para>
1980       <para>
1981        Description
1982       </para></entry>
1983      </row>
1984     </thead>
1985
1986     <tbody>
1987      <row>
1988       <entry role="catalog_table_entry"><para role="column_definition">
1989        <structfield>name</structfield> <type>text</type>
1990       </para>
1991       <para>
1992        The identifier of the prepared statement
1993       </para></entry>
1994      </row>
1995
1996      <row>
1997       <entry role="catalog_table_entry"><para role="column_definition">
1998        <structfield>statement</structfield> <type>text</type>
1999       </para>
2000       <para>
2001        The query string submitted by the client to create this
2002        prepared statement. For prepared statements created via SQL,
2003        this is the <command>PREPARE</command> statement submitted by
2004        the client. For prepared statements created via the
2005        frontend/backend protocol, this is the text of the prepared
2006        statement itself.
2007       </para></entry>
2008      </row>
2009
2010      <row>
2011       <entry role="catalog_table_entry"><para role="column_definition">
2012        <structfield>prepare_time</structfield> <type>timestamptz</type>
2013       </para>
2014       <para>
2015        The time at which the prepared statement was created
2016       </para></entry>
2017      </row>
2018
2019      <row>
2020       <entry role="catalog_table_entry"><para role="column_definition">
2021        <structfield>parameter_types</structfield> <type>regtype[]</type>
2022       </para>
2023       <para>
2024        The expected parameter types for the prepared statement in the
2025        form of an array of <type>regtype</type>. The OID corresponding
2026        to an element of this array can be obtained by casting the
2027        <type>regtype</type> value to <type>oid</type>.
2028       </para></entry>
2029      </row>
2030
2031      <row>
2032       <entry role="catalog_table_entry"><para role="column_definition">
2033        <structfield>result_types</structfield> <type>regtype[]</type>
2034       </para>
2035       <para>
2036        The types of the columns returned by the prepared statement in the
2037        form of an array of <type>regtype</type>. The OID corresponding
2038        to an element of this array can be obtained by casting the
2039        <type>regtype</type> value to <type>oid</type>.
2040        If the prepared statement does not provide a result (e.g., a DML
2041        statement), then this field will be null.
2042       </para></entry>
2043      </row>
2044
2045      <row>
2046       <entry role="catalog_table_entry"><para role="column_definition">
2047        <structfield>from_sql</structfield> <type>bool</type>
2048       </para>
2049       <para>
2050        <literal>true</literal> if the prepared statement was created
2051        via the <command>PREPARE</command> SQL command;
2052        <literal>false</literal> if the statement was prepared via the
2053        frontend/backend protocol
2054       </para></entry>
2055      </row>
2056
2057      <row>
2058       <entry role="catalog_table_entry"><para role="column_definition">
2059        <structfield>generic_plans</structfield> <type>int8</type>
2060       </para>
2061       <para>
2062        Number of times generic plan was chosen
2063       </para></entry>
2064      </row>
2065
2066      <row>
2067       <entry role="catalog_table_entry"><para role="column_definition">
2068        <structfield>custom_plans</structfield> <type>int8</type>
2069       </para>
2070       <para>
2071        Number of times custom plan was chosen
2072       </para></entry>
2073      </row>
2074     </tbody>
2075    </tgroup>
2076   </table>
2077
2078   <para>
2079    The <structname>pg_prepared_statements</structname> view is read-only.
2080   </para>
2081  </sect1>
2082
2083  <sect1 id="view-pg-prepared-xacts">
2084   <title><structname>pg_prepared_xacts</structname></title>
2085
2086   <indexterm zone="view-pg-prepared-xacts">
2087    <primary>pg_prepared_xacts</primary>
2088   </indexterm>
2089
2090   <para>
2091    The view <structname>pg_prepared_xacts</structname> displays
2092    information about transactions that are currently prepared for two-phase
2093    commit (see <xref linkend="sql-prepare-transaction"/> for details).
2094   </para>
2095
2096   <para>
2097    <structname>pg_prepared_xacts</structname> contains one row per prepared
2098    transaction.  An entry is removed when the transaction is committed or
2099    rolled back.
2100   </para>
2101
2102   <table>
2103    <title><structname>pg_prepared_xacts</structname> Columns</title>
2104    <tgroup cols="1">
2105     <thead>
2106      <row>
2107       <entry role="catalog_table_entry"><para role="column_definition">
2108        Column Type
2109       </para>
2110       <para>
2111        Description
2112       </para></entry>
2113      </row>
2114     </thead>
2115
2116     <tbody>
2117      <row>
2118       <entry role="catalog_table_entry"><para role="column_definition">
2119        <structfield>transaction</structfield> <type>xid</type>
2120       </para>
2121       <para>
2122        Numeric transaction identifier of the prepared transaction
2123       </para></entry>
2124      </row>
2125
2126      <row>
2127       <entry role="catalog_table_entry"><para role="column_definition">
2128        <structfield>gid</structfield> <type>text</type>
2129       </para>
2130       <para>
2131        Global transaction identifier that was assigned to the transaction
2132       </para></entry>
2133      </row>
2134
2135      <row>
2136       <entry role="catalog_table_entry"><para role="column_definition">
2137        <structfield>prepared</structfield> <type>timestamptz</type>
2138       </para>
2139       <para>
2140        Time at which the transaction was prepared for commit
2141       </para></entry>
2142      </row>
2143
2144      <row>
2145       <entry role="catalog_table_entry"><para role="column_definition">
2146        <structfield>owner</structfield> <type>name</type>
2147        (references <link linkend="catalog-pg-authid"><structname>pg_authid</structname></link>.<structfield>rolname</structfield>)
2148       </para>
2149       <para>
2150        Name of the user that executed the transaction
2151       </para></entry>
2152      </row>
2153
2154      <row>
2155       <entry role="catalog_table_entry"><para role="column_definition">
2156        <structfield>database</structfield> <type>name</type>
2157        (references <link linkend="catalog-pg-database"><structname>pg_database</structname></link>.<structfield>datname</structfield>)
2158       </para>
2159       <para>
2160        Name of the database in which the transaction was executed
2161       </para></entry>
2162      </row>
2163     </tbody>
2164    </tgroup>
2165   </table>
2166
2167   <para>
2168    When the <structname>pg_prepared_xacts</structname> view is accessed, the
2169    internal transaction manager data structures are momentarily locked, and
2170    a copy is made for the view to display.  This ensures that the
2171    view produces a consistent set of results, while not blocking
2172    normal operations longer than necessary.  Nonetheless
2173    there could be some impact on database performance if this view is
2174    frequently accessed.
2175   </para>
2176
2177  </sect1>
2178
2179  <sect1 id="view-pg-publication-tables">
2180   <title><structname>pg_publication_tables</structname></title>
2181
2182   <indexterm zone="view-pg-publication-tables">
2183    <primary>pg_publication_tables</primary>
2184   </indexterm>
2185
2186   <para>
2187    The view <structname>pg_publication_tables</structname> provides
2188    information about the mapping between publications and information of
2189    tables they contain.  Unlike the underlying catalog
2190    <link linkend="catalog-pg-publication-rel"><structname>pg_publication_rel</structname></link>,
2191    this view expands publications defined as
2192    <link linkend="sql-createpublication-params-for-all-tables"><literal>FOR ALL TABLES</literal></link>
2193    and <link linkend="sql-createpublication-params-for-tables-in-schema"><literal>FOR TABLES IN SCHEMA</literal></link>,
2194    so for such publications there will be a row for each eligible table.
2195   </para>
2196
2197   <table>
2198    <title><structname>pg_publication_tables</structname> Columns</title>
2199    <tgroup cols="1">
2200     <thead>
2201      <row>
2202       <entry role="catalog_table_entry"><para role="column_definition">
2203        Column Type
2204       </para>
2205       <para>
2206        Description
2207       </para></entry>
2208      </row>
2209     </thead>
2210
2211     <tbody>
2212      <row>
2213       <entry role="catalog_table_entry"><para role="column_definition">
2214        <structfield>pubname</structfield> <type>name</type>
2215        (references <link linkend="catalog-pg-publication"><structname>pg_publication</structname></link>.<structfield>pubname</structfield>)
2216       </para>
2217       <para>
2218        Name of publication
2219       </para></entry>
2220      </row>
2221
2222      <row>
2223       <entry role="catalog_table_entry"><para role="column_definition">
2224        <structfield>schemaname</structfield> <type>name</type>
2225        (references <link linkend="catalog-pg-namespace"><structname>pg_namespace</structname></link>.<structfield>nspname</structfield>)
2226       </para>
2227       <para>
2228        Name of schema containing table
2229       </para></entry>
2230      </row>
2231
2232      <row>
2233       <entry role="catalog_table_entry"><para role="column_definition">
2234        <structfield>tablename</structfield> <type>name</type>
2235        (references <link linkend="catalog-pg-class"><structname>pg_class</structname></link>.<structfield>relname</structfield>)
2236       </para>
2237       <para>
2238        Name of table
2239       </para></entry>
2240      </row>
2241
2242      <row>
2243       <entry role="catalog_table_entry"><para role="column_definition">
2244        <structfield>attnames</structfield> <type>name[]</type>
2245        (references <link linkend="catalog-pg-attribute"><structname>pg_attribute</structname></link>.<structfield>attname</structfield>)
2246       </para>
2247       <para>
2248        Names of table columns included in the publication. This contains all
2249        the columns of the table when the user didn't specify the column list
2250        for the table.
2251       </para></entry>
2252      </row>
2253
2254      <row>
2255       <entry role="catalog_table_entry"><para role="column_definition">
2256        <structfield>rowfilter</structfield> <type>text</type>
2257       </para>
2258       <para>
2259        Expression for the table's publication qualifying condition
2260       </para></entry>
2261      </row>
2262     </tbody>
2263    </tgroup>
2264   </table>
2265  </sect1>
2266
2267   <sect1 id="view-pg-replication-origin-status">
2268   <title><structname>pg_replication_origin_status</structname></title>
2269
2270   <indexterm zone="view-pg-replication-origin-status">
2271    <primary>pg_replication_origin_status</primary>
2272   </indexterm>
2273
2274   <para>
2275    The <structname>pg_replication_origin_status</structname> view
2276    contains information about how far replay for a certain origin has
2277    progressed.  For more on replication origins
2278    see <xref linkend="replication-origins"/>.
2279   </para>
2280
2281   <table>
2282    <title><structname>pg_replication_origin_status</structname> Columns</title>
2283    <tgroup cols="1">
2284     <thead>
2285      <row>
2286       <entry role="catalog_table_entry"><para role="column_definition">
2287        Column Type
2288       </para>
2289       <para>
2290        Description
2291       </para></entry>
2292      </row>
2293     </thead>
2294
2295     <tbody>
2296      <row>
2297       <entry role="catalog_table_entry"><para role="column_definition">
2298        <structfield>local_id</structfield> <type>oid</type>
2299        (references <link linkend="catalog-pg-replication-origin"><structname>pg_replication_origin</structname></link>.<structfield>roident</structfield>)
2300       </para>
2301       <para>
2302        internal node identifier
2303       </para></entry>
2304      </row>
2305
2306      <row>
2307       <entry role="catalog_table_entry"><para role="column_definition">
2308        <structfield>external_id</structfield> <type>text</type>
2309        (references <link linkend="catalog-pg-replication-origin"><structname>pg_replication_origin</structname></link>.<structfield>roname</structfield>)
2310       </para>
2311       <para>
2312        external node identifier
2313       </para></entry>
2314      </row>
2315
2316      <row>
2317       <entry role="catalog_table_entry"><para role="column_definition">
2318        <structfield>remote_lsn</structfield> <type>pg_lsn</type>
2319       </para>
2320       <para>
2321        The origin node's LSN up to which data has been replicated.
2322       </para></entry>
2323      </row>
2324
2325      <row>
2326       <entry role="catalog_table_entry"><para role="column_definition">
2327        <structfield>local_lsn</structfield> <type>pg_lsn</type>
2328       </para>
2329       <para>
2330        This node's LSN at which <literal>remote_lsn</literal> has
2331        been replicated. Used to flush commit records before persisting
2332        data to disk when using asynchronous commits.
2333       </para></entry>
2334      </row>
2335     </tbody>
2336    </tgroup>
2337   </table>
2338  </sect1>
2339
2340  <sect1 id="view-pg-replication-slots">
2341   <title><structname>pg_replication_slots</structname></title>
2342
2343   <indexterm zone="view-pg-replication-slots">
2344    <primary>pg_replication_slots</primary>
2345   </indexterm>
2346
2347   <para>
2348    The <structname>pg_replication_slots</structname> view provides a listing
2349    of all replication slots that currently exist on the database cluster,
2350    along with their current state.
2351   </para>
2352
2353   <para>
2354    For more on replication slots,
2355    see <xref linkend="streaming-replication-slots"/> and <xref linkend="logicaldecoding"/>.
2356   </para>
2357
2358   <table>
2359    <title><structname>pg_replication_slots</structname> Columns</title>
2360    <tgroup cols="1">
2361     <thead>
2362      <row>
2363       <entry role="catalog_table_entry"><para role="column_definition">
2364        Column Type
2365       </para>
2366       <para>
2367        Description
2368       </para></entry>
2369      </row>
2370     </thead>
2371
2372     <tbody>
2373      <row>
2374       <entry role="catalog_table_entry"><para role="column_definition">
2375        <structfield>slot_name</structfield> <type>name</type>
2376       </para>
2377       <para>
2378        A unique, cluster-wide identifier for the replication slot
2379       </para></entry>
2380      </row>
2381
2382      <row>
2383       <entry role="catalog_table_entry"><para role="column_definition">
2384        <structfield>plugin</structfield> <type>name</type>
2385       </para>
2386       <para>
2387        The base name of the shared object containing the output plugin this logical slot is using, or null for physical slots.
2388       </para></entry>
2389      </row>
2390
2391      <row>
2392       <entry role="catalog_table_entry"><para role="column_definition">
2393        <structfield>slot_type</structfield> <type>text</type>
2394       </para>
2395       <para>
2396        The slot type: <literal>physical</literal> or <literal>logical</literal>
2397       </para></entry>
2398      </row>
2399
2400      <row>
2401       <entry role="catalog_table_entry"><para role="column_definition">
2402        <structfield>datoid</structfield> <type>oid</type>
2403        (references <link linkend="catalog-pg-database"><structname>pg_database</structname></link>.<structfield>oid</structfield>)
2404       </para>
2405       <para>
2406        The OID of the database this slot is associated with, or
2407        null. Only logical slots have an associated database.
2408       </para></entry>
2409      </row>
2410
2411      <row>
2412       <entry role="catalog_table_entry"><para role="column_definition">
2413        <structfield>database</structfield> <type>name</type>
2414        (references <link linkend="catalog-pg-database"><structname>pg_database</structname></link>.<structfield>datname</structfield>)
2415       </para>
2416       <para>
2417        The name of the database this slot is associated with, or
2418        null. Only logical slots have an associated database.
2419       </para></entry>
2420      </row>
2421
2422      <row>
2423       <entry role="catalog_table_entry"><para role="column_definition">
2424        <structfield>temporary</structfield> <type>bool</type>
2425       </para>
2426       <para>
2427        True if this is a temporary replication slot. Temporary slots are
2428        not saved to disk and are automatically dropped on error or when
2429        the session has finished.
2430       </para></entry>
2431      </row>
2432
2433      <row>
2434       <entry role="catalog_table_entry"><para role="column_definition">
2435        <structfield>active</structfield> <type>bool</type>
2436       </para>
2437       <para>
2438        True if this slot is currently being streamed
2439       </para></entry>
2440      </row>
2441
2442      <row>
2443       <entry role="catalog_table_entry"><para role="column_definition">
2444        <structfield>active_pid</structfield> <type>int4</type>
2445       </para>
2446       <para>
2447        The process ID of the session streaming data for this slot.
2448        <literal>NULL</literal> if inactive.
2449       </para></entry>
2450      </row>
2451
2452      <row>
2453       <entry role="catalog_table_entry"><para role="column_definition">
2454        <structfield>xmin</structfield> <type>xid</type>
2455       </para>
2456       <para>
2457        The oldest transaction that this slot needs the database to
2458        retain.  <literal>VACUUM</literal> cannot remove tuples deleted
2459        by any later transaction.
2460       </para></entry>
2461      </row>
2462
2463      <row>
2464       <entry role="catalog_table_entry"><para role="column_definition">
2465        <structfield>catalog_xmin</structfield> <type>xid</type>
2466       </para>
2467       <para>
2468        The oldest transaction affecting the system catalogs that this
2469        slot needs the database to retain.  <literal>VACUUM</literal> cannot
2470        remove catalog tuples deleted by any later transaction.
2471       </para></entry>
2472      </row>
2473
2474      <row>
2475       <entry role="catalog_table_entry"><para role="column_definition">
2476        <structfield>restart_lsn</structfield> <type>pg_lsn</type>
2477       </para>
2478       <para>
2479        The address (<literal>LSN</literal>) of oldest WAL which still
2480        might be required by the consumer of this slot and thus won't be
2481        automatically removed during checkpoints unless this LSN
2482        gets behind more than <xref linkend="guc-max-slot-wal-keep-size"/>
2483        from the current LSN.  <literal>NULL</literal>
2484        if the <literal>LSN</literal> of this slot has never been reserved.
2485       </para></entry>
2486      </row>
2487
2488      <row>
2489       <entry role="catalog_table_entry"><para role="column_definition">
2490        <structfield>confirmed_flush_lsn</structfield> <type>pg_lsn</type>
2491       </para>
2492       <para>
2493        The address (<literal>LSN</literal>) up to which the logical
2494        slot's consumer has confirmed receiving data. Data corresponding to the
2495        transactions committed before this <literal>LSN</literal> is not
2496        available anymore. <literal>NULL</literal> for physical slots.
2497       </para></entry>
2498      </row>
2499
2500      <row>
2501       <entry role="catalog_table_entry"><para role="column_definition">
2502        <structfield>wal_status</structfield> <type>text</type>
2503       </para>
2504       <para>
2505        Availability of WAL files claimed by this slot.
2506        Possible values are:
2507        <itemizedlist>
2508         <listitem>
2509          <para><literal>reserved</literal> means that the claimed files
2510           are within <varname>max_wal_size</varname>.</para>
2511         </listitem>
2512         <listitem>
2513          <para><literal>extended</literal> means
2514           that <varname>max_wal_size</varname> is exceeded but the files are
2515           still retained, either by the replication slot or
2516           by <varname>wal_keep_size</varname>.
2517          </para>
2518         </listitem>
2519         <listitem>
2520          <para>
2521           <literal>unreserved</literal> means that the slot no longer
2522           retains the required WAL files and some of them are to be removed at
2523           the next checkpoint.  This state can return
2524           to <literal>reserved</literal> or <literal>extended</literal>.
2525          </para>
2526         </listitem>
2527         <listitem>
2528          <para>
2529           <literal>lost</literal> means that some required WAL files have
2530           been removed and this slot is no longer usable.
2531          </para>
2532         </listitem>
2533        </itemizedlist>
2534        The last two states are seen only when
2535        <xref linkend="guc-max-slot-wal-keep-size"/> is
2536        non-negative. If <structfield>restart_lsn</structfield> is NULL, this
2537        field is null.
2538       </para></entry>
2539      </row>
2540
2541      <row>
2542       <entry role="catalog_table_entry"><para role="column_definition">
2543        <structfield>safe_wal_size</structfield> <type>int8</type>
2544       </para>
2545       <para>
2546        The number of bytes that can be written to WAL such that this slot
2547        is not in danger of getting in state "lost".  It is NULL for lost
2548        slots, as well as if <varname>max_slot_wal_keep_size</varname>
2549        is <literal>-1</literal>.
2550       </para></entry>
2551      </row>
2552
2553      <row>
2554       <entry role="catalog_table_entry"><para role="column_definition">
2555        <structfield>two_phase</structfield> <type>bool</type>
2556       </para>
2557       <para>
2558        True if the slot is enabled for decoding prepared transactions.  Always
2559        false for physical slots.
2560       </para></entry>
2561      </row>
2562
2563      <row>
2564       <entry role="catalog_table_entry"><para role="column_definition">
2565        <structfield>inactive_since</structfield> <type>timestamptz</type>
2566       </para>
2567       <para>
2568         The time when the slot became inactive. <literal>NULL</literal> if the
2569         slot is currently being streamed.
2570         Note that for slots on the standby that are being synced from a
2571         primary server (whose <structfield>synced</structfield> field is
2572         <literal>true</literal>), the <structfield>inactive_since</structfield>
2573         indicates the time when slot synchronization (see <xref
2574         linkend="logicaldecoding-replication-slots-synchronization"/>)
2575         was most recently stopped.  <literal>NULL</literal> if the slot
2576         has always been synchronized. On standby, this is useful for slots
2577         that are being synced from a primary server (whose
2578         <structfield>synced</structfield> field is <literal>true</literal>)
2579         so they know when the slot stopped being synchronized.
2580       </para></entry>
2581      </row>
2582
2583      <row>
2584       <entry role="catalog_table_entry"><para role="column_definition">
2585        <structfield>conflicting</structfield> <type>bool</type>
2586       </para>
2587       <para>
2588        True if this logical slot conflicted with recovery (and so is now
2589        invalidated). When this column is true, check
2590        <structfield>invalidation_reason</structfield> column for the conflict
2591        reason. Always <literal>NULL</literal> for physical slots.
2592       </para></entry>
2593      </row>
2594
2595      <row>
2596       <entry role="catalog_table_entry"><para role="column_definition">
2597        <structfield>invalidation_reason</structfield> <type>text</type>
2598       </para>
2599       <para>
2600        The reason for the slot's invalidation. It is set for both logical and
2601        physical slots. <literal>NULL</literal> if the slot is not invalidated.
2602        Possible values are:
2603        <itemizedlist spacing="compact">
2604         <listitem>
2605          <para>
2606           <literal>wal_removed</literal> means that the required WAL has been
2607           removed.
2608          </para>
2609         </listitem>
2610         <listitem>
2611          <para>
2612           <literal>rows_removed</literal> means that the required rows have
2613           been removed. It is set only for logical slots.
2614          </para>
2615         </listitem>
2616         <listitem>
2617          <para>
2618           <literal>wal_level_insufficient</literal> means that the
2619           primary doesn't have a <xref linkend="guc-wal-level"/> sufficient to
2620           perform logical decoding.  It is set only for logical slots.
2621          </para>
2622         </listitem>
2623        </itemizedlist>
2624       </para></entry>
2625      </row>
2626
2627      <row>
2628       <entry role="catalog_table_entry"><para role="column_definition">
2629        <structfield>failover</structfield> <type>bool</type>
2630       </para>
2631       <para>
2632        True if this is a logical slot enabled to be synced to the standbys
2633        so that logical replication can be resumed from the new primary
2634        after failover. Always false for physical slots.
2635       </para></entry>
2636      </row>
2637
2638      <row>
2639       <entry role="catalog_table_entry"><para role="column_definition">
2640        <structfield>synced</structfield> <type>bool</type>
2641       </para>
2642       <para>
2643        True if this is a logical slot that was synced from a primary server.
2644        On a hot standby, the slots with the synced column marked as true can
2645        neither be used for logical decoding nor dropped manually. The value
2646        of this column has no meaning on the primary server; the column value on
2647        the primary is default false for all slots but may (if leftover from a
2648        promoted standby) also be true.
2649       </para></entry>
2650      </row>
2651
2652     </tbody>
2653    </tgroup>
2654   </table>
2655  </sect1>
2656
2657  <sect1 id="view-pg-roles">
2658   <title><structname>pg_roles</structname></title>
2659
2660   <indexterm zone="view-pg-roles">
2661    <primary>pg_roles</primary>
2662   </indexterm>
2663
2664   <para>
2665    The view <structname>pg_roles</structname> provides access to
2666    information about database roles.  This is simply a publicly
2667    readable view of
2668    <link linkend="catalog-pg-authid"><structname>pg_authid</structname></link>
2669    that blanks out the password field.
2670   </para>
2671
2672   <table>
2673    <title><structname>pg_roles</structname> Columns</title>
2674    <tgroup cols="1">
2675     <thead>
2676      <row>
2677       <entry role="catalog_table_entry"><para role="column_definition">
2678        Column Type
2679       </para>
2680       <para>
2681        Description
2682       </para></entry>
2683      </row>
2684     </thead>
2685
2686     <tbody>
2687      <row>
2688       <entry role="catalog_table_entry"><para role="column_definition">
2689        <structfield>rolname</structfield> <type>name</type>
2690       </para>
2691       <para>
2692        Role name
2693       </para></entry>
2694      </row>
2695
2696      <row>
2697       <entry role="catalog_table_entry"><para role="column_definition">
2698        <structfield>rolsuper</structfield> <type>bool</type>
2699       </para>
2700       <para>
2701        Role has superuser privileges
2702       </para></entry>
2703      </row>
2704
2705      <row>
2706       <entry role="catalog_table_entry"><para role="column_definition">
2707        <structfield>rolinherit</structfield> <type>bool</type>
2708       </para>
2709       <para>
2710        Role automatically inherits privileges of roles it is a
2711        member of
2712       </para></entry>
2713      </row>
2714
2715      <row>
2716       <entry role="catalog_table_entry"><para role="column_definition">
2717        <structfield>rolcreaterole</structfield> <type>bool</type>
2718       </para>
2719       <para>
2720        Role can create more roles
2721       </para></entry>
2722      </row>
2723
2724      <row>
2725       <entry role="catalog_table_entry"><para role="column_definition">
2726        <structfield>rolcreatedb</structfield> <type>bool</type>
2727       </para>
2728       <para>
2729        Role can create databases
2730       </para></entry>
2731      </row>
2732
2733      <row>
2734       <entry role="catalog_table_entry"><para role="column_definition">
2735        <structfield>rolcanlogin</structfield> <type>bool</type>
2736       </para>
2737       <para>
2738        Role can log in. That is, this role can be given as the initial
2739        session authorization identifier
2740       </para></entry>
2741      </row>
2742
2743      <row>
2744       <entry role="catalog_table_entry"><para role="column_definition">
2745        <structfield>rolreplication</structfield> <type>bool</type>
2746       </para>
2747       <para>
2748        Role is a replication role. A replication role can initiate replication
2749        connections and create and drop replication slots.
2750       </para></entry>
2751      </row>
2752
2753      <row>
2754       <entry role="catalog_table_entry"><para role="column_definition">
2755        <structfield>rolconnlimit</structfield> <type>int4</type>
2756       </para>
2757       <para>
2758        For roles that can log in, this sets maximum number of concurrent
2759        connections this role can make.  -1 means no limit.
2760       </para></entry>
2761      </row>
2762
2763      <row>
2764       <entry role="catalog_table_entry"><para role="column_definition">
2765        <structfield>rolpassword</structfield> <type>text</type>
2766       </para>
2767       <para>
2768        Not the password (always reads as <literal>********</literal>)
2769       </para></entry>
2770      </row>
2771
2772      <row>
2773       <entry role="catalog_table_entry"><para role="column_definition">
2774        <structfield>rolvaliduntil</structfield> <type>timestamptz</type>
2775       </para>
2776       <para>
2777        Password expiry time (only used for password authentication);
2778        null if no expiration
2779       </para></entry>
2780      </row>
2781
2782      <row>
2783       <entry role="catalog_table_entry"><para role="column_definition">
2784        <structfield>rolbypassrls</structfield> <type>bool</type>
2785       </para>
2786       <para>
2787        Role bypasses every row-level security policy, see
2788        <xref linkend="ddl-rowsecurity"/> for more information.
2789       </para></entry>
2790      </row>
2791
2792      <row>
2793       <entry role="catalog_table_entry"><para role="column_definition">
2794        <structfield>rolconfig</structfield> <type>text[]</type>
2795       </para>
2796       <para>
2797        Role-specific defaults for run-time configuration variables
2798       </para></entry>
2799      </row>
2800
2801      <row>
2802       <entry role="catalog_table_entry"><para role="column_definition">
2803        <structfield>oid</structfield> <type>oid</type>
2804        (references <link linkend="catalog-pg-authid"><structname>pg_authid</structname></link>.<structfield>oid</structfield>)
2805       </para>
2806       <para>
2807        ID of role
2808       </para></entry>
2809      </row>
2810     </tbody>
2811    </tgroup>
2812   </table>
2813
2814  </sect1>
2815
2816  <sect1 id="view-pg-rules">
2817   <title><structname>pg_rules</structname></title>
2818
2819   <indexterm zone="view-pg-rules">
2820    <primary>pg_rules</primary>
2821   </indexterm>
2822
2823   <para>
2824    The view <structname>pg_rules</structname> provides access to
2825    useful information about query rewrite rules.
2826   </para>
2827
2828   <table>
2829    <title><structname>pg_rules</structname> Columns</title>
2830    <tgroup cols="1">
2831     <thead>
2832      <row>
2833       <entry role="catalog_table_entry"><para role="column_definition">
2834        Column Type
2835       </para>
2836       <para>
2837        Description
2838       </para></entry>
2839      </row>
2840     </thead>
2841
2842     <tbody>
2843      <row>
2844       <entry role="catalog_table_entry"><para role="column_definition">
2845        <structfield>schemaname</structfield> <type>name</type>
2846        (references <link linkend="catalog-pg-namespace"><structname>pg_namespace</structname></link>.<structfield>nspname</structfield>)
2847       </para>
2848       <para>
2849        Name of schema containing table
2850       </para></entry>
2851      </row>
2852
2853      <row>
2854       <entry role="catalog_table_entry"><para role="column_definition">
2855        <structfield>tablename</structfield> <type>name</type>
2856        (references <link linkend="catalog-pg-class"><structname>pg_class</structname></link>.<structfield>relname</structfield>)
2857       </para>
2858       <para>
2859        Name of table the rule is for
2860       </para></entry>
2861      </row>
2862
2863      <row>
2864       <entry role="catalog_table_entry"><para role="column_definition">
2865        <structfield>rulename</structfield> <type>name</type>
2866        (references <link linkend="catalog-pg-rewrite"><structname>pg_rewrite</structname></link>.<structfield>rulename</structfield>)
2867       </para>
2868       <para>
2869        Name of rule
2870       </para></entry>
2871      </row>
2872
2873      <row>
2874       <entry role="catalog_table_entry"><para role="column_definition">
2875        <structfield>definition</structfield> <type>text</type>
2876       </para>
2877       <para>
2878        Rule definition (a reconstructed creation command)
2879       </para></entry>
2880      </row>
2881     </tbody>
2882    </tgroup>
2883   </table>
2884
2885   <para>
2886    The <structname>pg_rules</structname> view excludes the <literal>ON SELECT</literal> rules
2887    of views and materialized views; those can be seen in
2888    <link linkend="view-pg-views"><structname>pg_views</structname></link> and <link linkend="view-pg-matviews"><structname>pg_matviews</structname></link>.
2889   </para>
2890
2891  </sect1>
2892
2893  <sect1 id="view-pg-seclabels">
2894   <title><structname>pg_seclabels</structname></title>
2895
2896   <indexterm zone="view-pg-seclabels">
2897    <primary>pg_seclabels</primary>
2898   </indexterm>
2899
2900   <para>
2901    The view <structname>pg_seclabels</structname> provides information about
2902    security labels.  It as an easier-to-query version of the
2903    <link linkend="catalog-pg-seclabel"><structname>pg_seclabel</structname></link> catalog.
2904   </para>
2905
2906   <table>
2907    <title><structname>pg_seclabels</structname> Columns</title>
2908    <tgroup cols="1">
2909     <thead>
2910      <row>
2911       <entry role="catalog_table_entry"><para role="column_definition">
2912        Column Type
2913       </para>
2914       <para>
2915        Description
2916       </para></entry>
2917      </row>
2918     </thead>
2919
2920     <tbody>
2921      <row>
2922       <entry role="catalog_table_entry"><para role="column_definition">
2923        <structfield>objoid</structfield> <type>oid</type>
2924        (references any OID column)
2925       </para>
2926       <para>
2927        The OID of the object this security label pertains to
2928       </para></entry>
2929      </row>
2930
2931      <row>
2932       <entry role="catalog_table_entry"><para role="column_definition">
2933        <structfield>classoid</structfield> <type>oid</type>
2934        (references <link linkend="catalog-pg-class"><structname>pg_class</structname></link>.<structfield>oid</structfield>)
2935       </para>
2936       <para>
2937        The OID of the system catalog this object appears in
2938       </para></entry>
2939      </row>
2940
2941      <row>
2942       <entry role="catalog_table_entry"><para role="column_definition">
2943        <structfield>objsubid</structfield> <type>int4</type>
2944       </para>
2945       <para>
2946        For a security label on a table column, this is the column number (the
2947        <structfield>objoid</structfield> and <structfield>classoid</structfield> refer to
2948        the table itself).  For all other object types, this column is
2949        zero.
2950       </para></entry>
2951      </row>
2952
2953      <row>
2954       <entry role="catalog_table_entry"><para role="column_definition">
2955        <structfield>objtype</structfield> <type>text</type>
2956       </para>
2957       <para>
2958        The type of object to which this label applies, as text.
2959       </para></entry>
2960      </row>
2961
2962      <row>
2963       <entry role="catalog_table_entry"><para role="column_definition">
2964        <structfield>objnamespace</structfield> <type>oid</type>
2965        (references <link linkend="catalog-pg-namespace"><structname>pg_namespace</structname></link>.<structfield>oid</structfield>)
2966       </para>
2967       <para>
2968        The OID of the namespace for this object, if applicable;
2969        otherwise NULL.
2970       </para></entry>
2971      </row>
2972
2973      <row>
2974       <entry role="catalog_table_entry"><para role="column_definition">
2975        <structfield>objname</structfield> <type>text</type>
2976       </para>
2977       <para>
2978        The name of the object to which this label applies, as text.
2979       </para></entry>
2980      </row>
2981
2982      <row>
2983       <entry role="catalog_table_entry"><para role="column_definition">
2984        <structfield>provider</structfield> <type>text</type>
2985        (references <link linkend="catalog-pg-seclabel"><structname>pg_seclabel</structname></link>.<structfield>provider</structfield>)
2986       </para>
2987       <para>
2988        The label provider associated with this label.
2989       </para></entry>
2990      </row>
2991
2992      <row>
2993       <entry role="catalog_table_entry"><para role="column_definition">
2994        <structfield>label</structfield> <type>text</type>
2995        (references <link linkend="catalog-pg-seclabel"><structname>pg_seclabel</structname></link>.<structfield>label</structfield>)
2996       </para>
2997       <para>
2998        The security label applied to this object.
2999       </para></entry>
3000      </row>
3001     </tbody>
3002    </tgroup>
3003   </table>
3004  </sect1>
3005
3006  <sect1 id="view-pg-sequences">
3007   <title><structname>pg_sequences</structname></title>
3008
3009   <indexterm zone="view-pg-sequences">
3010    <primary>pg_sequences</primary>
3011   </indexterm>
3012
3013   <para>
3014    The view <structname>pg_sequences</structname> provides access to
3015    useful information about each sequence in the database.
3016   </para>
3017
3018   <table>
3019    <title><structname>pg_sequences</structname> Columns</title>
3020    <tgroup cols="1">
3021     <thead>
3022      <row>
3023       <entry role="catalog_table_entry"><para role="column_definition">
3024        Column Type
3025       </para>
3026       <para>
3027        Description
3028       </para></entry>
3029      </row>
3030     </thead>
3031
3032     <tbody>
3033      <row>
3034       <entry role="catalog_table_entry"><para role="column_definition">
3035        <structfield>schemaname</structfield> <type>name</type>
3036        (references <link linkend="catalog-pg-namespace"><structname>pg_namespace</structname></link>.<structfield>nspname</structfield>)
3037       </para>
3038       <para>
3039        Name of schema containing sequence
3040       </para></entry>
3041      </row>
3042
3043      <row>
3044       <entry role="catalog_table_entry"><para role="column_definition">
3045        <structfield>sequencename</structfield> <type>name</type>
3046        (references <link linkend="catalog-pg-class"><structname>pg_class</structname></link>.<structfield>relname</structfield>)
3047       </para>
3048       <para>
3049        Name of sequence
3050       </para></entry>
3051      </row>
3052
3053      <row>
3054       <entry role="catalog_table_entry"><para role="column_definition">
3055        <structfield>sequenceowner</structfield> <type>name</type>
3056        (references <link linkend="catalog-pg-authid"><structname>pg_authid</structname></link>.<structfield>rolname</structfield>)
3057       </para>
3058       <para>
3059        Name of sequence's owner
3060       </para></entry>
3061      </row>
3062
3063      <row>
3064       <entry role="catalog_table_entry"><para role="column_definition">
3065        <structfield>data_type</structfield> <type>regtype</type>
3066        (references <link linkend="catalog-pg-type"><structname>pg_type</structname></link>.<structfield>oid</structfield>)
3067       </para>
3068       <para>
3069        Data type of the sequence
3070       </para></entry>
3071      </row>
3072
3073      <row>
3074       <entry role="catalog_table_entry"><para role="column_definition">
3075        <structfield>start_value</structfield> <type>int8</type>
3076       </para>
3077       <para>
3078        Start value of the sequence
3079       </para></entry>
3080      </row>
3081
3082      <row>
3083       <entry role="catalog_table_entry"><para role="column_definition">
3084        <structfield>min_value</structfield> <type>int8</type>
3085       </para>
3086       <para>
3087        Minimum value of the sequence
3088       </para></entry>
3089      </row>
3090
3091      <row>
3092       <entry role="catalog_table_entry"><para role="column_definition">
3093        <structfield>max_value</structfield> <type>int8</type>
3094       </para>
3095       <para>
3096        Maximum value of the sequence
3097       </para></entry>
3098      </row>
3099
3100      <row>
3101       <entry role="catalog_table_entry"><para role="column_definition">
3102        <structfield>increment_by</structfield> <type>int8</type>
3103       </para>
3104       <para>
3105        Increment value of the sequence
3106       </para></entry>
3107      </row>
3108
3109      <row>
3110       <entry role="catalog_table_entry"><para role="column_definition">
3111        <structfield>cycle</structfield> <type>bool</type>
3112       </para>
3113       <para>
3114        Whether the sequence cycles
3115       </para></entry>
3116      </row>
3117
3118      <row>
3119       <entry role="catalog_table_entry"><para role="column_definition">
3120        <structfield>cache_size</structfield> <type>int8</type>
3121       </para>
3122       <para>
3123        Cache size of the sequence
3124       </para></entry>
3125      </row>
3126
3127      <row>
3128       <entry role="catalog_table_entry"><para role="column_definition">
3129        <structfield>last_value</structfield> <type>int8</type>
3130       </para>
3131       <para>
3132        The last sequence value written to disk.  If caching is used,
3133        this value can be greater than the last value handed out from the
3134        sequence.
3135       </para></entry>
3136      </row>
3137     </tbody>
3138    </tgroup>
3139   </table>
3140
3141   <para>
3142    The <structfield>last_value</structfield> column will read as null if any of
3143    the following are true:
3144    <itemizedlist>
3145     <listitem>
3146      <para>
3147       The sequence has not been read from yet.
3148      </para>
3149     </listitem>
3150     <listitem>
3151      <para>
3152       The current user does not have <literal>USAGE</literal> or
3153       <literal>SELECT</literal> privilege on the sequence.
3154      </para>
3155     </listitem>
3156     <listitem>
3157      <para>
3158       The sequence is unlogged and the server is a standby.
3159      </para>
3160     </listitem>
3161    </itemizedlist>
3162   </para>
3163
3164  </sect1>
3165
3166  <sect1 id="view-pg-settings">
3167   <title><structname>pg_settings</structname></title>
3168
3169   <indexterm zone="view-pg-settings">
3170    <primary>pg_settings</primary>
3171   </indexterm>
3172
3173   <para>
3174    The view <structname>pg_settings</structname> provides access to
3175    run-time parameters of the server.  It is essentially an alternative
3176    interface to the <link linkend="sql-show"><command>SHOW</command></link>
3177    and <link linkend="sql-set"><command>SET</command></link> commands.
3178    It also provides access to some facts about each parameter that are
3179    not directly available from <link linkend="sql-show"><command>SHOW</command></link>, such as minimum and
3180    maximum values.
3181   </para>
3182
3183   <table>
3184    <title><structname>pg_settings</structname> Columns</title>
3185    <tgroup cols="1">
3186     <thead>
3187      <row>
3188       <entry role="catalog_table_entry"><para role="column_definition">
3189        Column Type
3190       </para>
3191       <para>
3192        Description
3193       </para></entry>
3194      </row>
3195     </thead>
3196
3197     <tbody>
3198      <row>
3199       <entry role="catalog_table_entry"><para role="column_definition">
3200        <structfield>name</structfield> <type>text</type>
3201       </para>
3202       <para>
3203        Run-time configuration parameter name
3204       </para></entry>
3205      </row>
3206
3207      <row>
3208       <entry role="catalog_table_entry"><para role="column_definition">
3209        <structfield>setting</structfield> <type>text</type>
3210       </para>
3211       <para>
3212        Current value of the parameter
3213       </para></entry>
3214      </row>
3215
3216      <row>
3217       <entry role="catalog_table_entry"><para role="column_definition">
3218        <structfield>unit</structfield> <type>text</type>
3219       </para>
3220       <para>
3221        Implicit unit of the parameter
3222       </para></entry>
3223      </row>
3224
3225      <row>
3226       <entry role="catalog_table_entry"><para role="column_definition">
3227        <structfield>category</structfield> <type>text</type>
3228       </para>
3229       <para>
3230        Logical group of the parameter
3231       </para></entry>
3232      </row>
3233
3234      <row>
3235       <entry role="catalog_table_entry"><para role="column_definition">
3236        <structfield>short_desc</structfield> <type>text</type>
3237       </para>
3238       <para>
3239        A brief description of the parameter
3240       </para></entry>
3241      </row>
3242
3243      <row>
3244       <entry role="catalog_table_entry"><para role="column_definition">
3245        <structfield>extra_desc</structfield> <type>text</type>
3246       </para>
3247       <para>
3248        Additional, more detailed, description of the parameter
3249       </para></entry>
3250      </row>
3251
3252      <row>
3253       <entry role="catalog_table_entry"><para role="column_definition">
3254        <structfield>context</structfield> <type>text</type>
3255       </para>
3256       <para>
3257        Context required to set the parameter's value (see below)
3258       </para></entry>
3259      </row>
3260
3261      <row>
3262       <entry role="catalog_table_entry"><para role="column_definition">
3263        <structfield>vartype</structfield> <type>text</type>
3264       </para>
3265       <para>
3266        Parameter type (<literal>bool</literal>, <literal>enum</literal>,
3267        <literal>integer</literal>, <literal>real</literal>, or <literal>string</literal>)
3268       </para></entry>
3269      </row>
3270
3271      <row>
3272       <entry role="catalog_table_entry"><para role="column_definition">
3273        <structfield>source</structfield> <type>text</type>
3274       </para>
3275       <para>
3276        Source of the current parameter value
3277       </para></entry>
3278      </row>
3279
3280      <row>
3281       <entry role="catalog_table_entry"><para role="column_definition">
3282        <structfield>min_val</structfield> <type>text</type>
3283       </para>
3284       <para>
3285        Minimum allowed value of the parameter (null for non-numeric
3286        values)
3287       </para></entry>
3288      </row>
3289
3290      <row>
3291       <entry role="catalog_table_entry"><para role="column_definition">
3292        <structfield>max_val</structfield> <type>text</type>
3293       </para>
3294       <para>
3295        Maximum allowed value of the parameter (null for non-numeric
3296        values)
3297       </para></entry>
3298      </row>
3299
3300      <row>
3301       <entry role="catalog_table_entry"><para role="column_definition">
3302        <structfield>enumvals</structfield> <type>text[]</type>
3303       </para>
3304       <para>
3305        Allowed values of an enum parameter (null for non-enum
3306        values)
3307       </para></entry>
3308      </row>
3309
3310      <row>
3311       <entry role="catalog_table_entry"><para role="column_definition">
3312        <structfield>boot_val</structfield> <type>text</type>
3313       </para>
3314       <para>
3315        Parameter value assumed at server startup if the parameter is
3316        not otherwise set
3317       </para></entry>
3318      </row>
3319
3320      <row>
3321       <entry role="catalog_table_entry"><para role="column_definition">
3322        <structfield>reset_val</structfield> <type>text</type>
3323       </para>
3324       <para>
3325        Value that <link linkend="sql-reset"><command>RESET</command></link> would reset the parameter to
3326        in the current session
3327       </para></entry>
3328      </row>
3329
3330      <row>
3331       <entry role="catalog_table_entry"><para role="column_definition">
3332        <structfield>sourcefile</structfield> <type>text</type>
3333       </para>
3334       <para>
3335        Configuration file the current value was set in (null for
3336        values set from sources other than configuration files, or when
3337        examined by a user who neither is a superuser nor has privileges of
3338        <literal>pg_read_all_settings</literal>); helpful when using
3339        <literal>include</literal> directives in configuration files
3340       </para></entry>
3341      </row>
3342
3343      <row>
3344       <entry role="catalog_table_entry"><para role="column_definition">
3345        <structfield>sourceline</structfield> <type>int4</type>
3346       </para>
3347       <para>
3348        Line number within the configuration file the current value was
3349        set at (null for values set from sources other than configuration files,
3350        or when examined by a user who neither is a superuser nor has privileges of
3351        <literal>pg_read_all_settings</literal>).
3352       </para></entry>
3353      </row>
3354
3355      <row>
3356       <entry role="catalog_table_entry"><para role="column_definition">
3357        <structfield>pending_restart</structfield> <type>bool</type>
3358       </para>
3359       <para>
3360        <literal>true</literal> if the value has been changed in the
3361        configuration file but needs a restart; or <literal>false</literal>
3362        otherwise.
3363       </para></entry>
3364      </row>
3365     </tbody>
3366    </tgroup>
3367   </table>
3368
3369   <para>
3370    There are several possible values of <structfield>context</structfield>.
3371    In order of decreasing difficulty of changing the setting, they are:
3372   </para>
3373
3374   <variablelist>
3375    <varlistentry>
3376     <!-- PGC_INTERNAL -->
3377     <term><literal>internal</literal></term>
3378     <listitem>
3379      <para>
3380       These settings cannot be changed directly; they reflect internally
3381       determined values.  Some of them may be adjustable by rebuilding the
3382       server with different configuration options, or by changing options
3383       supplied to <application>initdb</application>.
3384      </para>
3385     </listitem>
3386    </varlistentry>
3387    <varlistentry>
3388     <!-- PGC_POSTMASTER -->
3389     <term><literal>postmaster</literal></term>
3390     <listitem>
3391      <para>
3392       These settings can only be applied when the server starts, so any change
3393       requires restarting the server.  Values for these settings are typically
3394       stored in the <filename>postgresql.conf</filename> file, or passed on
3395       the command line when starting the server.  Of course, settings with any
3396       of the lower <structfield>context</structfield> types can also be
3397       set at server start time.
3398      </para>
3399     </listitem>
3400    </varlistentry>
3401    <varlistentry>
3402     <!-- PGC_SIGHUP -->
3403     <term><literal>sighup</literal></term>
3404     <listitem>
3405      <para>
3406       Changes to these settings can be made in
3407       <filename>postgresql.conf</filename> without restarting the server.
3408       Send a <systemitem>SIGHUP</systemitem> signal to the postmaster to
3409       cause it to re-read <filename>postgresql.conf</filename> and apply
3410       the changes.  The postmaster will also forward the
3411       <systemitem>SIGHUP</systemitem> signal to its child processes so that
3412       they all pick up the new value.
3413      </para>
3414     </listitem>
3415    </varlistentry>
3416    <varlistentry>
3417     <!-- PGC_SU_BACKEND -->
3418     <term><literal>superuser-backend</literal></term>
3419     <listitem>
3420      <para>
3421       Changes to these settings can be made in
3422       <filename>postgresql.conf</filename> without restarting the server.
3423       They can also be set for a particular session in the connection request
3424       packet (for example, via <application>libpq</application>'s <literal>PGOPTIONS</literal>
3425       environment variable), but only if the connecting user is a superuser
3426       or has been granted the appropriate <literal>SET</literal> privilege.
3427       However, these settings never change in a session after it is started.
3428       If you change them in <filename>postgresql.conf</filename>, send a
3429       <systemitem>SIGHUP</systemitem> signal to the postmaster to cause it to
3430       re-read <filename>postgresql.conf</filename>.  The new values will only
3431       affect subsequently-launched sessions.
3432      </para>
3433     </listitem>
3434    </varlistentry>
3435    <varlistentry>
3436     <!-- PGC_BACKEND -->
3437     <term><literal>backend</literal></term>
3438     <listitem>
3439      <para>
3440       Changes to these settings can be made in
3441       <filename>postgresql.conf</filename> without restarting the server.
3442       They can also be set for a particular session in the connection request
3443       packet (for example, via <application>libpq</application>'s <literal>PGOPTIONS</literal>
3444       environment variable); any user can make such a change for their session.
3445       However, these settings never change in a session after it is started.
3446       If you change them in <filename>postgresql.conf</filename>, send a
3447       <systemitem>SIGHUP</systemitem> signal to the postmaster to cause it to
3448       re-read <filename>postgresql.conf</filename>.  The new values will only
3449       affect subsequently-launched sessions.
3450      </para>
3451     </listitem>
3452    </varlistentry>
3453    <varlistentry>
3454     <!-- PGC_SUSET -->
3455     <term><literal>superuser</literal></term>
3456     <listitem>
3457      <para>
3458       These settings can be set from <filename>postgresql.conf</filename>,
3459       or within a session via the <command>SET</command> command; but only superusers
3460       and users with the appropriate <literal>SET</literal> privilege
3461       can change them via <command>SET</command>.  Changes in
3462       <filename>postgresql.conf</filename> will affect existing sessions
3463       only if no session-local value has been established with <command>SET</command>.
3464      </para>
3465     </listitem>
3466    </varlistentry>
3467    <varlistentry>
3468     <!-- PGC_USERSET -->
3469     <term><literal>user</literal></term>
3470     <listitem>
3471      <para>
3472       These settings can be set from <filename>postgresql.conf</filename>,
3473       or within a session via the <command>SET</command> command.  Any user is
3474       allowed to change their session-local value.  Changes in
3475       <filename>postgresql.conf</filename> will affect existing sessions
3476       only if no session-local value has been established with <command>SET</command>.
3477      </para>
3478     </listitem>
3479    </varlistentry>
3480   </variablelist>
3481
3482   <para>
3483    See <xref linkend="config-setting"/> for more information about the various
3484    ways to change these parameters.
3485   </para>
3486
3487   <para>
3488    This view cannot be inserted into or deleted from, but it can be updated.  An
3489    <command>UPDATE</command> applied to a row of <structname>pg_settings</structname>
3490    is equivalent to executing the <command>SET</command> command on that named
3491    parameter. The change only affects the value used by the current
3492    session. If an <command>UPDATE</command> is issued within a transaction
3493    that is later aborted, the effects of the <command>UPDATE</command> command
3494    disappear when the transaction is rolled back. Once the surrounding
3495    transaction is committed, the effects will persist until the end of the
3496    session, unless overridden by another <command>UPDATE</command> or
3497    <command>SET</command>.
3498   </para>
3499
3500   <para>
3501    This view does not
3502    display <link linkend="runtime-config-custom">customized options</link>
3503    unless the extension module that defines them has been loaded by the
3504    backend process executing the query (e.g., via a mention in
3505    <xref linkend="guc-shared-preload-libraries"/>,
3506    a call to a C function in the extension, or the
3507    <link linkend="sql-load"><command>LOAD</command></link> command).
3508    For example, since <link linkend="archive-modules">archive modules</link>
3509    are normally loaded only by the archiver process not regular sessions,
3510    this view will not display any customized options defined by such modules
3511    unless special action is taken to load them into the backend process
3512    executing the query.
3513   </para>
3514
3515  </sect1>
3516
3517  <sect1 id="view-pg-shadow">
3518   <title><structname>pg_shadow</structname></title>
3519
3520   <indexterm zone="view-pg-shadow">
3521    <primary>pg_shadow</primary>
3522   </indexterm>
3523
3524   <para>
3525    The view <structname>pg_shadow</structname> exists for backwards
3526    compatibility: it emulates a catalog that existed in
3527    <productname>PostgreSQL</productname> before version 8.1.
3528    It shows properties of all roles that are marked as
3529    <structfield>rolcanlogin</structfield> in
3530    <link linkend="catalog-pg-authid"><structname>pg_authid</structname></link>.
3531   </para>
3532
3533   <para>
3534    The name stems from the fact that this table
3535    should not be readable by the public since it contains passwords.
3536    <link linkend="view-pg-user"><structname>pg_user</structname></link>
3537    is a publicly readable view on
3538    <structname>pg_shadow</structname> that blanks out the password field.
3539   </para>
3540
3541   <table>
3542    <title><structname>pg_shadow</structname> Columns</title>
3543    <tgroup cols="1">
3544     <thead>
3545      <row>
3546       <entry role="catalog_table_entry"><para role="column_definition">
3547        Column Type
3548       </para>
3549       <para>
3550        Description
3551       </para></entry>
3552      </row>
3553     </thead>
3554
3555     <tbody>
3556      <row>
3557       <entry role="catalog_table_entry"><para role="column_definition">
3558        <structfield>usename</structfield> <type>name</type>
3559        (references <link linkend="catalog-pg-authid"><structname>pg_authid</structname></link>.<structfield>rolname</structfield>)
3560       </para>
3561       <para>
3562        User name
3563       </para></entry>
3564      </row>
3565
3566      <row>
3567       <entry role="catalog_table_entry"><para role="column_definition">
3568        <structfield>usesysid</structfield> <type>oid</type>
3569        (references <link linkend="catalog-pg-authid"><structname>pg_authid</structname></link>.<structfield>oid</structfield>)
3570       </para>
3571       <para>
3572        ID of this user
3573       </para></entry>
3574      </row>
3575
3576      <row>
3577       <entry role="catalog_table_entry"><para role="column_definition">
3578        <structfield>usecreatedb</structfield> <type>bool</type>
3579       </para>
3580       <para>
3581        User can create databases
3582       </para></entry>
3583      </row>
3584
3585      <row>
3586       <entry role="catalog_table_entry"><para role="column_definition">
3587        <structfield>usesuper</structfield> <type>bool</type>
3588       </para>
3589       <para>
3590        User is a superuser
3591       </para></entry>
3592      </row>
3593
3594      <row>
3595       <entry role="catalog_table_entry"><para role="column_definition">
3596        <structfield>userepl</structfield> <type>bool</type>
3597       </para>
3598       <para>
3599        User can initiate streaming replication and put the system in and
3600        out of backup mode.
3601       </para></entry>
3602      </row>
3603
3604      <row>
3605       <entry role="catalog_table_entry"><para role="column_definition">
3606        <structfield>usebypassrls</structfield> <type>bool</type>
3607       </para>
3608       <para>
3609        User bypasses every row-level security policy, see
3610        <xref linkend="ddl-rowsecurity"/> for more information.
3611       </para></entry>
3612      </row>
3613
3614      <row>
3615       <entry role="catalog_table_entry"><para role="column_definition">
3616        <structfield>passwd</structfield> <type>text</type>
3617       </para>
3618       <para>
3619        Password (possibly encrypted); null if none.  See
3620        <link linkend="catalog-pg-authid"><structname>pg_authid</structname></link>
3621        for details of how encrypted passwords are stored.
3622       </para></entry>
3623      </row>
3624
3625      <row>
3626       <entry role="catalog_table_entry"><para role="column_definition">
3627        <structfield>valuntil</structfield> <type>timestamptz</type>
3628       </para>
3629       <para>
3630        Password expiry time (only used for password authentication)
3631       </para></entry>
3632      </row>
3633
3634      <row>
3635       <entry role="catalog_table_entry"><para role="column_definition">
3636        <structfield>useconfig</structfield> <type>text[]</type>
3637       </para>
3638       <para>
3639        Session defaults for run-time configuration variables
3640       </para></entry>
3641      </row>
3642     </tbody>
3643    </tgroup>
3644   </table>
3645
3646  </sect1>
3647
3648  <sect1 id="view-pg-shmem-allocations">
3649   <title><structname>pg_shmem_allocations</structname></title>
3650
3651   <indexterm zone="view-pg-shmem-allocations">
3652    <primary>pg_shmem_allocations</primary>
3653   </indexterm>
3654
3655   <para>
3656    The <structname>pg_shmem_allocations</structname> view shows allocations
3657    made from the server's main shared memory segment.  This includes both
3658    memory allocated by <productname>PostgreSQL</productname> itself and memory
3659    allocated by extensions using the mechanisms detailed in
3660    <xref linkend="xfunc-shared-addin" />.
3661   </para>
3662
3663   <para>
3664    Note that this view does not include memory allocated using the dynamic
3665    shared memory infrastructure.
3666   </para>
3667
3668   <table>
3669    <title><structname>pg_shmem_allocations</structname> Columns</title>
3670    <tgroup cols="1">
3671     <thead>
3672      <row>
3673       <entry role="catalog_table_entry"><para role="column_definition">
3674        Column Type
3675       </para>
3676       <para>
3677        Description
3678       </para></entry>
3679      </row>
3680     </thead>
3681
3682     <tbody>
3683      <row>
3684       <entry role="catalog_table_entry"><para role="column_definition">
3685        <structfield>name</structfield> <type>text</type>
3686       </para>
3687       <para>
3688        The name of the shared memory allocation. NULL for unused memory
3689        and <literal>&lt;anonymous&gt;</literal> for anonymous
3690        allocations.
3691       </para></entry>
3692      </row>
3693
3694      <row>
3695       <entry role="catalog_table_entry"><para role="column_definition">
3696        <structfield>off</structfield> <type>int8</type>
3697       </para>
3698       <para>
3699        The offset at which the allocation starts. NULL for anonymous
3700        allocations, since details related to them are not known.
3701       </para></entry>
3702      </row>
3703
3704      <row>
3705       <entry role="catalog_table_entry"><para role="column_definition">
3706        <structfield>size</structfield> <type>int8</type>
3707       </para>
3708       <para>
3709        Size of the allocation in bytes
3710       </para></entry>
3711      </row>
3712
3713      <row>
3714       <entry role="catalog_table_entry"><para role="column_definition">
3715        <structfield>allocated_size</structfield> <type>int8</type>
3716       </para>
3717       <para>
3718        Size of the allocation in bytes including padding. For anonymous
3719        allocations, no information about padding is available, so the
3720        <literal>size</literal> and <literal>allocated_size</literal> columns
3721        will always be equal. Padding is not meaningful for free memory, so
3722        the columns will be equal in that case also.
3723       </para></entry>
3724      </row>
3725     </tbody>
3726    </tgroup>
3727   </table>
3728
3729   <para>
3730    Anonymous allocations are allocations that have been made
3731    with <literal>ShmemAlloc()</literal> directly, rather than via
3732    <literal>ShmemInitStruct()</literal> or
3733    <literal>ShmemInitHash()</literal>.
3734   </para>
3735
3736   <para>
3737    By default, the <structname>pg_shmem_allocations</structname> view can be
3738    read only by superusers or roles with privileges of the
3739    <literal>pg_read_all_stats</literal> role.
3740   </para>
3741  </sect1>
3742
3743  <sect1 id="view-pg-stats">
3744   <title><structname>pg_stats</structname></title>
3745
3746   <indexterm zone="view-pg-stats">
3747    <primary>pg_stats</primary>
3748   </indexterm>
3749
3750   <para>
3751    The view <structname>pg_stats</structname> provides access to
3752    the information stored in the <link
3753    linkend="catalog-pg-statistic"><structname>pg_statistic</structname></link>
3754    catalog.  This view allows access only to rows of
3755    <link linkend="catalog-pg-statistic"><structname>pg_statistic</structname></link> that correspond to tables the
3756    user has permission to read, and therefore it is safe to allow public
3757    read access to this view.
3758   </para>
3759
3760   <para>
3761    <structname>pg_stats</structname> is also designed to present the
3762    information in a more readable format than the underlying catalog
3763    &mdash; at the cost that its schema must be extended whenever new slot types
3764    are defined for <link linkend="catalog-pg-statistic"><structname>pg_statistic</structname></link>.
3765   </para>
3766
3767   <table>
3768    <title><structname>pg_stats</structname> Columns</title>
3769    <tgroup cols="1">
3770     <thead>
3771      <row>
3772       <entry role="catalog_table_entry"><para role="column_definition">
3773        Column Type
3774       </para>
3775       <para>
3776        Description
3777       </para></entry>
3778      </row>
3779     </thead>
3780
3781     <tbody>
3782      <row>
3783       <entry role="catalog_table_entry"><para role="column_definition">
3784        <structfield>schemaname</structfield> <type>name</type>
3785        (references <link linkend="catalog-pg-namespace"><structname>pg_namespace</structname></link>.<structfield>nspname</structfield>)
3786       </para>
3787       <para>
3788        Name of schema containing table
3789       </para></entry>
3790      </row>
3791
3792      <row>
3793       <entry role="catalog_table_entry"><para role="column_definition">
3794        <structfield>tablename</structfield> <type>name</type>
3795        (references <link linkend="catalog-pg-class"><structname>pg_class</structname></link>.<structfield>relname</structfield>)
3796       </para>
3797       <para>
3798        Name of table
3799       </para></entry>
3800      </row>
3801
3802      <row>
3803       <entry role="catalog_table_entry"><para role="column_definition">
3804        <structfield>attname</structfield> <type>name</type>
3805        (references <link linkend="catalog-pg-attribute"><structname>pg_attribute</structname></link>.<structfield>attname</structfield>)
3806       </para>
3807       <para>
3808        Name of column described by this row
3809       </para></entry>
3810      </row>
3811
3812      <row>
3813       <entry role="catalog_table_entry"><para role="column_definition">
3814        <structfield>inherited</structfield> <type>bool</type>
3815       </para>
3816       <para>
3817        If true, this row includes values from child tables, not just the
3818        values in the specified table
3819       </para></entry>
3820      </row>
3821
3822      <row>
3823       <entry role="catalog_table_entry"><para role="column_definition">
3824        <structfield>null_frac</structfield> <type>float4</type>
3825       </para>
3826       <para>
3827        Fraction of column entries that are null
3828       </para></entry>
3829      </row>
3830
3831      <row>
3832       <entry role="catalog_table_entry"><para role="column_definition">
3833        <structfield>avg_width</structfield> <type>int4</type>
3834       </para>
3835       <para>
3836        Average width in bytes of column's entries
3837       </para></entry>
3838      </row>
3839
3840      <row>
3841       <entry role="catalog_table_entry"><para role="column_definition">
3842        <structfield>n_distinct</structfield> <type>float4</type>
3843       </para>
3844       <para>
3845        If greater than zero, the estimated number of distinct values in the
3846        column.  If less than zero, the negative of the number of distinct
3847        values divided by the number of rows.  (The negated form is used when
3848        <command>ANALYZE</command> believes that the number of distinct values is
3849        likely to increase as the table grows; the positive form is used when
3850        the column seems to have a fixed number of possible values.)  For
3851        example, -1 indicates a unique column in which the number of distinct
3852        values is the same as the number of rows.
3853       </para></entry>
3854      </row>
3855
3856      <row>
3857       <entry role="catalog_table_entry"><para role="column_definition">
3858        <structfield>most_common_vals</structfield> <type>anyarray</type>
3859       </para>
3860       <para>
3861        A list of the most common values in the column. (Null if
3862        no values seem to be more common than any others.)
3863       </para></entry>
3864      </row>
3865
3866      <row>
3867       <entry role="catalog_table_entry"><para role="column_definition">
3868        <structfield>most_common_freqs</structfield> <type>float4[]</type>
3869       </para>
3870       <para>
3871        A list of the frequencies of the most common values,
3872        i.e., number of occurrences of each divided by total number of rows.
3873        (Null when <structfield>most_common_vals</structfield> is.)
3874       </para></entry>
3875      </row>
3876
3877      <row>
3878       <entry role="catalog_table_entry"><para role="column_definition">
3879        <structfield>histogram_bounds</structfield> <type>anyarray</type>
3880       </para>
3881       <para>
3882        A list of values that divide the column's values into groups of
3883        approximately equal population.  The values in
3884        <structfield>most_common_vals</structfield>, if present, are omitted from this
3885        histogram calculation.  (This column is null if the column data type
3886        does not have a <literal>&lt;</literal> operator or if the
3887        <structfield>most_common_vals</structfield> list accounts for the entire
3888        population.)
3889       </para></entry>
3890      </row>
3891
3892      <row>
3893       <entry role="catalog_table_entry"><para role="column_definition">
3894        <structfield>correlation</structfield> <type>float4</type>
3895       </para>
3896       <para>
3897        Statistical correlation between physical row ordering and
3898        logical ordering of the column values.  This ranges from -1 to +1.
3899        When the value is near -1 or +1, an index scan on the column will
3900        be estimated to be cheaper than when it is near zero, due to reduction
3901        of random access to the disk.  (This column is null if the column data
3902        type does not have a <literal>&lt;</literal> operator.)
3903       </para></entry>
3904      </row>
3905
3906      <row>
3907       <entry role="catalog_table_entry"><para role="column_definition">
3908        <structfield>most_common_elems</structfield> <type>anyarray</type>
3909       </para>
3910       <para>
3911        A list of non-null element values most often appearing within values of
3912        the column. (Null for scalar types.)
3913       </para></entry>
3914      </row>
3915
3916      <row>
3917       <entry role="catalog_table_entry"><para role="column_definition">
3918        <structfield>most_common_elem_freqs</structfield> <type>float4[]</type>
3919       </para>
3920       <para>
3921        A list of the frequencies of the most common element values, i.e., the
3922        fraction of rows containing at least one instance of the given value.
3923        Two or three additional values follow the per-element frequencies;
3924        these are the minimum and maximum of the preceding per-element
3925        frequencies, and optionally the frequency of null elements.
3926        (Null when <structfield>most_common_elems</structfield> is.)
3927       </para></entry>
3928      </row>
3929
3930      <row>
3931       <entry role="catalog_table_entry"><para role="column_definition">
3932        <structfield>elem_count_histogram</structfield> <type>float4[]</type>
3933       </para>
3934       <para>
3935        A histogram of the counts of distinct non-null element values within the
3936        values of the column, followed by the average number of distinct
3937        non-null elements.  (Null for scalar types.)
3938       </para></entry>
3939      </row>
3940
3941      <row>
3942       <entry role="catalog_table_entry"><para role="column_definition">
3943        <structfield>range_length_histogram</structfield> <type>anyarray</type>
3944       </para>
3945       <para>
3946        A histogram of the lengths of non-empty and non-null range values of a
3947        range type column. (Null for non-range types.)
3948       </para>
3949       <para>
3950        This histogram is calculated using the <function>subtype_diff</function>
3951        range function regardless of whether range bounds are inclusive.
3952       </para></entry>
3953      </row>
3954
3955      <row>
3956       <entry role="catalog_table_entry"><para role="column_definition">
3957        <structfield>range_empty_frac</structfield> <type>float4</type>
3958       </para>
3959       <para>
3960        Fraction of column entries whose values are empty ranges.
3961        (Null for non-range types.)
3962       </para></entry>
3963      </row>
3964
3965      <row>
3966       <entry role="catalog_table_entry"><para role="column_definition">
3967        <structfield>range_bounds_histogram</structfield> <type>anyarray</type>
3968       </para>
3969       <para>
3970        A histogram of lower and upper bounds of non-empty and non-null range
3971        values. (Null for non-range types.)
3972       </para>
3973       <para>
3974        These two histograms are represented as a single array of ranges, whose
3975        lower bounds represent the histogram of lower bounds, and upper bounds
3976        represent the histogram of upper bounds.
3977       </para></entry>
3978      </row>
3979     </tbody>
3980    </tgroup>
3981   </table>
3982
3983   <para>
3984    The maximum number of entries in the array fields can be controlled on a
3985    column-by-column basis using the <link linkend="sql-altertable"><command>ALTER
3986    TABLE SET STATISTICS</command></link>
3987    command, or globally by setting the
3988    <xref linkend="guc-default-statistics-target"/> run-time parameter.
3989   </para>
3990
3991  </sect1>
3992
3993  <sect1 id="view-pg-stats-ext">
3994   <title><structname>pg_stats_ext</structname></title>
3995
3996   <indexterm zone="view-pg-stats-ext">
3997    <primary>pg_stats_ext</primary>
3998   </indexterm>
3999
4000   <para>
4001    The view <structname>pg_stats_ext</structname> provides access to
4002    information about each extended statistics object in the database,
4003    combining information stored in the <link
4004    linkend="catalog-pg-statistic-ext"><structname>pg_statistic_ext</structname></link>
4005    and <link linkend="catalog-pg-statistic-ext-data"><structname>pg_statistic_ext_data</structname></link>
4006    catalogs.  This view allows access only to rows of
4007    <link linkend="catalog-pg-statistic-ext"><structname>pg_statistic_ext</structname></link> and <link linkend="catalog-pg-statistic-ext-data"><structname>pg_statistic_ext_data</structname></link>
4008    that correspond to tables the user owns, and therefore
4009    it is safe to allow public read access to this view.
4010   </para>
4011
4012   <para>
4013    <structname>pg_stats_ext</structname> is also designed to present the
4014    information in a more readable format than the underlying catalogs
4015    &mdash; at the cost that its schema must be extended whenever new types
4016    of extended statistics are added to <link linkend="catalog-pg-statistic-ext"><structname>pg_statistic_ext</structname></link>.
4017   </para>
4018
4019   <table>
4020    <title><structname>pg_stats_ext</structname> Columns</title>
4021    <tgroup cols="1">
4022     <thead>
4023      <row>
4024       <entry role="catalog_table_entry"><para role="column_definition">
4025        Column Type
4026       </para>
4027       <para>
4028        Description
4029       </para></entry>
4030      </row>
4031     </thead>
4032
4033     <tbody>
4034      <row>
4035       <entry role="catalog_table_entry"><para role="column_definition">
4036        <structfield>schemaname</structfield> <type>name</type>
4037        (references <link linkend="catalog-pg-namespace"><structname>pg_namespace</structname></link>.<structfield>nspname</structfield>)
4038       </para>
4039       <para>
4040        Name of schema containing table
4041       </para></entry>
4042      </row>
4043
4044      <row>
4045       <entry role="catalog_table_entry"><para role="column_definition">
4046        <structfield>tablename</structfield> <type>name</type>
4047        (references <link linkend="catalog-pg-class"><structname>pg_class</structname></link>.<structfield>relname</structfield>)
4048       </para>
4049       <para>
4050        Name of table
4051       </para></entry>
4052      </row>
4053
4054      <row>
4055       <entry role="catalog_table_entry"><para role="column_definition">
4056        <structfield>statistics_schemaname</structfield> <type>name</type>
4057        (references <link linkend="catalog-pg-namespace"><structname>pg_namespace</structname></link>.<structfield>nspname</structfield>)
4058       </para>
4059       <para>
4060        Name of schema containing extended statistics object
4061       </para></entry>
4062      </row>
4063
4064      <row>
4065       <entry role="catalog_table_entry"><para role="column_definition">
4066        <structfield>statistics_name</structfield> <type>name</type>
4067        (references <link linkend="catalog-pg-statistic-ext"><structname>pg_statistic_ext</structname></link>.<structfield>stxname</structfield>)
4068       </para>
4069       <para>
4070        Name of extended statistics object
4071       </para></entry>
4072      </row>
4073
4074      <row>
4075       <entry role="catalog_table_entry"><para role="column_definition">
4076        <structfield>statistics_owner</structfield> <type>name</type>
4077        (references <link linkend="catalog-pg-authid"><structname>pg_authid</structname></link>.<structfield>rolname</structfield>)
4078       </para>
4079       <para>
4080        Owner of the extended statistics object
4081       </para></entry>
4082      </row>
4083
4084      <row>
4085       <entry role="catalog_table_entry"><para role="column_definition">
4086        <structfield>attnames</structfield> <type>name[]</type>
4087        (references <link linkend="catalog-pg-attribute"><structname>pg_attribute</structname></link>.<structfield>attname</structfield>)
4088       </para>
4089       <para>
4090        Names of the columns included in the extended statistics object
4091       </para></entry>
4092      </row>
4093
4094      <row>
4095       <entry role="catalog_table_entry"><para role="column_definition">
4096        <structfield>exprs</structfield> <type>text[]</type>
4097       </para>
4098       <para>
4099        Expressions included in the extended statistics object
4100       </para></entry>
4101       </row>
4102
4103      <row>
4104       <entry role="catalog_table_entry"><para role="column_definition">
4105        <structfield>kinds</structfield> <type>char[]</type>
4106       </para>
4107       <para>
4108        Types of extended statistics object enabled for this record
4109       </para></entry>
4110      </row>
4111
4112      <row>
4113       <entry role="catalog_table_entry"><para role="column_definition">
4114        <structfield>inherited</structfield> <type>bool</type>
4115        (references <link linkend="catalog-pg-statistic-ext-data"><structname>pg_statistic_ext_data</structname></link>.<structfield>stxdinherit</structfield>)
4116       </para>
4117       <para>
4118        If true, the stats include values from child tables, not just the
4119        values in the specified relation
4120       </para></entry>
4121      </row>
4122
4123      <row>
4124       <entry role="catalog_table_entry"><para role="column_definition">
4125        <structfield>n_distinct</structfield> <type>pg_ndistinct</type>
4126       </para>
4127       <para>
4128        N-distinct counts for combinations of column values. If greater
4129        than zero, the estimated number of distinct values in the combination.
4130        If less than zero, the negative of the number of distinct values divided
4131        by the number of rows.
4132        (The negated form is used when <command>ANALYZE</command> believes that
4133        the number of distinct values is likely to increase as the table grows;
4134        the positive form is used when the column seems to have a fixed number
4135        of possible values.)  For example, -1 indicates a unique combination of
4136        columns in which the number of distinct combinations is the same as the
4137        number of rows.
4138       </para></entry>
4139      </row>
4140
4141      <row>
4142       <entry role="catalog_table_entry"><para role="column_definition">
4143        <structfield>dependencies</structfield> <type>pg_dependencies</type>
4144       </para>
4145       <para>
4146        Functional dependency statistics
4147       </para></entry>
4148      </row>
4149
4150      <row>
4151       <entry role="catalog_table_entry"><para role="column_definition">
4152        <structfield>most_common_vals</structfield> <type>text[]</type>
4153       </para>
4154       <para>
4155        A list of the most common combinations of values in the columns.
4156        (Null if no combinations seem to be more common than any others.)
4157       </para></entry>
4158      </row>
4159
4160      <row>
4161       <entry role="catalog_table_entry"><para role="column_definition">
4162        <structfield>most_common_val_nulls</structfield> <type>bool[]</type>
4163       </para>
4164       <para>
4165        A list of NULL flags for the most common combinations of values.
4166        (Null when <structfield>most_common_vals</structfield> is.)
4167       </para></entry>
4168      </row>
4169
4170      <row>
4171       <entry role="catalog_table_entry"><para role="column_definition">
4172        <structfield>most_common_freqs</structfield> <type>float8[]</type>
4173       </para>
4174       <para>
4175        A list of the frequencies of the most common combinations,
4176        i.e., number of occurrences of each divided by total number of rows.
4177        (Null when <structfield>most_common_vals</structfield> is.)
4178       </para></entry>
4179      </row>
4180
4181      <row>
4182       <entry role="catalog_table_entry"><para role="column_definition">
4183        <structfield>most_common_base_freqs</structfield> <type>float8[]</type>
4184       </para>
4185       <para>
4186        A list of the base frequencies of the most common combinations,
4187        i.e., product of per-value frequencies.
4188        (Null when <structfield>most_common_vals</structfield> is.)
4189       </para></entry>
4190      </row>
4191     </tbody>
4192    </tgroup>
4193   </table>
4194
4195   <para>
4196    The maximum number of entries in the array fields can be controlled on a
4197    column-by-column basis using the <link linkend="sql-altertable"><command>ALTER
4198    TABLE SET STATISTICS</command></link> command, or globally by setting the
4199    <xref linkend="guc-default-statistics-target"/> run-time parameter.
4200   </para>
4201
4202  </sect1>
4203
4204  <sect1 id="view-pg-stats-ext-exprs">
4205   <title><structname>pg_stats_ext_exprs</structname></title>
4206
4207   <indexterm zone="view-pg-stats-ext-exprs">
4208    <primary>pg_stats_ext_exprs</primary>
4209   </indexterm>
4210
4211   <para>
4212    The view <structname>pg_stats_ext_exprs</structname> provides access to
4213    information about all expressions included in extended statistics objects,
4214    combining information stored in the <link
4215    linkend="catalog-pg-statistic-ext"><structname>pg_statistic_ext</structname></link>
4216    and <link linkend="catalog-pg-statistic-ext-data"><structname>pg_statistic_ext_data</structname></link>
4217    catalogs.  This view allows access only to rows of
4218    <link linkend="catalog-pg-statistic-ext"><structname>pg_statistic_ext</structname></link> and <link linkend="catalog-pg-statistic-ext-data"><structname>pg_statistic_ext_data</structname></link>
4219    that correspond to tables the user owns, and therefore
4220    it is safe to allow public read access to this view.
4221   </para>
4222
4223   <para>
4224    <structname>pg_stats_ext_exprs</structname> is also designed to present
4225    the information in a more readable format than the underlying catalogs
4226    &mdash; at the cost that its schema must be extended whenever the structure
4227    of statistics in <structname>pg_statistic_ext</structname> changes.
4228   </para>
4229
4230   <table>
4231    <title><structname>pg_stats_ext_exprs</structname> Columns</title>
4232    <tgroup cols="1">
4233     <thead>
4234      <row>
4235       <entry role="catalog_table_entry"><para role="column_definition">
4236        Column Type
4237       </para>
4238       <para>
4239        Description
4240       </para></entry>
4241      </row>
4242     </thead>
4243
4244     <tbody>
4245      <row>
4246       <entry role="catalog_table_entry"><para role="column_definition">
4247        <structfield>schemaname</structfield> <type>name</type>
4248        (references <link linkend="catalog-pg-namespace"><structname>pg_namespace</structname></link>.<structfield>nspname</structfield>)
4249       </para>
4250       <para>
4251        Name of schema containing table
4252       </para></entry>
4253      </row>
4254
4255      <row>
4256       <entry role="catalog_table_entry"><para role="column_definition">
4257        <structfield>tablename</structfield> <type>name</type>
4258        (references <link linkend="catalog-pg-class"><structname>pg_class</structname></link>.<structfield>relname</structfield>)
4259       </para>
4260       <para>
4261        Name of table the statistics object is defined on
4262       </para></entry>
4263      </row>
4264
4265      <row>
4266       <entry role="catalog_table_entry"><para role="column_definition">
4267        <structfield>statistics_schemaname</structfield> <type>name</type>
4268        (references <link linkend="catalog-pg-namespace"><structname>pg_namespace</structname></link>.<structfield>nspname</structfield>)
4269       </para>
4270       <para>
4271        Name of schema containing extended statistics object
4272       </para></entry>
4273      </row>
4274
4275      <row>
4276       <entry role="catalog_table_entry"><para role="column_definition">
4277        <structfield>statistics_name</structfield> <type>name</type>
4278        (references <link linkend="catalog-pg-statistic-ext"><structname>pg_statistic_ext</structname></link>.<structfield>stxname</structfield>)
4279       </para>
4280       <para>
4281        Name of extended statistics object
4282       </para></entry>
4283      </row>
4284
4285      <row>
4286       <entry role="catalog_table_entry"><para role="column_definition">
4287        <structfield>statistics_owner</structfield> <type>name</type>
4288        (references <link linkend="catalog-pg-authid"><structname>pg_authid</structname></link>.<structfield>rolname</structfield>)
4289       </para>
4290       <para>
4291        Owner of the extended statistics object
4292       </para></entry>
4293      </row>
4294
4295      <row>
4296       <entry role="catalog_table_entry"><para role="column_definition">
4297        <structfield>expr</structfield> <type>text</type>
4298       </para>
4299       <para>
4300        Expression included in the extended statistics object
4301       </para></entry>
4302      </row>
4303
4304      <row>
4305       <entry role="catalog_table_entry"><para role="column_definition">
4306        <structfield>inherited</structfield> <type>bool</type>
4307        (references <link linkend="catalog-pg-statistic-ext-data"><structname>pg_statistic_ext_data</structname></link>.<structfield>stxdinherit</structfield>)
4308       </para>
4309       <para>
4310        If true, the stats include values from child tables, not just the
4311        values in the specified relation
4312       </para></entry>
4313      </row>
4314
4315      <row>
4316       <entry role="catalog_table_entry"><para role="column_definition">
4317        <structfield>null_frac</structfield> <type>float4</type>
4318       </para>
4319       <para>
4320        Fraction of expression entries that are null
4321       </para></entry>
4322      </row>
4323
4324      <row>
4325       <entry role="catalog_table_entry"><para role="column_definition">
4326        <structfield>avg_width</structfield> <type>int4</type>
4327       </para>
4328       <para>
4329        Average width in bytes of expression's entries
4330       </para></entry>
4331      </row>
4332
4333      <row>
4334       <entry role="catalog_table_entry"><para role="column_definition">
4335        <structfield>n_distinct</structfield> <type>float4</type>
4336       </para>
4337       <para>
4338        If greater than zero, the estimated number of distinct values in the
4339        expression.  If less than zero, the negative of the number of distinct
4340        values divided by the number of rows.  (The negated form is used when
4341        <command>ANALYZE</command> believes that the number of distinct values is
4342        likely to increase as the table grows; the positive form is used when
4343        the expression seems to have a fixed number of possible values.)  For
4344        example, -1 indicates a unique expression in which the number of distinct
4345        values is the same as the number of rows.
4346       </para></entry>
4347      </row>
4348
4349      <row>
4350       <entry role="catalog_table_entry"><para role="column_definition">
4351        <structfield>most_common_vals</structfield> <type>anyarray</type>
4352       </para>
4353       <para>
4354        A list of the most common values in the expression. (Null if
4355        no values seem to be more common than any others.)
4356       </para></entry>
4357      </row>
4358
4359      <row>
4360       <entry role="catalog_table_entry"><para role="column_definition">
4361        <structfield>most_common_freqs</structfield> <type>float4[]</type>
4362       </para>
4363       <para>
4364        A list of the frequencies of the most common values,
4365        i.e., number of occurrences of each divided by total number of rows.
4366        (Null when <structfield>most_common_vals</structfield> is.)
4367       </para></entry>
4368      </row>
4369
4370      <row>
4371       <entry role="catalog_table_entry"><para role="column_definition">
4372        <structfield>histogram_bounds</structfield> <type>anyarray</type>
4373       </para>
4374       <para>
4375        A list of values that divide the expression's values into groups of
4376        approximately equal population.  The values in
4377        <structfield>most_common_vals</structfield>, if present, are omitted from this
4378        histogram calculation.  (This expression is null if the expression data type
4379        does not have a <literal>&lt;</literal> operator or if the
4380        <structfield>most_common_vals</structfield> list accounts for the entire
4381        population.)
4382       </para></entry>
4383      </row>
4384
4385      <row>
4386       <entry role="catalog_table_entry"><para role="column_definition">
4387        <structfield>correlation</structfield> <type>float4</type>
4388       </para>
4389       <para>
4390        Statistical correlation between physical row ordering and
4391        logical ordering of the expression values.  This ranges from -1 to +1.
4392        When the value is near -1 or +1, an index scan on the expression will
4393        be estimated to be cheaper than when it is near zero, due to reduction
4394        of random access to the disk.  (This expression is null if the expression's
4395        data type does not have a <literal>&lt;</literal> operator.)
4396       </para></entry>
4397      </row>
4398
4399      <row>
4400       <entry role="catalog_table_entry"><para role="column_definition">
4401        <structfield>most_common_elems</structfield> <type>anyarray</type>
4402       </para>
4403       <para>
4404        A list of non-null element values most often appearing within values of
4405        the expression. (Null for scalar types.)
4406       </para></entry>
4407      </row>
4408
4409      <row>
4410       <entry role="catalog_table_entry"><para role="column_definition">
4411        <structfield>most_common_elem_freqs</structfield> <type>float4[]</type>
4412       </para>
4413       <para>
4414        A list of the frequencies of the most common element values, i.e., the
4415        fraction of rows containing at least one instance of the given value.
4416        Two or three additional values follow the per-element frequencies;
4417        these are the minimum and maximum of the preceding per-element
4418        frequencies, and optionally the frequency of null elements.
4419        (Null when <structfield>most_common_elems</structfield> is.)
4420       </para></entry>
4421      </row>
4422
4423      <row>
4424       <entry role="catalog_table_entry"><para role="column_definition">
4425        <structfield>elem_count_histogram</structfield> <type>float4[]</type>
4426       </para>
4427       <para>
4428        A histogram of the counts of distinct non-null element values within the
4429        values of the expression, followed by the average number of distinct
4430        non-null elements.  (Null for scalar types.)
4431       </para></entry>
4432      </row>
4433     </tbody>
4434    </tgroup>
4435   </table>
4436
4437   <para>
4438    The maximum number of entries in the array fields can be controlled on a
4439    column-by-column basis using the <link linkend="sql-altertable"><command>ALTER
4440    TABLE SET STATISTICS</command></link> command, or globally by setting the
4441    <xref linkend="guc-default-statistics-target"/> run-time parameter.
4442   </para>
4443
4444  </sect1>
4445
4446  <sect1 id="view-pg-tables">
4447   <title><structname>pg_tables</structname></title>
4448
4449   <indexterm zone="view-pg-tables">
4450    <primary>pg_tables</primary>
4451   </indexterm>
4452
4453   <para>
4454    The view <structname>pg_tables</structname> provides access to
4455    useful information about each table in the database.
4456   </para>
4457
4458   <table>
4459    <title><structname>pg_tables</structname> Columns</title>
4460    <tgroup cols="1">
4461     <thead>
4462      <row>
4463       <entry role="catalog_table_entry"><para role="column_definition">
4464        Column Type
4465       </para>
4466       <para>
4467        Description
4468       </para></entry>
4469      </row>
4470     </thead>
4471
4472     <tbody>
4473      <row>
4474       <entry role="catalog_table_entry"><para role="column_definition">
4475        <structfield>schemaname</structfield> <type>name</type>
4476        (references <link linkend="catalog-pg-namespace"><structname>pg_namespace</structname></link>.<structfield>nspname</structfield>)
4477       </para>
4478       <para>
4479        Name of schema containing table
4480       </para></entry>
4481      </row>
4482
4483      <row>
4484       <entry role="catalog_table_entry"><para role="column_definition">
4485        <structfield>tablename</structfield> <type>name</type>
4486        (references <link linkend="catalog-pg-class"><structname>pg_class</structname></link>.<structfield>relname</structfield>)
4487       </para>
4488       <para>
4489        Name of table
4490       </para></entry>
4491      </row>
4492
4493      <row>
4494       <entry role="catalog_table_entry"><para role="column_definition">
4495        <structfield>tableowner</structfield> <type>name</type>
4496        (references <link linkend="catalog-pg-authid"><structname>pg_authid</structname></link>.<structfield>rolname</structfield>)
4497       </para>
4498       <para>
4499        Name of table's owner
4500       </para></entry>
4501      </row>
4502
4503      <row>
4504       <entry role="catalog_table_entry"><para role="column_definition">
4505        <structfield>tablespace</structfield> <type>name</type>
4506        (references <link linkend="catalog-pg-tablespace"><structname>pg_tablespace</structname></link>.<structfield>spcname</structfield>)
4507       </para>
4508       <para>
4509        Name of tablespace containing table (null if default for database)
4510       </para></entry>
4511      </row>
4512
4513      <row>
4514       <entry role="catalog_table_entry"><para role="column_definition">
4515        <structfield>hasindexes</structfield> <type>bool</type>
4516        (references <link linkend="catalog-pg-class"><structname>pg_class</structname></link>.<structfield>relhasindex</structfield>)
4517       </para>
4518       <para>
4519        True if table has (or recently had) any indexes
4520       </para></entry>
4521      </row>
4522
4523      <row>
4524       <entry role="catalog_table_entry"><para role="column_definition">
4525        <structfield>hasrules</structfield> <type>bool</type>
4526        (references <link linkend="catalog-pg-class"><structname>pg_class</structname></link>.<structfield>relhasrules</structfield>)
4527       </para>
4528       <para>
4529        True if table has (or once had) rules
4530       </para></entry>
4531      </row>
4532
4533      <row>
4534       <entry role="catalog_table_entry"><para role="column_definition">
4535        <structfield>hastriggers</structfield> <type>bool</type>
4536        (references <link linkend="catalog-pg-class"><structname>pg_class</structname></link>.<structfield>relhastriggers</structfield>)
4537       </para>
4538       <para>
4539        True if table has (or once had) triggers
4540       </para></entry>
4541      </row>
4542
4543      <row>
4544       <entry role="catalog_table_entry"><para role="column_definition">
4545        <structfield>rowsecurity</structfield> <type>bool</type>
4546        (references <link linkend="catalog-pg-class"><structname>pg_class</structname></link>.<structfield>relrowsecurity</structfield>)
4547       </para>
4548       <para>
4549        True if row security is enabled on the table
4550       </para></entry>
4551      </row>
4552     </tbody>
4553    </tgroup>
4554   </table>
4555
4556  </sect1>
4557
4558  <sect1 id="view-pg-timezone-abbrevs">
4559   <title><structname>pg_timezone_abbrevs</structname></title>
4560
4561   <indexterm zone="view-pg-timezone-abbrevs">
4562    <primary>pg_timezone_abbrevs</primary>
4563   </indexterm>
4564
4565   <para>
4566    The view <structname>pg_timezone_abbrevs</structname> provides a list
4567    of time zone abbreviations that are currently recognized by the datetime
4568    input routines.  The contents of this view change when the
4569    <xref linkend="guc-timezone"/> or
4570    <xref linkend="guc-timezone-abbreviations"/> run-time parameters are
4571    modified.
4572   </para>
4573
4574   <table>
4575    <title><structname>pg_timezone_abbrevs</structname> Columns</title>
4576    <tgroup cols="1">
4577     <thead>
4578      <row>
4579       <entry role="catalog_table_entry"><para role="column_definition">
4580        Column Type
4581       </para>
4582       <para>
4583        Description
4584       </para></entry>
4585      </row>
4586     </thead>
4587
4588     <tbody>
4589      <row>
4590       <entry role="catalog_table_entry"><para role="column_definition">
4591        <structfield>abbrev</structfield> <type>text</type>
4592       </para>
4593       <para>
4594        Time zone abbreviation
4595       </para></entry>
4596      </row>
4597
4598      <row>
4599       <entry role="catalog_table_entry"><para role="column_definition">
4600        <structfield>utc_offset</structfield> <type>interval</type>
4601       </para>
4602       <para>
4603        Offset from UTC (positive means east of Greenwich)
4604       </para></entry>
4605      </row>
4606
4607      <row>
4608       <entry role="catalog_table_entry"><para role="column_definition">
4609        <structfield>is_dst</structfield> <type>bool</type>
4610       </para>
4611       <para>
4612        True if this is a daylight-savings abbreviation
4613       </para></entry>
4614      </row>
4615     </tbody>
4616    </tgroup>
4617   </table>
4618
4619   <para>
4620    While most timezone abbreviations represent fixed offsets from UTC,
4621    there are some that have historically varied in value
4622    (see <xref linkend="datetime-config-files"/> for more information).
4623    In such cases this view presents their current meaning.
4624   </para>
4625
4626  </sect1>
4627
4628  <sect1 id="view-pg-timezone-names">
4629   <title><structname>pg_timezone_names</structname></title>
4630
4631   <indexterm zone="view-pg-timezone-names">
4632    <primary>pg_timezone_names</primary>
4633   </indexterm>
4634
4635   <para>
4636    The view <structname>pg_timezone_names</structname> provides a list
4637    of time zone names that are recognized by <command>SET TIMEZONE</command>,
4638    along with their associated abbreviations, UTC offsets,
4639    and daylight-savings status.  (Technically,
4640    <productname>PostgreSQL</productname> does not use UTC because leap
4641    seconds are not handled.)
4642    Unlike the abbreviations shown in <link
4643    linkend="view-pg-timezone-abbrevs"><structname>pg_timezone_abbrevs</structname></link>, many of these names imply a set of daylight-savings transition
4644    date rules.  Therefore, the associated information changes across local DST
4645    boundaries.  The displayed information is computed based on the current
4646    value of <function>CURRENT_TIMESTAMP</function>.
4647   </para>
4648
4649   <table>
4650    <title><structname>pg_timezone_names</structname> Columns</title>
4651    <tgroup cols="1">
4652     <thead>
4653      <row>
4654       <entry role="catalog_table_entry"><para role="column_definition">
4655        Column Type
4656       </para>
4657       <para>
4658        Description
4659       </para></entry>
4660      </row>
4661     </thead>
4662
4663     <tbody>
4664      <row>
4665       <entry role="catalog_table_entry"><para role="column_definition">
4666        <structfield>name</structfield> <type>text</type>
4667       </para>
4668       <para>
4669        Time zone name
4670       </para></entry>
4671      </row>
4672
4673      <row>
4674       <entry role="catalog_table_entry"><para role="column_definition">
4675        <structfield>abbrev</structfield> <type>text</type>
4676       </para>
4677       <para>
4678        Time zone abbreviation
4679       </para></entry>
4680      </row>
4681
4682      <row>
4683       <entry role="catalog_table_entry"><para role="column_definition">
4684        <structfield>utc_offset</structfield> <type>interval</type>
4685       </para>
4686       <para>
4687        Offset from UTC (positive means east of Greenwich)
4688       </para></entry>
4689      </row>
4690
4691      <row>
4692       <entry role="catalog_table_entry"><para role="column_definition">
4693        <structfield>is_dst</structfield> <type>bool</type>
4694       </para>
4695       <para>
4696        True if currently observing daylight savings
4697       </para></entry>
4698      </row>
4699     </tbody>
4700    </tgroup>
4701   </table>
4702
4703  </sect1>
4704
4705  <sect1 id="view-pg-user">
4706   <title><structname>pg_user</structname></title>
4707
4708   <indexterm zone="view-pg-user">
4709    <primary>pg_user</primary>
4710   </indexterm>
4711
4712   <para>
4713    The view <structname>pg_user</structname> provides access to
4714    information about database users.  This is simply a publicly
4715    readable view of
4716    <link linkend="view-pg-shadow"><structname>pg_shadow</structname></link>
4717    that blanks out the password field.
4718   </para>
4719
4720   <table>
4721    <title><structname>pg_user</structname> Columns</title>
4722    <tgroup cols="1">
4723     <thead>
4724      <row>
4725       <entry role="catalog_table_entry"><para role="column_definition">
4726        Column Type
4727       </para>
4728       <para>
4729        Description
4730       </para></entry>
4731      </row>
4732     </thead>
4733
4734     <tbody>
4735      <row>
4736       <entry role="catalog_table_entry"><para role="column_definition">
4737        <structfield>usename</structfield> <type>name</type>
4738       </para>
4739       <para>
4740        User name
4741       </para></entry>
4742      </row>
4743
4744      <row>
4745       <entry role="catalog_table_entry"><para role="column_definition">
4746        <structfield>usesysid</structfield> <type>oid</type>
4747       </para>
4748       <para>
4749        ID of this user
4750       </para></entry>
4751      </row>
4752
4753      <row>
4754       <entry role="catalog_table_entry"><para role="column_definition">
4755        <structfield>usecreatedb</structfield> <type>bool</type>
4756       </para>
4757       <para>
4758        User can create databases
4759       </para></entry>
4760      </row>
4761
4762      <row>
4763       <entry role="catalog_table_entry"><para role="column_definition">
4764        <structfield>usesuper</structfield> <type>bool</type>
4765       </para>
4766       <para>
4767        User is a superuser
4768       </para></entry>
4769      </row>
4770
4771      <row>
4772       <entry role="catalog_table_entry"><para role="column_definition">
4773        <structfield>userepl</structfield> <type>bool</type>
4774       </para>
4775       <para>
4776        User can initiate streaming replication and put the system in and
4777        out of backup mode.
4778       </para></entry>
4779      </row>
4780
4781      <row>
4782       <entry role="catalog_table_entry"><para role="column_definition">
4783        <structfield>usebypassrls</structfield> <type>bool</type>
4784       </para>
4785       <para>
4786        User bypasses every row-level security policy, see
4787        <xref linkend="ddl-rowsecurity"/> for more information.
4788       </para></entry>
4789      </row>
4790
4791      <row>
4792       <entry role="catalog_table_entry"><para role="column_definition">
4793        <structfield>passwd</structfield> <type>text</type>
4794       </para>
4795       <para>
4796        Not the password (always reads as <literal>********</literal>)
4797       </para></entry>
4798      </row>
4799
4800      <row>
4801       <entry role="catalog_table_entry"><para role="column_definition">
4802        <structfield>valuntil</structfield> <type>timestamptz</type>
4803       </para>
4804       <para>
4805        Password expiry time (only used for password authentication)
4806       </para></entry>
4807      </row>
4808
4809      <row>
4810       <entry role="catalog_table_entry"><para role="column_definition">
4811        <structfield>useconfig</structfield> <type>text[]</type>
4812       </para>
4813       <para>
4814        Session defaults for run-time configuration variables
4815       </para></entry>
4816      </row>
4817     </tbody>
4818    </tgroup>
4819   </table>
4820
4821  </sect1>
4822
4823  <sect1 id="view-pg-user-mappings">
4824   <title><structname>pg_user_mappings</structname></title>
4825
4826   <indexterm zone="view-pg-user-mappings">
4827    <primary>pg_user_mappings</primary>
4828   </indexterm>
4829
4830   <para>
4831    The view <structname>pg_user_mappings</structname> provides access
4832    to information about user mappings.  This is essentially a publicly
4833    readable view of
4834    <link linkend="catalog-pg-user-mapping"><structname>pg_user_mapping</structname></link>
4835    that leaves out the options field if the user has no rights to use
4836    it.
4837   </para>
4838
4839   <table>
4840    <title><structname>pg_user_mappings</structname> Columns</title>
4841    <tgroup cols="1">
4842     <thead>
4843      <row>
4844       <entry role="catalog_table_entry"><para role="column_definition">
4845        Column Type
4846       </para>
4847       <para>
4848        Description
4849       </para></entry>
4850      </row>
4851     </thead>
4852
4853     <tbody>
4854      <row>
4855       <entry role="catalog_table_entry"><para role="column_definition">
4856        <structfield>umid</structfield> <type>oid</type>
4857        (references <link linkend="catalog-pg-user-mapping"><structname>pg_user_mapping</structname></link>.<structfield>oid</structfield>)
4858       </para>
4859       <para>
4860        OID of the user mapping
4861       </para></entry>
4862      </row>
4863
4864      <row>
4865       <entry role="catalog_table_entry"><para role="column_definition">
4866        <structfield>srvid</structfield> <type>oid</type>
4867        (references <link linkend="catalog-pg-foreign-server"><structname>pg_foreign_server</structname></link>.<structfield>oid</structfield>)
4868       </para>
4869       <para>
4870        The OID of the foreign server that contains this mapping
4871       </para></entry>
4872      </row>
4873
4874      <row>
4875       <entry role="catalog_table_entry"><para role="column_definition">
4876        <structfield>srvname</structfield> <type>name</type>
4877        (references <link linkend="catalog-pg-foreign-server"><structname>pg_foreign_server</structname></link>.<structfield>srvname</structfield>)
4878       </para>
4879       <para>
4880        Name of the foreign server
4881       </para></entry>
4882      </row>
4883
4884      <row>
4885       <entry role="catalog_table_entry"><para role="column_definition">
4886        <structfield>umuser</structfield> <type>oid</type>
4887        (references <link linkend="catalog-pg-authid"><structname>pg_authid</structname></link>.<structfield>oid</structfield>)
4888       </para>
4889       <para>
4890        OID of the local role being mapped, or zero if the user mapping is public
4891       </para></entry>
4892      </row>
4893
4894      <row>
4895       <entry role="catalog_table_entry"><para role="column_definition">
4896        <structfield>usename</structfield> <type>name</type>
4897       </para>
4898       <para>
4899        Name of the local user to be mapped
4900       </para></entry>
4901      </row>
4902
4903      <row>
4904       <entry role="catalog_table_entry"><para role="column_definition">
4905        <structfield>umoptions</structfield> <type>text[]</type>
4906       </para>
4907       <para>
4908        User mapping specific options, as <quote>keyword=value</quote> strings
4909       </para></entry>
4910      </row>
4911     </tbody>
4912    </tgroup>
4913   </table>
4914
4915   <para>
4916    To protect password information stored as a user mapping option,
4917    the <structfield>umoptions</structfield> column will read as null
4918    unless one of the following applies:
4919    <itemizedlist>
4920     <listitem>
4921      <para>
4922       current user is the user being mapped, and owns the server or
4923       holds <literal>USAGE</literal> privilege on it
4924      </para>
4925     </listitem>
4926     <listitem>
4927      <para>
4928       current user is the server owner and mapping is for <literal>PUBLIC</literal>
4929      </para>
4930     </listitem>
4931     <listitem>
4932      <para>
4933       current user is a superuser
4934      </para>
4935     </listitem>
4936    </itemizedlist>
4937   </para>
4938
4939  </sect1>
4940
4941
4942  <sect1 id="view-pg-views">
4943   <title><structname>pg_views</structname></title>
4944
4945   <indexterm zone="view-pg-views">
4946    <primary>pg_views</primary>
4947   </indexterm>
4948
4949   <para>
4950    The view <structname>pg_views</structname> provides access to
4951    useful information about each view in the database.
4952   </para>
4953
4954   <table>
4955    <title><structname>pg_views</structname> Columns</title>
4956    <tgroup cols="1">
4957     <thead>
4958      <row>
4959       <entry role="catalog_table_entry"><para role="column_definition">
4960        Column Type
4961       </para>
4962       <para>
4963        Description
4964       </para></entry>
4965      </row>
4966     </thead>
4967
4968     <tbody>
4969      <row>
4970       <entry role="catalog_table_entry"><para role="column_definition">
4971        <structfield>schemaname</structfield> <type>name</type>
4972        (references <link linkend="catalog-pg-namespace"><structname>pg_namespace</structname></link>.<structfield>nspname</structfield>)
4973       </para>
4974       <para>
4975        Name of schema containing view
4976       </para></entry>
4977      </row>
4978
4979      <row>
4980       <entry role="catalog_table_entry"><para role="column_definition">
4981        <structfield>viewname</structfield> <type>name</type>
4982        (references <link linkend="catalog-pg-class"><structname>pg_class</structname></link>.<structfield>relname</structfield>)
4983       </para>
4984       <para>
4985        Name of view
4986       </para></entry>
4987      </row>
4988
4989      <row>
4990       <entry role="catalog_table_entry"><para role="column_definition">
4991        <structfield>viewowner</structfield> <type>name</type>
4992        (references <link linkend="catalog-pg-authid"><structname>pg_authid</structname></link>.<structfield>rolname</structfield>)
4993       </para>
4994       <para>
4995        Name of view's owner
4996       </para></entry>
4997      </row>
4998
4999      <row>
5000       <entry role="catalog_table_entry"><para role="column_definition">
5001        <structfield>definition</structfield> <type>text</type>
5002       </para>
5003       <para>
5004        View definition (a reconstructed <xref linkend="sql-select"/> query)
5005       </para></entry>
5006      </row>
5007     </tbody>
5008    </tgroup>
5009   </table>
5010  </sect1>
5011
5012
5013  <sect1 id="view-pg-wait-events">
5014   <title><structname>pg_wait_events</structname></title>
5015
5016   <indexterm zone="view-pg-wait-events">
5017    <primary>pg_wait_events</primary>
5018   </indexterm>
5019
5020   <para>
5021    The view <structname>pg_wait_events</structname> provides description about the
5022    wait events.
5023   </para>
5024
5025   <table>
5026    <title><structname>pg_wait_events</structname> Columns</title>
5027    <tgroup cols="1">
5028     <thead>
5029      <row>
5030       <entry role="catalog_table_entry"><para role="column_definition">
5031        Column Type
5032       </para>
5033       <para>
5034        Description
5035       </para></entry>
5036      </row>
5037     </thead>
5038
5039     <tbody>
5040      <row>
5041       <entry role="catalog_table_entry"><para role="column_definition">
5042        <structfield>type</structfield> <type>text</type>
5043       </para>
5044       <para>
5045        Wait event type
5046       </para></entry>
5047      </row>
5048
5049      <row>
5050       <entry role="catalog_table_entry"><para role="column_definition">
5051        <structfield>name</structfield> <type>text</type>
5052       </para>
5053       <para>
5054        Wait event name
5055       </para></entry>
5056      </row>
5057
5058      <row>
5059       <entry role="catalog_table_entry"><para role="column_definition">
5060        <structfield>description</structfield> <type>text</type>
5061       </para>
5062       <para>
5063        Wait event description
5064       </para></entry>
5065      </row>
5066     </tbody>
5067    </tgroup>
5068   </table>
5069  </sect1>
5070
5071 </chapter>