{"record":{"id":"0663e8259d0b670a","repo":"tursodatabase/turso","slug":"unrecognized-query-parameters-ignored-list-query","errorCode":null,"errorMessage":"Unrecognized query parameters ignored: {list(query_params.keys())}","messagePattern":"Unrecognized query parameters ignored: (.+?)","errorType":"validation","errorClass":"UserWarning","httpStatus":null,"severity":"warning","filePath":"bindings/python/turso/sqlalchemy/dialect.py","lineNumber":459,"sourceCode":"        remote_url = query_params.pop(\"remote_url\", None) or query_params.pop(\"sync_url\", None)\n        kwargs = self._extract_sync_params(query_params)\n\n        # Handle isolation_level\n        isolation_level = query_params.pop(\"isolation_level\", None)\n        if isolation_level:\n            if isolation_level.upper() == \"AUTOCOMMIT\":\n                kwargs[\"isolation_level\"] = None\n            else:\n                kwargs[\"isolation_level\"] = isolation_level\n\n        # Handle experimental_features\n        experimental_features = query_params.pop(\"experimental_features\", None)\n        if experimental_features:\n            kwargs[\"experimental_features\"] = experimental_features\n\n        # Warn about unused query parameters\n        if query_params:\n            warnings.warn(\n                f\"Unrecognized query parameters ignored: {list(query_params.keys())}\",\n                UserWarning,\n                stacklevel=2,\n            )\n\n        # Return (args, kwargs) for turso.sync.connect(path, remote_url, **kwargs)\n        if remote_url:\n            return ([path, remote_url], kwargs)\n        else:\n            # If no remote_url provided, let turso.sync.connect raise the error\n            # This allows connect_args to provide remote_url instead\n            return ([path], kwargs)\n\n    def get_pool_class(self, url: URL) -> type[Pool]:\n        \"\"\"\n        Return the connection pool class.\n\n        For sync connections with file databases, use QueuePool.","sourceCodeStart":441,"sourceCodeEnd":477,"githubUrl":"https://github.com/tursodatabase/turso/blob/244cde92a7df7f9b8b8b7a4075c35a12977e303e/bindings/python/turso/sqlalchemy/dialect.py#L441-L477","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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')."],"exampleFix":"# before: timeout is not a dialect parameter - warned and ignored\nengine = create_engine(\"turso:///app.db?timeout=30&remote_url=https://db.example.com\")\n\n# after: only supported keys in the URL, driver-level options via connect_args\nengine = create_engine(\n    \"turso:///app.db?remote_url=https://db.example.com\",\n    connect_args={\"timeout\": 30},\n)","handlingStrategy":"validation","validationCode":"# Validate the URL before create_engine so unsupported params fail loudly:\nfrom sqlalchemy.engine.url import make_url\nSUPPORTED = {\"remote_url\", \"sync_url\", \"auth_token\", \"client_name\",\n            \"long_poll_timeout_ms\", \"bootstrap_if_empty\",\n            \"isolation_level\", \"experimental_features\"}\nurl = make_url(db_url)\nunknown = set(url.query) - SUPPORTED\nif unknown:\n    raise ValueError(f\"unsupported turso URL parameters: {sorted(unknown)}\")\nengine = create_engine(url)","typeGuard":"def has_only_supported_turso_params(url: str) -> bool:\n    \"\"\"True if every query key in the URL is consumed by the turso dialect.\"\"\"\n    supported = {\"remote_url\", \"sync_url\", \"auth_token\", \"client_name\",\n                 \"long_poll_timeout_ms\", \"bootstrap_if_empty\",\n                 \"isolation_level\", \"experimental_features\"}\n    return set(make_url(url).query) <= supported","tryCatchPattern":"with warnings.catch_warnings(record=True) as caught:\n    warnings.simplefilter(\"always\")\n    engine = create_engine(db_url)\nfor w in caught:\n    if \"Unrecognized query parameters\" in str(w.message):\n        raise ValueError(f\"fix connection URL: {w.message}\")","preventionTips":["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."],"tags":["python","sqlalchemy","connection-string","query-parameters","warning","dialect","turso"],"backgroundTag":"invalid-connection-string-parameter","analyzedSha":"244cde92a7df7f9b8b8b7a4075c35a12977e303e","analyzedAt":"2026-08-20T07:02:18.389Z","contentChangedAt":"2026-08-20T07:02:18.389Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}