53장. libpq - C 라이브러리

libpq이것이C응용프로그램 프로그래머 인터페이스포스트그레스. libpq는 다음을 허용하는 라이브러리 루틴 세트입니다. 쿼리를 전달하는 클라이언트 프로그램포스트그레백엔드 서버를 사용하고 이 쿼리의 결과입니다.libpq또한 다른 여러 가지의 기본 엔진포스트그레다음을 포함한 애플리케이션 인터페이스libpq++(C++),libpgtcl(Tcl),펄및ecpg. 그래서 libpq 동작의 일부 측면은 다음과 같은 경우에 중요합니다. 해당 패키지 중 하나를 사용하세요.

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

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

다음을 사용하는 프런트엔드 프로그램libpq반드시 헤더 파일을 포함합니다libpq-fe.h그리고 다음과 연결되어야 합니다.libpq도서관.

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

다음 루틴은 다음에 대한 연결을 처리합니다.포스트그레백엔드 서버. 는 응용프로그램은 여러 백엔드 연결을 열어둘 수 있습니다. 한 번. (그렇게 하는 한 가지 이유는 둘 이상의 데이터베이스.) 각 연결은 PGconn 개체로 표시됩니다. PQconnectdb() 또는 PQsetdbLogin()에서 얻습니다. 참고하세요 함수는 항상 null이 아닌 객체 포인터를 반환합니다. PGconn을 할당하기에도 메모리가 너무 부족할 수 있습니다. 개체. PQstatus 함수를 호출하여 다음 사항을 확인해야 합니다. 쿼리가 다음을 통해 전송되기 전에 연결이 성공적으로 이루어졌습니다. 연결 개체입니다.

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

  PGconn *PQconnectdb(const char *conninfo)

  이 루틴은 다음을 사용하여 새 데이터베이스 연결을 엽니다. 문자열에서 가져온 매개변수콘인포. 아래의 PQsetdbLogin()과 달리 매개변수 세트를 확장할 수 있습니다. 함수 서명을 변경하지 않고 다음 중 하나를 사용하십시오. 루틴 또는 비차단 아날로그 PQconnectStart / PQconnectPoll은 애플리케이션 프로그래밍에 선호됩니다. 합격 문자열은 모든 기본 매개변수를 사용하기 위해 비어 있을 수 있습니다. 공백으로 구분된 하나 이상의 매개변수 설정을 포함합니다.

  각 매개변수 설정은 다음 형식으로 되어 있습니다.키워드 = 값. (Null 값이나 공백이 포함된 값은 작은따옴표로 묶습니다(예:키워드 = '값'. 작은따옴표 값 내에서는 다음과 같이 작성해야 합니다.\'. 등호 주위의 공백은 선택 사항입니다.) 현재 인식되는 매개변수 키워드는 다음과 같습니다.

  호스트

  연결할 호스트의 이름. 길이가 0이 아닌 문자열인 경우 지정하면 TCP/IP 통신이 사용됩니다. 이것을 사용하여 매개변수는 호스트 이름 조회를 발생시킵니다. 호스트 주소를 참조하세요.

  hostaddr

  연결할 호스트의 IP 주소입니다. 이 안에 있어야 BSD에서 사용되는 표준 숫자와 점 형식 함수 inet_aton 외. 길이가 0이 아닌 문자열인 경우 지정하면 TCP/IP 통신이 사용됩니다.

  호스트 대신 호스트 주소를 사용하면 응용프로그램이 다음을 수행할 수 있습니다. 호스트 이름 조회를 피하십시오. 이는 중요할 수 있습니다. 시간 제약이 있는 애플리케이션. 그러나 케르베로스 인증에는 호스트 이름이 필요합니다. 다음 그러므로 적용됩니다. Hostaddr 없이 호스트를 지정한 경우, 호스트 이름 조회가 강제됩니다. Hostaddr이 지정된 경우 호스트가 없으면, hostaddr의 값은 원격 호스트를 제공합니다. 주소; Kerberos를 사용하면 이름이 반대가 됩니다. 쿼리. 호스트와 호스트 주소를 모두 지정한 경우 값은 다음과 같습니다. Hostaddr은 원격 주소를 제공합니다. 호스트의 값 Kerberos를 사용하지 않는 한 무시됩니다. 값은 Kerberos 인증에 사용됩니다. 참고하세요 libpq가 호스트를 전달하면 인증이 실패할 가능성이 높습니다. Hostaddr에 있는 시스템의 이름이 아닌 이름입니다.

  호스트 이름과 호스트 주소가 모두 없으면 libpq는 로컬 Unix 도메인 소켓을 사용하여 연결합니다.

  포트

  서버 호스트 또는 소켓에 연결할 포트 번호 Unix 도메인 연결을 위한 파일 이름 확장자입니다.

  db이름

  데이터베이스 이름입니다.

  사용자

  연결할 사용자 이름.

  비밀번호

  서버가 비밀번호를 요구할 경우 사용할 비밀번호 인증.

  옵션

  추적/디버그 옵션이 서버로 전송됩니다.

  티

  선택적 디버그 출력을 위한 파일 또는 tty 백엔드.

  매개변수가 지정되지 않은 경우 해당 환경 변수("환경 변수" 섹션 참조)는 확인했습니다. 환경 변수도 설정되지 않은 경우 하드와이어된 기본값이 사용됩니다. 반환 값은 다음을 가리키는 포인터입니다. 백엔드에 대한 연결을 나타내는 추상 구조체입니다.

• PQsetdb로그인새로운 것을 만듭니다 데이터베이스 서버에 스포츠 토토 베트맨합니다.

  PGconn *PQsetdbLogin(const char *pghost,
                       const char *pgport,
                       const char *pgoptions,
                       const char *pgtty,
                       const char *db이름,
                       const char *로그인,
                       const char *pwd)

  이것은 다음의 전신입니다PQconnectdb매개변수 개수가 고정되어 있지만 기능은 동일합니다.

• PQsetdb다음에 새로운 연결을 만듭니다 데이터베이스 서버.

  PGconn *PQsetdb(char *pghost,
                  char *pgport,
                  char *pgoptions,
                  문자 *pgtty,
                  문자 *dbName)

  이것은 호출하는 매크로입니다PQsetdbLogin()로그인을 위한 널 포인터와 pwd 매개변수. 주로 이전 버전과의 호환성을 위해 제공됩니다. 오래된 프로그램으로.

• PQconnectStart PQconnectPoll데이터베이스에 스포츠 토토 베트맨하세요 비차단 방식으로 서버를 보호합니다.

  PGconn *PQconnectStart(const char *conninfo)

  PostgresPollingStatusType *PQconnectPoll(PQconn *conn)

  이 두 루틴은 다음에 대한 연결을 여는 데 사용됩니다. 애플리케이션의 실행 스레드가 다음과 같은 데이터베이스 서버 그렇게 하는 동안 원격 I/O가 차단되지 않습니다.

  데이터베이스 연결은 다음 매개변수를 사용하여 이루어졌습니다. 문자열에서콘인포, 전달됨 PQconnectStart. 이 문자열은 설명된 것과 동일한 형식입니다. PQconnectdb의 경우 위입니다.

  PQconnectStart도 PQconnectPoll도 차단하지 않습니다. 여러 가지 제한 사항이 충족되었기 때문에:

  • hostaddr 및 호스트 매개변수가 적절하게 사용되었습니다. 이름 및 역이름 쿼리가 수행되지 않도록 합니다. PQconnectdb에서 이러한 매개변수에 대한 문서를 참조하세요. 자세한 내용은 위를 참조하세요.

  • PQtrace를 호출하는 경우 스트림 개체가 추적하는 것은 차단되지 않습니다.

  • 당신은 소켓이 다음 위치에 있는지 스스로 확인합니다. PQconnectPoll을 호출하기 전의 적절한 상태입니다. 아래에 설명되어 있습니다.

  시작하려면 전화하세요conn=PQconnectStart("<connection_info_string"). conn이 NULL이면 libpq는 새 변수를 할당할 수 없습니다. PGconn 구조. 그렇지 않으면 유효한 PGconn 포인터가 반환됩니다. (아직 유효한 연결을 나타내지는 않지만 데이터베이스). PQconnectStart에서 돌아오면 다음을 호출하세요. 상태=PQ상태(conn). 상태가 CONNECTION_BAD인 경우 PQconnectStart가 실패했습니다.

  PQconnectStart가 성공하면 다음 단계는 libpq를 폴링하는 것입니다. 연결 순서를 진행할 수 있습니다. 다음과 같이 반복하세요. 기본적으로 '비활성' 연결을 고려하십시오. PQconnectPoll의 경우 마지막으로 PGRES_POLLING_ACTIVE를 반환했습니다. '활성'으로 간주하세요. 대신. PQconnectPoll(conn)이 마지막으로 반환된 경우 PGRES_POLLING_READING, 읽기를 위해 선택을 수행합니다. PQsocket(연결). 마지막으로 PGRES_POLLING_WRITING을 반환한 경우, PQsocket(conn)에 쓰기 위해 선택을 수행합니다. 아직 가지고 있다면 PQconnectPoll을 호출하려면, 즉 PQconnectStart를 호출한 후, 마지막으로 PGRES_POLLING_WRITING을 반환한 것처럼 동작합니다. 만약 select는 소켓이 준비되었음을 표시하므로 '활성'으로 간주합니다. 만약에 이 연결이 '활성'인 것으로 결정되었습니다. PQconnectPoll(conn)을 다시 실행합니다. 이 호출이 반환되면 PGRES_POLLING_FAILED, 연결 절차가 실패했습니다. 만약에 이 호출은 PGRES_POLLING_OK를 반환하고 연결이 완료되었습니다. 성공적으로 만들어졌습니다.

  소켓이 다음과 같은지 확인하기 위해 select()를 사용한다는 점에 유의하세요. 준비는 단지 (아마도) 예시일 뿐입니다. 그 외 시설을 갖춘 자 물론 poll() 호출과 같이 사용 가능한 경우도 있습니다. 대신.

  연결 중 언제든지 연결 상태 PQstatus를 호출하여 확인할 수 있습니다. CONNECTION_BAD인 경우 그러면 연결 절차가 실패했습니다. 만약 이것이라면 CONNECTION_OK이면 연결이 준비되었습니다. 둘 중 하나 상태는 반환 값에서 동일하게 감지할 수 있어야 합니다. 위와 같이 PQconnectPoll. 다른 상태는 (및 동안에만) 비동기 연결 절차. 이것들 연결 절차의 현재 단계를 나타내며 예를 들어 사용자에게 피드백을 제공하는 데 유용합니다. 이것들 상태에는 다음이 포함될 수 있습니다.

  • CONNECTION_STARTED: 스포츠 토토 베트맨 대기 중 만들어졌습니다.

  • CONNECTION_MADE: 스포츠 토토 베트맨 정상; 보내기를 기다리고 있습니다.

  • CONNECTION_AWAITING_RESPONSE: 응답을 기다리는 중 우체국장에게서요.

  • CONNECTION_AUTH_OK: 인증을 받았습니다. 기다리고있다 백엔드 시작.

  • CONNECTION_SETENV: 환경 협상 중입니다.

  이 상수는 그대로 유지되지만(순서대로) 호환성을 유지하기 위해) 애플리케이션은 절대 의존해서는 안 됩니다. 이것들이 특정한 순서로 나타나거나, 전혀, 또는 상태는 항상 문서화된 값 중 하나입니다. 안 애플리케이션은 다음과 같은 작업을 수행할 수 있습니다.

  스위치(PQstatus(conn))
  
          사례 CONNECTION_STARTED:
              Feedback = "스포츠 토토 베트맨 중...";
              부서지다;
  
          사례 CONNECTION_MADE:
              Feedback = "서버에 스포츠 토토 베트맨되었습니다...";
              부서지다;
  .
  .
  .
          기본값:
              Feedback = "스포츠 토토 베트맨 중...";

  PQconnectStart가 NULL이 아닌 포인터를 반환하면 작업이 끝나면 PQfinish를 호출해야 합니다. 구조 및 관련 메모리 블록을 폐기합니다. 이 PQconnectStart 또는 PQconnectPoll을 호출하는 경우에도 수행되어야 합니다. 실패했습니다.

  libpq가 다음과 같이 컴파일된 경우 PQconnectPoll은 현재 차단됩니다. USE_SSL이 정의되었습니다. 이 제한은 다음에서 제거될 수 있습니다. 미래.

  PQconnectPoll은 현재 Windows에서 차단됩니다. libpq는 WIN32_NON_BLOCKING_CONNECTIONS가 정의된 상태로 컴파일됩니다. 이 코드는 Windows에서 아직 테스트되지 않았으므로 다음과 같습니다. 현재는 기본적으로 꺼져 있습니다. 이는 다음에서 변경될 수 있습니다. 미래.

  이 함수는 다음과 같이 소켓을 비차단 상태로 둡니다. 만일PQset비차단이었어 전화했어요.

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

  PQconninfoOption *PQconndefaults(void)
  
  구조체 PQconninfoOption
  
      char *키워드;   /* 옵션의 키워드 */
      char *envvar;    /* 대체 환경 변수 이름 */
      char *컴파일됨;  /* 기본값으로 컴파일된 폴백 */
      char *발;       /* 옵션의 현재 값, 또는 NULL */
      char *레이블;     /* 연결 대화 상자의 필드 레이블 */
      char *dispchar;  /* 이 필드에 표시할 문자
                            연결 대화 상자에서. 값은 다음과 같습니다.
                            "" 입력된 값을 그대로 표시
                            "*" 비밀번호 필드 - 값 숨기기
                            "D" 디버그 옵션 - 기본적으로 표시되지 않음 */
      int dispsize;  /* 대화상자의 필드 크기(문자) */

  연결 옵션 배열을 반환합니다. 이는 다음에 사용될 수 있습니다. 가능한 모든 PQconnectdb 옵션과 현재 옵션을 결정합니다. 기본값. 반환 값은 다음 배열을 가리킵니다. NULL이 있는 항목으로 끝나는 PQconninfoOption 구조체 키워드 포인터. 기본값("val" 필드)은 환경 변수 및 기타 컨텍스트에 따라 달라집니다. 발신자는 반드시 연결 옵션 데이터를 읽기 전용으로 처리합니다.

  옵션 배열을 처리한 후 다음 위치에 전달하여 해제하세요. PQconninfoFree(). 이것이 완료되지 않으면 소량의 메모리가 PQconndefaults()를 호출할 때마다 유출됩니다.

  7.0 이전 Postgres 버전에서는 PQconndefaults()가 다음을 반환했습니다. 동적으로 할당된 배열이 아닌 정적 배열에 대한 포인터 배열. 이는 스레드로부터 안전하지 않았으므로 동작은 다음과 같습니다. 변경되었습니다.

• 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 구조는 향후 변경될 수 있기 때문입니다. (시작부터)포스트그레스출시 6.4에서는 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)

