Annotation of embedaddon/php/ext/pgsql/README, revision 1.1.1.1

1.1       misho       1: ==== About This Module ===
                      2: PostgreSQL module provides access to PostgreSQL server from 
                      3: PHP script. This module uses PostgreSQL C client lib called libpq.
                      4: It is important that you use libpq that is later than backend 
                      5: (PostgreSQL Server) version. Otherwise, you may experience 
                      6: strange problems. 
                      7: 
                      8: Please send e-mail to yohgaki@php.net if you have comments for 
                      9: pgsql module. I appreciate your feedback.
                     10: 
                     11: ==== API Change ===
                     12: Older PHP than 4.2.0, pg_loimport()/pg_loexport() connection 
                     13: parameter as last parameter, not like other functions. From 4.2.0,
                     14: connection parameter became 1st parameter. Old syntax is preserved, 
                     15: but it will raise NOTICE error message.
                     16: 
                     17: pg_connect()/pg_pconnect() has obsolete multi parameter syntax.
                     18: This syntax will be deleted in 4.3.0 or later.
                     19: 
                     20: Omitting connectin parameter is NOT recommended. Connection 
                     21: parameter may be required for future PHP version. Specify connection
                     22: always if you don't want to rewrite code when it is changed.
                     23: 
                     24: ==== Function Name Change ==== 
                     25: Function names are going to be changed to confirm coding
                     26: standard. MySQL module has been done this already. Function names will
                     27: be changed as follows.
                     28: 
                     29: pg_errormessage -> pg_error_message
                     30: pg_cmdtuples    -> pg_affected_rows
                     31: pg_fieldnum     -> pg_field_num
                     32: and so on. Except pg_cmdtuples, under scores '_'  will be added to 
                     33: names. 
                     34: 
                     35: Older names will become aliases of new functions for backward
                     36: compatibility.
                     37: 
                     38: Manual will be updated when this change is commited to CVS source.
                     39: 
                     40: ==== Configure Option Notes ====
                     41: You cannot specify PostgreSQL source directly to build PostgreSQL
                     42: module with specific version. You need to install PostgreSQL 
                     43: somewhere in your system to build PHP with PostgreSQL support.
                     44: 
                     45: ==== Note For PostgreSQL 7.2 ====
                     46: I've tested upto 7.2.2.
                     47: 
                     48: ==== TODO List ===
                     49: Make pg_convert() smater. 
                     50:  - Better regex
                     51:  - User defiend type support
                     52: Support async connection.
                     53: 
                     54: ==== Experimental Functions =====
                     55: 
                     56: WARNING: API/behavior may be changed without notice.
                     57: 
                     58: Async query can improve application performance
                     59: *significantly*. Please test and report any failure to
                     60: yohgaki@php.net 
                     61: 
                     62: There are some cases that async functions blocks process. Even if
                     63: process was blocked, functions work as expected. (except it blocks
                     64: process) These are cases that process is blocked. Refer to libpq
                     65: manual for details. Followings are common cases that async functions
                     66: are blocked.
                     67: 
                     68:  - If libpq is compile with USE_SSL, some async functions are 
                     69:    blocked.
                     70:  - If libpq under Win32 is *NOT* compiled with 
                     71:    WIN32_NON_BLOCKING_CONNECTIONS, non-blocking connection will block. 
                     72: 
                     73: Async function may also block if you have not retrive result and 
                     74: send or execute query. If there is result left on connection, 
                     75: pg_send_query() will block until last query is completed.
                     76: 
                     77: Garbages are cleaned when resource is cleaned up. There is no need to
                     78: clean up query result if it is not needed.
                     79: 
                     80: Please refer to libpq manual or source for details.
                     81: These functions are *NOT* supposed to be documented, yet.
                     82: API may be changed.
                     83: 
                     84: NOTE: These functions are added in PHP 4.2.0 unless they are mentioned.
                     85: 
                     86: -------------------------------------------------------------------
                     87: bool pg_send_query(resource connection, string query) 
                     88: 
                     89: Sends async query to backend. Result may be retrieved with
                     90: pg_get_result(). It does not accept multiple query, but it accepts
                     91: multiple queries at once. Each result may be retrieved separately by
                     92: pg_get_result().
                     93: 
                     94: --------------------------------------------------------------------
                     95: bool pg_cancel_query(resource connection) 
                     96: 
                     97: Cancels currently executing async query already sent to PostgreSQL
                     98: server. This function is useful when user request time consuming query
                     99: to server. It cannot cancel query executed by pg_exec(), since
                    100: pg_exec() is a blocking function.
                    101: 
                    102: --------------------------------------------------------------------
                    103: resource pg_get_result(resource conn) 
                    104: 
                    105: Gets pgsql query result resource. Returned value can be fed to
                    106: pg_result()/pg_fetch_*(). pg_get_result() may block if result is not
                    107: ready to be retrived. Use pg_is_busy() to check result is ready to be
                    108: retrieved or not. If multiple query is sent to backend, it may be
                    109: retrieved one by one using pg_get_result(). If there is no result left
                    110: in connection, it returns false.
                    111: 
                    112: --------------------------------------------------------------------
                    113: bool pg_connection_busy(resource connection)
                    114: 
                    115: Returns connections is executing query or not. 
                    116: 
                    117: --------------------------------------------------------------------
                    118: int pg_connection_status(resource connection)
                    119: 
                    120: Gets connection status. It returns PGSQL_CONNECTION_OK or
                    121: PGSQL_CONNECTION_BAD.
                    122: 
                    123: --------------------------------------------------------------------
                    124: bool pg_connection_reset(resource connection)
                    125: 
                    126: Resets communication port to Postgresql server using the same
                    127: connection parameter. It's useful for error recovery.
                    128: 
                    129: --------------------------------------------------------------------
                    130: string pg_result_error(resource result)
                    131: 
                    132: Get error message associated with result 
                    133: 
                    134: --------------------------------------------------------------------
                    135: int pg_result_status(resource result)
                    136: 
                    137: Get status of query result
                    138: 
                    139: --------------------------------------------------------------------
                    140: 
                    141: 
                    142: Copy functions
                    143: 
                    144: --------------------------------------------------------------------
                    145: mixed pg_copy_to(int connection_id, string table_name,
                    146:                   [, string delim [, string null_as]])
                    147: 
                    148: nt pg_copy_from(int connection_id, string table_name, array rows
                    149:                     [, string delim [, string null_as]])
                    150: 
                    151: --------------------------------------------------------------------
                    152: 
                    153: Utility functions
                    154: 
                    155: --------------------------------------------------------------------
                    156: string pg_escape_string(string data)
                    157: Escape string or binary for SQL statemen (7.2 or later)
                    158: 
                    159: 
                    160: string pg_escape_bytea(string data)
                    161: Escape string or binary for SQL statement (7.2 or later)
                    162: 
                    163: --------------------------------------------------------------------
                    164: 
                    165: Large Object Functions
                    166: 
                    167: --------------------------------------------------------------------
                    168: int pg_lo_tell(resource large_object)
                    169: Returns current position of large object 
                    170: 
                    171: --------------------------------------------------------------------
                    172: bool pg_lo_lseek(resource large_object, int offset[, int whence])
                    173: Seeks position of large object
                    174: 
                    175: --------------------------------------------------------------------
                    176: 
                    177: Notice message function
                    178: 
                    179: --------------------------------------------------------------------
                    180: 
                    181: string pg_last_notice(resource connection)
                    182: Returns the last notice set by the backend 
                    183: 
                    184: This function is fully implemed in only in current CVS version.
                    185: PHP 4.3.0 supposed to included fully implemented version.
                    186: 
                    187: NOTE: Added in PHP 4.0.6, but there is bug in notice message handling
                    188: in PHP 4.0.6. Do no use 4.0.6 with pgsql module!!
                    189: 
                    190: --------------------------------------------------------------------
                    191: 
                    192: Utility functions (for PHP 4.3.0)
                    193: 
                    194: --------------------------------------------------------------------
                    195: array pg_metadata(resource db, string table)
                    196:    Get metadata
                    197: 
                    198: --------------------------------------------------------------------
                    199: array pg_convert(resource db, string table, array values)
                    200:    Check and convert values for PostgreSQL SQL statement
                    201: 
                    202: --------------------------------------------------------------------
                    203: bool pg_insert(resource db, string table, array values[, bool convert[, bool async]])
                    204:    Insert values (filed=>value) to table 
                    205: 
                    206: --------------------------------------------------------------------
                    207: bool pg_update(resource db, string table, array fields, array ids[, bool convert[, bool async]])
                    208:    Update table using values (field=>value) and ids (id=>value) 
                    209: 
                    210: --------------------------------------------------------------------
                    211: bool pg_delete(resource db, string table, array ids[, bool convert[, bool async]])
                    212:    Delete records has ids (id=>value) 
                    213: 
                    214: --------------------------------------------------------------------
                    215: array pg_select(resource db, string table, array ids[, bool convert])
                    216:    Select records that has ids (id=>value) 
                    217: 
                    218: --------------------------------------------------------------------
                    219: array pg_get_notify([resource db[, notify]])
                    220:    Get notify message on the connection 
                    221: 
                    222: --------------------------------------------------------------------
                    223: string pg_unescape_bytea(string bytea_data)
                    224:    Unescape bytea field data 
                    225: 
                    226: --------------------------------------------------------------------
                    227: bool pg_ping(resource db)
                    228:    ping database connection and try to reset connection if it's
                    229:    broken 
                    230: 
                    231: -------------------------------------------------------------------
                    232: 
                    233: Again, experimental functions are subject to be changed without 
                    234: notice.
                    235: 

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>