dbbridgekit 0.1.0__py3-none-any.whl

dbbridge/core/ir.py

@@ -0,0 +1,106 @@
+"""IR (Intermediate Representation) canônica — o modelo comum que todo dialeto converge PRA (parser)
+e converge DE (renderer). Nenhuma classe aqui sabe nada sobre SQLite/Postgres/MySQL especificamente;
+esse é o ponto inteiro da arquitetura (ver core/parser.py e core/renderer.py pros pontos de extensão).
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from .types import CanonicalType
+
+
+@dataclass
+class Column:
+    name: str
+    type: CanonicalType
+    nullable: bool = True
+    primary_key: bool = False
+    auto_increment: bool = False
+    unique: bool = False
+    default: str | None = None          # texto do literal/expressão de default, já em forma canônica
+    length: int | None = None           # pra VARCHAR
+    precision: int | None = None        # pra NUMERIC (dígitos totais)
+    scale: int | None = None            # pra NUMERIC (dígitos após a vírgula)
+    enum_values: list[str] = field(default_factory=list)  # pra CanonicalType.ENUM
+    comment: str | None = None
+
+
+@dataclass
+class ForeignKey:
+    name: str | None
+    columns: list[str]
+    ref_table: str
+    ref_columns: list[str]
+    on_delete: str | None = None   # 'CASCADE' | 'SET NULL' | 'RESTRICT' | None
+    on_update: str | None = None
+
+
+@dataclass
+class UniqueConstraint:
+    name: str | None
+    columns: list[str]
+
+
+@dataclass
+class CheckConstraint:
+    name: str | None
+    expression: str  # expressão booleana em forma canônica simples (ex: "price >= 0")
+
+
+@dataclass
+class Index:
+    name: str
+    columns: list[str]
+    unique: bool = False
+
+
+@dataclass
+class Table:
+    name: str
+    columns: list[Column] = field(default_factory=list)
+    foreign_keys: list[ForeignKey] = field(default_factory=list)
+    unique_constraints: list[UniqueConstraint] = field(default_factory=list)
+    check_constraints: list[CheckConstraint] = field(default_factory=list)
+    indexes: list[Index] = field(default_factory=list)
+
+    def column(self, name: str) -> Column | None:
+        return next((c for c in self.columns if c.name == name), None)
+
+    @property
+    def primary_key_columns(self) -> list[str]:
+        return [c.name for c in self.columns if c.primary_key]
+
+
+@dataclass
+class View:
+    name: str
+    query: str  # texto do SELECT em forma canônica simples (sem tradução de sintaxe do dialeto origem)
+
+
+@dataclass
+class Trigger:
+    name: str
+    table: str
+    timing: str    # 'BEFORE' | 'AFTER' | 'INSTEAD OF'
+    event: str     # 'INSERT' | 'UPDATE' | 'DELETE'
+    body: str      # corpo bruto — trigger é o caso mais dialect-specific, quase sempre REVIEW_REQUIRED
+
+
+@dataclass
+class Enum:
+    name: str
+    values: list[str]
+
+
+@dataclass
+class Schema:
+    """Container de tudo que um dialeto consegue extrair de um schema — a unidade que passa pela
+    pipeline parser -> IR -> renderer inteira de uma vez."""
+
+    tables: list[Table] = field(default_factory=list)
+    views: list[View] = field(default_factory=list)
+    triggers: list[Trigger] = field(default_factory=list)
+    enums: list[Enum] = field(default_factory=list)
+
+    def table(self, name: str) -> Table | None:
+        return next((t for t in self.tables if t.name == name), None)

dbbridge/core/parser.py

@@ -0,0 +1,60 @@
+"""Contrato base do parser: todo dialeto implementa `DialectParser.parse(sql) -> ParseResult`,
+convertendo DDL do dialeto pra `Schema` (IR). Não é um parser SQL genérico de propósito — cada
+dialeto reconhece SÓ o subconjunto de sintaxe que ele mesmo produz/aceita, e qualquer coisa que não
+reconheça vira uma `Ambiguity` reportada, nunca uma adivinhação.
+"""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+
+from .ir import Schema
+from .types import Ambiguity
+
+
+@dataclass
+class ParseFinding:
+    kind: Ambiguity
+    statement: str
+    reason: str
+
+
+@dataclass
+class ParseResult:
+    schema: Schema
+    findings: list[ParseFinding] = field(default_factory=list)
+
+    @property
+    def ok(self) -> bool:
+        return len(self.findings) == 0
+
+
+class DialectParser(ABC):
+    """Uma instância por dialeto (ver dialects/sqlite.py, dialects/postgres.py)."""
+
+    name: str
+
+    @abstractmethod
+    def parse(self, sql: str) -> ParseResult:
+        """Recebe um script SQL (1+ statements) e devolve o Schema (IR) reconhecido, mais qualquer
+        finding de statement não reconhecido (nunca lançar exceção pra DDL desconhecido — reportar)."""
+        raise NotImplementedError
+
+
+_PARSERS: dict[str, DialectParser] = {}
+
+
+def register_parser(dialect: str, parser: DialectParser) -> None:
+    _PARSERS[dialect] = parser
+
+
+def get_parser(dialect: str) -> DialectParser:
+    try:
+        return _PARSERS[dialect]
+    except KeyError:
+        raise ValueError(f"Dialeto sem parser registrado: {dialect!r}. "
+                          f"Disponíveis: {sorted(_PARSERS)}") from None
+
+
+def available_parsers() -> list[str]:
+    return sorted(_PARSERS)

dbbridge/core/planner.py

@@ -0,0 +1,44 @@
+"""Orquestra o pipeline inteiro: SQL origem -> parser do dialeto origem -> IR -> renderer do dialeto
+destino -> SQL destino. É o módulo que `cli.py translate`/`scan`/`patch` chamam — a única peça que
+precisa saber que a pipeline tem essas 2 etapas; parsers/renderers continuam sem se conhecerem.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from .ir import Schema
+from .parser import ParseFinding, get_parser
+from .renderer import RenderFinding, get_renderer
+
+
+@dataclass
+class TranslationResult:
+    source_dialect: str
+    target_dialect: str
+    schema: Schema
+    sql: str
+    parse_findings: list[ParseFinding] = field(default_factory=list)
+    render_findings: list[RenderFinding] = field(default_factory=list)
+
+    @property
+    def review_required(self) -> bool:
+        return bool(self.parse_findings or self.render_findings)
+
+
+def translate(sql: str, source_dialect: str, target_dialect: str) -> TranslationResult:
+    """Ponto de entrada único da pipeline completa. Nunca lança por DDL não reconhecido — reporta via
+    `parse_findings`/`render_findings` e devolve o que CONSEGUIU converter, marcando o resto."""
+    parser = get_parser(source_dialect)
+    renderer = get_renderer(target_dialect)
+
+    parse_result = parser.parse(sql)
+    render_result = renderer.render_schema(parse_result.schema)
+
+    return TranslationResult(
+        source_dialect=source_dialect,
+        target_dialect=target_dialect,
+        schema=parse_result.schema,
+        sql=render_result.sql,
+        parse_findings=parse_result.findings,
+        render_findings=render_result.findings,
+    )

