dbbridgekit 0.1.0__py3-none-any.whl

dbbridge/__init__.py

@@ -0,0 +1,22 @@
+"""DBBridge — plataforma genérica de conversão/análise/migração entre bancos de dados, baseada numa
+Intermediate Representation (IR) canônica.
+
+    Banco origem -> Parser do dialeto origem -> IR -> Renderer do dialeto destino -> Banco destino
+
+Não é uma evolução ad-hoc pareada (SQLite->Postgres, SQLite->MySQL, ...) — é uma arquitetura N-para-N
+através de UM modelo comum. Ver core/ir.py pra IR, core/planner.py pro pipeline completo.
+
+    from dbbridge.core.planner import translate
+    result = translate(sql, source_dialect="sqlite", target_dialect="postgres")
+    print(result.sql)
+
+Fase 1 (atual): IR completa + SQLite <-> PostgreSQL, scanner, codemod, CLI, rollback.
+Dialetos MySQL/SQL Server: estrutura registrada, implementação nas Fases 2/5 (ver README.md).
+"""
+from . import dialects  # noqa: F401 — registra sqlite/postgres/mysql(stub)/sqlserver(stub)
+from .compat.runtime import connect
+from .core.planner import TranslationResult, translate
+
+__version__ = "0.1.0"
+
+__all__ = ["translate", "TranslationResult", "connect"]

dbbridge/cli.py

