SQLAlchemy com Python: modelagem e consultas para análise de dados

Saudando e apresentando audiodescrição

Olá!

Audiodescrição: Eu sou uma mulher branca, de cabelo curto, loiro e liso. Uso óculos de grau retangulares na cor roxa metálica e estou vestindo uma camiseta branca com gola de três cores: azul, vermelho e amarelo. Atrás de mim, há uma parede cinza com uma estante contendo alguns objetos de brincadeira.

Apresentando o curso e objetivos

Neste curso, eu irei acompanhar você para ensinar sobre SQL e sobre a biblioteca SQLAlchemy do Python.

Vamos aprender a manipular dados, a gerar e criar tabelas e, ao final de todas estas aulas, a responder perguntas das áreas de produto, de negócios e da área comercial com base em dados.

As pessoas gestoras farão algumas perguntas, e nós poderemos respondê-las utilizando a linguagem SQL e a biblioteca SQLAlchemy, com as quais podemos filtrar, agrupar e combinar tabelas entre si para obter mais informações.

Consolidando aprendizados e despedindo-se

Ao final dessas aulas, seremos capazes, de forma simples e rápida, de manipular dados a partir de uma base de dados utilizando diversas instruções SQL em conjunto com a biblioteca SQLAlchemy, uma das mais utilizadas na área de dados.

Até mais!

Introduzindo a biblioteca SQLAlchemy e motivações

Olá a todas as pessoas. Nesta aula, vamos entender o que é a biblioteca SQLAlchemy, por que ela existe, instalar e configurar nosso ambiente, criar a conexão com a base de dados e aprender a usar a IA para aumentar nossa produtividade no dia a dia.

Imaginemos que somos uma pessoa analista de dados recém-contratada por uma empresa chamada Data Vendas. Já no primeiro dia, recebemos o primeiro desafio: conectar a base de dados que sustentará todos os relatórios e análises da empresa. Poderíamos construir uma string (cadeia de caracteres) SQL manualmente, mas isso é inseguro, frágil e difícil de migrar entre bases de dados. A SQLAlchemy surgiu justamente para nos ajudar a resolver esse problema: ela traduz nosso código Python para SQL de forma automática e segura.

Por que utilizar essa biblioteca? Porque é fácil migrar entre bases de dados. Por exemplo, se temos SQLite e precisamos migrar para PostgreSQL, com uma única linha de código podemos fazer essa mudança. Além disso, conseguimos montar pipelines (fluxos) de ingestão de dados, construir APIs com FastAPI e evitar SQL Injection (injeção de SQL) ao lidar com dados externos.

Instalando dependências e importando bibliotecas

Agora que já formamos uma breve ideia do que é a biblioteca, vamos realizar as instalações necessárias. Precisamos instalar a biblioteca SQLAlchemy e a biblioteca Pandas, que nos ajudará com suporte a análises — ela é muito conhecida na área de dados e usada com frequência no dia a dia.

Para isso, podemos executar:

# !pip install sqlalchemy pandas

A priori, vamos carregar algumas bibliotecas. Primeiro, vamos usar a biblioteca padrão do Python, pathlib, da qual importaremos a classe Path, que ajudará a percorrer nossos diretórios. Faremos a importação da biblioteca SQLAlchemy e também importaremos uma função específica, create_engine, que nos ajudará a criar nossa conexão com a base de dados. Executamos o código e funcionou corretamente.

from pathlib import Path
import sqlalchemy
from sqlalchemy import create_engine

Explicando a engine e configurando a URL de conexão

Agora, vamos criar nossa conexão. A Engine é a porta de entrada da biblioteca SQLAlchemy. Ela representa a conexão com a base e gerencia o pool (conjunto) de conexões em segundo plano, de forma que não precisamos nos preocupar com esses detalhes, pois a biblioteca realiza essa gestão diretamente.

Por padrão, sempre precisamos de uma URL de conexão, que possui a seguinte estrutura: dialeto + driver (controlador), usuário, senha, host, porta e nome da base. Neste curso, vamos usar SQLite, que é uma base em arquivo — ideal para desenvolvimento e também para portfólio. Nesse caso, o dialeto é SQLite, seguido do caminho da pasta e do nome do arquivo que vamos definir como nossa base de dados.

Para deixar claro o formato que vamos usar com SQLite, a URL ficará assim:

"sqlite:///../database/datavendas.db"

Se fosse PostgreSQL, bastaria alterar o dialeto para PostgreSQL, além de configurar o usuário, a senha, localhost, a porta e o nome da base, por exemplo.

Um ponto importante: em projetos reais, a URL de conexão nunca deve ficar disponível diretamente no código (hard-coded). Por quê? Porque pessoas mal-intencionadas podem obter essas credenciais e usá-las para finalidades indevidas. Por isso, é importante sempre carregar essas informações por meio de variáveis de ambiente, evitando expor credenciais. Um exemplo prático seria manter essas variáveis em um arquivo separado e não expô-lo no repositório.

Preparando diretório e criando a engine

