Document PGSQL

Co-authored-by: KentarouTakeda <takeda@youmind.jp>

Author: Girgias

reference/pdo_pgsql/pdo/pgsql/escapeidentifier.xml

@@ -2,7 +2,7 @@
 <refentry xml:id="pdo-pgsql.escapeidentifier" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>Pdo\Pgsql::escapeIdentifier</refname>
-  <refpurpose>Description</refpurpose>
+  <refpurpose>Escapes a string for use as an SQL identifier</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
@@ -13,7 +13,11 @@
   </methodsynopsis>
   &warn.undocumented.func;
   <simpara>
-   Description.
+   Escapes a string for use as an SQL identifier, such as a table, column, or function name.
+   This is useful when a user-supplied identifier might contain special characters
+   that would otherwise not be interpreted as part of the identifier by the SQL parser,
+   or when the identifier might contain upper case characters
+   whose case should be preserved.
   </simpara>
  </refsect1>
 
@@ -24,7 +28,7 @@
     <term><parameter>input</parameter></term>
     <listitem>
      <simpara>
-      Description.
+      A <type>string</type> containing text to be escaped.
      </simpara>
     </listitem>
    </varlistentry>
@@ -34,15 +38,7 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <simpara>
-   Description.
-  </simpara>
- </refsect1>
-
- <refsect1 role="errors">
-  &reftitle.errors;
-  <simpara>
-   When does this function issue <constant>E_*</constant> level errors,
-   and/or throw <exceptionname>Exception</exceptionname>s.
+   A <type>string</type> containing the escaped data.
   </simpara>
  </refsect1>
 
@@ -56,14 +52,34 @@
    <programlisting role="php">
 <![CDATA[
 <?php
-echo "Code example";
+$pdo = new Pdo\Pgsql('pgsql:dbname=test host=localhost', $user, $pass);
+
+$unescapedTableName = 'UnescapedTableName';
+$pdo->exec("CREATE TABLE $unescapedTableName ()");
+
+$escapedTableName = $pdo->escapeIdentifier('EscapedTableName');
+$pdo->exec("CREATE TABLE $escapedTableName ()");
+
+$statement = $pdo->query(
+  "SELECT relname FROM pg_stat_user_tables WHERE relname ilike '%tablename'"
+);
+
+var_export($statement->fetchAll(PDO::FETCH_COLUMN, 0));
+
+$tableNameWithSymbols = 'Table-Name-With-Symbols';
+$pdo->exec("CREATE TABLE $tableNameWithSymbols ()");
 ?>
 ]]>
    </programlisting>
-   &example.outputs;
+   &example.outputs.similar;
    <screen>
 <![CDATA[
-Code example
+array (
+  0 => 'unescapedtablename',
+  1 => 'EscapedTableName',
+)
+Fatal error: Uncaught PDOException: SQLSTATE[42601]: Syntax error: 7 ERROR:  syntax error at or near "Table"
+LINE 1: CREATE TABLE Table-Name-With-Symbols ()
 ]]>
    </screen>
   </example>

reference/pdo_pgsql/pdo/pgsql/getpid.xml

@@ -2,7 +2,7 @@
 <refentry xml:id="pdo-pgsql.getpid" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
   <refname>Pdo\Pgsql::getPid</refname>
-  <refpurpose>Get the server PID</refpurpose>
+  <refpurpose>Get the PID of the backend process handling this connection</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
@@ -12,7 +12,9 @@
    <void/>
   </methodsynopsis>
   <simpara>
-   Returns the server's PID.
+   Returns the PID of the backend process handling this connection.
+   Note that the PID belongs to a process executing on the database server host,
+   not the local host.
   </simpara>
  </refsect1>
 
@@ -24,7 +26,7 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <simpara>
-   Returns the server's PID as an <type>int</type>.
+   Returns the PID as an <type>int</type>.
   </simpara>
  </refsect1>
 </refentry>

reference/pdo_pgsql/pdo/pgsql/lobcreate.xml

@@ -13,7 +13,7 @@
   </methodsynopsis>
   <simpara>
    <methodname>Pdo\Pgsql::lobCreate</methodname> creates a large object
-   and returns the ODI which refers to it.
+   and returns the OID which refers to it.
    It can be opened to read or write data with
    <methodname>Pdo\Pgsql::lobOpen</methodname>.
   </simpara>
