Skip to content

Runtime Introspection & DDL Synthesis

from sqlspec.driver import AsyncDataDictionaryBase, SyncDataDictionaryBase

Runtime introspection, DDL extraction, and column profiling methods provided by driver.data_dictionary on SyncDriverAdapterBase and AsyncDriverAdapterBase. For dialect-specific system catalog SQL queries (-- name: ...) and capability profiles, see Dialect SQL Catalogs.

Synchronous Introspection

SyncDataDictionaryBase

Bases: DataDictionaryDialectMixin, DataDictionaryMixin

Base class for synchronous data dictionary implementations.

Uses Python-compatible class layouts for cross-module inheritance. Child classes define dialect as a class attribute.

get_version

get_version(driver)

Get database version information.

Parameters:

Name Type Description Default
driver Any

Sync database driver instance

required

Returns:

Type Description
VersionInfo | None

Version information or None if detection fails

get_feature_flag

get_feature_flag(driver, feature)

Check if database supports a specific feature.

Parameters:

Name Type Description Default
driver Any

Sync database driver instance

required
feature str

Feature name to check

required

Returns:

Type Description
bool

True if feature is supported, False otherwise

get_optimal_type

get_optimal_type(driver, type_category)

Get optimal database type for a category.

Parameters:

Name Type Description Default
driver Any

Sync database driver instance

required
type_category str

Type category

required

Returns:

Type Description
str

Database-specific type name

get_metadata_capabilities

get_metadata_capabilities(driver, domains=None)

Get data-dictionary capability profile.

Parameters:

Name Type Description Default
driver Any

Sync database driver instance.

required
domains Sequence[str] | None

Optional metadata domains to report.

None

Returns:

Type Description
MetadataCapabilityProfile

Capability profile. Base implementations report requested domains as unsupported.

get_schemas

get_schemas(driver)

Get schema metadata or an unsupported-domain result.

get_tables

get_tables(driver, schema=None)

Get list of tables in schema.

Parameters:

Name Type Description Default
driver Any

Sync database driver instance

required
schema str | None

Schema name (None for default)

None

Returns:

Type Description
list[TableMetadata]

List of table metadata dictionaries

get_columns

get_columns(driver, table=None, schema=None)

Get column information for a table or schema.

Parameters:

Name Type Description Default
driver Any

Sync database driver instance

required
table str | None

Table name (None to fetch columns for all tables in schema)

None
schema str | None

Schema name (None for default)

None

Returns:

Type Description
list[ColumnMetadata]

List of column metadata dictionaries

get_indexes

get_indexes(driver, table=None, schema=None)

Get index information for a table or schema.

Parameters:

Name Type Description Default
driver Any

Sync database driver instance

required
table str | None

Table name (None to fetch indexes for all tables in schema)

None
schema str | None

Schema name (None for default)

None

Returns:

Type Description
list[IndexMetadata]

List of index metadata dictionaries

get_foreign_keys

get_foreign_keys(driver, table=None, schema=None)

Get foreign key metadata.

Parameters:

Name Type Description Default
driver Any

Sync database driver instance

required
table str | None

Optional table name filter

None
schema str | None

Optional schema name filter

None

Returns:

Type Description
list[ForeignKeyMetadata]

List of foreign key metadata

get_constraints

get_constraints(driver, table=None, schema=None)

Get constraint metadata or an unsupported-domain result.

get_views

get_views(driver, schema=None)

Get view metadata or an unsupported-domain result.

get_routines

get_routines(driver, schema=None)

Get routine metadata or an unsupported-domain result.

get_sequences

get_sequences(driver, schema=None)

Get sequence metadata or an unsupported-domain result.

get_types

get_types(driver, schema=None)

Get user-defined type metadata or an unsupported-domain result.

get_ddl

get_ddl(
    driver,
    object_name,
    schema=None,
    *,
    object_type="table",
    include_dependencies=True,
    prefer_native=True,
    redact=True,
    target_dialect=None,
)

