제  목:[Pg-perl] perl을 이용한 postgreSQL의 접근                   
 번역자:advances(정재익  )

 이 문서는 Pg.pm의 pod 문서를 번역한 것이다.
============================================================================

이름
      Pg - PosgreSQL을 위한 Perl 5
문법
      새로운 방식
          user Pg;
          $conn = Pg::connectdb("dbname = template1");
          $result = $conn->exec("create database test");

      예전의 방식대로 사용할수도 있습니다.
          use Pg;
          $conn = PQsetdb('','','','', template1);
          $result = PQexec($conn, "create database test");
          PQclear($result);
          PQfinish($conn);

기술
      Pg module은 여러분들에게 PostgreSQL의 Libpq상의 모든 함수를 사용할수
      있게 해준다. Libpq는 PostgreSQL에 대한 프로그래머의 interface이다.
      이 module을 어떻게 사용하는가 하는 것은 test.pl 파일을 참조하기 바란다.
      더 자세한 예는 Libpq 를 응용한 프로그램들을 참조하기 바란다.
      여러분들은 예전의 C-style을 사용할것인지 아니면 새로운 좀더 Perl과 
      닮은 방식을 사용할것인지를 결정해야 한다. 구식의 방식을 사용하면 이미
      만들어진 Libpq 응용프로그램의 모든 변수앞에 $를 추가함으로써 perl로 
      porting이 가능하다. 새로운 style은 class package를 사용하며 C++ 프로
      그래머에게 좀더 친숙한 형식이다.

사용안내
    새로운 방식 (new style)
      새로운 방식을 객체를 사용한다. 데이타베이스로의 새로운 연결(new
      connection)이나 또는 결과에 대한 객체(object to result)를 만들고 난 후에,
      Libpq 함수들은 virtual methods처럼 작동되어 진다. 이 새로운 방식의 장점
      한가지는 connection 또는 result 구조체에 대한 해제를 신경쓸 필요가 없다
      는 것이다. Perl은 없어진 object에대한 마지막 참조시에 destructor를 불러
      준다.

    예전의 방식(old style)
      모든 함수와 상수들은 호출한 package의 name-space내로 import 된다. 일정한
      형식의 명명방법을 취하기 위하여 모든 함수는 'PQ'로 시작하며(예:PQlo_open)
      모든 상수들은 'PQRES_'로 시작한다.(예:PQRES_CONNECTION_OK)

      메모리를 할당하는 두가지 함수가 있으며 사용후에 사용자가 해제 시켜주어야
      한다.
   
           PQsetdb, use PQfinish to free memory.
           PQexec, use PQclear to free memory.

      Pg.pm은 하나의 편한 함수:doQuery를 포함한다. 이것은 2차원 배열로서 
      질의(query)에 대한 결과로 채워진다. 사용법은 다음과 같다.

           Pg::doQuery($conn, "select attr1, attr2 from tbl", \@ary);
           
           for $i ( 0 .. $#ary ) {
               for $j ( 0 .. $#{$ary[$i]} ) {
                   print "$ary [$i][$j]\t";
               }
               print "\n";
           }

      내부의 loop를 주의해서 보라.

경고
      perl 함수와 C 함수간에 차이점이 있는 몇가지 예외적인 함수가 있다: PQprint,
      PQnotifies 그리고 PQconndefaults가 그러한 것들이다. 이들 함수들은 구조체를
      다루는데 이들은 perl에서 list나 hash를 이용해서 구현이 되어 있다.