@@ -26,10 +26,11 @@
   <simpara>
    Large objects are cumbersome to use.
    Indeed, it is required that <methodname>Pdo\Pgsql::lobUnlink</methodname>
-   is called prior to deleting the last row referencing the OID in the whole database.
+   is called prior to deleting the last row referencing the OID in the entire database;
+   otherwise, unreferenced large objects will remain on the server indefinitely.
    Moreover, large objects have no access controls.
    An alternative is the bytea column type, which can be up to 1GB in size,
-   and this row type transparently manage the storage for optimal row size.
+   and this column type transparently manages the storage for optimal row size.
   </simpara>
   <note>
    <simpara>

reference/pdo_pgsql/pdo/pgsql/setnoticecallback.xml

@@ -2,7 +2,7 @@
 <refentry xml:id="pdo-pgsql.setnoticecallback" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>Pdo\Pgsql::setNoticeCallback</refname>
-  <refpurpose>Description</refpurpose>
+  <refpurpose>Set a callback to handle notice and warning messages generated by the backend</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
@@ -11,7 +11,6 @@
    <modifier>public</modifier> <type>void</type><methodname>Pdo\Pgsql::setNoticeCallback</methodname>
    <methodparam><type class="union"><type>callable</type><type>null</type></type><parameter>callback</parameter></methodparam>
   </methodsynopsis>
-  &warn.undocumented.func;
   <simpara>
    Description.
   </simpara>
@@ -24,8 +23,25 @@
     <term><parameter>callback</parameter></term>
     <listitem>
      <simpara>
-      Description.
+      If &null; is passed, the handler is reset to its default state.
+      Otherwise, the handler is a callback with the following signature:
      </simpara>
+
+     <methodsynopsis>
+      <type>void</type><methodname><replaceable>handler</replaceable></methodname>
+      <methodparam><type>string</type><parameter>message</parameter></methodparam>
+     </methodsynopsis>
+
+     <variablelist>
+      <varlistentry>
+       <term><parameter>message</parameter></term>
+       <listitem>
+        <simpara>
+         A message generated by the backend.
+        </simpara>
+       </listitem>
+      </varlistentry>
+     <variablelist>
     </listitem>
    </varlistentry>
   </variablelist>
@@ -38,55 +54,36 @@
   </simpara>
  </refsect1>
 
- <refsect1 role="errors">
-  &reftitle.errors;
-  <simpara>
-   When does this function issue <constant>E_*</constant> level errors,
-   and/or throw <exceptionname>Exception</exceptionname>s.
-  </simpara>
- </refsect1>
-
  <refsect1 role="examples">
   &reftitle.examples;
   <example xml:id="pdo-pgsql.setnoticecallback.example.basic">
    <title><methodname>Pdo\Pgsql::setNoticeCallback</methodname> example</title>
-   <simpara>
-    Description.
-   </simpara>
    <programlisting role="php">
 <![CDATA[
 <?php
-echo "Code example";
+<?php
+$pdo = new Pdo\Pgsql('pgsql:dbname=test host=localhost', $user, $pass);
+
+$pdo->exec('CREATE TABLE parent(id int primary key)');
+$pdo->exec('CREATE TABLE child(id int references parent)');
+
+$pdo->setNoticeCallback(function ($message) {
+    echo $message;
+});
+
+$pdo->exec('TRUNCATE parent CASCADE');
 ?>
 ]]>
    </programlisting>
-   &example.outputs;
+   &example.outputs.similar;
    <screen>
 <![CDATA[
-Code example
+NOTICE:  truncate cascades to table "child"
 ]]>
    </screen>
   </example>
  </refsect1>
 
- <refsect1 role="notes">
-  &reftitle.notes;
-  <note>
-   <simpara>
-    Any notes that don't fit anywhere else should go here.
-   </simpara>
-  </note>
- </refsect1>
-
- <refsect1 role="seealso">
-  &reftitle.seealso;
-  <simplelist>
-   <member><methodname>ClassName::otherMethodName</methodname></member>
-   <member><function>some_function</function></member>
-   <!-- <member><link linkend="some.id.chunk.to.link">something appendix</link></member> -->
-  </simplelist>
- </refsect1>
-
 </refentry>
 <!-- Keep this comment at the end of the file
 Local variables: