Forem: Devs Norte

SOLID explicado com exemplos em Java — do jeito simples que todo dev gostaria de ter aprendido

Edson Costa — Mon, 01 Dec 2025 05:05:50 +0000

Ao longo da minha jornada como desenvolvedor — principalmente vindo do desenvolvimento web — sempre ouvi falar sobre SOLID. Mas foi entrando de vez no desenvolvimento mobile que esses princípios começaram a fazer um sentido muito maior no meu dia a dia.

SOLID não é um conjunto de regras rígidas, e sim um guia de boas práticas para construir sistemas mais limpos, flexíveis e fáceis de manter.
E, para explicar isso, vou usar analogias simples e exemplos reais em Java, mostrando como cada princípio se aplica no código.

Vamos direto ao ponto.

🧱 O que é SOLID?

SOLID é um acrônimo formado por cinco princípios fundamentais da programação orientada a objetos:

S — Single Responsibility Principle
O — Open/Closed Principle
L — Liskov Substitution Principle
I — Interface Segregation Principle
D — Dependency Inversion Principle

A ideia central é simples: projetar software que seja fácil de entender, evoluir, testar e manter.

Agora, vamos ver cada princípio na prática.

1️⃣ Single Responsibility Principle (Responsabilidade Única)

“Uma classe deve ter apenas um motivo para mudar.”

Imagine uma classe que salva usuários e também envia e-mails.
Ela faz duas coisas — e isso é um problema.

❌ Exemplo que viola o SRP

public class UserService {

    public void saveUser(User user) {
        // salva no banco
    }

    public void sendWelcomeEmail(User user) {
        // envia e-mail
    }
}

Se qualquer parte falhar (e-mail, banco, regra de negócio), a classe inteira é afetada.

✔️ Exemplo seguindo o SRP

public class UserRepository {
    public void save(User user) {
        // salva no banco
    }
}

public class EmailService {
    public void sendWelcomeEmail(User user) {
        // envia e-mail
    }
}

Cada classe tem sua responsabilidade, e o código fica muito mais claro e testável.

2️⃣ Open/Closed Principle (Aberto para Extensão, Fechado para Modificação)

“Você deve poder adicionar novos comportamentos sem alterar código existente.”

✔️ Exemplo com descontos

public interface Discount {
    double apply(double price);
}

public class NoDiscount implements Discount {
    public double apply(double price) {
        return price;
    }
}

public class BlackFridayDiscount implements Discount {
    public double apply(double price) {
        return price * 0.5;
    }
}

Precisa de um novo tipo de desconto?

Crie uma nova classe.
Nenhuma linha das anteriores precisa mudar.

Isso é Open/Closed na prática.

3️⃣ Liskov Substitution Principle (Substituição de Liskov)

“Subclasses devem poder substituir suas classes base sem quebrar o comportamento esperado.”

❌ Exemplo que quebra o princípio

public class Bird {
    public void fly() {
        System.out.println("Voando...");
    }
}

public class Penguin extends Bird {
    @Override
    public void fly() {
        throw new UnsupportedOperationException("Pinguins não voam!");
    }
}

O contrato promete que todo pássaro voa, mas o pinguim não.
Isso quebra o comportamento esperado.

✔️ Exemplo correto

Separando o que pode voar do que não pode:

public interface Bird {
    void eat();
}

public interface FlyingBird extends Bird {
    void fly();
}

public class Eagle implements FlyingBird {
    public void eat() {}
    public void fly() {}
}

public class Penguin implements Bird {
    public void eat() {}
}

Agora, tudo faz sentido.

4️⃣ Interface Segregation Principle (Segregação de Interfaces)

“Nenhuma classe deve ser forçada a implementar métodos que não usa.”

❌ Exemplo errado

public interface Worker {
    void work();
    void eat();
}

public class Robot implements Worker {
    public void work() {}
    public void eat() {
        // robô não come...
    }
}

O robô é obrigado a implementar algo que não faz sentido para ele.

✔️ Exemplo correto

public interface Workable {
    void work();
}

public interface Eatable {
    void eat();
}

public class Robot implements Workable {
    public void work() {}
}

public class Human implements Workable, Eatable {
    public void work() {}
    public void eat() {}
}

Interfaces menores = classes mais limpas.

5️⃣ Dependency Inversion Principle (Inversão de Dependência)

“Dependa de abstrações, não de implementações concretas.”

❌ Exemplo errado

public class MySQLDatabase {
    public void connect() {}
}

public class UserService {
    private MySQLDatabase database = new MySQLDatabase();

    public void save(User user) {
        database.connect();
    }
}

O serviço está acoplado ao MySQL.
Se quiser trocar para Postgres, precisa alterar o código.

✔️ Exemplo correto

public interface Database {
    void connect();
}

public class MySQLDatabase implements Database {
    public void connect() {}
}

public class PostgresDatabase implements Database {
    public void connect() {}
}

public class UserService {

    private Database database;

    public UserService(Database database) {
        this.database = database;
    }

    public void save(User user) {
        database.connect();
    }
}

Agora, trocar o banco é só configurar outra implementação.

🎯 Conclusão

SOLID não é sobre “seguir regras”, e sim sobre facilitar sua vida como desenvolvedor.
Quanto mais seu sistema cresce, mais esses princípios fazem diferença.

Eles ajudam a criar:

código mais limpo,
classes mais coesas,
responsabilidades claras,
menos bugs,
mais testes,
e mais flexibilidade para evoluir o projeto.

Se você está trabalhando com Android, KMP ou qualquer arquitetura moderna (como MVVM), SOLID é um aliado poderoso.

Descubra e Baixe os Melhores Apps do Pará: Conecte-se com a Região!

Project Spider — Fri, 07 Feb 2025 02:49:47 +0000

Com a COP 30 chegando à região de Belém do Pará, resolvi mostrar soluções de aplicativos que impactam de diversas formas, às vezes não só o local, como também a nível nacional.

Então, vamos dar início à lista com temas variados com relação ao mercado e seu público para plataformas Android e iOS.

AbaetéFest

Já imaginou precisar localizar pontos turísticos, shows e eventos na cidade de Abaetetuba? Visite a cidade com esse aplicativo e acompanhe o que aproveitar de culinária, cultura e muito mais!

Para Dispositivos Android:
https://ankitkamboj18.medium.com/pwa-web-app-as-twa-and-publish-on-google-play-store-c4e6431b9405

Para Dispositivos iOS (Apple):
https://app.abaetefest.com.b](url)r/

Belém em Dobro

Que tal conhecer os espaços gastronômicos da cidade de Belém e ainda conhecer restaurantes com descontos? Esse é o aplicativo ideal para quem quer ver locais novos ou ainda não tinha visitado como morador. Baixe agora!

Para Dispositivos Android: https://play.google.com/store/apps/developer?id=PlayEmber+Sp.+z+o.o.&hl=en_GB)

Para Dispositivos iOS (Apple):

Rock Doido

Já quer experimentar o estilo musical único do norte? Conheça um streaming próprio dedicado às músicas de tecnomelody do Pará. Esse é o aplicativo Rock Doido, que oferece a rádio.

Para Dispositivos Android: https://play.google.com/store/apps/details?)id=com.rockdoidoapp&hl=pt_BR
Para Dispositivos iOS (Apple): https://apps.apple.com/br/app/rockdoido/id1479712940

Rádio AD

O mundo gospel paraense em formato de rádio também disponível. Com o slogan “Você ouve e adora!” e uma programação musical de qualidade, a AD Belém.

Para Dispositivos Android: https://play.google.com/store/apps/details?id=project.android.radioadbelem

Palco Belém (Site)

Quer saber quais eventos no teatro estão acontecendo? Descubra um catálogo cultural de carimbó, orquestras e produções musicais incríveis. Acesse o site abaixo:

https://palcobelem.com.br/index_app

Lava Aqui

Precisa lavar seu carro? Com esse aplicativo, você agenda e um profissional vai até você e limpa seu carro, economizando seu tempo de sair. E o melhor? Totalmente de modo ecológico. Aproveite!

Para Dispositivos Android: https://play.google.com/store/apps/details?id=br.com.cassebtecnologia.lavaqui_app

Aluguel Direto

Como corretor, precisa de gestão imobiliária? Com o Aluguel Direto, você organiza contratos tudo em um só lugar e ainda garante facilidade para seus clientes no dia a dia. Baixe agora!

Para Dispositivos Android: https://play.google.com/store/apps/details?id=br.com.cassebtecnologia.lavaqui_app

Amazônia em Belém

Explore a riqueza natural e cultural de sua cidade de uma forma totalmente nova. Com ele, os usuários podem escanear QR codes colocados em monumentos, locais de interesse, plantas e animais, desbloqueando informações detalhadas sobre cada elemento. Baixe agora!

Para Dispositivos Android: https://play.google.com/store/apps/details?id=br.pa.semma&hl=pt_BR

Alaga-Info

Focado no alerta colaborativo dos usuários, o aplicativo oferece um modo de evitar alagamentos na cidade através do público que compartilha e, com isso, por meio de notificações e compartilhamento do endereço do local, você visualiza pontos alagados, além do nível de alagamento e seu trânsito local, não só na região como em todas as cidades do Brasil. Baixe e cuidado a locais alagados!

