tursodatabase/turso · warning · UserWarning

Unrecognized query parameters ignored: {list(query_params.ke

Error message

Unrecognized query parameters ignored: {list(query_params.keys())}

What it means

The turso SQLAlchemy dialect parses the engine URL's query parameters itself. It pops the known keys - remote_url/sync_url (dialect.py:441), client_name, long_poll_timeout_ms, bootstrap_if_empty (in _extract_sync_params), isolation_level (dialect.py:445), and experimental_features (dialect.py:453). Whatever remains triggers warnings.warn(..., UserWarning) at dialect.py:459 listing the ignored keys: those parameters are silently not applied to the connection, so settings like timeouts actually expected by the application never take effect.

Source

Thrown at bindings/python/turso/sqlalchemy/dialect.py:459

        remote_url = query_params.pop("remote_url", None) or query_params.pop("sync_url", None)
        kwargs = self._extract_sync_params(query_params)

        # Handle isolation_level
        isolation_level = query_params.pop("isolation_level", None)
        if isolation_level:
            if isolation_level.upper() == "AUTOCOMMIT":
                kwargs["isolation_level"] = None
            else:
                kwargs["isolation_level"] = isolation_level

        # Handle experimental_features
        experimental_features = query_params.pop("experimental_features", None)
        if experimental_features:
            kwargs["experimental_features"] = experimental_features

        # Warn about unused query parameters
        if query_params:
            warnings.warn(
                f"Unrecognized query parameters ignored: {list(query_params.keys())}",
                UserWarning,
                stacklevel=2,
            )

        # Return (args, kwargs) for turso.sync.connect(path, remote_url, **kwargs)
        if remote_url:
            return ([path, remote_url], kwargs)
        else:
            # If no remote_url provided, let turso.sync.connect raise the error
            # This allows connect_args to provide remote_url instead
            return ([path], kwargs)

    def get_pool_class(self, url: URL) -> type[Pool]:
        """
        Return the connection pool class.

        For sync connections with file databases, use QueuePool.

View on GitHub (pinned to 244cde92a7)

Solutions

Remove or correct the warned keys; the supported URL keys are remote_url (or sync_url), auth_token, client_name, long_poll_timeout_ms, bootstrap_if_empty, isolation_level, experimental_features.
Check the installed turso version - if the parameter was added later, upgrade the package.
Pass non-URL options via create_engine(..., connect_args={...}) when the underlying turso.sync.connect accepts them.
If the parameter is intentionally unused, silence it in tests: warnings.filterwarnings('ignore', message='Unrecognized query parameters').

Example fix

# before: timeout is not a dialect parameter - warned and ignored
engine = create_engine("turso:///app.db?timeout=30&remote_url=https://db.example.com")

# after: only supported keys in the URL, driver-level options via connect_args
engine = create_engine(
    "turso:///app.db?remote_url=https://db.example.com",
    connect_args={"timeout": 30},
)

Defensive patterns

Strategy: validation

Validate before calling

# Validate the URL before create_engine so unsupported params fail loudly:
from sqlalchemy.engine.url import make_url
SUPPORTED = {"remote_url", "sync_url", "auth_token", "client_name",
            "long_poll_timeout_ms", "bootstrap_if_empty",
            "isolation_level", "experimental_features"}
url = make_url(db_url)
unknown = set(url.query) - SUPPORTED
if unknown:
    raise ValueError(f"unsupported turso URL parameters: {sorted(unknown)}")
engine = create_engine(url)

Type guard

def has_only_supported_turso_params(url: str) -> bool:
    """True if every query key in the URL is consumed by the turso dialect."""
    supported = {"remote_url", "sync_url", "auth_token", "client_name",
                 "long_poll_timeout_ms", "bootstrap_if_empty",
                 "isolation_level", "experimental_features"}
    return set(make_url(url).query) <= supported

Try / catch

with warnings.catch_warnings(record=True) as caught:
    warnings.simplefilter("always")
    engine = create_engine(db_url)
for w in caught:
    if "Unrecognized query parameters" in str(w.message):
        raise ValueError(f"fix connection URL: {w.message}")

Prevention

Build connection URLs programmatically from a validated parameter dict instead of string concatenation.
Run tests with -W error::UserWarning so unrecognized params fail CI instead of silently not applying.
Re-check the dialect's supported parameter list whenever you upgrade the turso package.
Prefer connect_args for anything not representable as a documented URL parameter.

When it happens

Trigger: create_engine("turso:///app.db?timeout=30&auth_token=...&foo=bar") where timeout/foo are not in the dialect's supported set; typo'd keys such as experiemental_features; parameters supported only in a newer turso release; URLs copied from sqlite/libsql dialects.

Common situations: Migrating connection strings from pysqlite or libsql-sqlalchemy dialects, version skew between the dialect docs and the installed turso package, copy-paste from other projects' config files.

Related errors

AI-assisted analysis of tursodatabase/turso@244cde92a7 (2026-08-20). Data as JSON: /api/errors/0663e8259d0b670a. Report an issue: GitHub.