Agora, vamos criar nossa conexão de fato. Vamos utilizar a classe Path para especificar o caminho da pasta onde queremos salvar a base. Essa pasta será "database", e queremos criá-la. Vamos usar mkdir com exists_ok=True: se a pasta já existir, tudo bem; caso contrário, vamos criá-la.

Começando pelo caminho:

Path()

Ajustamos para apontar para a pasta desejada:

Path('../database')

Criamos a pasta:

Path('../database').mkdir()

E garantimos que não dará erro caso ela já exista:

Path('../database').mkdir(exist_ok=True)

Em seguida, vamos criar nossa engine, que é a ponte com a base de dados. Vamos nomeá-la na variável engine e criá-la utilizando create_engine. Primeiro estruturamos a chamada e, em seguida, inserimos a URL de conexão e o parâmetro echo=True para visualizar as instruções SQL geradas.

Começamos declarando a variável:

engine = create_engine()

Em seguida, informamos a URL do SQLite:

engine = create_engine("sqlite:///../database/datavendas.db")

E habilitamos o echo para aprendizado e depuração:

engine = create_engine(
    "sqlite:///../database/datavendas.db",
    echo=True
)

Por fim, vamos realizar um print para verificar se a engine foi criada. Com a criação confirmada, vamos testar a conexão para garantir que tudo está correto.

print(f'Engine criada: {engine}')

Testando a conexão e apresentando camadas do SQLAlchemy

Vamos importar o módulo text, que faz parte da biblioteca SQLAlchemy. Esse módulo auxilia na escrita de instruções SQL.

from sqlalchemy import text

Em seguida, abriremos a conexão com o nosso banco de dados. Vamos passar uma instrução simples e usar o gerenciador de contexto with para chamar o objeto engine que criamos anteriormente, utilizando a função connect(). Nomearemos essa conexão como com, de “conexão”.

Inicialmente, um exemplo com pequenos erros ilustra as correções que precisamos fazer (aspas e nome do método):

resultado = conn.excute(text("SELECT 'Conexão OK AS status'"))

Agora, com os ajustes aplicados — uso correto de aspas simples na string SQL e do método execute — obtemos o resultado e imprimimos a primeira linha retornada:

with engine.connect() as conn:
    resultado = conn.execute(text("SELECT 'Conexão OK' AS status"))
    print(resultado.fetchone())

Em seguida, vamos imprimir o resultado na tela para verificar se a conexão foi bem-sucedida. Após os ajustes, a conexão funcionou corretamente. É importante prestar atenção ao nome das funções.

Um ponto importante: usar with é uma boa prática, pois garante o fechamento da conexão mesmo em caso de erro. Com isso, o contexto sempre abrirá e fechará a conexão para nós.

Criamos a conexão, testamos e agora vamos avançar para entender duas camadas importantes do SQLAlchemy: o Core (núcleo), mais próximo do SQL do banco, e a ORM (mapeamento objeto-relacional), com a qual podemos mapear objetos Python. Durante o curso, usaremos ambas as camadas. É fundamental consultar a documentação da biblioteca para evoluirmos e aprendermos continuamente.

Inspecionando o banco e verificando tabelas

Agora, vamos verificar se o banco foi realmente criado, já que estabelecemos a conexão anteriormente. Para isso, usaremos o módulo inspect do SQLAlchemy. Vamos importar a função inspect e criar um inspector, passando a nossa engine.

from sqlalchemy import inspect

Criamos o inspector com a engine:

inspector = inspect(engine)

Em seguida, obteremos uma lista com os nomes das tabelas existentes no banco utilizando o método get_table_names(). Vamos armazenar essa lista em uma variável tabelas e verificar se existem tabelas. Se tabelas contiver resultados, imprimimos tabelas; caso contrário, imprimimos que o banco foi criado e está vazio.

tabelas = inspector.get_table_names()

if tabelas:
    print('Tabelas no banco: ')
else:
    print('Banco criado e vazio')

Como podemos observar, o banco ainda está vazio. Por quê? Porque ainda não criamos as tabelas. Na próxima aula, veremos como criar essas tabelas. O banco está disponível, apenas vazio.

Utilizando IA para gerar conexão com PostgreSQL

Como mencionamos no início da aula, vamos usar IA para aumentar nossa produtividade. Atualmente, há diversas IAs que auxiliam no dia a dia. Vamos criar um prompt (enunciado) para uma tarefa comum: configurar conexões com bancos usando IA. O prompt (enunciado) é o seguinte: gerar o código SQLAlchemy para criar uma engine conectando ao PostgreSQL, lembrando que usamos SQLite aqui; indicar qual é o host (servidor), qual é a port (porta), qual é o banco de dados, usuário e senha via variável de ambiente; incluir tratamento de erro de conexão e usar o padrão com os.environ.

É importante não colar credenciais, nem mesmo nas IAs que utilizamos. Devemos sempre simular usuário e senha, nunca inserir os reais.