Para Dispositivos Android:
https://play.google.com/store/apps/details?id=com.alagainfo.alagainfo

Para Dispositivos iOS(Apple):
https://apps.apple.com/us/app/alaga-info/id6593661838

Second Chance

E se pudesse reencontrar o seu amor ou então a oportunidade de reencontrar o amor de uma forma que ressoa com as experiências e expectativas acumuladas ao longo da vida. Voltado para aqueles que já estiveram em relacionamentos sérios e buscam uma nova conexão, o aplicativo apresenta uma experiência personalizada, pensada para quem valoriza a profundidade em um relacionamento. Baixe agora!

Para Dispositivos Android:
https://play.google.com/store/apps/details?id=com.secondchancebr

Zarpar

Precisa pegar uma lancha para conhecer outras regiões de Belém? Experimente o Zarpar! Chegaram com a missão de evoluir essa experiência de viagem dos povos ribeirinhos, turistas e empresas e trazer o porto para mais perto de você. Baixe e encontre o seu destino!

Para Dispositivos Android:
https://play.google.com/store/apps/details?id=br.com.zarpar&hl=pt_BR

Parazão

Curte futebol? Então saiba os jogos paraenses através do aplicativo Parazão, onde você acompanha os times paraenses em todos os campeonatos que eles disputarem (Série B, Série C, Campeonato Paraense, Copa Verde, Copa do Brasil). Todos os jogos em tempo real e com cobertura completa. Além de notícias diárias de seus clubes preferidos!

Para Dispositivos Android:
https://play.google.com/store/apps/details?id=com.br.parazao

Paysandu Sport Club Oficial

Aproveitando ainda sobre futebol, o oficial do Maior Campeão da Amazônia: Paysandu Sport Club. Nele, você terá acesso às últimas notícias do clube, tabela de jogos, receberá push dos jogos em tempo real e acesso ao Sócio Bicolor.

Para Dispositivos Android:
https://play.google.com/store/apps/details?id=com.bredi.paysandu

Círio de Nazaré

Época de outubro é celebrado o Círio de Nossa Senhora de Nazaré, evento que envolve, além da população paraense, devotos e turistas de várias cidades e países. Baixe e conheça sobre!

Para Dispositivos Android:
https://play.google.com/store/apps/details?id=com.bredi.app_cirio

Kd a Berlinda?

Ainda no tema Círio de Nazaré, tenha o aplicativo Kd a Berlinda, feito para que o usuário possa acompanhar as 13 procissões oficiais do Círio de Nazaré em tempo real. Em 2019, a ferramenta recebeu uma série de atualizações, incluindo design e melhorias na aplicação. Baixe no link!

Para Dispositivos Android:
https://play.google.com/store/apps/details?id=br.pa.prodepa.kdaberlinda

Pega o Beco

Em tempo livre, que tal jogar e se divertir com jogo focado em elementos da cidade de Belém, que pode experimentar locais e bairros conhecidos do povo? Baixe agora!

Para Dispositivos Android:
https://play.google.com/store/apps/details?id=com.pandergames.PegaoBeco

Flash Pará

Mobilidade? Temos também! Conheça o aplicativo e nos diga sua experiência com transporte executivo presente no próprio bairro e que garante que você e sua família serão atendidos por um motorista conhecido com segurança.

Para Dispositivos Android:
https://play.google.com/store/apps/details?id=br.com.flashpara.passenger.drivermachine

Meu Bolso

Precisa gerenciar suas contas ?
Simplifique o controle das suas finanças com o aplicativo MeuBolso
Baixe agora e comece a economizar.

Para Dispositivos Android:
https://play.google.com/store/apps/details?id=com.negoplay.Meu_Bolso

Para Dispositivos iOS(Apple):
https://apps.apple.com/us/app/app-meu-bolso/id6740345533

Vou de Moovapp

Sua alternativa de mobilidade para uso familiar ou para empresas,
Experimente carros selecionados para suas viagens.

Para Dispositivos Android:
https://play.google.com/store/apps/details?id=com.brediweb.voudemoovapp

Faltou Algum na lista? avise para colocarmos um proximo com mais apps paraenses e crescer na região!

Padronizando Commits com Commitizen e Husky

Edson Costa — Tue, 01 Oct 2024 00:03:02 +0000

Os commits bem estruturados são essenciais para manter a clareza e organização em projetos de desenvolvimento de software. Quando várias pessoas colaboram em um projeto, é crucial manter um padrão para mensagens de commit, facilitando a compreensão das alterações realizadas em um determinado momento. Neste artigo, exploraremos como padronizar commits usando as ferramentas Commitizen e Husky.

Por que padronizar commits?

Padronizar commits traz uma série de benefícios para equipes de desenvolvimento:

Clareza: Mensagens de commit bem estruturadas tornam mais fácil entender o propósito das alterações.
Rastreabilidade: Com commits padronizados, é mais simples rastrear a evolução do código ao longo do tempo.
Facilidade de Reversão: Commits bem documentados facilitam a identificação de alterações específicas, tornando mais fácil reverter mudanças indesejadas.
Colaboração: Padronizar commits promove uma melhor colaboração entre membros da equipe, pois todos seguem as mesmas convenções.

Introdução ao Commitizen e Husky

Commitizen é uma ferramenta que visa facilitar a criação de commits padronizados seguindo as convenções do Conventional Commits. Ele fornece uma interface interativa para guiar os desenvolvedores na criação de mensagens de commit consistentes.

Husky, por outro lado, é uma biblioteca que nos permite configurar ganchos (hooks) Git facilmente. Podemos usá-lo para executar scripts automatizados antes de certos eventos do Git, como commit, push e outros.

Passos para padronizar commits com Commitizen e Husky

Aqui estão os passos necessários para padronizar commits em seu projeto:

1. Instalação do Commitizen e Husky

Certifique-se de que o Node.js esteja instalado em seu sistema. Em seguida, instale o Commitizen e Husky como dependências de desenvolvimento em seu projeto:

npm install --save-dev commitizen husky

2. Configuração do Commitizen

Depois de instalar o Commitizen, você pode configurá-lo para seu projeto executando o seguinte comando:

npx commitizen init cz-conventional-changelog --save-dev --save-exact

Isso instalará o adaptador cz-conventional-changelog e configurará o Commitizen para usar o Conventional Commits.

3. Configuração do Husky

Com o Husky, podemos configurar ganchos Git para executar scripts antes de certos eventos. Para configurar o Husky, adicione o seguinte script ao seu package.json:

"husky": {
  "hooks": {
    "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
  }
}

Este script usa o commitlint para verificar se a mensagem de commit está em conformidade com as convenções especificadas.

4. Adicionar Configurações de Commitlint

O commitlint é uma ferramenta de validação de mensagens de commit baseada em regras. É comumente usado para garantir que as mensagens de commit sigam um formato específico. Você pode instalar o commitlint e as configurações do Conventional Commits usando:

npm install --save-dev @commitlint/{config-conventional,cli}

Em seguida, crie um arquivo commitlint.config.js na raiz do seu projeto e adicione o seguinte conteúdo:

module.exports = {extends: ['@commitlint/config-conventional']};

5. Usando Commitizen para commits

Agora que tudo está configurado, ao executar git commit, você será levado a uma interface interativa fornecida pelo Commitizen para criar mensagens de commit.

Conclusão

Padronizar commits é uma prática recomendada que promove clareza, rastreabilidade e colaboração em projetos de desenv

Automatizando Notificações via Telegram com GitHub Actions

Edson Costa — Tue, 01 Oct 2024 00:01:42 +0000

O GitHub Actions é uma ferramenta poderosa que permite automatizar tarefas dentro do fluxo de trabalho de desenvolvimento. Uma aplicação útil disso é a capacidade de enviar notificações para diferentes plataformas, como o Telegram, sempre que ocorrerem eventos específicos em seus repositórios do GitHub. Neste artigo, vamos explorar como configurar e utilizar o GitHub Actions para enviar notificações via Telegram.

O que é o GitHub Actions?

O GitHub Actions é um serviço de automação integrado diretamente no GitHub, permitindo que você crie fluxos de trabalho personalizados para automatizar processos de desenvolvimento, desde a construção e teste até a implantação e notificação.

Configurando o Telegram Bot

Antes de começarmos com o GitHub Actions, é necessário criar um bot no Telegram e obter seu token de acesso. Siga os passos abaixo:

Abra o Telegram e pesquise por BotFather.
Inicie uma conversa com o BotFather.
Use o comando /newbot para criar um novo bot.
Siga as instruções do BotFather, fornecendo um nome e um nome de usuário para o seu bot.
Após a criação, o BotFather irá fornecer um token de acesso para o seu bot. Mantenha esse token seguro, pois será usado posteriormente.

Configurando o GitHub Actions

Agora que temos o token do nosso bot, vamos configurar o GitHub Actions para enviar notificações para o Telegram sempre que ocorrerem eventos específicos em nosso repositório.

