eelke/pgLabII
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
pgLabII/pgLabII.PgUtils/ConnectionStrings/PLAN.md
eelke a5cb6ef7d4 added ServerConfigurationMapping 
split up Abstractions so we have one type per file.
2025-08-31 06:49:37 +02:00

3.3 KiB
Raw Blame History

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-30)

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.
  • Tests for both codecs: parse, format, round-trip, edge quoting.

Not yet implemented:

  • URL (postgresql://) codec ✓
  • JDBC (jdbc:postgresql://) codec
  • Composite ConnectionStringService (detect + convert) ✓
  • Mapping helpers to/from ServerConfiguration ✓

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:
    • Implement ConnectionStringService composing codecs, detecting formats, converting via ConnectionDescriptor, and resolving alias priorities.
  5. Mapping with application model:
    • Add mapping utilities between ConnectionDescriptor and ServerConfiguration (primary host/port, db, SSL mode), with sensible defaults.
  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 and JDBC codecs; composite service detect/convert; mapping functions; cross-format round-trips; edge cases (spaces, quotes, unicode, IPv6, percent-encoding).
  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 URL (postgresql://) codec with unit tests. Scope:

  • Parse: postgresql://[user[:password]@]host1[:port1][,hostN[:portN]]/[database]?param=value&...
    • Support percent-decoding for user, password, database, and query values.
    • Handle IPv6 literals in [::1] form; allow multiple hosts with optional per-host ports.
    • Map common params: sslmode, application_name, connect_timeout and preserve other query params in Properties.
  • Format: Build a URL using percent-encoding where required; emit multi-hosts and parameters from Properties not already emitted.
  • Tests: basic parse/format, quoting/percent-encoding, multi-host with mixed ports, round-trips.

After that, implement the composite ConnectionStringService to detect/convert across libpq, Npgsql, and URL formats.