@@ -0,0 +1,177 @@
+"""CLI: dbbridge scan|report|translate|patch|apply|migrate-data|validate|rollback|doctor."""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from . import dialects  # noqa: F401 — garante que sqlite/postgres/mysql/sqlserver estão registrados
+from .codemod.codemod import apply_changes, plan_file
+from .core.parser import available_parsers
+from .core.planner import translate as translate_ir
+from .core.renderer import available_renderers
+from .migration.rollback import rollback_code_changes
+from .reports.report import render_report
+from .scanner.scanner import scan_project
+
+
+def _add_common(p: argparse.ArgumentParser):
+    p.add_argument("--from", dest="source", required=True, choices=available_parsers(), help="Dialeto de origem")
+    p.add_argument("--to", dest="target", required=True, choices=available_renderers(), help="Dialeto de destino")
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(prog="dbbridge", description="Conversão/análise/migração entre bancos de dados via IR canônica")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_scan = sub.add_parser("scan", help="Varre um projeto Python procurando SQL incompatível entre os dois dialetos")
+    _add_common(p_scan)
+    p_scan.add_argument("path")
+    p_scan.add_argument("--json", action="store_true")
+
+    p_report = sub.add_parser("report", help="Gera relatório do último scan (texto ou JSON)")
+    p_report.add_argument("path")
+    p_report.add_argument("--from", dest="source", choices=available_parsers())
+    p_report.add_argument("--to", dest="target", choices=available_renderers())
+    p_report.add_argument("--json", action="store_true")
+    p_report.add_argument("--out", default=None)
+
+    p_translate = sub.add_parser("translate", help="Traduz um arquivo .sql (schema DDL) de um dialeto pro outro")
+    _add_common(p_translate)
+    p_translate.add_argument("sql_file")
+    p_translate.add_argument("--out", default=None)
+
+    p_patch = sub.add_parser("patch", help="Gera o plano de mudanças de código SEM escrever nada (dry-run)")
+    _add_common(p_patch)
+    p_patch.add_argument("path")
+
+    p_apply = sub.add_parser("apply", help="Aplica as mudanças de código seguras (com backup automático)")
+    _add_common(p_apply)
+    p_apply.add_argument("path")
+
+    p_migrate = sub.add_parser("migrate-data", help="Copia dados entre uma conexão origem e uma destino")
+    _add_common(p_migrate)
+    p_migrate.add_argument("--source-dsn", required=True)
+    p_migrate.add_argument("--target-dsn", required=True)
+    p_migrate.add_argument("--tables", nargs="+", required=True)
+
+    p_validate = sub.add_parser("validate", help="Valida contagens/checksums entre origem e destino após migrate-data")
+    _add_common(p_validate)
+    p_validate.add_argument("--source-dsn", required=True)
+    p_validate.add_argument("--target-dsn", required=True)
+    p_validate.add_argument("--tables", nargs="+", required=True)
+
+    p_rollback = sub.add_parser("rollback", help="Restaura arquivos de código a partir do backup mais recente")
+    p_rollback.add_argument("path")
+
+    sub.add_parser("doctor", help="Diagnóstico rápido: dialetos disponíveis, drivers instalados")
+    sub.add_parser("dialects", help="Lista os dialetos com parser/renderer disponíveis")
+
+    args = parser.parse_args(argv)
+
+    if args.command == "scan":
+        report = scan_project(Path(args.path), args.source, args.target)
+        print(render_report(f"DBBridge scan ({args.source} -> {args.target})", report, fmt="json" if args.json else "text"))
+
+    elif args.command == "report":
+        report = scan_project(Path(args.path), args.source or "sqlite", args.target or "postgres")
+        text = render_report(f"DBBridge report ({args.source} -> {args.target})", report, fmt="json" if args.json else "text")
+        if args.out:
+            Path(args.out).write_text(text, encoding="utf-8")
+            print(f"Relatório salvo em {args.out}")
+        else:
+            print(text)
+
+    elif args.command == "translate":
+        sql = Path(args.sql_file).read_text(encoding="utf-8")
+        result = translate_ir(sql, args.source, args.target)
+        if args.out:
+            Path(args.out).write_text(result.sql, encoding="utf-8")
+            print(f"SQL traduzido salvo em {args.out}")
+        else:
+            print(result.sql)
+        if result.review_required:
+            print("\n--- REVIEW_REQUIRED ---", file=sys.stderr)
+            for f in result.parse_findings:
+                print(f"  [parse] {f.statement[:80]!r}: {f.reason}", file=sys.stderr)
+            # Nenhum parser atual produz Trigger/View no IR que gere RenderFinding (CREATE TRIGGER já
+            # vira ParseFinding antes de chegar aqui) — mantido para dialetos futuros que possam parsear
+            # esses casos com sucesso e só falhar na hora de renderizar pro destino.
+            for f in result.render_findings:
+                print(f"  [render] {f.target}: {f.reason}", file=sys.stderr)
+
+    elif args.command == "patch":
+        total = 0
+        for path in sorted(Path(args.path).rglob("*.py")):
+            if any(part in ("venv", ".venv", "__pycache__") for part in path.parts):
+                continue
+            changes = plan_file(path, args.source, args.target)
+            if changes:
+                print(f"\n{path}:")
+                for c in changes:
+                    print(f"  [{c.status}] linha {c.line}: {c.reason}")
+                total += len(changes)
+        print(f"\nTotal planejado: {total} mudança(s). Nada foi escrito — rode 'apply' pra gravar.")
+
+    elif args.command == "apply":
+        applied_total = 0
+        touched = []
+        backup_dir = Path(args.path) / ".dbbridge_backups"
+        for path in sorted(Path(args.path).rglob("*.py")):
+            if any(part in ("venv", ".venv", "__pycache__", ".dbbridge_backups") for part in path.parts):
+                continue
+            changes = plan_file(path, args.source, args.target)
+            if not changes:
+                continue
+            ok = apply_changes(path, changes, backup_dir)
+            if ok:
+                n = sum(1 for c in changes if c.status == "APPLIED")
+                if n:
+                    applied_total += n
+                    touched.append(path)
+        print(f"{applied_total} mudança(s) aplicada(s) em {len(touched)} arquivo(s).")
+
+    elif args.command == "migrate-data":
+        from .compat.runtime import connect as db_connect
+        from .migration.data_migration import migrate_data
+
+        source_conn = db_connect(args.source, args.source, args.source_dsn)
+        target_conn = db_connect(args.source, args.target, args.target_dsn)
+        result = migrate_data(source_conn, target_conn, args.tables)
+        print(render_report(f"DBBridge migrate-data ({args.source} -> {args.target})", result))
+        if not result.all_counts_match:
+            sys.exit(1)
+
+    elif args.command == "validate":
+        from .compat.runtime import connect as db_connect
+        from .migration.validator import validate
+
+        source_conn = db_connect(args.source, args.source, args.source_dsn)
+        target_conn = db_connect(args.source, args.target, args.target_dsn)
+        report = validate(source_conn, target_conn, {t: None for t in args.tables})
+        print(render_report(f"DBBridge validate ({args.source} -> {args.target})", report))
+        if not report.all_ok:
+            sys.exit(1)
+
+    elif args.command == "rollback":
+        n = rollback_code_changes(Path(args.path))
+        print(f"{n} arquivo(s) restaurado(s) a partir do backup.")
+
+    elif args.command == "doctor":
+        print("Dialetos com parser:", available_parsers())
+        print("Dialetos com renderer:", available_renderers())
+        try:
+            import psycopg  # noqa: F401
+            print("psycopg (Postgres driver): instalado")
+        except ImportError:
+            print("psycopg (Postgres driver): NÃO instalado")
+        import sqlite3  # noqa: F401
+        print("sqlite3 (stdlib): disponível")
+
+    elif args.command == "dialects":
+        print("Parsers disponíveis:", available_parsers())
+        print("Renderers disponíveis:", available_renderers())
+
+
+if __name__ == "__main__":
+    main()