Get object DDL or an explicit unsupported DDL result.

Public alias of :meth:get_object_ddl that accepts schema positionally.

get_object_ddl

get_object_ddl(
    driver,
    object_name,
    *,
    schema=None,
    object_type="table",
    include_dependencies=True,
    prefer_native=True,
    redact=True,
    target_dialect=None,
)

Get one object's DDL or an explicit unsupported DDL result.

object_name and schema are caller input and follow the dialect's identifier normalization (quote a name to match it exactly). Native catalog DDL is preferred; table DDL is synthesized from catalog metadata when prefer_native is False, when a target_dialect is requested, or when native DDL is unavailable.

Parameters:

Name Type Description Default
driver Any

Database driver instance.

required
object_name str

Object name.

required
schema str | None

Schema name, or None for the dialect default.

None
object_type str

Object kind such as table, view, or sequence.

'table'
include_dependencies bool

Whether native helpers should report dependencies.

True
prefer_native bool

Prefer native catalog DDL over synthesized DDL.

True
redact bool

Whether native helpers should redact sensitive values.

True
target_dialect str | None

Dialect to render or transpile the DDL into.

None

Returns:

Type Description
DDLResult

DDL result for the object.

get_schema_ddl

get_schema_ddl(
    driver,
    schema=None,
    *,
    include_domains=None,
    exclude_domains=None,
    exclude_tables=(),
    direction="create",
    include_dependencies=True,
    prefer_native=True,
    redact=True,
    target_dialect=None,
)

Get schema DDL items in topological dependency order.

When prefer_native is set and no target_dialect is requested, adapters with a native schema DDL source supply the objects; tables whose native DDL is not faithful are synthesized from catalog metadata. Otherwise types, sequences, tables, and views are collected, and tables are synthesized from schema-wide catalog queries. direction="drop" only collects object identities and dependency edges; it never synthesizes table DDL. Domains that cannot be collected are reported in the result warnings.

Parameters:

Name Type Description Default
driver Any

Database driver instance.

required
schema str | None

Schema name, or None for the dialect default.

None
include_domains Sequence[str] | None

Domains to include (tables, views, sequences, types, ...).

None
exclude_domains Sequence[str] | None

Domains to exclude.

None
exclude_tables Sequence[str] | None

Table names to omit, matched as bare, unquoted, case-insensitive names with any schema qualification stripped.

()
direction Literal['create', 'drop']

create for CREATE statements in dependency order, drop for DROP ... IF EXISTS statements in reverse dependency order.

'create'
include_dependencies bool

Collect foreign keys and dependencies to order the output.

True
prefer_native bool

Prefer native catalog DDL over synthesized DDL.

True
redact bool

Whether native helpers should redact sensitive values.

True
target_dialect str | None

Dialect to render or transpile the DDL into.

None

Returns:

Type Description
MetadataResult

Schema DDL result.

get_table_profile

get_table_profile(
    driver, table, schema=None, *, sample_size=1000, target_dialect=None
)

Profile live table columns and infer refined SQL types from existing data.

Query failures (for example missing privileges) propagate to the caller.

infer_table_ddl_from_data

infer_table_ddl_from_data(
    driver,
    table,
    schema=None,
    *,
    target_table=None,
    target_dialect=None,
    sample_size=1000,
    primary_key=None,
)

Synthesize a refined table DDLResult by profiling live table data.

get_system_metadata

get_system_metadata(driver, request=None, **kwargs)

Get opt-in system metadata or a gated/unsupported result.

Asynchronous Introspection

AsyncDataDictionaryBase exposes async counterparts for every method on SyncDataDictionaryBase above:

AsyncDataDictionaryBase

Bases: DataDictionaryDialectMixin, DataDictionaryMixin

Base class for asynchronous data dictionary implementations.

Uses Python-compatible class layouts for cross-module inheritance. Child classes define dialect as a class attribute.