No seu repositório do GitHub, crie um diretório chamado .github/workflows se ainda não existir.
Dentro deste diretório, crie um arquivo YAML com o nome que desejar, por exemplo, telegram-notification.yml.
Adicione o seguinte conteúdo ao arquivo YAML:

name: Telegram Notification

on:
  push:
    branches:
      - main

jobs:
  telegram-notification:
    runs-on: ubuntu-latest
    steps:
      - name: Send Telegram Notification
        uses: appleboy/telegram-action@master
        with:
          to: ${{ secrets.TELEGRAM_TO }}
          token: ${{ secrets.TELEGRAM_TOKEN }}
          message: "New commit pushed to the repository."

Neste exemplo, configuramos o fluxo de trabalho para enviar uma notificação para o Telegram sempre que houver um push para a branch principal (main). Você pode personalizar os eventos e as branches conforme necessário.

Agora, precisamos adicionar as variáveis de ambiente TELEGRAM_TO e TELEGRAM_TOKEN como segredos em nosso repositório.

TELEGRAM_TO: Este é o ID do chat para o qual a mensagem será enviada. Você pode obter isso iniciando uma conversa com seu bot no Telegram e usando a API do Telegram para recuperar o ID do chat.
TELEGRAM_TOKEN: Este é o token de acesso que obtivemos anteriormente do BotFather.

Para adicionar esses segredos:

Navegue até as configurações do seu repositório no GitHub.
Selecione "Secrets" no menu lateral.
Clique em "New repository secret" e adicione as variáveis TELEGRAM_TO e TELEGRAM_TOKEN com seus valores correspondentes.

Testando o Fluxo de Trabalho

Com tudo configurado, você pode testar o fluxo de trabalho fazendo um push para a branch principal do seu repositório. Após o push, você deve receber uma notificação no Telegram informando sobre a nova alteração no repositório.

Conclusão

O GitHub Actions oferece uma maneira conveniente de automatizar tarefas repetitivas, como enviar notificações para plataformas externas como o Telegram. Neste artigo, vimos como configurar o GitHub Actions para enviar notificações via Telegram sempre que ocorrerem eventos específicos em um repositório do GitHub. Essa automação pode ajudar a manter equipes informadas sobre o progresso do desenvolvimento e a agilizar o fluxo de trabalho de desenvolvimento de software.

Sobre a bacia Tocantins-Araguaia

Gustavo Ramos — Tue, 27 Aug 2024 18:00:16 +0000

Esse artigo vem de um projeto que venho fazendo dos workshosps aos sábado sobre análise dos reservatórios (se quiser saber temos o repositório no Github onde poderá ter informações sobre todos os processo que estamos fazendo) e nessa parte estamos fazendo a análise de série histórica da bacia do Tocantins, então nada melhor sobre ter conhecimento sobre o que é essa bacia e a sua importância para a gestão de recursos hídricos no Brasil.

O texto deste artigo está apoiado em um trabalho de conclusão de curso que pode ser encontrado aqui

Tem como rio principal o Rio Tocantins, sendo o principal curso d’́ água que, possuindo uma extensão de 2.416 km, configurando-se como o segundo maior rio totalmente brasileiro, sendo que a sua nascente é localizada no Estado de Goiás, passando pelos Estados do Tocantins e Maranhão até chegar em sua foz, na Ilha do Marajó.

Tem como seu afluente principal o Rio Araguaia, com uma extensão de 2.115 km, atravessando os Estados de Mato Grosso, Goiás, Tocantins e Pará, nascendo na Serra dos Caiapós a uma altitude de 850 metros. Seu encontro com o Rio Tocantins ocorre próximo ao Bico do Papagaio.

O Rio Tocantins tem um potencial muito grande para construção de usinas hidrelétricas, sendo a mais conhecida a usina de Tucuruí, não sendo à toa que há vário usina construídas ao longo de seu percurso, como pode ser visto na imagem abaixo.

Dada a sua importância energética e para a população que vive envolta, é muito importante ter a sua conservação e que com os caso de desmatamento e agrotóxicos isso acarreta diminuição e sua superfície, trazendo prejuízos e consequências futuras que pode acabar com toda uma dinâmica social e econômica.

Como podemos ver nesta reportagem do Jornal Nacional em que foi feito um estudo conduzido pela UNB, constatando mediante dados sobre a superfície de água e a vazão da correnteza nas 21 estações de monitoramento desde 1980 que o rio nos últimos 40 anos perdeu em média 40% de vazão e entre 40% e 67% da superfície de água, dependendo em que parte do rio, havendo uma correlação forte entre redução da superfície da água com o aumento do desmatamento e da quantidade de áreas irrigadas. Havendo contaminação de agrotóxicos na água nas sub-bacias estudadas

Nesta reportagem da UOL mostra uma análise que observou os registros históricos de 27 estações de medição até o ano de 2019, e constatou vazões abaixo da média em 19 delas, com especial atenção para os períodos secos. Os resultados são um alerta para os projetos de irrigação, hidrelétricas e hidrovias propostos na região.

E no Afronoticias em que quase metade da bacia foi desmatada, a calha do rio Tocantins está muito seriamente impactada por barragens e os afluentes do rio Araguaia têm sofrido com a retirada de água para agricultura irrigada, além da perda de áreas ripárias (as regiões que estão diretamente relacionadas com os cursos d’água e onde ocorre a mata ciliar ou vegetação que influi na dinâmica ambiental relacionada) e o assoreamento do rio.

Dados os impactos ambientais, medidas precisam ser cuidados, inclusive está em tramitação o projeto de lei PL 4058/20 atribuindo ao poder público medidas de conservação na bacia do Tocantins-Araguaia, dentre as medidas

elaboração de zoneamento ecológico-econômico
sistema de monitoramento e recuperação da cobertura vegetal do Cerrado
implantação do programa de pagamento por serviços ambientais

É muito importante organizar para que esta lei seja aprovada para garantir uma melhor conservação da bacia e de sua importância, além de apoiar outros projetos que tenha por objetivo a conservação

Analisando série histórica bacia tocantins - parte 2

Gustavo Ramos — Mon, 12 Aug 2024 13:12:35 +0000

Neste encontro, tem-se a continuação da análise que começou do último encontro em que se começou pela bacia hidrográfica de Tocantins, nesse encontro começamos a fazer uma análise de tendência e de sazonalidade em específico a usina de Tucuruí para depois fazer comparação com as outras usinas dessa mesma bacia hidrográfica.

Pode observar um período de cheia, principalmente nos períodos de março e abril, e um período de estiagem de julho a outubro (seria essa a sazonalidade dos períodos de seca e cheia)

De janeiro a abril tem uma tendência de subida
De maio até outubro, uma tendência de queda e novembro uma subida

Isso pode ser visto aplicando a média móvel de 30 dias no gráfico abaixo

E um comportamento parecido pode observar comparando os anos, temos alguns de exemplo no gráfico abaixo

A partir dessas análises podemos fazer os seguintes questionamentos para as próximas

Os outros reservatórios desta mesma bacia hidrográfica tem este comportamento?
tem relação com o volume de chuvas na região durante o ano?
A vazão que entra no reservatório tem relação com a geração de energia da mesma

Analisando série histórica bacia tocantins - parte 1

Gustavo Ramos — Sun, 21 Jul 2024 13:49:40 +0000

Já foi feita uma análise geral das reservas federais, no qual todo o processo pode ser acompanhado no repositório do github, agora vai ser feito a análise das séries histórica da afluência dos reservatórios federais (Vazão/volume da água que entra no reservatório (m³/s))

Como são muitos reservatórios, decidiu-se fazer cada análise separado por bacia hidrográfica já que os reservatórios de bacias de uma mesma bacia hidrográfica tem comportamentos semelhantes, e começaremos nesta analise com a bacia Tocantins

Mais informações sobre esta bacia, consulte este link do Governo Federal aqui

Analisando a série histórica, como pode ser observado no gráfico abaixo, podemos ver que:

O reservatório de Tucuruí é o que mais apresenta vazão, se comparado com outros da mesma bacia hidrográfica, pois além do rio Tocantins, a usina de Tucuruí recebe do afluente do rio Araguaia, como pode ver no esquema abaixo

Observação:

Reservatório com triângulo: do tipo usina com reservatório(Usina hidrelétrica sem reservatório de acumulação. O barramento foi construído apenas com intuito de ter uma queda d’água e o volume armazenado no reservatório não é capaz de manter o funcionamento da usina por mais do que uma semana)
Reservatório com círculo: do tio usina fio água (Usinas nas quais o reservatório construído têm um volume armazenado capaz de atender as demandas por longo tempo (meses a anos))

Se olharmos uma média da afluência durante os meses, parece termos um seguinte padrão que pode ser investigado nos próximos encontros em que se observa tendência de subida até abril e começa a decrescer em maio e começa a subir em torno de novembro (a ser analisado)
pico normalmente em março ou abril (a ser analisado a sazonalidade)

A partir disso, nos próximos encontros será analisado melhor os comportamentos dos reservatórios da bacia de Tocantis

Análise das estações meteorológicas - parte extra 1

Gustavo Ramos — Sun, 07 Jul 2024 14:34:34 +0000

