connparse

Connparse parses database connection strings, DSNs, URLs, file paths, and cloud storage URIs into one predictable Python dict.

Connparse is useful when your app accepts connection strings from different systems and you want to pull out the host, port, database, bucket, path, credentials, query options, and a safe redacted string.

Supported sources include PostgreSQL, MySQL, MariaDB, SQLite, DuckDB, ClickHouse, Redis, Memcached, Elasticsearch, MongoDB, CockroachDB, QuestDB, YugabyteDB, TiDB, Valkey, Dragonfly, OpenSearch, FerretDB, ElastiCache, DocumentDB, SQL Server, Oracle, Snowflake, Cassandra, BigQuery, Redshift, Aurora, Neo4j, Trino, Databricks, DynamoDB, StarRocks, SAP HANA, Athena, Spanner, Google Cloud Storage, Azure Blob, Azure Data Lake Storage, Azure Files, Azure Cosmos DB, Business Central, TallyPrime, Amazon S3, and local file paths.

Install

pip install connparse

Basic Usage

from connparse import parse

result = parse("postgres://user:pass@localhost:5432/app?sslmode=require")

if not result["ok"]:
    print(result["errors"])
else:
    print(result["value"])

Result:

{
  "scheme": "postgres",
  "type": "database",
  "authority": {
    "host": "localhost",
    "port": 5432
  },
  "resource": {
    "type": "database",
    "name": "app"
  },
  "path": "",
  "query": {
    "sslmode": "require"
  },
  "fragment": null,
  "credentials": {
    "username": "user",
    "password": "pass"
  },
  "options": {},
  "raw": "postgres://user:pass@localhost:5432/app?sslmode=require",
  "safe": "postgres://user:***@localhost:5432/app?sslmode=require"
}

Recommended Usage

Use parse() for form handling, validation, and showing parsed connection details to users.

result = parse(input)

if result["ok"]:
    address = result["value"]
    save_connection(
        host=address["authority"].get("host"),
        port=address["authority"].get("port"),
        database=address["resource"]["name"],
        safe_label=address["safe"],
    )

Use safe for logs and UI labels. Do not log raw or credentials unless the user explicitly asks to reveal secrets.

logger.info("connection=%s", result["value"]["safe"])

Use parse_normalize() when you need a stable identity for dedupe, cache keys, or config comparison.

from connparse import parse_normalize

parse_normalize("postgresql://LOCALHOST:5432/app?sslmode=require")["value"]["canonical"]
# "postgres://localhost/app?sslmode=require"

Use provider when the string does not clearly identify the source type.

parse("host=db.example.com port=5432 dbname=app user=alice", {
    "provider": "postgres",
})

parse("https://clickhouse.example.com:8443/default", {
    "provider": "clickhouse",
})

Use strict when you want unknown query parameters to fail validation.

parse("postgres://localhost/app?unexpected=1", {"strict": True})

Examples