dbbridge/codemod/__init__.py

@@ -0,0 +1,3 @@
+from .codemod import APPLIED, REVIEW_REQUIRED, SKIPPED_COMPLEX, CodemodChange, apply_changes, plan_file
+
+__all__ = ["APPLIED", "REVIEW_REQUIRED", "SKIPPED_COMPLEX", "CodemodChange", "apply_changes", "plan_file"]

dbbridge/codemod/codemod.py

@@ -0,0 +1,194 @@
+"""Codemod genérico: localiza via `ast` (nunca regex solto no arquivo inteiro) os argumentos de
+`.execute()`/`.executemany()` e reescreve SÓ os casos sem ambiguidade — o mesmo princípio de
+PostgresModel, generalizado pra qualquer par de dialetos suportado (a diferença real é qual
+placeholder o destino espera: `?` pro SQLite/SQL Server, `%s` pro Postgres/MySQL).
+
+Edição é cirúrgica por span de texto-fonte (via lineno/col_offset/end_lineno/end_col_offset) — nunca
+um `ast.unparse()` do arquivo inteiro, que reformataria tudo.
+"""
+from __future__ import annotations
+
+import ast
+import re
+import shutil
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+
+REVIEW_REQUIRED = "REVIEW_REQUIRED"
+APPLIED = "APPLIED"
+SKIPPED_COMPLEX = "SKIPPED_COMPLEX_EXPRESSION"
+
+_PLACEHOLDER_STYLE = {"sqlite": "?", "postgres": "%s", "mysql": "%s", "sqlserver": "?"}
+
+_AMBIGUOUS_PATTERNS = [
+    (re.compile(r"\bINSERT\s+OR\s+REPLACE\b", re.IGNORECASE), "INSERT OR REPLACE precisa da coluna de conflito."),
+    (re.compile(r"\bsqlite_master\b", re.IGNORECASE), "sqlite_master não tem equivalente direto fora do SQLite."),
+    (re.compile(r"\bPRAGMA\s+\w+", re.IGNORECASE), "PRAGMA é específico do SQLite."),
+    (re.compile(r'(=|,|\(|\|\|)\s*"[^"]*"'), "Aspas duplas podem ser string literal (SQLite) ou identificador — ambíguo sem revisão."),
+]
+
+
+@dataclass
+class CodemodChange:
+    file: Path
+    line: int
+    status: str
+    before: str
+    after: str | None
+    reason: str
+
+
+def _translate_placeholder(sql: str, source: str, target: str) -> str:
+    src_ph = _PLACEHOLDER_STYLE.get(source, "?")
+    tgt_ph = _PLACEHOLDER_STYLE.get(target, "?")
+    if src_ph == tgt_ph:
+        return sql
+    if src_ph == "?":
+        return sql.replace("?", tgt_ph)
+    return sql.replace(src_ph, "?") if tgt_ph == "?" else sql
+
+
+def _has_ambiguity(sql: str) -> str | None:
+    for pattern, reason in _AMBIGUOUS_PATTERNS:
+        if pattern.search(sql):
+            return reason
+    return None
+
+
+def _quote_style(raw: str) -> tuple[str, str]:
+    prefix = ""
+    while raw and raw[0].lower() in ("f", "r", "b", "u"):
+        prefix += raw[0]
+        raw = raw[1:]
+    for delim in ('"""', "'''", '"', "'"):
+        if raw.startswith(delim) and raw.endswith(delim) and len(raw) >= 2 * len(delim):
+            return prefix + delim, raw[len(delim):-len(delim)]
+    raise ValueError(f"Não reconheci o estilo de aspas de: {raw!r}")
+
+
+def _rewrap(inner: str, original_delim: str) -> str:
+    prefix = original_delim.rstrip("'\"")
+    bare_delim = original_delim[len(prefix):]
+    if bare_delim in ('"""', "'''"):
+        return prefix + bare_delim + inner + bare_delim
+    quote_char = bare_delim
+    if quote_char not in inner:
+        return prefix + quote_char + inner + quote_char
+    other = '"' if quote_char == "'" else "'"
+    if other not in inner:
+        return prefix + other + inner + other
+    raise ValueError("texto contém os dois tipos de aspas — precisa de escape manual")
+
+
+def _get_span_text(lines: list[str], lineno: int, col_offset: int, end_lineno: int, end_col_offset: int) -> str:
+    if lineno == end_lineno:
+        return lines[lineno - 1][col_offset:end_col_offset]
+    parts = [lines[lineno - 1][col_offset:]]
+    parts.extend(lines[lineno:end_lineno - 1])
+    parts.append(lines[end_lineno - 1][:end_col_offset])
+    return "".join(parts)
+
+
+class _ExecuteArgVisitor(ast.NodeVisitor):
+    def __init__(self):
+        self.simple_string_args: list[ast.Constant] = []
+        self.complex_args: list[ast.AST] = []
+
+    def visit_Call(self, node: ast.Call):
+        if isinstance(node.func, ast.Attribute) and node.func.attr in ("execute", "executemany"):
+            if node.args:
+                arg = node.args[0]
+                if isinstance(arg, ast.Constant) and isinstance(arg.value, str):
+                    self.simple_string_args.append(arg)
+                else:
+                    self.complex_args.append(arg)
+        self.generic_visit(node)
+
+
+def plan_file(path: Path, source: str, target: str) -> list[CodemodChange]:
+    source_text = path.read_text(encoding="utf-8")
+    lines = source_text.splitlines(keepends=True)
+    tree = ast.parse(source_text, filename=str(path))
+    visitor = _ExecuteArgVisitor()
+    visitor.visit(tree)
+
+    changes: list[CodemodChange] = []
+
+    for arg in visitor.complex_args:
+        changes.append(CodemodChange(
+            path, getattr(arg, "lineno", 0), SKIPPED_COMPLEX,
+            "<f-string, concatenação ou expressão dinâmica>", None,
+            "Codemod só reescreve literais de string simples."))
+
+    for arg in visitor.simple_string_args:
+        sql = arg.value
+        ambiguity_reason = _has_ambiguity(sql)
+        if ambiguity_reason:
+            changes.append(CodemodChange(path, arg.lineno, REVIEW_REQUIRED, sql, None, ambiguity_reason))
+            continue
+
+        translated = _translate_placeholder(sql, source, target)
+        if translated == sql:
+            continue
+
+        original_span = _get_span_text(lines, arg.lineno, arg.col_offset, arg.end_lineno, arg.end_col_offset)
+        try:
+            delim, _inner = _quote_style(original_span)
+            new_literal = _rewrap(translated, delim)
+        except ValueError as e:
+            changes.append(CodemodChange(path, arg.lineno, REVIEW_REQUIRED, sql, None,
+                                          f"Não consegui re-serializar com segurança: {e}"))
+            continue
+
+        changes.append(CodemodChange(path, arg.lineno, APPLIED, original_span, new_literal,
+                                      f"Placeholder '{_PLACEHOLDER_STYLE.get(source,'?')}' -> "
+                                      f"'{_PLACEHOLDER_STYLE.get(target,'?')}', sem ambiguidade."))
+
+    return changes
+
+
+def apply_changes(path: Path, changes: list[CodemodChange], backup_dir: Path) -> bool:
+    applied = [c for c in changes if c.status == APPLIED and c.after is not None]
+    if not applied:
+        return True
+
+    source_text = path.read_text(encoding="utf-8")
+    lines = source_text.splitlines(keepends=True)
+
+    tree = ast.parse(source_text, filename=str(path))
+    visitor = _ExecuteArgVisitor()
+    visitor.visit(tree)
+    by_line = {a.lineno: a for a in visitor.simple_string_args}
+
+    for change in sorted(applied, key=lambda c: c.line, reverse=True):
+        arg = by_line.get(change.line)
+        if arg is None:
+            continue
+        before = _get_span_text(lines, arg.lineno, arg.col_offset, arg.end_lineno, arg.end_col_offset)
+        if before != change.before:
+            continue
+        if arg.lineno == arg.end_lineno:
+            line = lines[arg.lineno - 1]
+            lines[arg.lineno - 1] = line[:arg.col_offset] + change.after + line[arg.end_col_offset:]
+        else:
+            first = lines[arg.lineno - 1][:arg.col_offset]
+            last = lines[arg.end_lineno - 1][arg.end_col_offset:]
+            lines[arg.lineno - 1:arg.end_lineno] = [first + change.after + last]
+
+    new_source = "".join(lines)
+
+    backup_dir.mkdir(parents=True, exist_ok=True)
+    stamp = datetime.now().strftime("%Y%m%d_%H%M%S_%f")
+    backup_path = backup_dir / f"{path.name}.{stamp}.bak"
+    shutil.copy2(path, backup_path)
+
+    path.write_text(new_source, encoding="utf-8")
+
+    try:
+        ast.parse(new_source, filename=str(path))
+    except SyntaxError:
+        shutil.copy2(backup_path, path)
+        return False
+
+    return True

