Skip to content

Service

home / developer / concepts / database / service

Overview

The DatabaseService is the foundation layer for PostgreSQL database operations, providing robust connection management, session handling, health monitoring, and error recovery with automatic retry logic and exponential backoff.

Architecture

Connection Lifecycle

The service manages PostgreSQL connections through well-defined states: disconnected, connected, and error states with automatic retry logic for transient failures.

Session Factory Pattern

Sessions are created through a factory pattern ensuring consistency with proper async session configuration, automatic transaction handling, and context manager support.

Retry Logic Implementation

Operations include automatic retry with exponential backoff for handling transient database failures, Docker container startup delays, and network resilience.

Key Concepts

Async Session Context Managers

Sessions provide automatic resource management with context managers that ensure proper cleanup, automatic commit/rollback, and exception safety.

Connection Pooling Configuration

PostgreSQL connections are efficiently pooled with pre-ping validation, periodic recycling, and async driver support for optimal performance in high-concurrency workloads.

Health Checks

Monitor database connectivity and performance with basic connectivity tests and status reporting for operational monitoring.

Sentry Integration

Performance monitoring and error tracking with spans, error context, attempt tracking, and status updates for observability.

Retry Logic with Exponential Backoff

Handles transient failures gracefully with configurable max retries, exponential backoff timing, and selective retryable error handling.

Usage Patterns

Session Context Manager Usage

Always use context managers for session management to ensure automatic cleanup and proper transaction handling.

Health Check Pattern

Implement health checks for monitoring database connectivity and responsiveness.

Batch Operations

Use sessions for batch operations to ensure all operations occur within single transactions.

Best Practices

Always Use Context Managers

  • Automatic cleanup of sessions and resources
  • Exception safety with proper rollback handling
  • No resource leaks or manual management required

Configure Connection Pooling Appropriately

Set appropriate pool sizes, recycle intervals, and pre-ping validation for production workloads.

Handle Connection Errors Gracefully

Implement reconnection logic and proper error handling for operational resilience.

Monitor Connection Health

Regular health checks and monitoring for proactive issue detection and alerting.

Use Appropriate Error Handling Levels

  • Connection errors at service level with retries
  • Query errors at controller level with user-friendly messages
  • Validation errors at application level with specific feedback

Log Database Operations Appropriately

Use appropriate log levels for different types of database operations and events.