pgLabII/pgLabII.PgUtils/ConnectionStrings/PLAN.md

Connection Strings Plan

This document tracks the plan for supporting multiple PostgreSQL connection string formats, converting between them, and mapping to/from a canonical model.

Current Status (2025-08-31)

Implemented:

• Abstractions: ConnStringFormat, HostEndpoint, ConnectionDescriptor, IConnectionStringCodec, IConnectionStringService.
• Codecs:
  • LibpqCodec (libpq): parse/format; multi-host; sslmode, application_name, connect_timeout; quoting/escaping; preserves extras.
  • NpgsqlCodec (.NET/Npgsql): parse/format; alias recognition; multi-host with single or per-host ports; SSL Mode, Application Name, Timeout; double-quote rules; preserves extras.
  • UrlCodec (postgresql://): parse/format; userinfo, multi-host with per-host ports, IPv6 [::1] handling, database path, percent-decoding/encoding, common params mapping, preserves extras.
• Composite ConnectionStringService (detect + convert) composing Libpq, Npgsql, and Url codecs.
• Mapping helpers to/from ServerConfiguration (primary host/port, database, SSL mode) with sensible defaults.
• Tests:
  • Unit tests for Libpq, Npgsql, and Url codecs (parse/format/round-trip/edge quoting and percent-encoding).
  • ConnectionStringService detection/conversion tests.
  • ServerConfiguration mapping tests.

Not yet implemented:

• JDBC (jdbc:postgresql://) codec

Updated Plan

1. Define canonical model and interfaces for connection strings. ✓
2. Establish normalization strategy for parameter aliases and extra Properties handling. ✓
3. Implement format-specific codecs:
   • libpq codec (parse/format; multi-host, quoting, sslmode, timeout, extras). ✓
   • Npgsql codec (parse/format; aliases, multi-host/ports, quoting, ssl mode, timeout, extras). ✓
   • URL (postgresql://) codec (parse/format; userinfo, host[:port], db, query params, percent-encoding). ✓
   • JDBC (jdbc:postgresql://) codec (parse/format; hosts, ports, db, properties; URL-like semantics).
4. Composite conversion service. ✓
5. Mapping with application model. ✓
6. Validation and UX:
   • Validation for malformed inputs & edge cases (mismatched host/port counts, invalid SSL mode, missing db/host, IPv6 bracket handling). ✓
   • Ensure sensitive fields (password) are masked in logs/preview). ✓
7. Tests:
   • Unit tests for URL codec (parse/format/round-trip/percent-encoding). ✓
   • Tests for composite service detect/convert; mapping functions; cross-format round-trips; edge cases (spaces, quotes, unicode, IPv6, percent-encoding). ✓
   • Unit tests for JDBC codec.
8. Documentation:
   • Keep this plan updated and enrich XML docs on codecs/service including alias mappings and quoting/escaping rules per format. *

Next Small Step

Implement the JDBC (jdbc:postgresql://) codec with unit tests. Scope:

• Parse: jdbc:postgresql://host1[:port1][,hostN[:portN]]/[database]?param=value&...
  • Support multiple hosts with optional per-host ports; IPv6 bracket handling.
  • Recognize common properties (sslmode/SSL, applicationName, loginTimeout/connectTimeout) and preserve unrecognized properties.
  • Ensure URL-like semantics consistent with UrlCodec percent-decoding/encoding.
• Format: Build JDBC URL from ConnectionDescriptor; emit multi-hosts and properties from Properties not already emitted.
• Tests: basic parse/format, multi-host with mixed ports, percent-encoding, round-trips; cross-format conversions via ConnectionStringService.

After that, consider minor documentation polish and any gaps in edge-case validation discovered while adding JDBC support.