dbbridge/compat/__init__.py

@@ -0,0 +1,3 @@
+from .runtime import Connection, Cursor, Row, connect, translate_query
+
+__all__ = ["connect", "Connection", "Cursor", "Row", "translate_query"]

dbbridge/compat/runtime.py

@@ -0,0 +1,193 @@
+"""Compatibility Mode do DBBridge: código escrito contra a sintaxe de `source_dialect` roda de
+verdade contra um banco `target_dialect`, sem reescrita — o mesmo papel que PostgresModel cumpre só
+pro par SQLite->Postgres, generalizado (Fase 1: os dois sentidos SQLite<->Postgres já funcionam;
+MySQL/SQL Server entram nas Fases 2/5 assim que os dialetos tiverem parser/renderer reais).
+
+    from dbbridge import connect
+    db = connect(source_dialect="sqlite", target_dialect="postgres", dsn="host=... dbname=...")
+    db.execute("SELECT * FROM users WHERE id=?", (1,))  # vira %s por baixo, de verdade no Postgres
+"""
+from __future__ import annotations
+
+import logging
+import re
+
+logger = logging.getLogger("dbbridge")
+
+_PLACEHOLDER_STYLE = {"sqlite": "?", "postgres": "%s", "mysql": "%s", "sqlserver": "?"}
+_SUPPORTED_TARGETS = ("sqlite", "postgres")
+
+_LAST_INSERT_ROWID_RE = re.compile(r"last_insert_rowid\(\)", re.IGNORECASE)
+_LASTVAL_RE = re.compile(r"lastval\(\)", re.IGNORECASE)
+_INSERT_OR_IGNORE_RE = re.compile(r"INSERT\s+OR\s+IGNORE\s+INTO", re.IGNORECASE)
+
+
+def translate_query(sql: str, source_dialect: str, target_dialect: str) -> str:
+    """Tradução pura texto->texto pro par (source, target) — mesma peça central que PostgresModel,
+    só que parametrizada pelos dois lados em vez de assumir sqlite->postgres sempre."""
+    out = sql
+    if source_dialect == target_dialect:
+        return out
+
+    if source_dialect == "sqlite" and target_dialect == "postgres":
+        out = _LAST_INSERT_ROWID_RE.sub("lastval()", out)
+        if _INSERT_OR_IGNORE_RE.search(out):
+            out = _INSERT_OR_IGNORE_RE.sub("INSERT INTO", out)
+            out = out.rstrip().rstrip(";") + " ON CONFLICT DO NOTHING"
+    elif source_dialect == "postgres" and target_dialect == "sqlite":
+        out = _LASTVAL_RE.sub("last_insert_rowid()", out)
+        # "INSERT ... ON CONFLICT DO NOTHING" -> "INSERT OR IGNORE ..." só no caso simples (sem
+        # DO UPDATE, que não tem equivalente direto em INSERT OR IGNORE — fica como está, sem
+        # tradução perigosa, se detectarmos DO UPDATE presente).
+        if re.search(r"ON\s+CONFLICT.*DO\s+NOTHING", out, re.IGNORECASE | re.DOTALL) and \
+                not re.search(r"DO\s+UPDATE", out, re.IGNORECASE):
+            out = re.sub(r"INSERT\s+INTO", "INSERT OR IGNORE INTO", out, count=1, flags=re.IGNORECASE)
+            out = re.sub(r"\s*ON\s+CONFLICT.*DO\s+NOTHING\s*", " ", out, flags=re.IGNORECASE | re.DOTALL).rstrip()
+
+    src_ph = _PLACEHOLDER_STYLE.get(source_dialect, "?")
+    tgt_ph = _PLACEHOLDER_STYLE.get(target_dialect, "?")
+    if src_ph != tgt_ph:
+        out = out.replace(src_ph, tgt_ph)
+
+    return out
+
+
+def _log_sql_error(original_sql, translated_sql, params, source_dialect, target_dialect, exc):
+    logger.error(
+        "Falha ao executar SQL traduzido (%s -> %s).\n"
+        "--- SQL original ---\n%s\n--- SQL traduzido ---\n%s\n--- Parâmetros ---\n%r\n--- Erro ---\n%s",
+        source_dialect, target_dialect, original_sql, translated_sql, params, exc,
+    )
+
+
+class Row:
+    __slots__ = ("_keys", "_values")
+
+    def __init__(self, keys, values):
+        self._keys = keys
+        self._values = values
+
+    def __getitem__(self, key):
+        if isinstance(key, int):
+            return self._values[key]
+        try:
+            idx = self._keys.index(key)
+        except ValueError:
+            raise KeyError(key)
+        return self._values[idx]
+
+    def keys(self):
+        return list(self._keys)
+
+    def __iter__(self):
+        return iter(self._values)
+
+    def __len__(self):
+        return len(self._values)
+
+    def __repr__(self):
+        return f"Row({dict(zip(self._keys, self._values))!r})"
+
+
+class Cursor:
+    def __init__(self, raw_cursor, source_dialect: str, target_dialect: str, row_factory=None):
+        self._cur = raw_cursor
+        self._source = source_dialect
+        self._target = target_dialect
+        self._row_factory = row_factory
+
+    def execute(self, sql: str, params=None):
+        translated = translate_query(sql, self._source, self._target)
+        try:
+            if params is None:
+                self._cur.execute(translated)
+            else:
+                self._cur.execute(translated, params)
+        except Exception as e:
+            _log_sql_error(sql, translated, params, self._source, self._target, e)
+            raise
+        return self
+
+    def fetchone(self):
+        row = self._cur.fetchone()
+        return self._wrap(row) if row is not None else None
+
+    def fetchall(self):
+        return [self._wrap(r) for r in self._cur.fetchall()]
+
+    def _wrap(self, row):
+        if self._row_factory:
+            return self._row_factory(row)
+        return row
+
+    def __getattr__(self, name):
+        return getattr(self._cur, name)
+
+
+class Connection:
+    def __init__(self, raw_conn, source_dialect: str, target_dialect: str, row_factory=None):
+        self._conn = raw_conn
+        self._source = source_dialect
+        self._target = target_dialect
+        self._row_factory = row_factory
+
+    def _new_cursor(self) -> Cursor:
+        return Cursor(self._conn.cursor(), self._source, self._target, row_factory=self._row_factory)
+
+    def execute(self, sql: str, params=None):
+        return self._new_cursor().execute(sql, params)
+
+    def cursor(self) -> Cursor:
+        return self._new_cursor()
+
+    def commit(self):
+        self._conn.commit()
+
+    def rollback(self):
+        self._conn.rollback()
+
+    def close(self):
+        self._conn.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc, tb):
+        if exc_type is None:
+            self.commit()
+        else:
+            self.rollback()
+        self.close()
+
+
+def connect(source_dialect: str, target_dialect: str, dsn: str) -> Connection:
+    """Ponto de entrada público. `dsn` é a string de conexão no formato que o driver do
+    `target_dialect` espera (caminho de arquivo pro sqlite3, string psycopg pro postgres)."""
+    if target_dialect not in _SUPPORTED_TARGETS:
+        raise NotImplementedError(
+            f"Compatibility Mode ainda não implementado pro destino '{target_dialect}' "
+            f"(suportados nesta fase: {_SUPPORTED_TARGETS}).")
+
+    if target_dialect == "postgres":
+        import psycopg
+        from psycopg.rows import dict_row
+
+        raw = psycopg.connect(dsn, row_factory=dict_row)
+
+        def row_factory(row):
+            return Row(list(row.keys()), list(row.values())) if row else row
+
+        return Connection(raw, source_dialect, target_dialect, row_factory=row_factory)
+
+    if target_dialect == "sqlite":
+        import sqlite3
+
+        raw = sqlite3.connect(dsn)
+        raw.row_factory = sqlite3.Row
+
+        def row_factory(row):
+            return Row(row.keys(), tuple(row)) if row else row
+
+        return Connection(raw, source_dialect, target_dialect, row_factory=row_factory)
+
+    raise AssertionError("inalcançável — já validado por _SUPPORTED_TARGETS acima")

dbbridge/core/__init__.py

@@ -0,0 +1,2 @@
+"""Núcleo da IR (Intermediate Representation) — modelo comum entre dialetos, parser/renderer base,
+e o planner que orquestra a pipeline completa. Nenhum código aqui conhece um dialeto específico."""