Neste encontro extra, durante a Jornada de Desenvolvimento de Software (JES) organizada pelos discentes em engenharia de software da Universidade do Estado do Pará, foi feito uma amostra do que vem sendo feito durante os encontros do workshop de python para análise de dados

Assim foi feito uma análise com base no segundo (você pode ler sobre clicando aqui) encontro em que foi levantado os impactos ambientais que os reservatórios causam a sua construção, a partir disso foi levantado se poderia utilizar as estações meteorológicas do Instituto nacional de Meteorologia (INMET) e se seria possível utilizar para fazer essa análise dos impactos ambientais sobre os reservatórios

Assim foi extraído os dados de todas as estações instaladas verificar elas, em que ano foram fundadas e se estão próximas aos reservatórios

Quanto ao Estado, temos que a maioria das estações estão localizadas em Minas Gerais, se comparada em outros Estados como Amapá e Roraima, por exemplo, podendo indicar que há uma distribuição desigual das estações em volta do Brasil

Quanto ao ano de fundação, a maioria das estações está principalmente em três anos, 2006, 2007 e 2008, podemos verificar se houve alguma política pública federal que houve para fazer essa construção e qual necessidade houve na época

Inclusive quando olhamos esse ano de construção por Estado, vemos em que nos Estado, maioria foi construída nesse período, comparado a outros Estados em que tem um período maior de construção, como pode ser visto no gráfico abaixo

Agora, quando geramos um mapa com os pontos das estações meteorológicas da INMET, podemos ver que há muito bem distribuídas, principalmente na região Sul e Sudeste, mas quando olhamos para a região Norte, principalmente há muito poucas estações, talvez havendo a necessidade de políticas para instalação de mais estação para coleta de informações e previsões para apoiar os cenários de planejamento nas mais diversas situações

Mas enquanto para poder fazer a comparação dos impactos, talvez não haja essa possibilidade para fazer, porque a maioria dos reservatórios foram construídos na década de 70, enquanto a maioria das estações em 2006, 2007 e 2008, então a maioria não vai poder ser utilizado

Mas há uma proximidade, então outros tipos de análise do que estamos procurando seria possível, e que talvez outros tipos de análise poderiam ser feitas

Análise dos reservatórios federais - parte 2

Gustavo Ramos — Mon, 24 Jun 2024 11:31:34 +0000

Continuando o que foi feito no último workshop (se ainda não leu, pode ser acessar clicando aqui), daremos continuidade para dar análise dos reservatórios, quanto ao tipo de reservatórios, ele pode ser classificar em três, sendo eles:

Usina a fio d’água: usina hidrelétrica sem reservatório de acumulação. O barramento foi construído apenas com intuito de ter uma queda d’água e o volume armazenado no reservatório não é capaz de manter o funcionamento da usina por mais do que uma semana.
Usina com reservatório: usinas nas quais o reservatório construído têm um volume armazenado capaz de atender as demandas por longo período (de meses a anos).
Usina de bombeamento: usinas construídas para o bombeamento d’água, transposição de rios.

Podemos ver que a maioria é do tipo fio d’água, ou seja, não se tem um reservatório para acumulação, logo quando houver uma estiagem, não se tem água armazenada o suficiente por um tempo para entrar em todas as turbina, mas, comparado as usina com reservatório apresenta menos impactos ambientais

Inclusive ano passado o Governo pensou em planos para retomar projetos de usinas com reservatório, como pode ser lida na matéria abaixo (a matéria pode ser vista clicando aqui)

Mas segundo essa reportagem de 2012, ambientalistas alertam para o perigo de se ter usina com reservatório, pelos impactos ambientais que a mesma pode ocasionar, o melhor, pelo que propõem, é usar as hidrelétricas em conjunto com as energias renováveis, como a elétrica e a solar (que pode ser lida aqui)

Em relação aos reservatórios por Estado, temos que:

Temos Estados que só tem fio d’água com Piauí, Maranhão, Alagoas, Sergipe e Amapá
Amazonas e Paraíba só tem usinas com reservatório
e todas as usina de bombeamento estão no Rio de Janeiro

Podemos ver que em questão de volume, o tipo de usina com reservatório são as que apresentam ter mais, em relação as outras

Agora se vemos em relação aos Estados isso, podemos ver que o Pará e Bahia tem os maiores volumes em questão de usina com reservatório e Mato Grosso do Sul é o que tem mais em relação ao fio d’água

Se isso for observado por bacia, a bacia do Tocantins apresenta maior volume útil em relação da usina do tipo reservatório e a bacia Paraná apresenta maiores volume do tipo fio d’água

Com isso também foi gerado dois mapas, um separado conforme o tipo de usina, e outro sobre o volume útil, sendo que os três maiores são: Tucuruí, Serra da Mesa e Sobradinho

Conclusão

Pela análise feita vemos que existe mais usinas do tipo fio d’água e que usina com reservatório tem mais volume útil se comparado a outros, quanto a isso a questão que fica e vale dá uma pesquisa é:

Quais impactos ambientais a usina com reservatório pode causar em relação ao fio d’água do que foi mencionado na reportagem acima?
Qual seria a solução diante disso apontada pelos especialistas?

Também mostra uma possível análise futura seria pegar as estações meteorológicas mais próximas dos reservatórios e verificar se houve alguma alteração climática com a construção da usina e qual tipo de usina fica mais nítido observar essas alterações

Percepções sobre análise dos reservatórios parte 1

Gustavo Ramos — Wed, 12 Jun 2024 09:26:33 +0000

A partir da parte 1 da análise de reservatórios federais (se não leu e quiser dá uma lida acesse aqui), fiquei curioso com o gráfico abaixo do porquê tem uma concentração dos anos 1970 e anos 2000 e busquei pesquisar o contexto histórico.

Então encontrei esse artigo chamado "A grande aceleração e a construção de barragens hidrelétricas no Brasil" (que pode ser acessado aqui)

Segundo este artigo a construção de hidrelétricas tem relação com o desenvolvimento de indústria aqui no Brasil, assim se deu a necessidade de construção, por volta do início do século XX, em que se consolidou no período da ditadura militar aqui no Brasil, na década de 70, em que o modelo de geração hidrelétrica ocorreu através das esferas institucionais, dados principalmente pela Eletrobras com objetivo do fomentar o desenvolvimento industrial do mundo, coisa que vinha acontecendo desde a década de 30 com Vargas, entretanto foi na década de 70 que isso ganhou mais força e com forte intervenção do Estado.

Sendo que na década de 80, ocasionado, pela crise do petróleo de 79 e pelos movimentos sociais, o governo entrou em crise política e economicamente, fato que reduziu no número de construção de hidrelétricas e começou a ser considerada variáveis de impactos ambientais começaram a ser consideradas na construção de hidrelétricas

Agora sobre a época de 2000 (você pode ler melhor nesse documento aqui) se deu pelo fator de