기능 
      함수들은 세가지 영역으로 구분할수 있다: Connection, Result, Large objects.

   1. Connection (연결)
      이들 함수들로 데이타베이스에 대한 연결을 설정할수도 그리고 닫을수도 있다.
      Libpq에서 connection은 PGconn에 의해 불리워지는 구조체로서 구현되어 있다.
      여러분들은 적절한 methods를 이용하여 이 구조체에 대한 거의 모든 fields로
      접근할 수 있다.

           $conn = Pg::setdb( $pghost, $pgport, $pgoptions, $pgtty, $dbname)

      Backend와 새로운 연결을 설정한다. 만약에 환경변수를 검사하여 미리 설정된
      defaults를 사용하고자 하는 경우에는 argument로서 빈 문자열을 사용할수
      있다. 연결식별자 $conn (PGconn 구조체에 대한 ponter이다.) 은 다음에 사용
      되는 명령어들에서 유일한 식별자로서 이용된다. $conn을 이용하기 전에
      연결이 적절하게 만들어졌다는 것을 보증하기 위하여 $conn->status를 호출
      해야만 한다. PGconn 구조체의 내용으로 접근할려면 아래의 methods를 사용
      한다.

           $conn = Pg::connectdb("option = value");

      이것은 문자열(string)속에 있는 연결정보를 이용하여 backend로의 새로운 
      연결을 설정한다. 연결식별자(connection identifier) $conn (PGconn 자료
      구조에 대한 pointer)은 뒤이어 오는 명령어들에서 유일한 식별자로서 
      사용된다. 마찬가지로 $conn을 호출하기 전에 연결이 적절히 만들어 
      졌다는 보증을 하기 위해서 $conn->status를 호출해야만한다. PGconn 구조체
      의 내용에 대한 접근을 하려면 다음 methods를 사용한다.

          $Option_ref = Pg:conndefaults()

          while (($key, $val) = each %$Option_ref) {
                print "$key, $val\n";
          }

      connectdb()함수의 모든 가능한 option의 키를 포함하는 hash에대한 
      참조를 되돌려준다. 값은 현재의 defaults이다. 이 함수는 C 에서 사용되는
      같은 기능을 하는 함수와는 약간 다르다. C 에서는 conninfoOption 구조체
      를 돌려준다.

          PQfinish ($conn)
      구식 방식에서만 사용한다. Backend에 대한 연결을 해제하고 모든 메모리
      할당을 해제시킨다.

          $conn->reset
      Backend의 연결 port를 reset하고 새로운 연결을 설정한다.

          $dbname = $conn->db
      현재 연결의 데이타베이스 이름을 돌려준다.
    
          $pguser = $conn->user
      연결한 postgres 사용자 이름을 돌려준다.

          $pghost = $conn->host
      연결한 host 이름을 돌려준다.

          $pgoptions = $conn->options
      연결에 사용된 option을 돌려준다.

          $pgport = $conn->port
      연결이 이루어진 port번호를 돌려준다.

          $pgtty = $conn->tty
      연결이 이루어진 tty를 돌려준다.

          $status = $conn->status
      연결의 상태 (status)를 돌려준다.이들 연결 상태는 다음 상수들과 비교
      해서 그 결과를 알수 있다.
        - PGRES_CONNECTION_OK
        - PGRES_CONNECTION_BAD

          $errorMessage = $conn->errorMessage
      연결과 관련된 마지막 에러 메시지를 보여준다.

          $conn->trace(debug_port)
      Frontedn와 Backend간에 전달되는 메시지들이 debug_port file stream으로
      echo 된다.

          $conn->untrace
      trace를 해제한다.

          $result = $conn->exec($query)
      Backend로 질의를 전달한다. 복귀값은 PGresult 구조체에대한 pointer이다.
      이것은 backend에 의한 완전한 질의결과를 담고있다. 질의에 실패한 경우
      빈 구조체를 가르키는 pointer가 된다. 이 경우에 perl의 구현은 C의 경우와
      는 다르다. 구식 방식을 사용할 경우 비어있는 구조체라 하더라도 PQfree를
      이용하여 해제해 주어야 한다. $result를 사용하기 전에 질의가 적절하게 
      실행되었는지 확인하기 위해여 resultStatus를 호출해야 한다. 

          $ret = $conn->getline($string, $length)
      Backend로 부터 문자열을 $length-1자까지 읽어 들인다. getline은 EOF의
      위치에서는 EOF를 돌려주며, 모든 줄이 다 읽혀 진 경우 0을, 그리고 
      buffer가 다 찬 경우에는 1을 돌려 준다. 만약 한줄이 두글자 "\."으로 
      이루어진 경우 backend는 복사명령의 결과를 보내는 것을 중단한다.

          $ret = $conn->putline($string)
      문자열을 backend로 보낸다. 응용프로그램은 명확하게 두글자 "\."을 
      backend로 보냄으로서 자료의 전송이 끝났음을 알려야 한다.

          $ret = $conn->endcopy
      이함수는 backend가 copy를 끝낼때까지 기다린다. 이것은 마지막 문자열이
      putline을 이용해서 backend로 전달이 되던지 또는 마지막 문자열을 backend
      로부터 getline을 이용해서 받았을 경우 끝나게 된다. endcopy는 성공적일
      경우 0을 돌려주며, 그렇지 않을 경우 0이 아닌 수치를 돌려준다.

          ($table, $pid) = $conn->notifies
      비공기적인 통보를 검사한다. 이 함수는 C 에 있는 함수와는 다르게 구현되어
      있다. C에서는 새로할당된 구조체를 돌려주지만 perl은 list를 돌려준다.
      $table은 backend로 부터 온 table이고 $pid는 backend의 process ID이다.
  
   2. Result (결과)
     
      여러분들은 여기에 속한 함수들을 이용하여 데이타베이스에 명령어를 보내고
      그 결과를 조사할 수 있다. Libpq에서는 명령의 결과는 PGresult에 의해 
      호출되어진 구조체에 의해 구현되어 있다. 적절한 methods를 이용하여 이 
      구조체의 거의 모든 field로 접근할수 있다.

      아래 함수들을 이용하여 PGresult 구조체의 내용들에 대해 접근이 가능하다.

          $ntuples = $result->ntuples
      질의결과의 tuple의 수를 돌려준다.

          $nfields = $result->nfields
      질의결과의 fields의 수를 돌려준다.
  
          $fname = $result->fname($field_num)
      주어진 field 번호에 해당하는 field 이름을 돌려준다.

          $fnumber = $result->fnumber($field_name)
      주어진 field 이름과 연관된 field 번호를 돌려준다.
     
          $ftype = $result->ftype($field_num)
      주어진 field 번호의 field 형을 돌려준다.

          $fsize = $result->fsize($field_num)
      주어진 field 번호의 형(type)의 크기를 byte로서 표시한다. 만약 필드가
      가변적인 길이를 가질 경우 -1을 돌려준다.

          $value = $result->getvalue($tupnum, $field_num)
      주어진 tuple과 filed에 해당하는 값을 돌려준다. 이것은 null로 끝나는 
      ASCII 문자열이다.  이진 cursor(Binary cursors)는 작동하지 않는다.      

          $length = $result->getlength($tup_num, $field_num)
      주어진 tuple과 filed 번호에 해당하는 값의 길이를 돌려준다.

          $null_status = $result->getisnull($tup_num, $field_num)
      주어진 tuple과 field의 NULL status를 돌려준다.

          $result_status = $result->resultStatus
      결과의 상태를 돌려준다. 실행된 명령의 종류에 따라서 다음의 상수들과 
      비교를 해서 status를 알수 있다.

        - PGRES_EMPTY_QUERY
        - PGRES_COMMAND_OK
        - PGRES_TUPLES_OK
        - PGRES_COPY_OUT
        - PGRES_COPY_IN
        - PGRES_BAD_RESPONSE
        - PGRES_NONFATAL_ERROR
        - PGRES_FATAL_ERROR

          $cmdStatus = $result->cmdStatus
      마지막 질의 명령어의 command status를 돌려준다. 만약 DELETE의 경우 
      지워진 tuple의 수를 돌려준다. INSERT의 경우 1 (영향을 받은 tuple의 
      수) 다음에 삽입된 tuple의 oid를 돌려준다. 

          $oid = $result->oidStatus
      마지막 질의가 INSERT인 경우 삽입된 tuple의 oid를 돌려준다.

          $oid = $result->cmdTuples
      마지막 질의가 INSERT나 DELETE 명령어인 경우 영향을 받은 tuple의 수를
      돌려준다. 

          $result->printTuples($fout, $printAttName, $terseOutput, $width)
      뒤쪽으로의 호환성을 유지하라. print를 사용한다.

          $result->print($fout, $header, $align, $standard, $html3,
                   $expanded, $pager, $fieldSep, $tableOpt, $caption, ... )
      모든 tuple들을 지능적인 형태로 print한다. 이함수는 C 에서 구현된 것과
      는 다르다. PQprintOpt 구조체가 여기서는 list로 구현되어 있다. 이 list
      는 PQprintOpt 속에 있는 fieldName의 문자배열을 다루기 위해여 가변적인
      길이를 갖는 list로 되어 있다.  $header, $align, $standard, $html3, 
      $expanded, $pager 등과 같은 argument들은 boolean flag들이다. $fieldSep,
      $tableOpt, $caption 등과 같은 인자들은 문자열이다. field 이름을 위해 
      대치시킬 추가적인 문자열을 더해야만 한다.

          PQclear($result)
      구식 방식에서만 사용한다. 주어진 result에대한 메모리 할당을 해제한다.

   3. Large Objects (거대객체)
     
      이들 함수들은 사용자 자료에 대해 file과 같은 방식의 접근을 허용한다.
      Large object interface는 Unix file system interface를 모델로 하여 
      만들어 졌으며, open, close, read, write, lseek, tell과 유사한 함수를
      지닌다. 모든 함수 이름들은 머리에 'PQ'를 추가한다. (구식방식에서만..)
      
          $lobjId = $conn->lo_creat($mode)
      새로운 large object를 만든다. $mode는 새로운 객체의 속성을 기술하는
      bit-mask 이다. 다음 상수를 사용한다:

        - PGRES_INV_SMGRMASK
        - PGRES_INV_ARCHIVE
        - PGRES_INV_WRITE
        - PGRES_INV_READ

      실패할 경우 PGRES_InvalidOid를 돌려준다.
  
          $ret = $conn->lo_unlink($lobjId)
      Large object를 삭제한다. 실패할 경우 -1을 돌려준다.

          $lobj_fd = $conn->lo_open($lobjId, $mode)
      이미 존재하는 large object를 열고 object id를 돌려준다. mode bits는
      lo_creat를 참고하라. 실패할 경우 -1을 돌려준다.

          $ret = $conn->lo_close($lobj_fd)
      존재하는 large object를 닫는다. 성공할 경우 0을 그리고 실패할 경우
      -1을 돌려준다.

          $nbytes = $conn->lo_read($lobj_fd, $buf, $len)
      Large object인 $lobj_fd로 부터 $len bytes 만큼 $buf로 읽어 들인다.
      읽어 들인 byte의 수를 돌려주며, 실패할경우 -1을 돌려준다.

          $nbytes = $conn->lo_write($lobj_fd, $buf, $len)
      Large object $lobj_fd에 $buf속의 내용중 $len byte만큼 쓴다. 쓴 byte
      수를 돌려주며, 실패할 경우 -1을 돌려준다.

          $ret = $conn->lo_lseek( $lobj_fd, $offset, $whence)
      Large object $lobj_fd 상에서 현재의 읽기와 쓰기 위치를 바꾼다.
      현재 구현되어 있는 함수에서는 $whence는 0 (L_SET) 만이 가능하다.

          $location = $conn->lo_tell($lobj_fd)
      Large object인 $lobj_fd에서 현재의 읽기, 또는 쓰기 위치를 구한다.

          $lobjId= $conn->lo_import($lobjId)
      Unix 파일을 large object로서 읽어 들이고, 새로운 object의 object id
      를 돌려 준다.

          $ret = $conn->lo_export($lobjId, $filename)    
      Large object를 Unix file로 만들어 준다. 실패할 경우 -1을 돌려주고,
      그외에는 1을 돌려 준다.

저자
      Edmund Mergl       <E.Mergl@bawue.de>

번역자 
      정재익             <advance@advance.sarang.net>

참고할 것
      libpq manpage, large_object manpage