dbbridge/core/renderer.py

@@ -0,0 +1,57 @@
+"""Contrato base do renderer: todo dialeto implementa `DialectRenderer.render_schema(schema) -> str`,
+convertendo a IR de volta pra DDL do dialeto destino. Onde a IR não tem informação suficiente pra
+gerar algo seguro (ex: Trigger — corpo é texto bruto do dialeto ORIGEM, quase sempre incompatível
+com o destino), o renderer devolve isso como uma `RenderFinding` REVIEW_REQUIRED em vez de copiar
+o texto original cegamente (isso seria "inventar tradução perigosa").
+"""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+
+from .ir import Schema
+from .types import Ambiguity
+
+
+@dataclass
+class RenderFinding:
+    kind: Ambiguity
+    target: str  # nome da tabela/view/trigger afetada
+    reason: str
+
+
+@dataclass
+class RenderResult:
+    sql: str
+    findings: list[RenderFinding] = field(default_factory=list)
+
+    @property
+    def ok(self) -> bool:
+        return len(self.findings) == 0
+
+
+class DialectRenderer(ABC):
+    name: str
+
+    @abstractmethod
+    def render_schema(self, schema: Schema) -> RenderResult:
+        raise NotImplementedError
+
+
+_RENDERERS: dict[str, DialectRenderer] = {}
+
+
+def register_renderer(dialect: str, renderer: DialectRenderer) -> None:
+    _RENDERERS[dialect] = renderer
+
+
+def get_renderer(dialect: str) -> DialectRenderer:
+    try:
+        return _RENDERERS[dialect]
+    except KeyError:
+        raise ValueError(f"Dialeto sem renderer registrado: {dialect!r}. "
+                          f"Disponíveis: {sorted(_RENDERERS)}") from None
+
+
+def available_renderers() -> list[str]:
+    return sorted(_RENDERERS)