Geramos esse código com Copilot. Ele indicou como instalar as bibliotecas, fazer os imports, carregar as variáveis de ambiente, simular o host (servidor), a port (porta), o nome do banco, a senha e o usuário, além de criar uma URL padrão com o dialeto do PostgreSQL utilizando as variáveis de ambiente. Em seguida, montou a conexão com essa URL, realizou um teste de conexão e incluiu um bloco para, em caso de erro, exibir qual foi o erro.

Se executarmos esse código agora, veremos um erro esperado: o módulo não existe, pois não fizemos as instalações necessárias. Para que o código funcione, será preciso instalar a biblioteca correspondente.

Apresentando os objetivos da aula

Olá a todas as pessoas, nesta aula vamos aprender a modelar o banco de dados com SQL e SQLAlchemy Core. Vamos criar tabelas com MetaData e Table, definir colunas com tipos e restrições, usar ForeignKey para relacionar tabelas, inspecionar o banco de dados criado e também usar a IA para gerar esquemas a partir de uma descrição que fornecermos, aumentando nossa produtividade no dia a dia.

A gerência da área de dados nos forneceu um diagrama do banco de dados e solicitou que criássemos um esquema por meio de código em Python. Por que em código e não diretamente no banco de dados? Porque, dessa forma, o esquema entra em um controle de versão, fica documentado e é reproduzível em qualquer outro ambiente. Essa abordagem garante que, se em algum momento nós sairmos da empresa ou alguma pessoa colega de trabalho ingressar, todo esse material estará versionado e será mais fácil para essa pessoa assumir e entender o contexto — e também para nós mesmos, nosso eu do futuro.

Portanto, é muito importante que, no nosso dia a dia, documentemos tudo para facilitar tanto para nós quanto para outras pessoas. É desagradável quando alguém precisa utilizar um material sem documentação, então precisamos pensar em nós, mas também na próxima pessoa.

Utilizando componentes do sqlalchemy

Na aula passada, importamos algumas bibliotecas. Agora, vamos utilizar, a partir do SQLAlchemy, alguns componentes novos — MetaData, Table, Column, Integer e String — para especificar, em cada coluna, quais tipos de dados essas colunas devem receber.

Para começar, importamos os módulos necessários do Python e do SQLAlchemy, incluindo MetaData, Table, Column, Integer, String e também outros utilitários que usaremos ao longo do curso, como ForeignKey e inspect:

# Importações necessárias do SQLAlchemy para modelagem de tabelas
from pathlib import Path
from sqlalchemy import (
    create_engine, text, inspect,
    MetaData, Table, Column,
    Integer, String, DateTime, Numeric, ForeignKey, CheckConstraint, Boolean
)

Esse conjunto de importações prepara o ambiente para modelarmos o esquema via código, além de permitir inspeções futuras do banco de dados e a definição de restrições e chaves estrangeiras.

Configurando a conexão com o banco de dados

Se o diretório que armazenará o banco de dados não existir, vamos criá-lo. Em seguida, vamos criar o nosso engine para conectar ao banco de dados SQLite. Após executar a configuração, confirmamos que a conexão foi estabelecida e iniciamos os trabalhos.

Para isso, usamos o seguinte código:

# Cria o diretório do banco se não existir
Path("../database").mkdir(exist_ok=True)

Cria a engine para conectar ao banco SQLite



engine = create_engine('sqlite:///../database/datavendas.db')


print("Pronto! ✅")

Esse bloco cria o diretório ../database (caso ainda não exista) e instancia uma engine do SQLAlchemy apontando para um arquivo SQLite chamado datavendas.db. A mensagem "Pronto! ✅" sinaliza que a configuração inicial foi executada com sucesso.

Explicando o papel do metadata

O que é o MetaData? O MetaData é o catálogo da base de dados. Ele funciona como um catálogo central que registra todas as tabelas que definirmos. Com esse catálogo, podemos acessar e identificar quais tabelas estão registradas e quais não estão. Assim, se acreditarmos que registramos uma tabela e isso não tiver acontecido, podemos consultar o catálogo para saber exatamente quais tabelas foram registradas.

Nesta aula, precisaremos criar as tabelas de clientes, pedidos, produtos e itens do pedido. Para isso, criamos um objeto chamado MetaData: declaramos uma variável que recebe a chamada para MetaData, que servirá como o catálogo central onde registraremos as tabelas. A partir de agora, todas as tabelas serão registradas nesse catálogo.

Criando o catálogo metadata

Vamos criar o catálogo MetaData:

# Cria o objeto MetaData, que é o catálogo central para registrar tabelas
metadata = MetaData()
print(f"MetaData criado: {metadata}")

Esse metadata será usado para registrar as tabelas que construiremos nas próximas etapas. Por enquanto, ele está vazio, já que nenhuma Table foi definida.

Ao executar a criação, veremos que o MetaData recém-criado ainda está vazio, pois nenhuma tabela foi definida até o momento, portanto, não há nada a ser registrado.

Antecipando os próximos passos

Na próxima aula, aprenderemos a criar as tabelas mencionadas — clientes, pedidos, produtos e itens do pedido.

Nos vemos na próxima aula.