Skip to content

URL

deep_db_agents.url

Database URL parsing.

Two supported forms:

  • Network DBs (mysql, postgres, mongodb, neo4j…): <scheme>://<host>:<port>.
  • File-based DBs (sqlite, duckdb): <scheme>://<path> where <path> is the file path (or directory, for the DuckDB data lake) following the SQLAlchemy convention: sqlite:///rel.db is relative to the working dir, sqlite:////abs.db is absolute, sqlite://:memory: is in-memory.

ParsedUrl dataclass 

ParsedUrl(scheme: str, host: str | None, port: int | None, path: str | None = None)

Components of a database URL.

scheme is normalized to lowercase and is what selects the dialect. host/port are set for network DBs; path is set for file-based DBs (with :memory: for in-memory databases). A trailing slash in path indicates a directory (DuckDB data lake).

Attributes:

Name Type Description
scheme str

The normalized (lowercase) URL scheme.
host str | None

Hostname for network databases, or None for file-based databases.
port int | None

Port for network databases, or None for file-based databases.
path str | None

File/directory path for file-based databases, or None for network databases.

parse_db_url 

parse_db_url(db_url: str) -> ParsedUrl

Extract the components from a <scheme>://<host>:<port> or <scheme>://<path> URL.

Parameters:

Name Type Description Default
db_url str

The database URL to parse.

 required

Returns:

Name Type Description
ParsedUrl ParsedUrl

The parsed URL components.

Raises:

Type Description
InvalidDbUrlError

If db_url is not a string, has no "://" separator, has an empty scheme, or (for network schemes) has a non-numeric port.

Examples:

>>> parse_db_url("mysql://localhost:3306")
ParsedUrl(scheme='mysql', host='localhost', port=3306, path=None)
>>> parse_db_url("sqlite:///data/app.db")
ParsedUrl(scheme='sqlite', host=None, port=None, path='data/app.db')
Source code in src/deep_db_agents/url.py 
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
def parse_db_url(db_url: str) -> ParsedUrl:
    """Extract the components from a ``<scheme>://<host>:<port>`` or ``<scheme>://<path>`` URL.

    Args:
        db_url: The database URL to parse.

    Returns:
        ParsedUrl: The parsed URL components.

    Raises:
        InvalidDbUrlError: If ``db_url`` is not a string, has no ``"://"`` separator,
            has an empty scheme, or (for network schemes) has a non-numeric port.

    Examples:
        >>> parse_db_url("mysql://localhost:3306")
        ParsedUrl(scheme='mysql', host='localhost', port=3306, path=None)
        >>> parse_db_url("sqlite:///data/app.db")
        ParsedUrl(scheme='sqlite', host=None, port=None, path='data/app.db')
    """
    if not isinstance(db_url, str) or "://" not in db_url:
        raise InvalidDbUrlError(
            f"Invalid URL: {db_url!r}. Expected format '<scheme>://<host>:<port>'."
        )

    scheme = db_url.split("://", 1)[0].lower().strip()
    if not scheme:
        raise InvalidDbUrlError(f"Missing scheme in URL: {db_url!r}.")

    if scheme in FILE_SCHEMES:
        return _parse_file_url(scheme, db_url)

    parts = urlsplit(db_url)
    try:
        port = parts.port
    except ValueError as exc:  # non-numeric port
        raise InvalidDbUrlError(f"Invalid port in URL: {db_url!r}.") from exc

    return ParsedUrl(scheme=scheme, host=parts.hostname, port=port)