53 장. libpq - C 도서관

libpqC응용 프로그램 프로그래머의 인터페이스Postgres. libpq는 허용하는 일련의 라이브러리 루틴입니다 쿼리를 전달하는 클라이언트 프로그램Postgres백엔드 서버 및 수신 이 쿼리의 결과.libpq도 있습니다 다른 여러 가지를위한 기본 엔진Postgresapplication interfaces,libpq ++(C ++),libpgtcl(tcl),Perl및ECPG. 그래서 libpq의 행동의 일부 측면이 당신에게 중요 할 것입니다. 그 패키지 중 하나를 사용하십시오.

이 섹션의 끝에 3 개의 짧은 프로그램이 포함되어 있습니다. 사용하는 프로그램을 작성하는 방법 표시libpq. 의 몇 가지 완전한 예가 있습니다.libpq다음의 응용 프로그램 디렉토리 :

../ src/test/regress
../src/test/examples
../src/bin/psql

사용하는 프론트 엔드 프로그램libpq헤더 파일 포함libpq-fe.h및 와 스포츠 토토 베트맨해야합니다.libpq도서관.

데이터베이스 스포츠 토토 베트맨 기능

다음 루틴은 a와 연결을 다루고 있습니다.Postgres백엔드 서버. 그만큼 애플리케이션 프로그램은 여러 백엔드 스포츠 토토 베트맨을 열 수 있습니다 일회. (그렇게해야 할 이유 중 하나는 둘 이상의 액세스입니다. 데이터베이스.) 각 스포츠 토토 베트맨은 pgconn 객체로 표시됩니다. pqconnectdb () 또는 pqsetdblogin ()로부터 얻어진다. 이것들에 유의하십시오 함수는 항상 널이 아닌 객체 포인터를 반환합니다 아마도 pgconn을 할당하기에는 기억이 너무 적을 것입니다. 물체. pqstatus 함수는 쿼리가 스포츠 토토 베트맨 객체.

