al-data-utils 0.3.1__py3-none-any.whl

al_data_utils/backup_utils/mssql/schema_snapshot/snapshot_processor.py

@@ -0,0 +1,754 @@
+from __future__ import annotations
+
+from collections import defaultdict
+from dataclasses import replace
+from datetime import datetime
+from pathlib import Path
+import re
+from uuid import uuid4
+
+from al_data_utils import files_sync_utils
+from al_data_utils.logging_utils import info
+from al_data_utils.sql_utils.sql_utils import UnifiedSQLClient, SQLDialect
+
+from .config import SnapshotConfig
+from .emit import emit_index_ddl, emit_table_ddl, emit_sql_object_ddl
+from .introspect import (
+    get_indexes,
+    get_foreign_keys,
+    get_tables,
+    get_views,
+    get_stored_procedures,
+    get_functions,
+    get_sequences,
+    get_synonyms,
+)
+from .io import (
+    table_file_path,
+    object_file_path,
+    write_text_atomic,
+    set_mtime_like,
+    read_text_if_exists,
+)
+
+
+def _run_id() -> str:
+    return datetime.now().strftime('%Y%m%d_%H%M%S')
+
+
+def _safe_path_token(value: str) -> str:
+    # Keep only characters that are safe and portable across Windows/Linux filesystems.
+    token = re.sub(r'[^A-Za-z0-9._-]+', '_', value.strip())
+    token = token.strip('._-')
+    return token[:80] if token else 'default'
+
+
+def _run_folder_name(cfg: SnapshotConfig) -> str:
+    rid = _run_id()
+    if cfg.staging_include_run_guid:
+        return f'{rid}_{uuid4().hex[:8]}'
+    return rid
+
+
+def _run_root(*, staging_root: Path, cfg: SnapshotConfig) -> Path:
+    base = staging_root
+    if cfg.staging_group_by_database and cfg.staging_database_name:
+        base = base / _safe_path_token(cfg.staging_database_name)
+    return base / _run_folder_name(cfg)
+
+
+def _default_staging_root(output_root: Path) -> Path:
+    return Path(str(output_root) + '__staging')
+
+
+def _batch_sep(cfg: SnapshotConfig) -> str:
+    return cfg.batch_separator.strip()
+
+
+def _join_blocks(blocks: list[str], cfg: SnapshotConfig) -> str:
+    sep = _batch_sep(cfg)
+    nl = cfg.newline
+    if not blocks:
+        return ''
+    if sep:
+        return (f'{nl}{sep}{nl}{nl}').join(blocks) + f'{nl}{sep}{nl}'
+    return (f'{nl}{nl}').join(blocks) + nl
+
+
+def _read_template_override(
+    *, cfg: SnapshotConfig, file_name: str, object_folder: str | None = None
+) -> str | None:
+    if not cfg.prefer_template_files:
+        return None
+    root = cfg.datagrip_templates_root
+    if root is None:
+        return None
+
+    folder_candidates: list[str] = []
+    if object_folder:
+        folder_candidates.append(object_folder)
+        # Backward-compat alias between old and new naming.
+        if object_folder == 'routines':
+            folder_candidates.append('stored_procedures')
+        if object_folder == 'stored_procedures':
+            folder_candidates.append('routines')
+
+    # 1) Exact folder + file path.
+    for folder in folder_candidates:
+        candidate = root / folder / file_name
+        if candidate.exists() and candidate.is_file():
+            return candidate.read_text(encoding=cfg.encoding)
+
+    # 2) Legacy flat root path.
+    candidate = root / file_name
+    if candidate.exists() and candidate.is_file():
+        return candidate.read_text(encoding=cfg.encoding)
+
+    lower_name = file_name.lower()
+    try:
+        # 3) Recursive search, folder-scoped first.
+        for folder in folder_candidates:
+            folder_path = root / folder
+            if not folder_path.exists() or not folder_path.is_dir():
+                continue
+            for p in folder_path.rglob('*.sql'):
+                if p.name.lower() == lower_name:
+                    return p.read_text(encoding=cfg.encoding)
+
+        # 4) Recursive fallback across template root.
+        for p in root.rglob('*.sql'):
+            if p.name.lower() == lower_name:
+                return p.read_text(encoding=cfg.encoding)
+    except Exception:
+        return None
+
+    return None
+
+
+def _iter_template_folder_files(
+    *, cfg: SnapshotConfig, object_folder: str
+) -> list[Path]:
+    root = cfg.datagrip_templates_root
+    if root is None:
+        return []
+    folder = root / object_folder
+    if not folder.exists() or not folder.is_dir():
+        return []
+    return sorted(folder.glob('*.sql'))
+
+
+def _parse_schema_object_from_file_name(file_name: str) -> tuple[str, str] | None:
+    name = file_name.strip()
+    if not name.lower().endswith('.sql'):
+        return None
+    stem = name[:-4]
+    if '.' not in stem:
+        return None
+    schema, object_name = stem.split('.', 1)
+    schema = schema.strip()
+    object_name = object_name.strip()
+    if not schema or not object_name:
+        return None
+    return schema, object_name
+
+
+def _render_table_file(
+    *, schema: str, table: str, table_ddl: str, indexes: list[str], cfg: SnapshotConfig
+) -> str:
+    nl = cfg.newline
+    lines: list[str] = []
+
+    if cfg.header_comment:
+        lines.append(cfg.header_comment)
+    if cfg.section_comments:
+        lines.append(f'-- table: {schema}.{table}')
+    lines.append('')
+
+    if table_ddl:
+        if cfg.section_comments:
+            lines.append('-- === table ===')
+        lines.append(table_ddl.strip())
+        lines.append('')
+
+    if indexes:
+        if cfg.section_comments:
+            lines.append('-- === indexes ===')
+        lines.append(_join_blocks(indexes, cfg).rstrip(nl))
+        lines.append('')
+
+    return nl.join(lines).strip() + nl
+
+
+def _render_sql_object_file(
+    *,
+    schema: str,
+    object_name: str,
+    object_kind: str,
+    object_ddl: str,
+    cfg: SnapshotConfig,
+) -> str:
+    nl = cfg.newline
+    lines: list[str] = []
+
+    if cfg.header_comment:
+        lines.append(cfg.header_comment)
+    if cfg.section_comments:
+        lines.append(f'-- {object_kind}: {schema}.{object_name}')
+    lines.append('')
+    lines.append(object_ddl.strip())
+
+    sep = _batch_sep(cfg)
+    if sep:
+        lines.append('')
+        lines.append(sep)
+
+    return nl.join(lines).strip() + nl
+
+
+def _write_object_file(
+    *, text: str, staging_path: Path, dest_path: Path, cfg: SnapshotConfig
+) -> None:
+    write_text_atomic(staging_path, text, encoding=cfg.encoding, newline=cfg.newline)
+
+    # keep mtime aligned when content matches so files_sync_utils doesn't "update"
+    dest_text = read_text_if_exists(dest_path, encoding=cfg.encoding)
+    if dest_text is not None:
+        norm_dest = dest_text.replace('\r\n', '\n').replace('\r', '\n')
+        norm_new = text.replace('\r\n', '\n').replace('\r', '\n')
+        if norm_dest == norm_new:
+            set_mtime_like(staging_path, dest_path)
+
+
+def snapshot_schema(
+    *, sql_client: UnifiedSQLClient, config: SnapshotConfig
+) -> list[Path]:
+    cfg = config
+    _info = info if cfg.verbose else (lambda _: None)
+    output_root = cfg.output_root
+    staging_root = cfg.staging_root or _default_staging_root(output_root)
+    run_root = _run_root(staging_root=staging_root, cfg=cfg)
+
+    _info(f'[schema_snapshot..] run root: {run_root}')
+    _info(
+        '[schema_snapshot..] collecting metadata (tables, indexes, foreign keys, views, procedures)...'
+    )
+
+    if cfg.include_table_definitions:
+        _info('[schema_snapshot..] metadata step: fetching tables (filtered SQL query)')
+        table_defs = get_tables(
+            sql_client,
+            include_schemas=cfg.include_schemas,
+            exclude_schemas=cfg.exclude_schemas,
+            include_tables=cfg.include_tables,
+            exclude_tables=cfg.exclude_tables,
+        )
+    else:
+        table_defs = []
+
+    if cfg.include_indexes:
+        _info('[schema_snapshot..] metadata step: fetching indexes (filtered SQL query)')
+        indexes = get_indexes(
+            sql_client,
+            include_schemas=cfg.include_schemas,
+            exclude_schemas=cfg.exclude_schemas,
+            include_tables=cfg.include_tables,
+            exclude_tables=cfg.exclude_tables,
+        )
+    else:
+        indexes = []
+
+    if cfg.include_foreign_keys:
+        _info(
+            '[schema_snapshot..] metadata step: fetching foreign keys (filtered SQL query)'
+        )
+        fks = get_foreign_keys(
+            sql_client,
+            include_schemas=cfg.include_schemas,
+            exclude_schemas=cfg.exclude_schemas,
+            include_tables=cfg.include_tables,
+            exclude_tables=cfg.exclude_tables,
+        )
+    else:
+        fks = []
+
+    if cfg.include_views:
+        _info('[schema_snapshot..] metadata step: fetching views (filtered SQL query)')
+        views = get_views(
+            sql_client,
+            include_schemas=cfg.include_schemas,
+            exclude_schemas=cfg.exclude_schemas,
+            include_views=cfg.include_views_objects,
+            exclude_views=cfg.exclude_views_objects,
+        )
+    else:
+        views = []
+
+    if cfg.include_stored_procedures:
+        _info(
+            '[schema_snapshot..] metadata step: fetching stored procedures '
+            '(filtered SQL query/per-object definitions)'
+        )
+        sprocs = get_stored_procedures(
+            sql_client,
+            include_schemas=cfg.include_schemas,
+            exclude_schemas=cfg.exclude_schemas,
+            include_objects=cfg.include_stored_procedures_objects,
+            exclude_objects=cfg.exclude_stored_procedures_objects,
+            verbose=cfg.verbose,
+        )
+    else:
+        sprocs = []
+
+    if cfg.include_functions:
+        _info(
+            '[schema_snapshot..] metadata step: fetching functions (filtered SQL query)'
+        )
+        funcs = get_functions(
+            sql_client,
+            include_schemas=cfg.include_schemas,
+            exclude_schemas=cfg.exclude_schemas,
+            include_objects=cfg.include_functions_objects,
+            exclude_objects=cfg.exclude_functions_objects,
+        )
+    else:
+        funcs = []
+
+    if cfg.include_sequences:
+        _info(
+            '[schema_snapshot..] metadata step: fetching sequences (filtered SQL query)'
+        )
+        sequences = get_sequences(
+            sql_client,
+            include_schemas=cfg.include_schemas,
+            exclude_schemas=cfg.exclude_schemas,
+            include_objects=cfg.include_sequences_objects,
+            exclude_objects=cfg.exclude_sequences_objects,
+        )
+    else:
+        sequences = []
+
+    if cfg.include_synonyms:
+        _info(
+            '[schema_snapshot..] metadata step: fetching synonyms (filtered SQL query)'
+        )
+        synonyms = get_synonyms(
+            sql_client,
+            include_schemas=cfg.include_schemas,
+            exclude_schemas=cfg.exclude_schemas,
+            include_objects=cfg.include_synonyms_objects,
+            exclude_objects=cfg.exclude_synonyms_objects,
+        )
+    else:
+        synonyms = []
+
+    _info(
+        '[schema_snapshot..] metadata counts: '
+        f'tables={len(table_defs)}, indexes={len(indexes)}, '
+        f'foreign_keys={len(fks)}, views={len(views)}, '
+        f'procedures={len(sprocs)}, functions={len(funcs)}, '
+        f'sequences={len(sequences)}, synonyms={len(synonyms)}'
+    )
+
+    idx_by_table: dict[tuple[str, str], list[str]] = defaultdict(list)
+    for idx in indexes:
+        if idx.is_hypothetical:
+            continue
+        if not cfg.is_schema_allowed(idx.schema_name):
+            continue
+        if not cfg.is_table_allowed(idx.schema_name, idx.table_name):
+            continue
+        idx_by_table[(idx.schema_name, idx.table_name)].append(emit_index_ddl(idx))
+
+    fk_by_table: dict[tuple[str, str], list] = defaultdict(list)
+    for fk in fks:
+        if not cfg.is_schema_allowed(fk.parent_schema):
+            continue
+        if not cfg.is_table_allowed(fk.parent_schema, fk.parent_table):
+            continue
+        fk_by_table[(fk.parent_schema, fk.parent_table)].append(fk)
+
+    tables_by_key = {
+        (t.schema_name, t.table_name): t
+        for t in table_defs
+        if cfg.is_schema_allowed(t.schema_name)
+        and cfg.is_table_allowed(t.schema_name, t.table_name)
+    }
+
+    all_tables = sorted(
+        set(tables_by_key.keys()) | set(idx_by_table.keys()) | set(fk_by_table.keys()),
+        key=lambda x: (x[0].lower(), x[1].lower()),
+    )
+
+    written_paths: list[Path] = []
+
+    _info(f'[schema_snapshot..] writing table files: {len(all_tables)}')
+
+    for schema, table in all_tables:
+        _info(f'[schema_snapshot..] extracting table: {schema}.{table}')
+        text = _read_template_override(
+            cfg=cfg, file_name=f'{schema}.{table}.sql', object_folder='tables'
+        )
+        if text is None:
+            table_def = tables_by_key.get((schema, table))
+            table_ddl = (
+                emit_table_ddl(
+                    table_def, foreign_keys=fk_by_table.get((schema, table), [])
+                )
+                if table_def is not None
+                else ''
+            )
+
+            idx_list = sorted(idx_by_table.get((schema, table), []))
+
+            text = _render_table_file(
+                schema=schema,
+                table=table,
+                table_ddl=table_ddl,
+                indexes=idx_list,
+                cfg=cfg,
+            )
+
+        staging_path = table_file_path(
+            root=run_root,
+            root_folder_name=cfg.root_folder_name,
+            schema=schema,
+            table=table,
+        )
+        dest_path = table_file_path(
+            root=output_root,
+            root_folder_name=cfg.root_folder_name,
+            schema=schema,
+            table=table,
+        )
+
+        _write_object_file(
+            text=text, staging_path=staging_path, dest_path=dest_path, cfg=cfg
+        )
+        _info(f'[schema_snapshot..] wrote table file: {dest_path}')
+        written_paths.append(dest_path)
+
+    filtered_views = [
+        v
+        for v in views
+        if cfg.is_schema_allowed(v.schema_name)
+        and cfg.is_view_allowed(v.schema_name, v.object_name)
+    ]
+    _info(f'[schema_snapshot..] writing view files: {len(filtered_views)}')
+    for v in sorted(
+        filtered_views, key=lambda x: (x.schema_name.lower(), x.object_name.lower())
+    ):
+        _info(f'[schema_snapshot..] extracting view: {v.schema_name}.{v.object_name}')
+        text = _read_template_override(
+            cfg=cfg,
+            file_name=f'{v.schema_name}.{v.object_name}.sql',
+            object_folder='views',
+        )
+        if text is None:
+            text = _render_sql_object_file(
+                schema=v.schema_name,
+                object_name=v.object_name,
+                object_kind='view',
+                object_ddl=emit_sql_object_ddl(v),
+                cfg=cfg,
+            )
+        staging_path = object_file_path(
+            root=run_root,
+            root_folder_name=cfg.root_folder_name,
+            schema=v.schema_name,
+            object_folder='views',
+            object_name=v.object_name,
+        )
+        dest_path = object_file_path(
+            root=output_root,
+            root_folder_name=cfg.root_folder_name,
+            schema=v.schema_name,
+            object_folder='views',
+            object_name=v.object_name,
+        )
+        _write_object_file(
+            text=text, staging_path=staging_path, dest_path=dest_path, cfg=cfg
+        )
+        _info(f'[schema_snapshot..] wrote view file: {dest_path}')
+        written_paths.append(dest_path)
+
+    filtered_sprocs = [
+        p
+        for p in sprocs
+        if cfg.is_schema_allowed(p.schema_name)
+        and cfg.is_stored_procedure_allowed(p.schema_name, p.object_name)
+    ]
+    filtered_funcs = [
+        f
+        for f in funcs
+        if cfg.is_schema_allowed(f.schema_name)
+        and cfg.is_function_allowed(f.schema_name, f.object_name)
+    ]
+
+    total_routines = len(filtered_sprocs) + len(filtered_funcs)
+    _info(f'[schema_snapshot..] writing routines files: {total_routines}')
+
+    for f in sorted(
+        filtered_funcs, key=lambda x: (x.schema_name.lower(), x.object_name.lower())
+    ):
+        _info(f'[schema_snapshot..] extracting routine: {f.schema_name}.{f.object_name}')
+        text = _read_template_override(
+            cfg=cfg,
+            file_name=f'{f.schema_name}.{f.object_name}.sql',
+            object_folder='routines',
+        )
+        if text is None:
+            text = _render_sql_object_file(
+                schema=f.schema_name,
+                object_name=f.object_name,
+                object_kind='routine',
+                object_ddl=emit_sql_object_ddl(f),
+                cfg=cfg,
+            )
+        staging_path = object_file_path(
+            root=run_root,
+            root_folder_name=cfg.root_folder_name,
+            schema=f.schema_name,
+            object_folder='routines',
+            object_name=f.object_name,
+        )
+        dest_path = object_file_path(
+            root=output_root,
+            root_folder_name=cfg.root_folder_name,
+            schema=f.schema_name,
+            object_folder='routines',
+            object_name=f.object_name,
+        )
+        _write_object_file(
+            text=text, staging_path=staging_path, dest_path=dest_path, cfg=cfg
+        )
+        _info(f'[schema_snapshot..] wrote routine file: {dest_path}')
+        written_paths.append(dest_path)
+
+    for p in sorted(
+        filtered_sprocs, key=lambda x: (x.schema_name.lower(), x.object_name.lower())
+    ):
+        _info(f'[schema_snapshot..] extracting routine: {p.schema_name}.{p.object_name}')
+        text = _read_template_override(
+            cfg=cfg,
+            file_name=f'{p.schema_name}.{p.object_name}.sql',
+            object_folder='routines',
+        )
+        if text is None:
+            text = _render_sql_object_file(
+                schema=p.schema_name,
+                object_name=p.object_name,
+                object_kind='stored_procedure',
+                object_ddl=emit_sql_object_ddl(p),
+                cfg=cfg,
+            )
+        staging_path = object_file_path(
+            root=run_root,
+            root_folder_name=cfg.root_folder_name,
+            schema=p.schema_name,
+            object_folder='routines',
+            object_name=p.object_name,
+        )
+        dest_path = object_file_path(
+            root=output_root,
+            root_folder_name=cfg.root_folder_name,
+            schema=p.schema_name,
+            object_folder='routines',
+            object_name=p.object_name,
+        )
+        _write_object_file(
+            text=text, staging_path=staging_path, dest_path=dest_path, cfg=cfg
+        )
+        _info(f'[schema_snapshot..] wrote routine file: {dest_path}')
+        written_paths.append(dest_path)
+
+    filtered_sequences = [
+        s
+        for s in sequences
+        if cfg.is_schema_allowed(s.schema_name)
+        and cfg.is_sequence_allowed(s.schema_name, s.object_name)
+    ]
+    _info(f'[schema_snapshot..] writing sequences files: {len(filtered_sequences)}')
+    for s in sorted(
+        filtered_sequences, key=lambda x: (x.schema_name.lower(), x.object_name.lower())
+    ):
+        _info(
+            f'[schema_snapshot..] extracting sequence: {s.schema_name}.{s.object_name}'
+        )
+        text = _read_template_override(
+            cfg=cfg,
+            file_name=f'{s.schema_name}.{s.object_name}.sql',
+            object_folder='sequences',
+        )
+        if text is None:
+            text = _render_sql_object_file(
+                schema=s.schema_name,
+                object_name=s.object_name,
+                object_kind='sequence',
+                object_ddl=emit_sql_object_ddl(s),
+                cfg=cfg,
+            )
+        staging_path = object_file_path(
+            root=run_root,
+            root_folder_name=cfg.root_folder_name,
+            schema=s.schema_name,
+            object_folder='sequences',
+            object_name=s.object_name,
+        )
+        dest_path = object_file_path(
+            root=output_root,
+            root_folder_name=cfg.root_folder_name,
+            schema=s.schema_name,
+            object_folder='sequences',
+            object_name=s.object_name,
+        )
+        _write_object_file(
+            text=text, staging_path=staging_path, dest_path=dest_path, cfg=cfg
+        )
+        _info(f'[schema_snapshot..] wrote sequence file: {dest_path}')
+        written_paths.append(dest_path)
+
+    filtered_synonyms = [
+        s
+        for s in synonyms
+        if cfg.is_schema_allowed(s.schema_name)
+        and cfg.is_synonym_allowed(s.schema_name, s.object_name)
+    ]
+    _info(f'[schema_snapshot..] writing synonyms files: {len(filtered_synonyms)}')
+    for s in sorted(
+        filtered_synonyms, key=lambda x: (x.schema_name.lower(), x.object_name.lower())
+    ):
+        _info(f'[schema_snapshot..] extracting synonym: {s.schema_name}.{s.object_name}')
+        text = _read_template_override(
+            cfg=cfg,
+            file_name=f'{s.schema_name}.{s.object_name}.sql',
+            object_folder='synonyms',
+        )
+        if text is None:
+            text = _render_sql_object_file(
+                schema=s.schema_name,
+                object_name=s.object_name,
+                object_kind='synonym',
+                object_ddl=emit_sql_object_ddl(s),
+                cfg=cfg,
+            )
+        staging_path = object_file_path(
+            root=run_root,
+            root_folder_name=cfg.root_folder_name,
+            schema=s.schema_name,
+            object_folder='synonyms',
+            object_name=s.object_name,
+        )
+        dest_path = object_file_path(
+            root=output_root,
+            root_folder_name=cfg.root_folder_name,
+            schema=s.schema_name,
+            object_folder='synonyms',
+            object_name=s.object_name,
+        )
+        _write_object_file(
+            text=text, staging_path=staging_path, dest_path=dest_path, cfg=cfg
+        )
+        _info(f'[schema_snapshot..] wrote synonym file: {dest_path}')
+        written_paths.append(dest_path)
+
+    # Optional passthrough: copy template-only SQL files from dedicated folders.
+    # This allows extra object types (e.g., sequences/synonyms/routines functions)
+    # to be produced even when they are not introspected from the database yet.
+    if cfg.prefer_template_files and cfg.datagrip_templates_root is not None:
+        written_set = {str(p).lower() for p in written_paths}
+        for folder_name in ('tables', 'views', 'routines', 'sequences', 'synonyms'):
+            for template_path in _iter_template_folder_files(
+                cfg=cfg, object_folder=folder_name
+            ):
+                parsed = _parse_schema_object_from_file_name(template_path.name)
+                if parsed is None:
+                    continue
+
+                schema, object_name = parsed
+                if folder_name == 'tables':
+                    dest_path = table_file_path(
+                        root=output_root,
+                        root_folder_name=cfg.root_folder_name,
+                        schema=schema,
+                        table=object_name,
+                    )
+                    staging_path = table_file_path(
+                        root=run_root,
+                        root_folder_name=cfg.root_folder_name,
+                        schema=schema,
+                        table=object_name,
+                    )
+                else:
+                    dest_path = object_file_path(
+                        root=output_root,
+                        root_folder_name=cfg.root_folder_name,
+                        schema=schema,
+                        object_folder=folder_name,
+                        object_name=object_name,
+                    )
+                    staging_path = object_file_path(
+                        root=run_root,
+                        root_folder_name=cfg.root_folder_name,
+                        schema=schema,
+                        object_folder=folder_name,
+                        object_name=object_name,
+                    )
+
+                key = str(dest_path).lower()
+                text = template_path.read_text(encoding=cfg.encoding)
+                _write_object_file(
+                    text=text, staging_path=staging_path, dest_path=dest_path, cfg=cfg
+                )
+                _info(
+                    f'[schema_snapshot..] wrote template passthrough file: {dest_path}'
+                )
+                written_paths.append(dest_path)
+                written_set.add(key)
+
+    # sync staging -> destination using existing module (unchanged)
+    sync_cfg = files_sync_utils.SyncConfig(
+        source_paths=[str(run_root)],
+        target_path=str(output_root),
+        log_folder=str(cfg.sync_log_folder or (output_root / 'sync_logs')),
+        copy_folders_names_to_skip=[],
+        copy_files_names_to_skip=[],
+        delete_folders_names_to_skip=[],
+        delete_files_names_to_skip=[],
+        delete_folders_names_to_try=[],
+        delete_files_names_to_try=[],
+    )
+
+    plan_df = files_sync_utils.build_plan_df(sync_cfg)
+    _info('[schema_snapshot..] syncing staging -> output...')
+    executed_df, summary = files_sync_utils.execute_plan(plan_df)
+    files_sync_utils.log_activity(executed_df, summary, sync_cfg.log_folder)
+    if cfg.sync_log_retention_days is not None and cfg.sync_log_retention_days >= 0:
+        files_sync_utils.log_folder_retention(
+            sync_cfg.log_folder, retain_days=cfg.sync_log_retention_days
+        )
+    _info('[schema_snapshot..] sync completed')
+
+    if cfg.cleanup_staging:
+        try:
+            import shutil
+
+            shutil.rmtree(run_root, ignore_errors=True)
+            _info('[schema_snapshot..] staging cleaned up')
+        except Exception:
+            pass
+
+    _info(f'[schema_snapshot..] done. written files: {len(written_paths)}')
+    return written_paths
+
+
+def snapshot_schema_from_params(
+    *, mssql_params: dict, config: SnapshotConfig
+) -> list[Path]:
+    cfg = config
+    if not cfg.staging_database_name:
+        db_name = mssql_params.get('database')
+        if isinstance(db_name, str) and db_name.strip():
+            cfg = replace(cfg, staging_database_name=db_name.strip())
+
+    sql_client = UnifiedSQLClient(SQLDialect.MSSQL, mssql_params)
+    return snapshot_schema(sql_client=sql_client, config=cfg)