or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

connection-management.mdcustom-types.mdexception-handling.mdindex.mdlegacy-dbapi.mdnative-interface.mdpostgresql-types.md
tile.json

tessl/pypi-pg8000

Pure-Python PostgreSQL driver providing DB-API 2.0 compliant database connectivity with native pg8000 API and comprehensive PostgreSQL data type support.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/pg8000@1.31.x

To install, run

npx @tessl/cli install tessl/pypi-pg8000@1.31.0

index.mddocs/

pg8000

A pure-Python PostgreSQL driver that provides DB-API 2.0 compliant database connectivity with comprehensive PostgreSQL data type support. pg8000 offers both a legacy DB-API 2.0 interface for compatibility with standard Python database patterns and a modern native interface for streamlined usage.

Package Information

  • Package Name: pg8000
  • Package Type: pypi
  • Language: Python
  • Installation: pip install pg8000

Core Imports

import pg8000

For legacy DB-API 2.0 interface:

import pg8000
# Use pg8000.connect() to get Connection objects

For native interface:

import pg8000.native
# Use pg8000.native.Connection directly

Module Constants

__version__: str
"""Package version string."""

apilevel: str = "2.0"
"""DBAPI level supported by pg8000."""

threadsafety: int = 1
"""Thread safety level - module sharing only, connections not thread-safe."""

paramstyle: str = "format"
"""Parameter style used for SQL queries."""

Basic Usage

Legacy DB-API 2.0 Interface

import pg8000

# Connect to database
conn = pg8000.connect(
    user="username",
    password="password", 
    host="localhost",
    port=5432,
    database="mydb"
)

# Create cursor and execute query
cursor = conn.cursor()
cursor.execute("SELECT version()")
result = cursor.fetchone()
print(result)

# Commit and close
conn.commit()
cursor.close()
conn.close()

Native Interface

import pg8000.native

# Connect to database
conn = pg8000.native.Connection(
    user="username",
    password="password",
    host="localhost", 
    port=5432,
    database="mydb"
)

# Execute query directly
result = conn.run("SELECT version()")
print(result)

# Close connection
conn.close()

Architecture

pg8000 provides two distinct interfaces:

  • Legacy DB-API 2.0 Interface: Complete Python Database API specification compliance with Connection and Cursor objects, supporting traditional database programming patterns including transactions, prepared statements, and cursor-based result iteration.

  • Native Interface: Streamlined API optimized for modern Python usage with direct query execution, automatic parameter handling, and simplified connection management.

Both interfaces share the same comprehensive PostgreSQL type system, supporting all standard PostgreSQL data types including arrays, JSON/JSONB, UUIDs, ranges, intervals, and network types with automatic Python conversion.

Capabilities

Connection Management

Primary functions for establishing and managing database connections using both legacy DB-API 2.0 and native interfaces.

def connect(
    user: str,
    host: str = "localhost", 
    database: str = None,
    port: int = 5432,
    password: str = None,
    source_address: tuple = None,
    unix_sock: str = None,
    ssl_context = None,
    timeout: float = None,
    tcp_keepalive: bool = True,
    application_name: str = None,
    replication: str = None,
    startup_params: dict = None,
    sock = None
) -> Connection: ...

Connection Management

Legacy DB-API 2.0 Interface

Standard Python Database API 2.0 compliant interface with Connection and Cursor classes for compatibility with existing database code.

class Connection:
    def cursor(self) -> Cursor: ...
    def commit(self) -> None: ...
    def rollback(self) -> None: ...
    def run(self, sql: str, stream=None, **params) -> tuple: ...
    def close(self) -> None: ...

class Cursor:
    def execute(self, operation: str, args: tuple = (), stream=None) -> Cursor: ...
    def fetchone(self) -> tuple: ...
    def fetchmany(self, num: int = None) -> tuple: ...
    def fetchall(self) -> tuple: ...
    def close(self) -> None: ...

Legacy DB-API 2.0 Interface

Native Interface

Modern streamlined interface optimized for direct query execution with automatic parameter handling and simplified result processing.

class Connection:
    def run(self, sql: str, stream=None, types=None, **params) -> list: ...
    def prepare(self, sql: str) -> PreparedStatement: ...
    def close(self) -> None: ...

class PreparedStatement:
    def run(self, stream=None, **params) -> list: ...
    def close(self) -> None: ...

Native Interface

PostgreSQL Data Types

Comprehensive support for all PostgreSQL data types with automatic Python conversion, including numeric types, text types, date/time types, arrays, JSON, network types, and custom types.

# Type constants
BIGINT: int = 20
INTEGER: int = 23
TEXT: int = 25
BOOLEAN: int = 16
JSON: int = 114
JSONB: int = 3802
UUID_TYPE: int = 2950
INTEGER_ARRAY: int = 1007
TEXT_ARRAY: int = 1009

PostgreSQL Data Types

Custom Types

Custom Python classes for PostgreSQL-specific data types including intervals and ranges.

class PGInterval:
    @classmethod
    def from_str(cls, interval_str: str) -> PGInterval: ...
    def normalize(self) -> PGInterval: ...
    def to_timedelta(self) -> timedelta: ...

class Range:
    def __init__(self, lower=None, upper=None, bounds: str = "[)", is_empty: bool = False): ...

Custom Types

Exception Handling

Complete exception hierarchy for proper error handling following DB-API 2.0 standards.

class Error(Exception): ...
class DatabaseError(Error): ...
class InterfaceError(Error): ...
class DataError(DatabaseError): ...
class OperationalError(DatabaseError): ...
class IntegrityError(DatabaseError): ...
class InternalError(DatabaseError): ...
class ProgrammingError(DatabaseError): ...
class NotSupportedError(DatabaseError): ...

Exception Handling