Racionamento de energia de 2001 (você pode entender melhor sobre na matéria aqui
Assim teve uma necessidade construção de mais energia elétrica para que isso não acontecesse e uma universalização de energia elétrica

Para facilitar o entendimento, têm-se a tabela abaixo para entender melhor o pontos importantes do contexto histórico (o material de onde vem a tabela pode ser encontrado aqui)

Assim, conforme os materiais obtidos, temos que o gráfico acima se deu por:

A construção de hidrelétrica, durante boa parte da história, se deu pelo processo de industrialização do Brasil
Os pico na década de 70 pelo investimento massivo do governo para a indústria e 2000 para a universalização para não ocorrer o racionamento de 2001
Explica também porque a maioria do reservatório estão localizados no sul e sudeste do Brasil, como podemos ver no mapa abaixo, devido que, historicamente, a industrialização começo nessas duas regiões, principalmente.

Análise dos reservatórios federais - parte 1

Gustavo Ramos — Sun, 09 Jun 2024 02:12:16 +0000

Este projeto tem como principal razão fazer uma visão exploratória das reservas federais utilizadas para mover as turbinas das hidrelétricas do país, o ponto também é fazer associações com outras variáveis, como produção de energia elétrica e dados meteorológicas para trazer uma análise mais completa

Objetivos e formulação de hipóteses

Nesse primeiro encontro foram definidos os objetivos, formulação de hipóteses e uma análise inicial acerca das variáveis presentes no dataset

O objetivo desta análise é:

Fazer uma análise da vazão dos reservatórios e verificar se houve um aumento ou uma diminuição ao longo do tempo
Fazer relação com dados de meteorologia e dados de geração de energia elétrica nas hidrelétricas

Com base nos objetivos descritos acima, foram formulados as seguintes hipóteses:

Houve uma diminuição nos reservatórios brasileiros (com base da notícia abaixo)

Brasil perde 15% de superfície de água desde o começo dos anos 1990

Há uma relação entre índices meteorológicos e vazão de água
Há uma relação da vazão de água com a produção de energia nas hidrelétricas

Sobre o base de dados a ser utilizada

O objetivo do dataset é usar os dados dos reservatórios federais da ANA (Agência Nacional de Águas e Saneamento Básico) de sua série histórica, mas não tem na base dos dados informações da bacia e geração de energia elétrica, logo, terá que ser utilizada outras bases de dados para fazer o cruzamento das informações.

Então foi usado outro dataset onde teria esses dados, mas não informações de que Estado estava localizado o reservatório, foi então que se usou a base do dados do pacote R dai cruzando essas informações

GitHub - brunomioto/reservatoriosBR: R package for Brazilian reservoirs data

Avaliação da Operação do Sistema Interligado Nacional (SIN) e outros subsistemas – Base dos Dados

Com isso agora se tem informações desejáveis sobre os reservatórios federais e usaremos essa base para fazemos a análise antes de usar para cruzar com a série histórica da ANA

Análise inicial

Em relação entre os Estados, verifica-se que os Estados que tem mais reservatório são Minas Gerais e São Paulo, podemos ver que RS tem quase 15 reservatórios e muitos podem ter sido danificados com a recente tragédia no Estado, podemos verificar a partir disso verificar se por ter mais reservatórios, os Estados de SP e MG tem uma produção de energia elétrica comparado com outros Estados

Em relação ao ano de fundação dos reservatórios, podemos ver que tem dois picos: um durante as décadas de 70 e 80 e outra próxima próximo aos anos 2000, podemos ver qual contexto histórico e econômico da época que pode ter ocasionado isso para entender melhor essa distribuição

Em relação às bacias, a grande parte se localiza na Grande, Paranaiba, Paranapanema, Amazonas, São Francisco e Uruguai, verificar então se tem uma grande vazão por esse reservatório é maior em relação as demais

Em relação ao rio, temos que os rios que possuem mais reservatórios são o Grande, Paranapanema e o São Francisco, sendo necessário, a partir disso, verificar o mesmo que na bacia

A cota máxima e mínima é sempre próxima de 400, sendo que neste problema dos dados, não será utilizada a média como referência, devido aos valores extremos, e sim a mediana, pois é uma medida que não tão influenciada aos valores extremos, se comparado com a média

Algumas medidas-resumo de algumas das variáveis, vendo pelo desvio padrão que é a última linha, o porquê a média não ser utilizada como referência

Em questão de volume, temos que a maioria está concentrado em valores com menos de 5 mil, vendo a investigar quem são esses reservatórios que tem esses valores extremos

Em questão de ganhos de MW pela queda temos que a maioria é maior que 0,08, o que nos vai fazer investigar o porquê disso ser importante, se há um número aceitável para isso

Geramos um mapa para ver como estão a maioria concentrado em MG e em SP comparado como outros Estados no Brasil

Questões para a próxima análise

Feito isso, podemos pensar no que analisar a partir daqui, sendo os seguintes pontos

Os Estados onde se tem mais reservatório implica em mais produção de energia elétrica (referente as hidrelétricas)?
O volume do reservatório influência na produção de energia elétrica?
A altura também influencia na produção de energia elétrica?
Pode fazer comparação da localização dos reservatórios com as estações meteorológicas

Para saber mais

Se quiser contribuir com o projeto ou é um especialista na área e queria dá uma direção no trabalho, segue os seguintes links

Repositório github: https://github.com/acaicomdados/analise-reservatorios-federais
Documentação do projeto: https://flint-texture-e2f.notion.site/An-lise-de-recursos-h-dricos-6d430a9618054bc1b8cd6f213cad6e3c
Meu linkedin: https://www.linkedin.com/in/gustavoramos82/

Setting up a standalone SQLAlchemy 2.0 ORM application

Diego Souza — Mon, 20 May 2024 13:42:52 +0000

SQLAlchemy is a widely used database toolkit for Python, providing a SQL abstraction layer covering most, if not all, your relational database needs. It's often used together with popular frameworks such as Flask and FastAPI, using either its Core library and/or its ORM components.

This article will take a look at how to set up a basic, standalone SQLAlchemy application, meaning we'll take a look into SQLAlchemy itself and skip other frameworks like the ones we just mentioned. We'll explore some of SQAlchemy's foundational concepts, so we better understand how it works and have some insight about how other frameworks may be using it under their hood.

We will also focus on SQLAlchemy's ORM component. As we'll learn along this article, SQLALchemy is divided into a Core and an ORM component, that represent different ways to achieve the same result, that being interacting with a database. This article is ORM-centered. I suggest checking the documentation for a full introduction to the library, and there is also a comprehensive unified tutorial provided by the SQLAlchemy team, which explores both sides in-depth.

Finally, we'll see some very brief CRUD examples, just so we have a basis on data manipulation. Overall the article works as a simple setup guide with some refreshers about the framework. It does not intend to analyze concepts in great depth, nor a full-fledged tutorial on relational databases or data operations for the sake of brevity. I'll leave the final code available in this GitHub repository

With all that being said, let's start with a few key concepts to familiarize ourselves with SQLAlchemy.

1. Key concepts

The first thing to understand about SQLAlchemy is that it is divided into two major parts: the Object Relational Mapper (ORM) and the Core. Basically, they are different ways to implement the same thing: database interactions. While developers tend to choose and stick to one of them when creating applications, it's not impossible to find codebases with both out in the wild. It's a good idea to understand both so you can make educated implementation choices and be able to comprehend the choices made in pre-existing applications.

The Core component contains the foundation for the whole SQLAlchemy's framework, with most of the library's database services and integrations. It's most significant part is the SQL Expression Language, which in fact works as a query builder system. In other words, a toolkit to construct SQL expressions through composable objects, which can then be executed against the database.

The ORM is built on top of this Core foundation. It expands upon it through a domain object model that is mapped to a database schema. This means you can have classes that are mapped to the database tables and columns, and implement different operations in an object-oriented way. This can be further expanded with external tools such as Alembic, which is a migration tool, or marshmallow, which is a serialization tool.

While using an ORM or a query builder can be quite different, both are able to implement the same operations, and SQLAlchemy's ORM is an extension of the Core. As such, both will rely on a few identical fundamental pieces, such as the database connection. We'll begin our exploration by them.

Our starting point will be the engine and the aforementioned connection.

2. Getting started

Let's get some initial setup out of the way, starting by an empty directory and a virtual environment. Create a new directory with any name you like, and a virtual environment with your preferred tool. I personally use Pyenv. It is worth noting that this tutorial was created with Python 3.11.3, and SQLAlchemy version 2.0.27.

pyenv virtualenv 3.11.3 standalone-sqlalchemy
pyenv activate standalone-sqlalchemy

With the virtual environment activated, install SQLAlchemy.

pyenv exec pip install SQLAlchemy
pyenv exec pip freeze > requirements.txt

Create a database subdirectory with an empty __init__.py file, which will contain our files as we progress along the article. The directory tree will look like this:

.
├── database
│   └── __init__.py
└── requirements.txt

3. Creating an engine

The Engine is the starting point of a SQLAlchemy application. It is the central source of connections to the database and holds the application's connection pool. It's independent from either the Core or the ORM and will be used in any and all SQLAlchemy applications.

The usual implementation is to have the engine object created only once in a particular database server. For that, we can use a factory function provided by SQLAlchemy, where we can create and tune database connections. It's the create_engine() function. We use it by passing a database URL as the first positional argument, followed by keyword arguments containing the configuration options we wish to have in place.

The database URL is a usual connection URL. It indicates the database dialect to be used and other required connection parameters. Here's an example:

"dialect+driver://username:password@host:port/database"

The dialect part tells SQLAlchemy what kind of database it will be interacting with. The driver part is pointing to a specific DBAPI implementation, tuned to the database type being used. The DBAPI, in short, is a widely used Python specification providing a low-level system to talk to particular databases. Together, the dialect and driver combination ensures the Python code we write is translated to the correct SQL expressions before they're sent to the database. Changing the dialect changes the SQL translation to other database types without having to modify our Python code.

Refer to this documentation if you want to explore the dialects in detail, including current support level for different database types.

Let's see some examples. We could connect to an in-memory SQLite database:

from sqlalchemy import create_engine

engine = create_engine("sqlite+pysqlite:///:memory:")

Or to one in the filesystem:

from sqlalchemy import create_engine

engine = create_engine("sqlite+pysqlite:///dbname.db")

On a local port:

from sqlalchemy import create_engine

engine = create_engine("sqlite+pysqlite:///127.0.0.1:3307/dbname")

And so on. It's worth knowing that you may also create database URLs programmatically through the URL.create() constructor. Hardcoding credentials is generally a bad idea, and this constructor is handy for defining credentials through environment variables, for example. The resulting object can be passed to create_engine() directly:

from sqlalchemy import create_engine
from sqlalchemy import URL

url_object = URL.create(
    "postgresql+pg8000",
    username="dbadmin",
    password="zjjk@4863/v",
    host="pghost10",
    database="dbname",
)

engine = create_engine(url_object, echo=True)

This documentation section goes in-depth about the engine options we have available. For the purposes of this article we'll set everything to default, save for an echo=True parameter that causes SQL generated by our code to be logged to stdout. It'll be handy to demonstrate our code being translated to SQL.

4. Connecting

Remember that the engine is independent from both the Core and the ORM, but is used by both implementations. However, there are slight differences in how these implementations use the engine object to establish a connection.

On the Core implementation we usually work with Connection and Result objects. Put simply, the Connection object interacts with the engine to connect to the database. The Result objects are simply a set of database results, generated whenever we perform any given database operation.

The way we tend to use Connection objects is to have them represent a specific resource open against the database (usually a table), such that the scope of operations we want to perform is kept well-defined. We do the by means of Python's with statements, which also leaves the code organized and easy to read. Here's an example:

from sqlalchemy import text
from database.engine import engine

with engine.connect() as conn:
    result = conn.execute(text("SELECT 'hello world'"))
    print(result.all())

Here used a connection call wrapped into the engine object itself and defined a connection context within the with block. This also leads the connection to be automatically closed. We then used the text() construct to write textual SQL, just so we can demonstrate this connection. We perform a SELECT statement and bind the results to the result variable.

Remember we configured our engine with the echo=True setting so we can see the emitted SQL logged to stdout. Here's what running this code results in:

BEGIN (implicit)
select 'hello world'
[...]
[('hello world',)]
ROLLBACK

The SELECT statement is executed, giving the [('hello world',)] result you see above. SQLAlchemy then retrieves this data and returns it as Result objects to the result variable in our code above. SQLAlchemy did all the heavy lift of opening and closing the connection, translating the correct SQL, executing it and parsing the results.

There's another thing of notice on the translated SQL snippet above: the ROLLBACK statement. The reason it's there is because of one major aspect of SQLAlchemy and the underlying Python DBAPI: transactions, by default, are not committed automatically. If you want to persist changes, you must explicitly use the Connection.commit() method:

from sqlalchemy import text

with engine.connect() as conn:
    result = conn.execute(text("select 'hello world'"))
    print(result.all())
    conn.commit()

BEGIN (implicit)
select 'hello world'
[...]
[('hello world',)]
COMMIT

Now, while the Connection pattern I just showed you is typically used on Core-centric implementations, the patterns we used are very similar to what is done on the ORM. The difference is that we'll use Session objects instead of Connection.

The Session is the ORM's fundamental interface for database interaction. It holds the connection and uses with statements just like we saw, but it also has additional features to manage operations for ORM objects. In order to effectively demonstrate this, however, we first need to understand what these ORM objects are. We'll do this in the next section.

5. Setting up mapped models

ORM models, ORM classes, mapped classes or mapped objects are, in short, objects that correspond to a particular database table. Each column is mapped to a class attribute, and each class attribute is implemented in a way that describes the column's properties and constraints. Thus the "mapped objects" designation.

The ORM implements this via Declarative Mapping. Its most common pattern is to define a Base class that inherits from the built-in DeclarativeBase superclass. We then subclass this Base class for each of our database tables. The underlying inheritance chain causes each subclass to acquire ORM mappings and functionalities.

We'll demonstrate this with two simple classes, Artist and Track. First, let's also organize some code into dedicated modules. On the database directory we created earlier, create a engine.py, a models.py, a utils.py and a __init__py file. Our project's directory tree will look like this:

.
├── db
│   ├── __init__.py
│   ├── engine.py
│   ├── models.py
│   └── utils.py
└── requirements.txt

Add the code below to engine.py:

import os
from sqlalchemy import create_engine

current_path = os.path.dirname(os.path.realpath(__file__))
database_url = f"sqlite+pysqlite:///{current_path}/database.db"
engine = create_engine(database_url, echo=True)

This will point the application to the database.bd file, in the same directory as the engine.py file, where we'll keep a SQLite database. Next, add the following bits to the models.py file. I'll explain the classes shortly.

from typing import List
from sqlalchemy import ForeignKey
from sqlalchemy import String
from sqlalchemy.orm import DeclarativeBase
from sqlalchemy.orm import Mapped
from sqlalchemy.orm import mapped_column
from sqlalchemy.orm import relationship


class Base(DeclarativeBase):
    pass

class Artist(Base):
    __tablename__ = "artist"
    id: Mapped[int] = mapped_column(primary_key=True)
    name: Mapped[str] = mapped_column(String(30))
    tracks: Mapped[List["Track"]] = relationship(
        back_populates="artist", cascade="all, delete-orphan"
    )
    def __repr__(self) -> str:
        return f"Artist(id={self.id!r}, name={self.name!r})"

class Track(Base):
    __tablename__ = "track"
    id: Mapped[int] = mapped_column(primary_key=True)
    title: Mapped[str]
    artist_id: Mapped[int] = mapped_column(ForeignKey("artist.id"))
    artist: Mapped["Artist"] = relationship(back_populates="tracks")
    def __repr__(self) -> str:
        return f"Track(id={self.id!r}, title={self.title!r})"

Here we're defining a Base class that inherits from DeclarativeBase, and then defining the Artist and Track subclasses. As discussed earlier, this informs SQLAlchemy that Artist and Track are mapped ORM objects, providing them with all instrumentation needed to interact with the database.

Because of this, we are also able to interact with the table schemas themselves. This is exemplified by the __tablename__ class-level attribute, which defines table names for the respective ORM classes.

The other class attributes are each mapped to a table column. This mapping, more specifically, is established by the mapped_column() directive. Alongside it, the Mapped typing is used by SQLAlchemy to derive the corresponding SQL types and their nullability constraints.

The Column.primary_key parameter, as the name implies, identifies the columns defined as the table's primary key. Table relationships can be defined through the the relationship() construct. We won't go in depth, but relationships and mapped columns have quite a lot of options and arguments that help define every aspect of the underlying relationship. Be sure to check the documentation if you need more detail on this.

Finally, we come to the concept of table metadata. In this context, table metadata is a SQLAlchemy construct defined by our mapped classes, which describes what each underlying database table looks like. This construct is defined by both class-level attributes such as __tablename__ and the attributes that are mapped to table columns. The metadata enables us to interact with the database in some interesting ways. Let's demonstrate some by adding the helper functions below to the utils.py file:

from database import models
from database.engine import engine


def create_database() -> None:
    models.Base.metadata.create_all(engine)

def drop_database() -> None:
    models.Base.metadata.drop_all(engine)

def reset_database() -> None:
    drop_database()
    create_database()

create_database() will create all tables described in the mapped classes in the models module. If the file pointed to in the engine does not yet exist, it will be automatically created. drop_database() will do the opposite, leaving us with an empty database (but still keep the file). reset_database() will drop and re-create the database leaving us with empty tables, which is useful if you want to play around with the mapped objects. Try opening a Python shell in your virtual environment and executing the first function. We'll be able to visualize the emitted SQL due to the echo=True property we set on the engine:

PRAGMA main.table_info("artist")
...
PRAGMA temp.table_info("track")
...
CREATE TABLE artist (
    id INTEGER NOT NULL, 
    name VARCHAR(30) NOT NULL, 
    PRIMARY KEY (id)
)
...

CREATE TABLE track (
    id INTEGER NOT NULL, 
    title VARCHAR NOT NULL, 
    artist_id INTEGER NOT NULL, 
    PRIMARY KEY (id), 
    FOREIGN KEY(artist_id) REFERENCES artist (id)
)
...
COMMIT

Note that handling the schema directly like will will cause changes to be auto-committed. The following statements are logged to stdout as result from running the drop function, showing the reverse operation.

BEGIN (implicit)
PRAGMA main.table_info("artist")
...
PRAGMA main.table_info("track")
... 
DROP TABLE track
...
DROP TABLE artist
...
COMMIT

With functional mapped classes, we can return to the matter of using Session objects for out connection. We'll see this in practice, as we go over some basic CRUD operations on the next section, where we'll also get the hang of data manipulation.

6. Basic CRUD examples

Going forth, we will be adding, fetching, updating and deleting records from the database by means of Session objects. Let us revise some key points about them:

Sessions are how the SQLAlchemy ORM connects to the database and performs transactions.
A Session object connects to the database via the Engine object, where we configure various connection parameters.
Transactions are to be executed within a session context, which is usually done through Python's with statements.
Transactions are not committed automatically, requiring us to call Session.commit() to persist changes.

There's a lot more detail we could talk about sessions, such as how the engine connection is handled or how to create session factories with sessionmaker. We'll stick to the basics for brevity, but you may start exploring these topics in this part of the documentation.

With that being said, let's dig in.

Create

To add rows to a table, in this example, we'll be using session contexts to create instances of our mapped objects. Then, we use Session.add() and Session.commit() to save them. Let's demonstrate this with our Artist model. In the database directory, create a operations.py file:

.
├── database
│   ├── __init__.py
│   ├── engine.py
│   ├── models.py
│   ├── operations.py
│   └── utils.py
└── requirements.txt

And add the following bits:

from sqlalchemy.orm import Session
from database.engine import engine
from database.models import Artist, Track
# from database.utils import reset_database


def create_artist(name: str) -> None:
    with Session(engine) as session:
      artist = Artist(name=name)
      session.add(artist)
      session.commit()

def populate_artists() -> None:
    create_artist("David Bowie")
    create_artist("Queen")
    create_artist("Iggy Pop")

The commented-out reset_database method above can be used to reset the database if at any point you want to return it to a blank slate with empty tables.

We can create mapped object instances simply by passing named arguments to our mapped classes. By doing this within a session context, and then committing the changes, will lead ORM to do all the work of adding new database records for each of the instances we created. Adding data is as simple as that. This can be verified by looking at the SQL statements logged to stdout. Here's an excerpt for the snippet above:

INSERT INTO artist (name) VALUES ('David Bowie')
[...] ('David Bowie',)
COMMIT

We'll discuss reading data on the next section, but here's a sneak peek so I can show you some additional details into one of the rows we just added:

from sqlalchemy import select


def find_bowie():
    with Session(engine) as session:
        query = select(Artist).filter_by(name="David Bowie")
        result = session.execute(query)
        print(result)

Here's the print statement output:

[(Artist(id=1, name='David Bowie'),)]

We can confirm the David Bowie row has been saved successfully, and also that a primary key was automatically assigned to it. By default, primary key columns will be auto-incrementing integers starting at 1, unless configured otherwise.

Also, not the contents of the result variable. It contains a list with a tuple-like data structure. This tuple is actually a SQLAlchemy data structure that we'll come back to in the next section.

Let's shift up a gear. Replace the find_bowie function with the code below:

from sqlalchemy import Row
from typing import Tuple


def find_artist_by_name(name: str) -> Row[Tuple[Artist]] | None:
    with Session(engine) as session:
        query = select(Artist).filter_by(name=name)
        result = session.execute(query)
        return result.first()

def find_track_by_title(title: str) -> (Track | None):
    with Session(engine) as session:
        query = select(Track).filter_by(title=title)
        result = session.scalars(query)
        return result.first()

def create_track(title: str, artist: Artist) -> None:
    with Session(engine) as session:
        track = Track(title=title, artist=artist)
        session.add(track)
        session.commit()

def populate_bowie_tracks() -> None:
    result = find_artist_by_name("David Bowie")
    if result is None:
        return

    bowie = result[0]
    with Session(engine) as session:
        track1 = Track(title="Under Pressure", artist=bowie)
        track2 = Track(title="Starman", artist=bowie)
        track3 = Track(title="Heroes", artist=bowie)
        track4 = Track(title="Space Oddity", artist=bowie)
        track5 = Track(title="Rebel Rebel", artist=bowie)

        session.add(track1)
        session.add(track2)
        session.add(track3)
        session.add(track4)
        session.add(track5)

        session.commit()

def populate_queen_tracks() -> None:
    result = find_artist_by_name("Queen")
    if result is None:
        return

    queen = result[0]
    with Session(engine) as session:
        track1 = Track(title="Bohemian Rhapsody", artist=queen)
        track2 = Track(title="Don't Stop Me Now", artist=queen)
        track3 = Track(title="We Will Rock You", artist=queen)
        track4 = Track(title="We Are The Champions", artist=queen)
        track5 = Track(title="I Want To Break Free", artist=queen)

        session.add(track1)
        session.add(track2)
        session.add(track3)
        session.add(track4)
        session.add(track5)

        session.commit()

def populate_iggy_tracks() -> None:
    result = find_artist_by_name("Iggy Pop")
    if result is None:
        return

    iggy = result[0]
    with Session(engine) as session:
        track1 = Track(title="The Passenger", artist=iggy)
        track2 = Track(title="Lust For Life", artist=iggy)
        track3 = Track(title="Candy", artist=iggy)
        track4 = Track(title="Livin' On The Edge Of The Night", artist=iggy)
        track5 = Track(title="Hold The Line", artist=iggy)

        session.add(track1)
        session.add(track2)
        session.add(track3)
        session.add(track4)
        session.add(track5)

        session.commit()

def populate_tracks() -> None:
    populate_bowie_tracks()
    populate_queen_tracks()
    populate_iggy_tracks()

This gives us a proper artist search function which returns either the searched artist or None if it is not found. There's also a track creation function, and some utility functions to populate our tables with some data.

There's also a relationship creation example in there. You can create one by passing an existing mapped object instance, to another mapped object instance, to establish a relationship. Note that this is done specifically in the attribute defined as a relationship, or in this case the artist attribute in the Track class.

Alternatively, we could achieve the same by passing an instance's primary key to an attribute defined as a foreign key:

Track(title="Ziggy Stardust", artist_id=bowie.id)

Now that we have added some data, let's explore querying.

Read

Querying is a wide topic, with many strategies available in SQLAlchemy, such as filtering, ordering, joins and others. Whichever the case, we'll usually use a combination of Sessions, mapped objects and the SQL Expression Language system.

Once again, we'll stick to the basics for brevity. To start, add this bit to operations.py:

def find_artists() -> None:
    with Session(engine) as session:
        query = select(Artist)
        result = session.execute(query)
        print(result.all())

Here's the printed statement:

[
    (Artist(id=1, name='David Bowie'),),
    (Artist(id=2, name='Queen'),),
    (Artist(id=3, name='Iggy Pop'),)
]

Remember that whenever we execute a SQL statement against the database (in this case a SELECT statement through the select function), it generates a Result object. It represents a set of database results for the performed operation, from which we can retrieve the resulting data.

There are a few ways retrieving this data. One is calling the .all() method like we did in the snippet above. It returns a list of Row objects. The Row object represents a single database row, that is, a table record.

We can also use the .fist() method to extract just the first row from the Result object, or None if it doesn't exists:

print(find_artist_by_name("Lou Reed"))

# Output:
None

Row and Result objects are used on both Core or ORM implementations. However, when we are using mapped ORM objects, rows may be mapped to one of our ORM classes. For example, let's check data types at different levels: the Row object itself, and the data within.

def find_artists() -> None:
    with Session(engine) as session:
        query = select(Artist)
        result = session.execute(query)
        first_artist = result.first()
        print(type(first_artist))
        print(type(first_artist[0]))
        print(first_artist[0])

# First print output:
<class 'sqlalchemy.engine.row.Row'>
# Second print output:
<class 'database.models.Artist'>
# Third print output:
Artist(id=1, name='David Bowie')

Better explaining the outputs above:

When we perform any given operation in the database, we get Result objects wrapping the obtained data. We got one on the result variable.
When we call .first(), .all() or any such methods of the Result object, we get access to one or more Row objects contained in it. These objects usually represent table rows.
Because we're working with the ORM, the data within the Row objects was transformed to an instance of the mapped ORM class we just queried upon.

Because the first_artist[0] is a mapped object instance, we can access any of its attributes to get the corresponding data:

print(first_artist[0].id)
# Output:
1

print(first_artist[0].name)
# Output:
"David Bowie"

Remember that we defined a relationship between artists and tracks. Try accessing the tracks attribute:

print(first_artist[0].tracks)

# Output:
[
    Track(id=1, title='Under Pressure'),
    Track(id=2, title='Starman'),
    Track(id=3, title='Heroes'),
    Track(id=4, title='Space Oddity'),
    Track(id=5, title='Rebel Rebel')
]

If you look back at how we defined this relationship in the Artist and Track classes you'll see that, in addition to a foreign key attribute in the Track class, we added relationship attributes with a back_populate parameter in both of them. The effect of this is that relationships are kept synchronized and easily accessible, which is a nice ORM feature.

The next thing I'd like to introduce to you is the concept of scalars. No doubt you noticed we needed to use some intricate index syntax above (first_artist[0]), to access the mapped ORM instance from the Row object. You might have foreseen even worse situations, like this:

all_artists = result.all()
desired_record = all_artists[1][0]

Scalars are a way to avoid this by bypassing the Row objects entirely, getting direct access to the mapped instances. We can do this in two ways. Either call a .scalars() method in a result object:

def find_artists() -> None:
    with Session(engine) as session:
        query = select(Artist)
        result = session.execute(query)
        all_artists = result.scalars().all() 
        print(all_artists)

Or use Session.scalars() to execute the operation, which is often preferred:

def find_artists() -> None:
    with Session(engine) as session:
        query = select(Artist)
        result = session.scalars(query)
        all_artists = result.all()
        print(all_artists)

Both will lead to the same result:

[
    Artist(id=1, name='David Bowie'),
    Artist(id=2, name='Queen'),
    Artist(id=3, name='Iggy Pop')
]

As you can see, we skipped the Row objects entirely and obtained mapped objects instances directly. This is a very common ORM pattern and reduces code complexity by a fair amount.

Still, you may be asking whether Rows still have use cases. The answer is mostly yes, although it's more common outside the ORM. That's because scalars only work like with queries that return ORM objects. You may encounter scenarios where this is not the case, however. A good example of this is selecting specific table columns, common when doing joins. The snippet below demonstrates this. It uses Row objects to pick data coming from from multiple tables:

def find_tracks() -> None:
    with Session(engine) as session:
        query = select(Artist.name, Track.title).join(Artist.tracks)
        result = session.execute(query)
        for row in result:
            print(f"Track: {row.title}, by {row.name}")

Track: Under Pressure, by David Bowie
Track: Starman, by David Bowie
Track: Heroes, by David Bowie
Track: Space Oddity, by David Bowie
Track: Rebel Rebel, by David Bowie
Track: Bohemian Rhapsody, by Queen
Track: Don't Stop Me Now, by Queen
Track: We Will Rock You, by Queen
Track: We Are The Champions, by Queen
Track: I Want To Break Free, by Queen
Track: The Passenger, by Iggy Pop
Track: Lust For Life, by Iggy Pop
Track: Candy, by Iggy Pop
Track: Livin' On The Edge Of The Night, by Iggy Pop
Track: Hold The Line, by Iggy Pop

If we call session.scalars() instead of the session.execute() in the code above, it runs but the Row object casting does not work as expected. It erroneously become a string:

def find_tracks() -> None:
    with Session(engine) as session:
        query = select(Artist.name, Track.title).join(Artist.tracks)
        result = session.scalar(query)
        print(result)

# Output:
"David Bowie"

So we lost ORM capabilities in exchange for constructing a tailored dataset. While we could still get the same data while sticking to the ORM, this example serves to demonstrate the usability of Row objects. Nevertheless, it's always a good idea to keep the codebase concise and reduce complexity to the minimum. It's better to choose a paradigm and stick to it unless the need really arises.

TO wrap this section up, we saw that Result, Row and Scalar objects are the base blocks we need to understand how querying works in SQLAlchemy. Knowing this makes it easier to read and dive deeper into the ORM querying guide and other related documentation. There's still a lot of querying topics such as joins, set operations, pagination, ordering, subqueries and others that we won't have the time to explore.

Finally before we move on, let's tidy up our operations.py file and make use of scalars in our functions:

from sqlalchemy import select
from sqlalchemy.orm import Session
from typing import Sequence

from database.engine import engine
from database.models import Artist, Track


def find_artists() -> Sequence[Artist]:
    with Session(engine) as session:
        query = select(Artist)
        result = session.scalars(query)
        return result.all()

def find_artist_by_name(name: str) -> (Artist | None):
    with Session(engine) as session:
        query = select(Artist).filter_by(name=name)
        result = session.scalars(query)
        return result.first()

def find_tracks() -> Sequence[Track]:
    with Session(engine) as session:
        query = select(Track).where(Track.id < 10)
        result = session.scalars(query)
        return result.all()

def find_track_by_title(title: str) -> (Track | None):
    with Session(engine) as session:
        query = select(Track).filter_by(title=title)
        result = session.scalars(query)
        return result.first()

def create_artist(name: str) -> None:
    with Session(engine) as session:
        artist = Artist(name=name)
        session.add(artist)
        session.commit()

def create_track(title: str, artist: Artist) -> None:
    with Session(engine) as session:
        track = Track(title=title, artist=artist)
        session.add(track)
        session.commit()

def populate_artists() -> None:
    create_artist("David Bowie")
    create_artist("Queen")
    create_artist("Iggy Pop")

def populate_bowie_tracks() -> None:
    bowie = find_artist_by_name("David Bowie")
    if bowie is None:
        return

    with Session(engine) as session:
        track1 = Track(title="Under Pressure", artist=bowie)
        track2 = Track(title="Starman", artist=bowie)
        track3 = Track(title="Heroes", artist=bowie)
        track4 = Track(title="Space Oddity", artist=bowie)
        track5 = Track(title="Rebel Rebel", artist=bowie)

        session.add(track1)
        session.add(track2)
        session.add(track3)
        session.add(track4)
        session.add(track5)

        session.commit()

def populate_queen_tracks() -> None:
    queen = find_artist_by_name("Queen")
    if queen is None:
        return

    with Session(engine) as session:
        track1 = Track(title="Bohemian Rhapsody", artist=queen)
        track2 = Track(title="Don't Stop Me Now", artist=queen)
        track3 = Track(title="We Will Rock You", artist=queen)
        track4 = Track(title="We Are The Champions", artist=queen)
        track5 = Track(title="I Want To Break Free", artist=queen)

        session.add(track1)
        session.add(track2)
        session.add(track3)
        session.add(track4)
        session.add(track5)

        session.commit()

def populate_iggy_tracks() -> None:
    iggy = find_artist_by_name("Iggy Pop")
    if iggy is None:
        return

    with Session(engine) as session:
        track1 = Track(title="The Passenger", artist=iggy)
        track2 = Track(title="Lust For Life", artist=iggy)
        track3 = Track(title="Candy", artist=iggy)
        track4 = Track(title="Livin' On The Edge Of The Night", artist=iggy)
        track5 = Track(title="Hold The Line", artist=iggy)

        session.add(track1)
        session.add(track2)
        session.add(track3)
        session.add(track4)
        session.add(track5)

        session.commit()

def populate_tracks() -> None:
    populate_bowie_tracks()
    populate_queen_tracks()
    populate_iggy_tracks()

Update

Updating records is really easy. All we need is a mapped object instance, usually obtained after querying the database in any way. If we change one of its attributes within a session context and commit the changes, the ORM will save them in the database. To demonstrate, let's create two update functions for our classes:

def update_artist(artist: Artist, name: str) -> None:
    with Session(engine) as session:
        artist.name = name
        session.add(artist)
        session.commit()

def update_track(track: Track, title: str, artist_id: int) -> None:
    with Session(engine) as session:
        track.title = title
        track.artist_id = artist_id
        session.add(track)
        session.commit()

These methods take a mapped instance of one of the models and their corresponding attributes as arguments. Now, assume we create an artist with a typo, for example:

def create_m83():
    with Session(engine) as session:
        create_artist("m83")
        m83 = find_artist_by_name("m83")
        print(m83)

# Output:
# Artist(id=4, name='m83')

All we need is to pass the instance and updated data to the update function:

def fix_m83():
    with Session(engine) as session:
        m83 = find_artist_by_name("m83")
        print(m83)

        update_artist(m83, "M83")
        m83 = find_artist_by_name("M83")
        print(m83)

        # First output:
        # Artist(id=4, name='m83')

        # Second output:
        # Artist(id=4, name='M83')

It's similar if we want to update a relationship:

def create_midnight_city():
    # Here we create Midnight City with a typo and the wrong artist
    with Session(engine) as session:
        artist = find_artist_by_name("David Bowie")
        create_track("Midnight CIty", artist)

    # Here we query the track and its artist to show data currently in the database
    with Session(engine) as session:
        track = find_track_by_title("Midnight CIty")
        artist = session.scalars(
            select(Artist).where(Artist.id == track.artist_id)
        ).first()
        print(track)
        print(artist)

        # First output:
        # Track(id=16, title='Midnight CIty')
        # Second output:
        # Artist(id=1, name='David Bowie')

def fix_midnight_city():
    with Session(engine) as session:
        artist = find_artist_by_name("M83")
        track = find_track_by_title("Midnight CIty")
        update_track(track, "Midnight City", artist_id=artist.id)

        track = find_track_by_title("Midnight City")
        artist = session.scalars(
            select(Artist).where(Artist.id == track.artist_id)
        ).first()
        print(track)
        print(artist)

        # First output:
        # Track(id=16, title='Midnight City')
        # Second output:
        # Artist(id=4, name='M83')

Surely, these methods are just for demonstration purposes and there are better implementations. This is a good opportunity to play around with them to practice querying and modifying data. Save for the update methods, they will be discarded from the final code.

Delete

Like updating, deletion operations will require a mapped object instance and a session context. Then you call session.delete() and session.commit():

def delete_artist(artist: Artist) -> None:
    with Session(engine) as session:
        session.delete(artist)
        session.commit()

def delete_track(track: Track) -> None:
    with Session(engine) as session:
        session.delete(track)
        session.commit()

Let's try deleting an artist:

with Session(engine) as session:
    m83 = find_artist_by_name("M83")
    print(m83)

    delete_artist(m83)
    session.commit()

# Output:
# Artist(id=4, name='m83')

Now if you try finding the same artist again:

with Session(engine) as session:
    m83 = find_artist_by_name("M83")
    print(m83)

# Output:
# None

Now try running the find_tracks function. You'll notice any tracks from the deleted artist are no longer present in the database. This is because of the deletion constraints we defined in our Artist class, specifically:

tracks: Mapped[List["Track"]] = relationship(
    back_populates="artist", cascade="all, delete-orphan"
)

Which defines an ON DELETE CASCADE behavior when deleting from a parent table. For more details on cascades, check this documentation.

This covers the basic CRUD operations for our application. Next, let's wrap up.

7. Wrapping up

This article has explored the basics of SQLAlchemy and leaves you with a very simple ORM application. From here you're able to head to the documentation to analyze the concepts we discussed in more detail, as well as delve into more advanced topics. I'll leave you with a list of ideas to try and learn more, in no particular order. Write an application of your own, or feel free to reuse the code we have created. It's available here. Best of luck!

Learn more about sessions. Learn about sessionmaker, try refactoring the application around it.
Add more mapped ORM classes with different column definitions. Learn the available data types and constraints, and how to define them.
Try creating different kinds of relationships and testing their behavior.
Write more complex queries. Try sorting, filtering and pagination. Try performing searches that involve relationships.
Head over to Alembic and learn about migrations. Think how you could implement them.
Try writing serializers to convert instances or you mapped objects to simple Python dictionaries. For a whole framework dedicated to this purpose, head over to marshmallow.