Copy page

DAL Library

Dal Gateway

Dal Gateway

Relevant source files

The following files were used as context for generating this wiki page:

• docs/ai/dal-usage-guide.md
• src/dal/dal.ts

The Dal class serves as the high-level entry point for the @primebrick/dal-pg library. It centralizes pool management, type parsing, and session configuration into a single process-wide gateway. While the Repository class handles the low-level SQL generation and execution, the Dal class provides the infrastructure and lifecycle management required for robust database interactions in a high-concurrency environment.

Core Responsibilities

The Dal gateway is designed to solve three primary concerns:

1. Pool Ownership & Lifecycle: Managing a pg.Pool with best-practice defaults to prevent connection exhaustion and "stuck" queries.
2. Singleton Pattern: Ensuring a single instance per database connection string to avoid redundant resource allocation.
3. Type Parser Registration: Automatically configuring global PostgreSQL-to-JS type mappings (e.g., INT8 to bigint) upon initialization.

System Architecture

The following diagram illustrates how the Dal class bridges the application code with the underlying PostgreSQL driver and the internal Repository engine.

Dal Gateway Context Diagram

Code
graph TD
    subgraph "Application Space"
        [AppCode] --> |"getDal(config)"| DAL["Dal (Singleton)"]
    end

    subgraph "Code Entity Space (Internal)"
        DAL --> |"owns"| POOL["pg.Pool"]
        DAL --> |"delegates to"| REPO["Repository"]
        DAL --> |"initializes"| TP["type-parsers.ts"]
    end

    subgraph "Database Space"
        POOL --> |"manages"| CONN["PostgreSQL Connections"]
        CONN --> |"SET application_name"| PG_STAT["pg_stat_activity"]
    end

    [AppCode] -.-> |"Optional Transaction"| WC["dal.withClient()"]
    WC --> |"provides"| REPO_CLIENT["Repository (PoolClient)"]

Sources: src/dal/dal.ts:1-31, src/dal/dal.ts:101-170

---

Key Components

Singleton Gateway (getDal)

The library enforces a singleton pattern via the getDal() factory. This ensures that the same pg.Pool is reused across all requests, preventing memory leaks and connection spikes. If a consumer attempts to call getDal() with a different connection string than the one already initialized, the library throws an error to prevent accidental multi-DB cross-talk within a single instance.

Type Parser Registration

Upon construction, the Dal class calls ensureTypeParsers(). This is an idempotent operation that registers global parsers for PostgreSQL types that do not map naturally to JavaScript, such as converting INT8 (bigint) and NUMERIC to appropriate JS types. Sources: src/dal/dal.ts:127-128, src/dal/dal.ts:25-36

Session Configuration (onConnect)

Every time the pool creates a new connection, the Dal gateway executes an onConnect hook. This hook standardizes the session environment by setting:

• search_path: Ensures queries target the correct schema.
• statement_timeout: Prevents runaway queries from starving the pool.
• application_name: Improves observability in pg_stat_activity.

For details on how these settings are applied and managed, see Connection Pool and Session Configuration.

---

Anti-Throttling and Safety Patterns

The Dal gateway is built with a "fail-fast" and "anti-throttling" philosophy. By default, it applies a statement_timeout (default 30s) to every connection. This ensures that if a query hangs or a network partition occurs, the connection is eventually released back to the pool rather than being held indefinitely.

Timeout Interaction Map

Mechanism	Scope	Description
statementTimeoutMs	Session	Global default set on every connection in the pool.
withClient({ timeoutMs })	Client	Temporary override for a single client session; reset on release.
BulkOptions.timeoutMs	Transaction	Applied via SET LOCAL for the duration of a bulk operation.

For details on manual transaction management and timeout overrides, see Timeout Management and withClient.

Sources: src/dal/dal.ts:15-31, docs/ai/dal-usage-guide.md:124-133

---

Child Pages

• Connection Pool and Session Configuration: Deep dive into pg.Pool initialization, the DalConfig schema, and the onConnect lifecycle.
• Timeout Management and withClient: Details on the withClient pattern for transactions and strategies for preventing timeout leakage.

---