@danhachuel/prodmaker 0.1.10 → 0.1.12

package/app/services/database.py

@@ -1,200 +1,237 @@
-"""Banco SQLite local (stdlib) — helpers compartilhados."""
-import sqlite3
-import time
-from pathlib import Path
+"""Banco de dados — façade sobre dbengine (SQLite padrão, PostgreSQL/Supabase via DATABASE_URL).
 
-from .store import STATE
+Esquema único para os dois engines. Todas as tabelas carregam `user_id` (preparação
+multi-tenant — hoje vazio). `ensure_db()` cria o que falta e aplica ALTERs de migração.
+"""
+from .dbengine import (
+    add_column_if_missing,
+    is_postgres,
+    now_str,  # noqa: F401  (reexportado para os serviços)
+    row_to_dict,  # noqa: F401  (reexportado para os serviços)
+)
 
-DB_PATH = STATE / "prodmaker.db"
+# ---------------------------------------------------------------------------
+# Esquema — SQLite DDL; para PostgreSQL as mesmas definições são traduzidas.
+# ---------------------------------------------------------------------------
 
-
-def get_db():
-    STATE.mkdir(parents=True, exist_ok=True)
-    conn = sqlite3.connect(DB_PATH)
-    conn.row_factory = sqlite3.Row
-    return conn
-
-
-def ensure_db() -> None:
-    with get_db() as conn:
-        conn.execute(
-            """
-            CREATE TABLE IF NOT EXISTS produtos (
-                id INTEGER PRIMARY KEY AUTOINCREMENT,
-                nome TEXT NOT NULL,
-                plataforma TEXT NOT NULL DEFAULT 'Outro',
-                link_afiliado TEXT NOT NULL DEFAULT '',
-                comissao REAL NOT NULL DEFAULT 0,
-                preco REAL NOT NULL DEFAULT 0,
-                nicho TEXT NOT NULL DEFAULT '',
-                status TEXT NOT NULL DEFAULT 'em_analise',
-                created_at TEXT NOT NULL,
-                updated_at TEXT NOT NULL
-            )
-            """
+TABLES = {
+    "produtos": """
+        CREATE TABLE IF NOT EXISTS produtos (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            user_id TEXT NOT NULL DEFAULT '',
+            nome TEXT NOT NULL,
+            plataforma TEXT NOT NULL DEFAULT 'Outro',
+            link_afiliado TEXT NOT NULL DEFAULT '',
+            comissao REAL NOT NULL DEFAULT 0,
+            preco REAL NOT NULL DEFAULT 0,
+            nicho TEXT NOT NULL DEFAULT '',
+            status TEXT NOT NULL DEFAULT 'em_analise',
+            analysis TEXT NOT NULL DEFAULT '',
+            created_at TEXT NOT NULL,
+            updated_at TEXT NOT NULL
         )
-        conn.execute(
-            """
-            CREATE TABLE IF NOT EXISTS infoprodutos (
-                id INTEGER PRIMARY KEY AUTOINCREMENT,
-                titulo TEXT NOT NULL,
-                formato TEXT NOT NULL DEFAULT 'E-book',
-                nicho TEXT NOT NULL DEFAULT '',
-                modo TEXT NOT NULL DEFAULT 'rapido',
-                provider TEXT NOT NULL DEFAULT '',
-                pdf_path TEXT NOT NULL DEFAULT '',
-                md_path TEXT NOT NULL DEFAULT '',
-                created_at TEXT NOT NULL
-            )
-            """
+    """,
+    "infoprodutos": """
+        CREATE TABLE IF NOT EXISTS infoprodutos (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            user_id TEXT NOT NULL DEFAULT '',
+            titulo TEXT NOT NULL,
+            formato TEXT NOT NULL DEFAULT 'E-book',
+            nicho TEXT NOT NULL DEFAULT '',
+            modo TEXT NOT NULL DEFAULT 'rapido',
+            provider TEXT NOT NULL DEFAULT '',
+            pdf_path TEXT NOT NULL DEFAULT '',
+            md_path TEXT NOT NULL DEFAULT '',
+            created_at TEXT NOT NULL
         )
-        conn.execute(
-            """
-            CREATE TABLE IF NOT EXISTS paginas (
-                id INTEGER PRIMARY KEY AUTOINCREMENT,
-                titulo TEXT NOT NULL,
-                tipo TEXT NOT NULL,
-                produto_id INTEGER,
-                idioma TEXT NOT NULL DEFAULT 'Portugues',
-                html_path TEXT NOT NULL DEFAULT '',
-                status TEXT NOT NULL DEFAULT 'rascunho',
-                published_url TEXT NOT NULL DEFAULT '',
-                created_at TEXT NOT NULL,
-                updated_at TEXT NOT NULL
-            )
-            """
+    """,
+    "paginas": """
+        CREATE TABLE IF NOT EXISTS paginas (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            user_id TEXT NOT NULL DEFAULT '',
+            titulo TEXT NOT NULL,
+            tipo TEXT NOT NULL,
+            produto_id INTEGER,
+            idioma TEXT NOT NULL DEFAULT 'Portugues',
+            html_path TEXT NOT NULL DEFAULT '',
+            status TEXT NOT NULL DEFAULT 'rascunho',
+            published_url TEXT NOT NULL DEFAULT '',
+            created_at TEXT NOT NULL,
+            updated_at TEXT NOT NULL
         )
-        conn.execute(
-            """
-            CREATE TABLE IF NOT EXISTS dominios (
-                id INTEGER PRIMARY KEY AUTOINCREMENT,
-                nome TEXT NOT NULL,
-                status TEXT NOT NULL DEFAULT 'pendente',
-                cf_zone_id TEXT NOT NULL DEFAULT '',
-                ns_data TEXT NOT NULL DEFAULT '',
-                a_data TEXT NOT NULL DEFAULT '',
-                tags TEXT NOT NULL DEFAULT '',
-                created_at TEXT NOT NULL,
-                updated_at TEXT NOT NULL
-            )
-            """
+    """,
+    "dominios": """
+        CREATE TABLE IF NOT EXISTS dominios (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            user_id TEXT NOT NULL DEFAULT '',
+            nome TEXT NOT NULL,
+            status TEXT NOT NULL DEFAULT 'pendente',
+            cf_zone_id TEXT NOT NULL DEFAULT '',
+            ns_data TEXT NOT NULL DEFAULT '',
+            a_data TEXT NOT NULL DEFAULT '',
+            tags TEXT NOT NULL DEFAULT '',
+            created_at TEXT NOT NULL,
+            updated_at TEXT NOT NULL
         )
-        conn.execute(
-            """
-            CREATE TABLE IF NOT EXISTS visitas (
-                id INTEGER PRIMARY KEY AUTOINCREMENT,
-                event TEXT NOT NULL DEFAULT '',
-                page TEXT NOT NULL DEFAULT '',
-                gclid TEXT NOT NULL DEFAULT '',
-                utm_source TEXT NOT NULL DEFAULT '',
-                utm_medium TEXT NOT NULL DEFAULT '',
-                utm_campaign TEXT NOT NULL DEFAULT '',
-                ref TEXT NOT NULL DEFAULT '',
-                ip TEXT NOT NULL DEFAULT '',
-                user_agent TEXT NOT NULL DEFAULT '',
-                extra TEXT NOT NULL DEFAULT '',
-                created_at TEXT NOT NULL
-            )
-            """
+    """,
+    "visitas": """
+        CREATE TABLE IF NOT EXISTS visitas (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            user_id TEXT NOT NULL DEFAULT '',
+            event TEXT NOT NULL DEFAULT '',
+            page TEXT NOT NULL DEFAULT '',
+            gclid TEXT NOT NULL DEFAULT '',
+            utm_source TEXT NOT NULL DEFAULT '',
+            utm_medium TEXT NOT NULL DEFAULT '',
+            utm_campaign TEXT NOT NULL DEFAULT '',
+            ref TEXT NOT NULL DEFAULT '',
+            ip TEXT NOT NULL DEFAULT '',
+            user_agent TEXT NOT NULL DEFAULT '',
+            extra TEXT NOT NULL DEFAULT '',
+            created_at TEXT NOT NULL
         )
-        conn.execute(
-            """
-            CREATE TABLE IF NOT EXISTS vendas (
-                id INTEGER PRIMARY KEY AUTOINCREMENT,
-                fonte TEXT NOT NULL DEFAULT 'manual',
-                produto_id INTEGER,
-                produto_nome TEXT NOT NULL DEFAULT '',
-                transacao_id TEXT NOT NULL DEFAULT '',
-                comprador_email TEXT NOT NULL DEFAULT '',
-                valor REAL NOT NULL DEFAULT 0,
-                comissao REAL NOT NULL DEFAULT 0,
-                gclid TEXT NOT NULL DEFAULT '',
-                utm_source TEXT NOT NULL DEFAULT '',
-                utm_medium TEXT NOT NULL DEFAULT '',
-                utm_campaign TEXT NOT NULL DEFAULT '',
-                status TEXT NOT NULL DEFAULT 'aprovada',
-                conversao_status TEXT NOT NULL DEFAULT 'pendente',
-                conversao_erro TEXT NOT NULL DEFAULT '',
-                gclid_match TEXT NOT NULL DEFAULT '',
-                raw TEXT NOT NULL DEFAULT '',
-                created_at TEXT NOT NULL
-            )
-            """
+    """,
+    "vendas": """
+        CREATE TABLE IF NOT EXISTS vendas (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            user_id TEXT NOT NULL DEFAULT '',
+            fonte TEXT NOT NULL DEFAULT 'manual',
+            produto_id INTEGER,
+            produto_nome TEXT NOT NULL DEFAULT '',
+            transacao_id TEXT NOT NULL DEFAULT '',
+            comprador_email TEXT NOT NULL DEFAULT '',
+            valor REAL NOT NULL DEFAULT 0,
+            comissao REAL NOT NULL DEFAULT 0,
+            gclid TEXT NOT NULL DEFAULT '',
+            utm_source TEXT NOT NULL DEFAULT '',
+            utm_medium TEXT NOT NULL DEFAULT '',
+            utm_campaign TEXT NOT NULL DEFAULT '',
+            status TEXT NOT NULL DEFAULT 'aprovada',
+            conversao_status TEXT NOT NULL DEFAULT 'pendente',
+            conversao_erro TEXT NOT NULL DEFAULT '',
+            gclid_match TEXT NOT NULL DEFAULT '',
+            raw TEXT NOT NULL DEFAULT '',
+            created_at TEXT NOT NULL
         )
-        conn.execute("CREATE INDEX IF NOT EXISTS idx_vendas_gclid ON vendas (gclid)")
-        conn.execute("CREATE INDEX IF NOT EXISTS idx_vendas_created ON vendas (created_at)")
-        conn.execute("CREATE INDEX IF NOT EXISTS idx_visitas_gclid ON visitas (gclid)")
-        conn.execute(
-            """
-            CREATE TABLE IF NOT EXISTS palavras (
-                id INTEGER PRIMARY KEY AUTOINCREMENT,
-                produto_id INTEGER,
-                produto_nome TEXT NOT NULL DEFAULT '',
-                tipo TEXT NOT NULL DEFAULT 'positiva',
-                texto TEXT NOT NULL,
-                correspondencia TEXT NOT NULL DEFAULT 'frase',
-                origem TEXT NOT NULL DEFAULT 'ia',
-                created_at TEXT NOT NULL
-            )
-            """
+    """,
+    "palavras": """
+        CREATE TABLE IF NOT EXISTS palavras (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            user_id TEXT NOT NULL DEFAULT '',
+            produto_id INTEGER,
+            produto_nome TEXT NOT NULL DEFAULT '',
+            tipo TEXT NOT NULL DEFAULT 'positiva',
+            texto TEXT NOT NULL,
+            correspondencia TEXT NOT NULL DEFAULT 'frase',
+            origem TEXT NOT NULL DEFAULT 'ia',
+            created_at TEXT NOT NULL
+        )
+    """,
+    "campanhas": """
+        CREATE TABLE IF NOT EXISTS campanhas (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            user_id TEXT NOT NULL DEFAULT '',
+            produto_id INTEGER,
+            plataforma TEXT NOT NULL DEFAULT 'google',
+            nome TEXT NOT NULL,
+            objetivo TEXT NOT NULL DEFAULT '',
+            cpa_alvo REAL NOT NULL DEFAULT 0,
+            orcamento_diario REAL NOT NULL DEFAULT 0,
+            keywords_json TEXT NOT NULL DEFAULT '[]',
+            negativas_json TEXT NOT NULL DEFAULT '[]',
+            criativos_json TEXT NOT NULL DEFAULT '[]',
+            plano_json TEXT NOT NULL DEFAULT '',
+            status TEXT NOT NULL DEFAULT 'rascunho',
+            resultado_json TEXT NOT NULL DEFAULT '',
+            erro TEXT NOT NULL DEFAULT '',
+            created_at TEXT NOT NULL,
+            updated_at TEXT NOT NULL
         )
-        conn.execute(
-            """
-            CREATE TABLE IF NOT EXISTS campanhas (
-                id INTEGER PRIMARY KEY AUTOINCREMENT,
-                produto_id INTEGER,
-                plataforma TEXT NOT NULL DEFAULT 'google',
-                nome TEXT NOT NULL,
-                objetivo TEXT NOT NULL DEFAULT '',
-                cpa_alvo REAL NOT NULL DEFAULT 0,
-                orcamento_diario REAL NOT NULL DEFAULT 0,
-                keywords_json TEXT NOT NULL DEFAULT '[]',
-                negativas_json TEXT NOT NULL DEFAULT '[]',
-                criativos_json TEXT NOT NULL DEFAULT '[]',
-                plano_json TEXT NOT NULL DEFAULT '',
-                status TEXT NOT NULL DEFAULT 'rascunho',
-                resultado_json TEXT NOT NULL DEFAULT '',
-                erro TEXT NOT NULL DEFAULT '',
-                created_at TEXT NOT NULL,
-                updated_at TEXT NOT NULL
-            )
-            """
+    """,
+    "lancamentos": """
+        CREATE TABLE IF NOT EXISTS lancamentos (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            user_id TEXT NOT NULL DEFAULT '',
+            produto_id INTEGER,
+            etapa_atual INTEGER NOT NULL DEFAULT 1,
+            status TEXT NOT NULL DEFAULT 'em_andamento',
+            dados_json TEXT NOT NULL DEFAULT '{}',
+            created_at TEXT NOT NULL,
+            updated_at TEXT NOT NULL
         )
-        columns = [row["name"] for row in conn.execute("PRAGMA table_info(produtos)")]
-        if "analysis" not in columns:
-            conn.execute("ALTER TABLE produtos ADD COLUMN analysis TEXT NOT NULL DEFAULT ''")
-        conn.execute(
-            """
-            CREATE TABLE IF NOT EXISTS lancamentos (
-                id INTEGER PRIMARY KEY AUTOINCREMENT,
-                produto_id INTEGER,
-                etapa_atual INTEGER NOT NULL DEFAULT 1,
-                status TEXT NOT NULL DEFAULT 'em_andamento',
-                dados_json TEXT NOT NULL DEFAULT '{}',
-                created_at TEXT NOT NULL,
-                updated_at TEXT NOT NULL
-            )
-            """
+    """,
+    "notificacoes": """
+        CREATE TABLE IF NOT EXISTS notificacoes (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            user_id TEXT NOT NULL DEFAULT '',
+            event TEXT NOT NULL DEFAULT '',
+            titulo TEXT NOT NULL DEFAULT '',
+            mensagem TEXT NOT NULL DEFAULT '',
+            canal TEXT NOT NULL DEFAULT '',
+            status TEXT NOT NULL DEFAULT 'pendente',
+            erro TEXT NOT NULL DEFAULT '',
+            created_at TEXT NOT NULL
         )
-        conn.execute(
-            """
-            CREATE TABLE IF NOT EXISTS notificacoes (
-                id INTEGER PRIMARY KEY AUTOINCREMENT,
-                event TEXT NOT NULL DEFAULT '',
-                titulo TEXT NOT NULL DEFAULT '',
-                mensagem TEXT NOT NULL DEFAULT '',
-                canal TEXT NOT NULL DEFAULT '',
-                status TEXT NOT NULL DEFAULT 'pendente',
-                erro TEXT NOT NULL DEFAULT '',
-                created_at TEXT NOT NULL
-            )
-            """
+    """,
+    "pins": """
+        CREATE TABLE IF NOT EXISTS pins (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            user_id TEXT NOT NULL DEFAULT '',
+            produto_id INTEGER,
+            titulo TEXT NOT NULL,
+            descricao TEXT NOT NULL DEFAULT '',
+            texto_imagem TEXT NOT NULL DEFAULT '',
+            sugestao_imagem TEXT NOT NULL DEFAULT '',
+            board TEXT NOT NULL DEFAULT '',
+            link TEXT NOT NULL DEFAULT '',
+            status TEXT NOT NULL DEFAULT 'ideia',
+            provider TEXT NOT NULL DEFAULT '',
+            erro TEXT NOT NULL DEFAULT '',
+            created_at TEXT NOT NULL
         )
+    """,
+    "investimentos": """
+        CREATE TABLE IF NOT EXISTS investimentos (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            user_id TEXT NOT NULL DEFAULT '',
+            data TEXT NOT NULL DEFAULT '',
+            valor REAL NOT NULL DEFAULT 0,
+            fonte TEXT NOT NULL DEFAULT 'manual',
+            observacao TEXT NOT NULL DEFAULT '',
+            created_at TEXT NOT NULL
+        )
+    """,
+}
+
+ALL_TABLES = list(TABLES.keys())
 
 
-def now_str() -> str:
-    return time.strftime("%Y-%m-%d %H:%M:%S")
+def _pg_ddl(sqlite_ddl: str) -> str:
+    """Traduz o DDL SQLite para PostgreSQL."""
+    return sqlite_ddl.replace("INTEGER PRIMARY KEY AUTOINCREMENT", "BIGSERIAL PRIMARY KEY")
+
+
+def get_db():
+    from .dbengine import connect
+
+    return connect()
+
+
+def ensure_db() -> None:
+    with get_db() as conn:
+        if is_postgres():
+            for ddl in TABLES.values():
+                conn.execute(_pg_ddl(ddl))
+        else:
+            for ddl in TABLES.values():
+                conn.execute(ddl)
+            # Migração: bancos criados antes da coluna user_id / da tabela investimentos
+            for table in ALL_TABLES:
+                add_column_if_missing(conn, table, "user_id TEXT NOT NULL DEFAULT ''", "user_id")
+            if "investimentos" not in [row["name"] for row in conn.execute("SELECT name FROM sqlite_master WHERE type='table'")]:
+                conn.execute(TABLES["investimentos"])
+        conn.execute("CREATE INDEX IF NOT EXISTS idx_vendas_gclid ON vendas (gclid)")
+        conn.execute("CREATE INDEX IF NOT EXISTS idx_visitas_gclid ON visitas (gclid)")
 
 
-def row_to_dict(row) -> dict:
-    return {key: row[key] for key in row.keys()}
+ensure_db()

package/app/services/dbengine.py

@@ -0,0 +1,195 @@
+"""Camada de abstração de banco — SQLite (padrão) + PostgreSQL/Supabase (DATABASE_URL).
+
+Objetivo (radar Supabase): o sistema aceita `DATABASE_URL` apontando para o PostgreSQL
+do Supabase SEM quebrar a compatibilidade local com SQLite. Todos os serviços continuam
+usando `get_db()` com a mesma API (execute/fetchall/fetchone, context manager, rows
+acessíveis por nome de coluna). Para PostgreSQL os placeholders `?` são traduzidos para
+`%s` e as linhas viram dicts (mesmo acesso por nome).
+
+Multi-tenant (preparado, NÃO implementado): todas as tabelas têm `user_id TEXT DEFAULT ''`.
+Quando o Supabase Auth entrar, basta filtrar por `current_user_id()` (hoje retorna '').
+"""
+import os
+import sqlite3
+import time
+import uuid
+from pathlib import Path
+
+from .store import STATE
+
+
+def now_str() -> str:
+    return time.strftime("%Y-%m-%d %H:%M:%S")
+
+
+def row_to_dict(row) -> dict:
+    if row is None:
+        return {}
+    if isinstance(row, dict):
+        return dict(row)
+    return {key: row[key] for key in row.keys()}
+
+
+def dsn() -> str | None:
+    return (os.environ.get("DATABASE_URL") or "").strip() or None
+
+
+def is_postgres() -> bool:
+    value = dsn()
+    return bool(value and value.startswith(("postgres://", "postgresql://")))
+
+
+def engine_name() -> str:
+    return "postgres" if is_postgres() else "sqlite"
+
+
+def current_user_id() -> str:
+    """Placeholder multi-tenant: vazio enquanto não houver Supabase Auth."""
+    return (os.environ.get("PRODMAKER_USER_ID") or "").strip()
+
+
+def new_user_id() -> str:
+    return str(uuid.uuid4())
+
+
+# ---------------------------------------------------------------------------
+# PostgreSQL — wrapper mínimo (imports preguiçosos de psycopg)
+# ---------------------------------------------------------------------------
+
+
+def _translate(sql: str) -> str:
+    return sql.replace("?", "%s")
+
+
+class _PgRow(dict):
+    """Acesso por nome (row["col"]) como sqlite3.Row."""
+
+
+class _PgResult:
+    def __init__(self, cursor):
+        self._cursor = cursor
+        self._description = cursor.description
+        self._rows = None
+
+    def _materialize(self):
+        if self._rows is None:
+            columns = [col.name for col in self._description] if self._description else []
+            self._rows = [_PgRow(zip(columns, values)) for values in (self._cursor.fetchall() if self._description else [])]
+
+    def fetchall(self):
+        self._materialize()
+        return list(self._rows)
+
+    def fetchone(self):
+        self._materialize()
+        return self._rows[0] if self._rows else None
+
+    @property
+    def lastrowid(self):
+        # PostgreSQL: capturamos o id via RETURNING nas inserções específicas
+        self._materialize()
+        row = self._rows[0] if self._rows else None
+        return row.get("id") if row else None
+
+    def __iter__(self):
+        self._materialize()
+        return iter(self._rows)
+
+
+class _PgConn:
+    def __init__(self, connection):
+        self._conn = connection
+
+    def execute(self, sql: str, params=()):
+        cursor = self._conn.cursor()
+        cursor.execute(_translate(sql), tuple(params or ()))
+        return _PgResult(cursor)
+
+    def executescript(self, sql: str):
+        cursor = self._conn.cursor()
+        cursor.execute(sql)
+        return _PgResult(cursor)
+
+    def commit(self):
+        self._conn.commit()
+
+    def close(self):
+        try:
+            self._conn.rollback()
+        except Exception:  # noqa: BLE001
+            pass
+        self._conn.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc, tb):
+        if exc_type is None:
+            self._conn.commit()
+        else:
+            self._conn.rollback()
+        self.close()
+
+
+# ---------------------------------------------------------------------------
+# Conexão
+# ---------------------------------------------------------------------------
+
+
+def _sqlite_path():
+    STATE.mkdir(parents=True, exist_ok=True)
+    return STATE / "prodmaker.db"
+
+
+def connect():
+    """Conexão do engine ativo (sqlite padrão; postgres quando DATABASE_URL definido)."""
+    if is_postgres():
+        try:
+            import psycopg
+        except ImportError as exc:
+            raise RuntimeError(
+                "DATABASE_URL definido, mas o driver psycopg não está instalado — "
+                "rode 'pip install psycopg[binary]' (ou 'prodmaker install' com o requirements atualizado)."
+            ) from exc
+        try:
+            connection = psycopg.connect(dsn(), connect_timeout=10)
+        except Exception as exc:  # noqa: BLE001
+            raise RuntimeError(
+                f"Falha ao conectar no PostgreSQL (DATABASE_URL): {exc}. "
+                "Confira a connection string do Supabase ou desdefina DATABASE_URL para voltar ao SQLite local."
+            ) from exc
+        return _PgConn(connection)
+    conn = sqlite3.connect(_sqlite_path())
+    conn.row_factory = sqlite3.Row
+    return conn
+
+
+# Compatibilidade com o nome antigo usado pelos serviços
+def get_db():
+    return connect()
+
+
+# ---------------------------------------------------------------------------
+# Introspecção / migração (dialect-aware)
+# ---------------------------------------------------------------------------
+
+
+def table_columns(conn, table: str) -> list[str]:
+    if is_postgres():
+        rows = (
+            conn.execute(
+                "SELECT column_name AS name FROM information_schema.columns WHERE table_name = %s",
+                (table,),
+            )
+            .fetchall()
+        )
+        return [row["name"] for row in rows]
+    rows = conn.execute(f"PRAGMA table_info({table})").fetchall()
+    return [row["name"] for row in rows]
+
+
+def add_column_if_missing(conn, table: str, column_ddl: str, column_name: str) -> bool:
+    if column_name not in table_columns(conn, table):
+        conn.execute(f"ALTER TABLE {table} ADD COLUMN {column_ddl}")
+        return True
+    return False