• pqconnectdb새로운 스포츠 토토 베트맨을 만듭니다 데이터베이스 서버에.

  pgconn *pqconnectdb (const char *conninfo)

  이 루틴은 다음을 사용하여 새로운 데이터베이스 연결을 엽니 다 문자열에서 가져온 매개 변수Conninfo. 아래 pqsetdblogin ()과 달리 매개 변수 세트를 확장 할 수 있습니다 기능 서명을 변경하지 않고이 중 하나를 사용하십시오. 루틴 또는 비 블로킹 아날로그 PQConnectStart / PQConnectPoll은 응용 프로그램 프로그래밍에 선호됩니다. 통과 모든 기본 매개 변수를 사용하기 위해 문자열이 비어 있거나 공백으로 분리 된 하나 이상의 매개 변수 설정을 포함합니다.

  각 매개 변수 설정은 양식에 있습니다keyword = value. (널 값 또는 a를 작성하려면 공백을 포함하는 값, 단일 따옴표로 둘러싸여 있습니다 (예 :keyword = 'value'. 단일 따옴표 값 내에서로 작성해야합니다.\ '. 동일한 부호 주위의 공간은 선택 사항입니다.) 현재 인식 된 매개 변수 키워드는 다음과 같습니다.

  host

  연결할 호스트 이름. 0이 아닌 길이의 문자열 인 경우 지정되며 TCP/IP 통신이 사용됩니다. 이것을 사용합니다 매개 변수는 호스트 이름이 조회됩니다. hostaddr 참조.

  hostaddr

  스포츠 토토 베트맨할 호스트의 IP 주소. 이것은 들어와야합니다 BSD가 사용하는 표준 번호 및 점 양식 기능 inet_aton et al. 0이 아닌 길이의 문자열 인 경우 지정된 TCP/IP 통신이 사용됩니다.

  호스트 대신 hostAddr를 사용하면 응용 프로그램이 허용됩니다 호스트 이름 조회를 피하면 중요 할 수 있습니다. 시간 제약 조건이있는 응용 프로그램. 그러나 Kerberos 인증에는 호스트 이름이 필요합니다. 다음 따라서 적용됩니다. 호스트가 HostAddr없이 지정된 경우 a 호스트 이름 조회가 강요됩니다. HostADDR이 지정된 경우 호스트가 없으면 HostAddr의 값은 리모컨을 제공합니다 주소; Kerberos를 사용하면 반대 이름이 발생합니다 질문. 호스트와 hostaddr이 모두 지정되면 값이 있습니다 HostAddr의 경우 원격 주소를 제공합니다. 호스트의 값 Kerberos가 사용되지 않는 한 무시됩니다. 값은 Kerberos 인증에 사용됩니다. 주목하십시오 LIBPQ가 호스트를 통과하면 인증이 실패 할 가능성이 높습니다. hostaddr에서 기계의 이름이 아닌 이름

  호스트 이름과 호스트 주소가 없으면 libpq는 로컬 UNIX 도메인 소켓을 사용하여 연결하십시오.

  포트

  서버 호스트 또는 소켓에 연결할 포트 번호 Unix-Domain 연결을위한 파일 이름 확장.

  dbname

  데이터베이스 이름.

  사용자

  사용자 이름으로 연결합니다.

  비밀번호

  서버가 암호를 요구하는 경우 사용할 비밀번호 입증.

  옵션

  서버로 전송할 추적/디버그 옵션.

  tty

  옵션 디버그 출력을위한 파일 또는 tty 백엔드.

  매개 변수가 지정되지 않은 경우 해당 환경 변수 ( "환경 변수"섹션 참조)는 다음과 같습니다 확인. 그렇다면 환경 변수가 설정되지 않은 경우 하드 유용 기본값이 사용됩니다. 반환 값은 포인터입니다 백엔드와의 연결을 나타내는 추상 구조.

• pqsetdblogin새로운 것을 만듭니다 데이터베이스 서버 스포츠 토토 베트맨.

  pgconn *pqsetdblogin (const char *pghost,
                       const char *pgport,
                       const char *pgoptions,
                       const char *pgtty,
                       const char *dbname,
                       const char *로그인,
                       const char *pwd)

  이것은의 전임자입니다.PQCONNECTDB고정 된 수의 매개 변수가 있지만 동일한 기능.

• PQSETDB새로운 스포츠 토토 베트맨 데이터베이스 서버.

  pgconn *pqsetdb (char *pghost,
                  char *pgport,
                  char *pgoptions,
                  char *pgtty,
                  char *dbname)

  이것은 호출하는 매크로입니다pqsetdblogin ()로그인을위한 널 포인터와 함께 PWD 매개 변수. 주로 후진 호환성을 위해 제공됩니다 오래된 프로그램과 함께.

• PQConnectStart PQConnectPoll데이터베이스에 스포츠 토토 베트맨합니다 블로킹하지 않은 방식으로 서버.

  PGCONN *PQCONNECTSTART (const char *conninfo)

  PostGrespollingStatUtype *PQConnectPoll (PQConn *Conn)

  이 두 루틴은 응용 프로그램의 실행 스레드가 그렇게하는 동안 원격 I/O에서 차단되지 않았습니다.

  데이터베이스 스포츠 토토 베트맨은 취한 매개 변수를 사용하여 이루어집니다 문자열에서ConninfoPQConnectStart. 이 문자열은 설명과 동일한 형식입니다 PQConnectDB 위의 위.

  PQCONNECTSTART 나 PQCONNECTPOLL은 오랫동안 차단되지 않습니다 여러 제한이 충족되면서 :

  • HostADDR 및 호스트 매개 변수는 적절하게 사용됩니다 이름과 리버스 이름 쿼리가 이루어지지 않도록합니다. PQConnectDB에서 이러한 매개 변수의 문서를 참조하십시오 자세한 내용은 위.

  • PQTRACE를 호출하는 경우 스트림 객체가 당신이 추적하는 것은 차단되지 않습니다.

  • 당신은 소켓이 pqconnectpoll을 호출하기 전에 적절한 상태로 아래 설명.

  시작하려면conn = pqConnectStart ( "<connection_info_string"). Conn이 NULL이면 LIBPQ가 새로운 것을 할당 할 수 없었습니다. PGCONN 구조. 그렇지 않으면 유효한 PGConn 포인터가 반환됩니다 (아직 유효한 연결을 나타내지는 않지만 데이터 베이스). PQConnectStart에서 돌아 오면 전화하십시오 상태 = pqstatus (conn). 상태가 Connection_Bad와 같은 경우 PQConnectStart가 실패했습니다.

  PQCONNECTSTART가 성공하면 다음 단계는 LIBPQ를 폴링하는 것입니다. 연결 순서를 진행할 수 있습니다. 따라서 루프 : 기본적으로 '비활성'연결을 고려하십시오. pqconnectpoll 인 경우 마지막으로 반환 된 pgres_polling_active, 'Active'를 고려하십시오. 대신에. PQConnectPoll (Conn)이 마지막으로 돌아온 경우 pgres_polling_Reading, eleg reading on one을 수행하십시오 PQSocket (Conn). 마지막으로 pgres_polling_writing을 반환 한 경우 pqsocket (conn)에서 작성하기 위해 선택하십시오. 당신이 아직 있다면 PQConnectPoll에 전화하십시오. 마지막으로 pgres_polling_writing을 반환 한 것처럼 행동하십시오. 만약 선택은 소켓이 준비되었음을 보여주고 '활성'을 고려하십시오. 만약에 이 연결이 '활성'이라고 결정되었습니다. pqconnectpoll (conn) 다시. 이 호출이 반환되는 경우 pgres_polling_failed, 연결 절차가 실패했습니다. 만약에 이 호출은 pgres_polling_ok를 반환합니다 성공적으로 만들었습니다.

  소켓이 준비는 단지 (아마도) 예일뿐입니다. 다른 시설이있는 사람들 Poll () 전화와 같은 사용 가능한 경우 물론 사용할 수 있습니다. 대신에.

  연결하는 동안 언제든지 연결 상태 pqstatus에 전화하여 점검 할 수 있습니다. 이것이 Connection_bad라면 그런 다음 연결 절차가 실패했습니다. 이것이 있다면 Connection_ok, 그러면 연결이 준비되었습니다. 이 중 하나 주정부는 위와 같이 pqconnectpoll. 다른 상태 (및 비동기 연결 절차 중에 만. 이것들 연결 절차의 현재 단계를 표시하면 예를 들어 사용자에게 피드백을 제공하는 데 유용합니다. 이것들 상태는 다음을 포함 할 수 있습니다.

  • Connection_Started : 스포츠 토토 베트맨을 기다리고 있습니다 만들어진.

  • Connection_Made : Connection OK; 보내기를 기다리고 있습니다.

  • Connection_awaiting_Response : 응답을 기다리고 있습니다 우체국 장에서.

  • Connection_auth_ok : 인증을 받았습니다. 기다리고 있습니다 백엔드 스타트 업.

  • Connection_Setenv : 협상 환경.

  이 상수는 (순서대로) 남아있을 것입니다 호환성을 유지하려면) 응용 프로그램은 절대 의존해서는 안됩니다 특정 순서 또는 전혀 또는 상태는 항상 문서화 된 값 중 하나입니다. an 응용 프로그램은 다음과 같은 일을 할 수 있습니다 :

  스위치 (pqstatus (conn))
  
          Case Connection_Started :
              피드백 = "스포츠 토토 베트맨 ...";
              부서지다;
  
          Case Connection_Made :
              피드백 = "서버에 스포츠 토토 베트맨되어 ...";
              부서지다;
  .
  .
  .
          기본:
              피드백 = "스포츠 토토 베트맨 ...";

  PQConnectStart가 널이 아닌 포인터를 반환하는 경우, 귀하는 귀하에게 주목하십시오 PQFinish에게 전화를 걸어야합니다. 구조 및 관련 메모리 블록을 폐기하십시오. 이것 pqconnectstart 또는 pqconnectpoll에 대한 호출에도 완료해야합니다. 실패한.

  PQConnectPoll은 LIBPQ가 컴파일 된 경우 현재 차단됩니다 use_ssl 정의. 이 제한은 미래.

  PQConnectPoll은 현재 Windows에서 차단됩니다 LIBPQ는 정의 된 Win32_Non_Blocking_Connections로 컴파일됩니다. 이 코드는 아직 Windows에서 테스트되지 않았으므로 현재 기본적으로 꺼져 있습니다. 이것은 변경 될 수 있습니다 미래.

  이 기능은 소켓을 비 차단 상태로 남겨 둡니다. 만약에pqsetnonblocking라고 불리는.

• pqconndefaults기본값을 반환합니다 연결 옵션.

  PQCONNINFOOPTION *PQCONNDEFAULTS (void)
  
  구조 pqconninfooption
  
      char *키워드;   / * 옵션 키워드 */
      char *envvar;    / * 폴백 환경 변수 이름 */
      char *편집;  / * 기본값으로 컴파일 된 폴백 */
      char *val;       / * 옵션의 현재 값 또는 null */
      숯 *레이블;     / * 연결 대화 상자에서 필드에 대한 레이블 */
      char *dispchar;  /*이 필드에 표시 할 문자
                            연결 대화 상자에서. 값은 다음과 같습니다.
                            ""디스플레이가 그대로 입력되었습니다
                            "*"비밀번호 필드 - 값 숨기기
                            "D"디버그 옵션 - 기본적으로 표시하지 마십시오 */
      int dispsize;  / * 대화 상자의 문자의 필드 크기 */

  연결 옵션 배열을 반환합니다. 이것은 익숙 할 수 있습니다 가능한 모든 PQCONNECTDB 옵션 및 현재를 결정하십시오 기본값. 리턴 값은 배열을 가리 킵니다 pqconninfooption structs, null이있는 항목으로 끝납니다. 키워드 포인터. 기본값 ( "val"필드)은 그렇습니다 환경 변수 및 기타 컨텍스트에 따라 다릅니다. 발신자는해야합니다 연결 옵션 데이터를 읽기 전용으로 처리하십시오.

  옵션 배열을 처리 한 후 전달하여 무료로 사용하십시오. PQCONNINFOFREE (). 이 작업이 완료되지 않으면 소량의 메모리 pqconndefaults ().에 대한 각 호출마다 유출됩니다.

  7.0 이전의 Postgres 버전에서 pqConnDefaults ()는 a를 반환했습니다 동적으로 할당되지 않고 정적 배열에 대한 포인터 정렬. 그것은 스레드 안전이 아니 었으므로 동작이 그랬습니다 변경.

• pqfinish스포츠 토토 베트맨을 닫습니다 백엔드. 또한 pgconn 객체에서 사용하는 메모리를 해방합니다.

  void pqfinish (pgconn *conn)

  백엔드 연결 시도가 실패하더라도 PQSTATUS로 표시), 응용 프로그램은 pqfinish로 호출해야합니다 pgconn 객체에서 사용하는 메모리를 자유롭게하십시오. PGCONN 포인터 pqfinish라고 불린 후에 사용해서는 안됩니다.

• pqreset통신을 재설정하십시오 백엔드가있는 포트.

  void pqreset (pgconn *conn)

  이 기능은 백엔드와의 연결을 닫고 동일한 우체국 장에 대한 새로운 연결을 재건하려고 시도하고 이전에 사용 된 동일한 매개 변수를 모두 사용합니다. 이것은 유용 할 수 있습니다 작업 연결이 손실되면 오류 복구.

• PQRESETSTART pqresetpoll통신 포트를 재설정하십시오 백엔드, 비 블로킹 방식.

  int pqresetstart (pgconn *conn);

  PostGrespollingStatUstype PQRESETPOLL (PGCONN *CONN);

  이 기능은 백엔드와의 연결을 닫고 동일한 우체국 장에 대한 새로운 연결을 재건하려고 시도하고 이전에 사용 된 동일한 매개 변수를 모두 사용합니다. 이것은 유용 할 수 있습니다 작업 연결이 손실되면 오류 복구. 그들은 다릅니다 PQRESET (위)에서 비 블로킹 방식으로 작용한다는 점에서. 이러한 기능은 PQConnectStart와 동일한 제한을 겪습니다 및 pqconnectpoll.

  PQRESETSTART에 전화하십시오. 0을 반환하면 재설정이 실패했습니다. 만약에 그것은 1을 반환하고, 정확히 pqresetpoll을 사용하여 재설정을 폴링합니다. 연결을 사용하여 연결하는 것과 마찬가지로 pqconnectpoll.

LIBPQ 응용 프로그램 프로그래머는 유지해야합니다 PGCONN 추상화. 아래의 액세서 기능을 사용하여 pgconn의 내용. 필드를 직접 참조하지 마십시오 PGConn 구조는 미래에 변화를 겪을 수 있기 때문입니다. (시작Postgres릴리스 6.4, struct pgconn의 정의는에도 제공되지 않습니다.libpq-fe.h. 오래된 코드가 있다면 pgconn 필드에 직접 액세스하면를 포함하여 계속 사용할 수 있습니다.libpq-int.h도 권장됩니다 곧 코드를 수정하려면.)

• PQDB데이터베이스 이름을 반환합니다 스포츠 토토 베트맨.

  char *pqdb (const pgconn *conn)

  PQDB 및 다음 몇 가지 함수는 값을 반환합니다 연결시 설정. 이 값은 수명을 위해 고정되어 있습니다 pgconn 객체.

• PQUSER사용자 이름을 반환합니다 스포츠 토토 베트맨.

  char *pquser (const pgconn *conn)

• pqpass스포츠 토토 베트맨.

  char *pqpass (const pgconn *conn)

• pqhost서버 호스트를 반환합니다 스포츠 토토 베트맨 이름.

  char *pqhost (const pgconn *conn)

• PQPORT포트를 반환합니다 스포츠 토토 베트맨.

  char *pqport (const pgconn *conn)

• pqtty디버그 tty를 반환합니다 스포츠 토토 베트맨.

  char *pqtty (const pgconn *conn)

• pqoptions백엔드를 반환합니다 연결에 사용 된 옵션.

  char *pqoptions (const pgconn *conn)

• pqstatus스포츠 토토 베트맨.

  Connstatustype pqstatus (const pgconn *conn)

  상태는 여러 값 중 하나 일 수 있습니다. 그러나만 이 중 두 개는 비동기 스포츠 토토 베트맨 외부에서 볼 수 있습니다. 절차 -Connection_ok또는Connection_Bad. 좋은 스포츠 토토 베트맨 데이터베이스에는 상태 connection_ok가 있습니다. 실패한 스포츠 토토 베트맨 시도는 상태에 따라 신호Connection_Bad. 일반적으로 괜찮은 상태가 될 것입니다 까지pqfinish그러나 a 커뮤니케이션 실패는 상태가 변경 될 수 있습니다Connection_Bad조기. 그것에 신청서가 전화를 통해 복구하려고 시도 할 수 있습니다pqreset.

  PQConnectStart 및 PQConnectPoll의 항목을 참조하십시오 볼 수있는 다른 상태 코드와 관련하여.

• PQERRORMESSAGE오류를 반환합니다 가장 최근에 작전에서 생성 된 메시지 스포츠 토토 베트맨.

  char * pqerrormessage (const pgconn * conn);

  거의 모든 libpq 함수가 설정됩니다PQERRORMESSAGE실패하면. libpq에 의해 주목하십시오 컨벤션, 비어 있지 않음PQERRORMESSAGE후행이 포함됩니다 Newline.

• pqbackendpid프로세스 반환id26424_26478

  int pqbackendpid (const pgconn *conn);

  백엔드PID디버깅 목적 및 비교를 알리기 위해 메시지 (who 포함PID백엔드).PID로컬이 아닌 데이터베이스 서버 호스트에서 실행되는 프로세스 주인!