dbbridge/core/sql_lex.py

@@ -0,0 +1,61 @@
+"""Utilitários de split de texto SQL respeitando parênteses e aspas — usados por TODO dialeto pra
+separar statements (`;`) e itens de coluna dentro de um `CREATE TABLE(...)` (`,`). Não é um
+tokenizer/parser SQL completo (não entende gramática, só profundidade de parênteses e strings) —
+o suficiente pra dividir texto corretamente sem cortar no meio de uma expressão como
+`CHECK(price >= 0 AND price <= 1000)` ou um default `DEFAULT 'a, b'`.
+"""
+from __future__ import annotations
+
+
+def _split_respecting_parens_and_quotes(text: str, sep: str) -> list[str]:
+    parts: list[str] = []
+    depth = 0
+    quote_char: str | None = None
+    current: list[str] = []
+    i = 0
+    while i < len(text):
+        ch = text[i]
+        if quote_char:
+            current.append(ch)
+            if ch == quote_char:
+                # aspa duplicada dentro de string ('' ou "") = escape, não fecha a string
+                if i + 1 < len(text) and text[i + 1] == quote_char:
+                    current.append(text[i + 1])
+                    i += 1
+                else:
+                    quote_char = None
+        elif ch in ("'", '"'):
+            quote_char = ch
+            current.append(ch)
+        elif ch == "(":
+            depth += 1
+            current.append(ch)
+        elif ch == ")":
+            depth -= 1
+            current.append(ch)
+        elif ch == sep and depth == 0:
+            parts.append("".join(current))
+            current = []
+        else:
+            current.append(ch)
+        i += 1
+    if current:
+        parts.append("".join(current))
+    return [p.strip() for p in parts if p.strip()]
+
+
+def split_statements(sql: str) -> list[str]:
+    """Separa um script em statements individuais por `;` no nível 0 de parênteses/aspas."""
+    return _split_respecting_parens_and_quotes(sql, ";")
+
+
+def split_top_level_commas(text: str) -> list[str]:
+    """Separa por `,` no nível 0 — usado pra dividir os itens dentro de `CREATE TABLE nome(...)`."""
+    return _split_respecting_parens_and_quotes(text, ",")
+
+
+def strip_outer_parens(text: str) -> str:
+    text = text.strip()
+    if text.startswith("(") and text.endswith(")"):
+        return text[1:-1].strip()
+    return text

dbbridge/core/types.py

@@ -0,0 +1,47 @@
+"""Sistema de tipos canônico — o vocabulário comum que todo dialeto mapeia PARA (no parser) e DE
+(no renderer). Isso é o que permite N dialetos se conectarem através de UM ponto central em vez de
+N×N conversores diretos: cada dialeto só precisa saber conversar com o `CanonicalType`, nunca com
+os outros dialetos diretamente.
+"""
+from __future__ import annotations
+
+from enum import Enum
+
+
+class CanonicalType(str, Enum):
+    """Vocabulário de tipos que a IR entende. Deliberadamente um conjunto PEQUENO e bem definido —
+    cobre o que os dialetos suportados (Fase 1: SQLite/Postgres) realmente precisam representar,
+    não uma tentativa de modelar todo tipo de coluna que já existiu em algum banco."""
+
+    INTEGER = "integer"
+    SMALLINT = "smallint"
+    BIGINT = "bigint"
+    FLOAT = "float"
+    NUMERIC = "numeric"      # precisão/escala arbitrária (DECIMAL/NUMERIC)
+    BOOLEAN = "boolean"
+    TEXT = "text"
+    VARCHAR = "varchar"      # string de tamanho limitado (tem `length`)
+    DATE = "date"
+    TIME = "time"
+    DATETIME = "datetime"    # sem timezone
+    TIMESTAMP_TZ = "timestamp_tz"
+    JSON = "json"
+    UUID = "uuid"
+    BINARY = "binary"        # BLOB/BYTEA
+    ENUM = "enum"            # valores fixos — ver Column.enum_values
+
+
+# Tipos que exigem um parâmetro extra pra renderizar direito (tamanho, precisão/escala, valores de enum).
+TYPES_WITH_LENGTH = {CanonicalType.VARCHAR}
+TYPES_WITH_PRECISION = {CanonicalType.NUMERIC}
+
+
+class Ambiguity(str, Enum):
+    """Por que uma tradução NÃO foi feita automaticamente — usado tanto pelo parser (DDL não
+    reconhecido) quanto pelo scanner (padrão de código arriscado)."""
+
+    UNRECOGNIZED_DDL = "unrecognized_ddl"
+    UNSUPPORTED_TYPE = "unsupported_type"
+    AMBIGUOUS_DEFAULT = "ambiguous_default"
+    UNSUPPORTED_EXPRESSION = "unsupported_expression"
+    MULTIPLE_STATEMENTS_IN_ONE = "multiple_statements_in_one"

