Excel-Pajak-Generator-Ak/openspec/specs/postgresql-query/spec.md

ADDED Requirements

Requirement: Configuration loading from appsettings.json

The system SHALL load the PostgreSQL connection string from appsettings.json using the ConnectionStrings:DefaultConnection configuration key.

Scenario: Successful configuration loading

• WHEN the application starts and appsettings.json exists with a valid ConnectionStrings:DefaultConnection entry
• THEN the system shall successfully load the connection string
• AND the connection string shall be available for database connections

Scenario: Missing connection string

• WHEN the application starts and appsettings.json is missing the ConnectionStrings:DefaultConnection entry
• THEN the system shall throw an InvalidOperationException with a clear error message indicating the missing configuration

Scenario: Invalid appsettings.json format

• WHEN the application starts and appsettings.json contains invalid JSON
• THEN the system shall throw a configuration exception indicating the JSON parsing error

Requirement: Database query execution

The system SHALL provide a function that accepts a SQL query string and returns the first column of the first row as a string value.

Scenario: Successful query execution with single result

• WHEN a valid SQL query is executed that returns a single row with a single column
• THEN the system shall return the value as a string
• AND the database connection shall be properly opened and closed

Scenario: Query returning NULL value

• WHEN a SQL query is executed that returns a NULL value in the first column of the first row
• THEN the system shall return null instead of throwing an exception

Scenario: Query returning no rows

• WHEN a SQL query is executed that returns zero rows
• THEN the system shall return null

Scenario: Invalid SQL syntax

• WHEN a SQL query with invalid syntax is executed
• THEN the system shall throw a PostgresException with the PostgreSQL error details

Scenario: Database connection failure

• WHEN the database server is unreachable or credentials are invalid
• THEN the system shall throw a PostgresException or NpgsqlException with connection error details

Requirement: Connection management

The system SHALL properly manage database connections using proper disposal patterns to prevent connection leaks.

Scenario: Connection properly disposed after query

• WHEN a query is executed successfully
• THEN the database connection shall be disposed after the query completes
• AND the connection shall be returned to the connection pool

Scenario: Connection disposed on exception

• WHEN a query execution throws an exception
• THEN the database connection shall still be properly disposed
• AND no connection leak shall occur

Requirement: Static Service Initialization

The system SHALL provide a static method to initialize the database service with a connection string.

Scenario: Successful static initialization

• WHEN the Initialize method is called with a valid connection string
• THEN the static internal state shall be updated
• AND subsequent query calls shall use this connection string

Requirement: Synchronous Database Query Execution

The system SHALL provide static functions that accept SQL query strings and return results synchronously.

Scenario: Successful synchronous query execution

• WHEN a valid SQL query is executed via a static method
• THEN the system shall return the result string synchronously
• AND the database connection shall be properly opened and closed synchronously

Requirement: Static Configuration Access

The system SHALL provide static access to configuration properties through a dedicated service.

Scenario: Accessing connection string via static method

• WHEN the static GetConnectionString() method is called
• THEN it shall return the connection string from the internal static configuration
• AND it shall throw an InvalidOperationException if the configuration is missing the required key

Requirement: Static Configuration Initialization

The system SHALL provide a way to initialize the static configuration state.

Scenario: Default static initialization

• WHEN the configuration service is first accessed without explicit initialization
• THEN it shall automatically load configuration from appsettings.json

Scenario: Explicit static initialization

• WHEN the Initialize method is called with a custom IConfiguration object
• THEN the static internal state shall be updated with the provided configuration