Migration Guide: v0.33.0¶

Configuration Parameter Renaming¶

SQLSpec v0.33.0 renames configuration parameters for consistency across all database adapters.

Changed Parameters¶

Old Name	New Name	Affected Configs
`pool_config`	`connection_config`	All adapters
`pool_instance`	`connection_instance`	All adapters

Migration Steps¶

Update your configuration instantiation to use the new parameter names:

# Before (deprecated, will be removed in v0.34.0)
from sqlspec.adapters.asyncpg import AsyncpgConfig

config = AsyncpgConfig(
    pool_config={"dsn": "postgresql://localhost/mydb"},
    pool_instance=existing_pool,
)

# After (recommended)
from sqlspec.adapters.asyncpg import AsyncpgConfig

config = AsyncpgConfig(
    connection_config={"dsn": "postgresql://localhost/mydb"},
    connection_instance=existing_pool,
)

Rationale¶

The new parameter names accurately reflect usage across both:

Pooled adapters (AsyncPG, DuckDB, Psycopg, etc.) - where the parameters configure connection pools
Non-pooled adapters (BigQuery, ADBC, Spanner) - where the parameters configure individual connections

This eliminates conceptual confusion and provides consistent API across all adapters.

Backwards Compatibility¶

Deprecation Period: v0.33.0 - v0.33.x

Old parameter names continue to work with deprecation warnings. You will see warnings like:

DeprecationWarning: Use of deprecated parameter 'pool_config'.
Deprecated in SQLSpec 0.33.0.
This parameter will be removed in 0.34.0.
Use 'connection_config' instead.
Parameter renamed for consistency across pooled and non-pooled adapters.

Breaking Change: v0.34.0

Old parameter names will be completely removed in v0.34.0. Update your code during the deprecation period to avoid breakage.

Affected Adapters¶

All database adapter configurations are affected:

Async Pooled: AsyncPG, Asyncmy, Aiosqlite, Psqlpy, Psycopg (async), Spanner (async), Oracle (async)
Sync Pooled: DuckDB, SQLite, Psycopg (sync), Spanner (sync), Oracle (sync)
Non-pooled: BigQuery, ADBC

Type Checking¶

Type checkers (mypy, pyright) will not autocomplete or recognize the old parameter names. This is intentional to encourage migration to the new names.

Examples¶

AsyncPG (Pooled)¶

from sqlspec.adapters.asyncpg import AsyncpgConfig

# Old
config = AsyncpgConfig(
    pool_config={"dsn": "postgresql://localhost/db", "min_size": 5, "max_size": 10}
)

# New
config = AsyncpgConfig(
    connection_config={"dsn": "postgresql://localhost/db", "min_size": 5, "max_size": 10}
)

BigQuery (Non-pooled)¶

from sqlspec.adapters.bigquery import BigQueryConfig

# Old
config = BigQueryConfig(
    pool_config={"project": "my-project"}
)

# New
config = BigQueryConfig(
    connection_config={"project": "my-project"}
)

Pre-created Pool Instance¶

import asyncpg
from sqlspec.adapters.asyncpg import AsyncpgConfig

pool = await asyncpg.create_pool(dsn="postgresql://localhost/db")

# Old
config = AsyncpgConfig(pool_instance=pool)

# New
config = AsyncpgConfig(connection_instance=pool)

Search and Replace¶

For quick migration across your codebase:

# Find all occurrences
grep -r "pool_config" . --include="*.py"
grep -r "pool_instance" . --include="*.py"

# Replace (GNU sed)
find . -name "*.py" -exec sed -i 's/pool_config=/connection_config=/g' {} +
find . -name "*.py" -exec sed -i 's/pool_instance=/connection_instance=/g' {} +

Review changes carefully after automated replacement to ensure correctness.

Questions?¶

If you encounter issues during migration:

Check that you’re using SQLSpec v0.33.0 or later
Verify deprecation warnings appear (ensures old names are recognized)
Update to new parameter names when you see warnings
Test your application thoroughly after migration

Report migration issues at: https://github.com/litestar-org/sqlspec/issues