dbbridge/dialects/__init__.py

@@ -0,0 +1,6 @@
+"""Implementações por dialeto. Importar este pacote registra todos os dialetos disponíveis nos
+registries de core/parser.py e core/renderer.py (via register_parser/register_renderer chamados no
+import de cada módulo de dialeto). Dialetos "estrutura preparada" (mysql, sqlserver — Fases 2/5)
+aparecem em `available_parsers()`/`available_renderers()` mas levantam `NotImplementedError` com
+mensagem clara SE alguém tentar usá-los de verdade — nunca na importação."""
+from . import mysql, postgres, sqlite, sqlserver  # noqa: F401 — o import já registra os dialetos

dbbridge/dialects/_stub.py

@@ -0,0 +1,31 @@
+"""Base compartilhada dos dialetos "estrutura preparada, não implementados ainda" (mysql, sqlserver
+nesta fase — ver README.md/ENTREGA do projeto pra fases). Registrar um stub (em vez de simplesmente
+não registrar nada) permite que `available_parsers()`/`available_renderers()` e a CLI mostrem esses
+dialetos como "conhecidos, ainda não implementados" com uma mensagem clara — melhor experiência que
+um erro genérico de "dialeto desconhecido"."""
+from __future__ import annotations
+
+from ..core.parser import DialectParser, ParseResult
+from ..core.renderer import DialectRenderer, RenderResult
+
+
+class NotImplementedDialectParser(DialectParser):
+    def __init__(self, name: str, phase: str):
+        self.name = name
+        self._phase = phase
+
+    def parse(self, sql: str) -> ParseResult:
+        raise NotImplementedError(
+            f"Parser do dialeto '{self.name}' ainda não implementado (planejado pra {self._phase}). "
+            f"Estrutura do módulo já existe em dialects/{self.name}.py — ver README.md/ROADMAP.")
+
+
+class NotImplementedDialectRenderer(DialectRenderer):
+    def __init__(self, name: str, phase: str):
+        self.name = name
+        self._phase = phase
+
+    def render_schema(self, schema) -> RenderResult:
+        raise NotImplementedError(
+            f"Renderer do dialeto '{self.name}' ainda não implementado (planejado pra {self._phase}). "
+            f"Estrutura do módulo já existe em dialects/{self.name}.py — ver README.md/ROADMAP.")

dbbridge/dialects/mysql.py

@@ -0,0 +1,16 @@
+"""Dialeto MySQL — estrutura preparada (Fase 2 do roadmap), ainda não implementado.
+
+Quando chegar a hora: mapa de tipos (INT/TINYINT/AUTO_INCREMENT/ENUM nativo/JSON/DATETIME), parser
+de CREATE TABLE no mesmo padrão de dialects/sqlite.py e dialects/postgres.py (reaproveitando
+core/sql_lex.py pra split de statements/colunas), tratamento de `ON UPDATE CURRENT_TIMESTAMP`
+(peculiaridade MySQL sem equivalente direto) e `ENGINE=InnoDB`/charset (ignorados na IR — são
+metadados de armazenamento, não de schema lógico).
+"""
+from __future__ import annotations
+
+from ..core.parser import register_parser
+from ..core.renderer import register_renderer
+from ._stub import NotImplementedDialectParser, NotImplementedDialectRenderer
+
+register_parser("mysql", NotImplementedDialectParser("mysql", "Fase 2"))
+register_renderer("mysql", NotImplementedDialectRenderer("mysql", "Fase 2"))