• PQ호스트서버 호스트를 반환합니다. 연결 이름입니다.

  char *PQhost(const PGconn *conn)

• PQ포트포트를 반환합니다. 연결.

  char *PQport(const PGconn *conn)

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

  char *PQtty(const PGconn *conn)

• PQ옵션백엔드를 반환합니다. 연결에 사용되는 옵션입니다.

  char *PQoptions(const PGconn *conn)

• PQ상태상태를 반환합니다. 스포츠 토토 베트맨.

  ConnStatusType PQstatus(const PGconn *conn)

  상태는 여러 값 중 하나일 수 있습니다. 그러나 단지 이 중 두 개는 비동기 스포츠 토토 베트맨 외부에 표시됩니다. 절차 -CONNECTION_OK또는CONNECTION_BAD. 좋은 연결 데이터베이스의 상태는 CONNECTION_OK입니다. 실패한 연결 시도는 상태로 표시됩니다.CONNECTION_BAD. 일반적으로 OK 상태는 그때까지 그대로 유지PQfinish하지만 통신 실패로 인해 상태가 다음으로 변경될 수 있습니다.CONNECTION_BAD조기. 그 안에 애플리케이션이 호출을 통해 복구를 시도할 수 있는 경우PQreset.

  PQconnectStart 및 PQconnectPoll 항목을 참조하세요. 표시될 수 있는 기타 상태 코드에 대해 설명합니다.

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

  char *PQerrorMessage(const PGconn* conn);

  거의 모든 libpq 기능이 설정됩니다PQerrorMessage실패할 경우. libpq의 참고 사항 규칙, 비어 있지 않음PQerrorMessage후행을 포함합니다 개행.

• PQbackendPID프로세스를 반환합니다.ID26428_26482

  int PQbackendPID(const PGconn *conn);

  백엔드PID다음에 유용합니다. 디버깅 목적 및 NOTIFY 메시지와의 비교( 다음을 포함합니다.PID알림의 백엔드). 참고하세요PID다음에 속함 로컬이 아닌 데이터베이스 서버 호스트에서 실행되는 프로세스 호스트!