[Final] PEP 248 - Python Database API Specification v1.0

원문 링크: PEP 248 - Python Database API Specification v1.0

상태: Final 유형: Informational 작성일: 08-May-1996

서론 (Introduction)

이 API는 데이터베이스에 접근하는 데 사용되는 Python 모듈들 간의 유사성을 장려하기 위해 정의되었습니다. 이를 통해, 더 쉽게 이해할 수 있는 모듈, 데이터베이스 간에 더 높은 이식성을 가진 코드, 그리고 Python에서 더 광범위한 데이터베이스 연결성을 확보할 수 있도록 일관성을 달성하고자 합니다.

이 인터페이스 사양은 다음 항목들로 구성됩니다:

  • 모듈 인터페이스 (Module Interface)
  • 연결 객체 (Connection Objects)
  • 커서 객체 (Cursor Objects)
  • DBI 헬퍼 객체 (DBI Helper Objects)

이 사양에 대한 의견 및 질문은 Python의 Tabular Databases SIG (http://www.python.org/sigs/db-sig)로 보낼 수 있습니다. 이 사양 문서는 1996년 4월 9일에 마지막으로 업데이트되었으며, 이 사양의 버전 1.0으로 알려질 것입니다.

모듈 인터페이스 (Module Interface)

데이터베이스 인터페이스 모듈은 일반적으로 이름이 db로 끝나는 형태여야 합니다. 기존 예시로는 oracledb, informixdb, pg95db 등이 있습니다. 이 모듈들은 다음과 같은 이름들을 노출해야 합니다:

  • modulename(connection_string): 데이터베이스에 대한 연결을 생성하기 위한 생성자입니다. Connection Object를 반환합니다.
  • error: 데이터베이스 모듈에서 발생하는 오류에 대해 발생하는 예외입니다.

연결 객체 (Connection Objects)

Connection Object는 다음 메서드에 응답해야 합니다:

  • close(): 즉시 연결을 닫습니다 ( __del__이 호출될 때까지 기다리지 않음). 이 시점부터 연결은 사용할 수 없으며, 연결로 어떤 작업을 시도하면 예외가 발생합니다.
  • commit(): 보류 중인 모든 트랜잭션을 데이터베이스에 커밋합니다.
  • rollback(): 보류 중인 트랜잭션의 시작 지점으로 데이터베이스를 롤백합니다.
  • cursor(): 새로운 Cursor Object를 반환합니다. 데이터베이스가 커서 개념을 지원하지 않는 경우 예외가 발생할 수 있습니다.
  • callproc([params]): (참고: 이 메서드는 아직 잘 정의되지 않았습니다.) 주어진 (선택적) 매개변수와 함께 저장된 데이터베이스 프로시저를 호출합니다. 저장 프로시저의 결과를 반환합니다.
  • (모든 Cursor Object의 속성 및 메서드): 커서가 없는 데이터베이스나 커서의 복잡성이 필요 없는 간단한 애플리케이션의 경우, Connection Object는 Cursor Object의 각 속성 및 메서드에 응답해야 합니다. 커서가 있는 데이터베이스는 암시적인 내부 커서를 사용하여 이를 구현할 수 있습니다.

커서 객체 (Cursor Objects)

이 객체들은 데이터베이스 커서를 나타내며, 이는 가져오기(fetch) 작업의 컨텍스트를 관리하는 데 사용됩니다.

Cursor Object는 다음 메서드와 속성에 응답해야 합니다:

  • arraysize: 이 읽기/쓰기 속성은 fetchmany()를 사용하여 한 번에 가져올 행 수를 지정합니다. 이 값은 여러 행을 한 번에 삽입할 때도 사용됩니다 ( execute() 메서드의 params 값으로 튜플/리스트의 튜플/리스트를 전달). 이 속성의 기본값은 단일 행입니다.
    • arraysize는 선택 사항이며, 더 높은 성능의 데이터베이스 상호 작용을 위해 제공됩니다. 구현은 fetchmany() 메서드와 관련하여 이를 준수해야 하지만, 한 번에 한 행씩 데이터베이스와 상호 작용할 수 있습니다.
  • description: 이 읽기 전용 속성은 7개의 튜플로 구성된 튜플입니다. 각 7-튜플은 각 결과 열에 대한 정보를 포함합니다: (name, type_code, display_size, internal_size, precision, scale, null_ok). 행을 반환하지 않는 작업의 경우 또는 커서가 아직 execute() 메서드를 통해 작업을 호출하지 않은 경우 이 속성은 None이 됩니다.
    • type_code는 아래 섹션에 명시된 ‘dbi’ 값 중 하나입니다.
    • 참고: 이 부분은 다소 유동적입니다. 일반적으로 7-튜플의 처음 두 항목은 항상 존재하며, 나머지는 데이터베이스별로 다를 수 있습니다.
  • close(): 즉시 커서를 닫습니다 ( __del__이 호출될 때까지 기다리지 않음). 이 시점부터 커서는 사용할 수 없으며, 커서로 어떤 작업을 시도하면 예외가 발생합니다.
  • execute(operation [,params]): 데이터베이스 작업 (쿼리 또는 명령)을 실행 (준비)합니다. 매개변수는 시퀀스(예: 튜플/리스트)로 제공될 수 있으며, 작업의 변수에 바인딩됩니다. 변수는 매개변수 튜플의 인덱스(이름 기반이 아닌 위치 기반)에 기반한 데이터베이스별 표기법으로 지정됩니다.
    • 매개변수는 단일 작업으로 여러 행을 삽입하기 위해 시퀀스의 시퀀스(예: 튜플 리스트)로도 지정될 수 있습니다.
    • 작업에 대한 참조는 커서에 의해 유지됩니다. 동일한 작업 객체가 다시 전달되면 커서는 동작을 최적화할 수 있습니다. 이는 동일한 작업을 사용하지만 다른 매개변수가 바인딩되는 알고리즘(여러 번)에 가장 효과적입니다.
    • 작업을 재사용할 때 최대 효율성을 위해서는 setinputsizes() 메서드를 사용하여 매개변수 유형과 크기를 미리 지정하는 것이 가장 좋습니다. 매개변수가 미리 정의된 정보와 일치하지 않는 것이 합법적이며, 구현은 효율성 손실과 함께 보상해야 합니다.
    • SQL 용어를 사용하여, execute() 메서드의 가능한 결과 값은 다음과 같습니다:
      • 문이 DDL (예: CREATE TABLE)인 경우, 1이 반환됩니다.
      • 문이 DML (예: UPDATE 또는 INSERT)인 경우, 영향을 받은 행 수가 반환됩니다 (0 또는 양의 정수).
      • 문이 DQL (예: SELECT)인 경우, None이 반환됩니다. 이는 ‘fetch’ 메서드 중 하나를 사용하기 전까지 문이 실제로 완료되지 않았음을 나타냅니다.
  • fetchone(): 쿼리 결과의 다음 행을 가져와 단일 튜플을 반환합니다.
  • fetchmany([size]): 쿼리 결과의 다음 행 세트를 가져와 튜플 리스트로 반환합니다. 더 이상 행이 없으면 빈 리스트가 반환됩니다. 가져올 행의 수는 매개변수로 지정됩니다. None인 경우, 커서의 arraysize가 가져올 행 수를 결정합니다.
    • size 매개변수와 관련된 성능 고려 사항이 있습니다. 최적의 성능을 위해서는 일반적으로 arraysize 속성을 사용하는 것이 가장 좋습니다. size 매개변수가 사용되는 경우, fetchmany() 호출마다 동일한 값을 유지하는 것이 가장 좋습니다.
  • fetchall(): 쿼리 결과의 모든 행을 가져와 튜플 리스트로 반환합니다. 커서의 arraysize 속성이 이 작업의 성능에 영향을 미칠 수 있습니다.
  • setinputsizes(sizes): (참고: 이 메서드는 아직 잘 정의되지 않았습니다.) execute() 호출 전에 사용하여 작업의 매개변수에 대한 메모리 영역을 미리 정의할 수 있습니다. sizes는 튜플로 지정됩니다 – 각 입력 매개변수에 대해 하나의 항목. 항목은 사용될 입력에 해당하는 Type 객체이거나, 문자열 매개변수의 최대 길이를 지정하는 정수여야 합니다. 항목이 None이면 해당 열에 대해 미리 정의된 메모리 영역이 예약되지 않습니다 (이는 큰 입력에 대해 미리 정의된 영역을 피하는 데 유용합니다).
    • 이 메서드는 execute() 메서드가 호출되기 전에 사용됩니다.
    • 이 메서드는 선택 사항이며, 더 높은 성능의 데이터베이스 상호 작용을 위해 제공됩니다. 구현은 아무것도 하지 않아도 되고, 사용자는 이를 사용하지 않아도 됩니다.
  • setoutputsize(size [,col]): (참고: 이 메서드는 아직 잘 정의되지 않았습니다.) 큰 열 (예: LONG)의 가져오기를 위해 열 버퍼 크기를 설정합니다. 열은 결과 튜플의 인덱스로 지정됩니다. None인 열을 사용하면 커서의 모든 큰 열에 대한 기본 크기가 설정됩니다.
    • 이 메서드는 execute() 메서드가 호출되기 전에 사용됩니다.
    • 이 메서드는 선택 사항이며, 더 높은 성능의 데이터베이스 상호 작용을 위해 제공됩니다. 구현은 아무것도 하지 않아도 되고, 사용자는 이를 사용하지 않아도 됩니다.

DBI 헬퍼 객체 (DBI Helper Objects)

많은 데이터베이스는 작업의 입력 매개변수에 바인딩하기 위해 특정 형식의 입력을 필요로 합니다. 예를 들어, 입력이 DATE 열에 할당될 경우 특정 문자열 형식으로 데이터베이스에 바인딩되어야 합니다. “Row ID” 열 또는 큰 바이너리 항목(예: blobs 또는 RAW 열)에 대해서도 유사한 문제가 존재합니다. execute() 메서드의 매개변수가 형식이 지정되지 않기 때문에 이는 Python에 문제를 제기합니다. 데이터베이스 모듈이 Python 문자열 객체를 볼 때, 그것이 단순한 CHAR 열로 바인딩되어야 하는지, 원시 바이너리 항목으로 바인딩되어야 하는지, 아니면 DATE로 바인딩되어야 하는지 알 수 없습니다.

이 문제를 해결하기 위해 ‘dbi’ 모듈이 생성되었습니다. 이 모듈은 데이터베이스 작업에 대한 몇 가지 기본 데이터베이스 인터페이스 유형을 지정합니다. 두 개의 클래스가 있습니다: dbiDate와 dbiRaw. 이들은 값을 래핑하는 간단한 컨테이너 클래스입니다. 데이터베이스 모듈에 전달될 때, 모듈은 입력 매개변수가 DATE 또는 RAW로 의도되었음을 감지할 수 있습니다. 대칭을 위해, 데이터베이스 모듈은 DATE 및 RAW 열을 이러한 클래스의 인스턴스로 반환할 것입니다.

Cursor Object의 description 속성은 쿼리의 각 결과 열에 대한 정보를 반환합니다. type_code는 이 모듈에서 내보내는 다섯 가지 유형 중 하나로 정의됩니다: STRING, RAW, NUMBER, DATE, 또는 ROWID.

모듈은 다음 이름들을 내보냅니다:

  • dbiDate(value): 날짜 값을 보유하는 dbiDate 인스턴스를 생성하는 함수입니다. 값은 “epoch” 이후의 초 수를 나타내는 정수로 지정되어야 합니다 (예: time.time()).
  • dbiRaw(value): 원시 (이진) 값을 보유하는 dbiRaw 인스턴스를 생성하는 함수입니다. 값은 Python 문자열로 지정되어야 합니다.
  • STRING: 데이터베이스의 문자열 기반 열 (예: CHAR)을 설명하는 데 사용되는 객체입니다.
  • RAW: 데이터베이스의 (큰) 이진 열 (예: LONG RAW, blobs)을 설명하는 데 사용되는 객체입니다.
  • NUMBER: 데이터베이스의 숫자 열을 설명하는 데 사용되는 객체입니다.
  • DATE: 데이터베이스의 날짜 열을 설명하는 데 사용되는 객체입니다.
  • ROWID: 데이터베이스의 “Row ID” 열을 설명하는 데 사용되는 객체입니다.

감사의 말 (Acknowledgements)

Python Database API Specification 1.0을 원본 HTML 형식에서 PEP 형식으로 2001년에 변환해준 Andrew Kuchling에게 많은 감사를 표합니다. Greg Stein은 Python Database API Specification 1.0의 원저자이며, Marc-André Lemburg는 이후 편집자로서 API의 유지 보수를 계속했습니다.

이 문서는 Public Domain에 배포되었습니다.

⚠️ 알림: 이 문서는 AI를 활용하여 번역되었으며, 기술적 정확성을 보장하지 않습니다. 정확한 내용은 반드시 원문을 확인하시기 바랍니다.

Comments