{"id":18287568,"url":"https://github.com/tsffarias/crud-api","last_synced_at":"2026-04-03T23:38:31.540Z","repository":{"id":244679581,"uuid":"815714095","full_name":"tsffarias/CRUD-API","owner":"tsffarias","description":"Este repositório apresenta um exemplo de aplicação CRUD simples utilizando FastAPI para o backend, PostgreSQL como banco de dados e Streamlit para o frontend. A estrutura foi criada para ser um ponto de partida e exemplo para desenvolvedores que desejam construir aplicações web modernas e escaláveis.","archived":false,"fork":false,"pushed_at":"2024-06-22T02:00:20.000Z","size":340,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-15T01:14:17.222Z","etag":null,"topics":["api","crud","docker","fastapi","mvc","postgresql","pydantic","python","sqlalchemy","streamlit","uvicorn"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tsffarias.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-06-15T23:27:51.000Z","updated_at":"2024-06-22T02:00:23.000Z","dependencies_parsed_at":"2024-06-16T18:08:56.495Z","dependency_job_id":"6228bfc3-39c0-4f3b-a9a8-62709eb88b73","html_url":"https://github.com/tsffarias/CRUD-API","commit_stats":null,"previous_names":["tsffarias/crud-api"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tsffarias%2FCRUD-API","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tsffarias%2FCRUD-API/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tsffarias%2FCRUD-API/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tsffarias%2FCRUD-API/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tsffarias","download_url":"https://codeload.github.com/tsffarias/CRUD-API/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247994068,"owners_count":21030048,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","crud","docker","fastapi","mvc","postgresql","pydantic","python","sqlalchemy","streamlit","uvicorn"],"created_at":"2024-11-05T13:28:20.167Z","updated_at":"2025-12-30T20:23:05.942Z","avatar_url":"https://github.com/tsffarias.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003eProjeto CRUD com FastAPI, PostgreSQL e Streamlit\u003c/h1\u003e \n\n\u003e Este repositório apresenta um exemplo de aplicação CRUD simples utilizando FastAPI para o backend, PostgreSQL como banco de dados e Streamlit para o frontend. A estrutura foi criada para ser um ponto de partida e exemplo para desenvolvedores que desejam construir aplicações web modernas e escaláveis.\n\n---\n\n🎯 **Objetivo:**\nO objetivo deste projeto é fornecer uma base sólida para desenvolvedores iniciarem projetos de CRUD com tecnologias modernas. Ele demonstra como configurar e integrar FastAPI, PostgreSQL e Streamlit, proporcionando uma aplicação funcional que pode ser facilmente estendida e personalizada.\n\n💡 **Utilidade:**\n\nEste projeto é útil para:\n- Desenvolvedores que estão começando com FastAPI e desejam um exemplo prático de integração com PostgreSQL.\n- Aqueles que desejam aprender a usar Streamlit para criar interfaces front-end rápidas e interativas.\n- Projetos que precisam de uma base para construir aplicações CRUD escaláveis e de fácil manutenção.\n\n![arquitetura](assets/arquitetura.png)\n\n## Instalação via docker\nAntes de rodar o Docker, crie um arquivo .env na raiz do projeto com os seguintes valores:\n\n```\nDB_HOST_PROD = postgres\nDB_PORT_PROD = 5432\nDB_NAME_PROD = mydatabase\nDB_USER_PROD = user\nDB_PASS_PROD = password\nPGADMIN_EMAIL = email_pgadmin\nPGADMIN_PASSWORD = password_pgadmin\n```\n\nPara iniciar a aplicação, execute:\n\n```bash\ndocker-compose up -d --build\n```\n\n### Uso\n\nFrontend:\nAcesse o endereço http://localhost:8501\n\n![frontend](assets/frontend.png)\n\n\n### Documentação\n\nBackend:\nAcesse o endereço http://localhost:8000/docs\n\n![backend](assets/documentacao.png)\n\n## Nossa estrutura de pastas e arquivos\n\n```bash\n├── README.md # arquivo com a documentação do projeto\n├── backend # pasta do backend (FastAPI, SQLAlchemy, Uvicorn, Pydantic)\n├── frontend # pasta do frontend (Streamlit, Requests, Pandas)\n├── docker-compose.yml # arquivo de configuração do docker-compose (backend, frontend, postgres)\n├── poetry.lock # arquivo de lock do poetry\n└── pyproject.toml # arquivo de configuração do poetry\n```\n\n## Nosso Backend\n\nNosso backend vai ser uma API, que será responsável por fazer a comunicação entre o nosso frontend com o banco de dados. Vamos detalhar cada uma das pastas e arquivos do nosso backend.\n\n### FastAPI\n\nO FastAPI é um framework web para construir APIs com Python. Ele é baseado no Starlette, que é um framework assíncrono para construir APIs. O FastAPI é um framework que está crescendo muito, e que tem uma curva de aprendizado muito baixa, pois ele é muito parecido com o Flask.\n\n### Uvicorn\n\nO Uvicorn é um servidor web assíncrono, que é baseado no ASGI, que é uma especificação para servidores web assíncronos. O Uvicorn é o servidor web recomendado pelo FastAPI, e é o servidor que vamos utilizar nesse projeto.\n\n### SQLAlchemy\n\nO SQLAlchemy é uma biblioteca para fazer a comunicação com o banco de dados. Ele é um ORM (Object Relational Mapper), que é uma técnica de mapeamento objeto-relacional que permite fazer a comunicação com o banco de dados utilizando objetos.\n\nUma das principais vantagens de trabalhar com o SQLAlchemy é que ele é compatível com vários bancos de dados, como MySQL, PostgreSQL, SQLite, Oracle, Microsoft SQL Server, Firebird, Sybase e até mesmo o Microsoft Access.\n\nAlém disso, ele realiza a sanitização dos dados, evitando ataques de SQL Injection.\n\nOutro ponto, é que você pode trabalhar com métodos nativos do Python, como por exemplo o filter, que é muito utilizado para fazer filtros em listas. Isso facilita muito a nossa vida, pois não precisamos aprender uma nova linguagem para fazer a comunicação com o banco de dados. Quem tiver familidade com Pandas, vai se sentir em casa.\n\n### Pydantic\n\nO Pydantic é uma biblioteca para fazer a validação de dados. Ele é utilizado pelo FastAPI para fazer a validação dos dados que são recebidos na API, e também para definir os tipos de dados que são retornados pela API.\n\n## docker-compose.yml\n\nEsse arquivo `docker-compose.yml` define uma aplicação composta por três serviços: `postgres`, `backend` e `frontend`, e cria uma rede chamada `mynetwork`. Vou explicar cada parte em detalhes:\n\n### Services:\n\n#### Postgres:\n\n* `image: postgres:latest`: Esse serviço utiliza a imagem mais recente do PostgreSQL disponível no Docker Hub.\n* `volumes`: Mapeia o diretório `/var/lib/postgresql/data` dentro do contêiner do PostgreSQL para um volume chamado `postgres_data` no sistema hospedeiro. Isso permite que os dados do banco de dados persistam mesmo quando o contêiner é desligado.\n* `environment`: Define variáveis de ambiente para configurar o banco de dados PostgreSQL, como nome do banco de dados (`POSTGRES_DB`), nome de usuário (`POSTGRES_USER`) e senha (`POSTGRES_PASSWORD`).\n* `networks`: Define que este serviço está na rede chamada `mynetwork`.\n\n#### Backend:\n\n* `build`: Especifica que o Docker deve construir uma imagem para esse serviço, usando um Dockerfile localizado no diretório `./backend`.\n* `volumes`: Mapeia o diretório `./backend` (no sistema hospedeiro) para o diretório `/app` dentro do contêiner. Isso permite que as alterações no código fonte do backend sejam refletidas no contêiner em tempo real.\n* `environment`: Define a variável de ambiente `DATABASE_URL`, que especifica a URL de conexão com o banco de dados PostgreSQL.\n* `ports`: Mapeia a porta `8000` do sistema hospedeiro para a porta `8000` do contêiner, permitindo que o serviço seja acessado através da porta `8000`.\n* `depends_on`: Indica que este serviço depende do serviço `postgres`, garantindo que o banco de dados esteja pronto antes que o backend seja iniciado.\n* `networks`: Também define que este serviço está na rede `mynetwork`.\n\n#### Frontend:\n\n* `build`: Similar ao backend, especifica que o Docker deve construir uma imagem para este serviço, usando um Dockerfile localizado no diretório `./frontend`.\n* `volumes`: Mapeia o diretório `./frontend` (no sistema hospedeiro) para o diretório `/app` dentro do contêiner, permitindo alterações em tempo real.\n* `ports`: Mapeia a porta `8501` do sistema hospedeiro para a porta `8501` do contêiner, permitindo acesso ao frontend através da porta `8501`.\n* `networks`: Define que este serviço também está na rede `mynetwork`.\n\n### Networks:\n\n* `mynetwork`: Define uma rede personalizada para os serviços se comunicarem entre si.\n\n### Volumes:\n\n* `postgres_data`: Define um volume para armazenar os dados do banco de dados PostgreSQL.\n\n### Comando `docker-compose up`:\n\nQuando você executa `docker-compose up`, o Docker Compose lerá o arquivo `docker-compose.yml`, criará os serviços conforme as definições especificadas e os iniciará. Isso significa que os contêineres para o banco de dados PostgreSQL, o backend e o frontend serão criados e conectados à rede `mynetwork`. O banco de dados será configurado com os detalhes fornecidos (nome do banco de dados, usuário e senha), e as imagens para os serviços de backend e frontend serão construídas a partir dos Dockerfiles fornecidos. Uma vez iniciados, você poderá acessar o backend através de `http://localhost:8000` e o frontend através de `http://localhost:8501`. Os dados do banco de dados serão persistidos no volume `postgres_data`.\n\n## Nossa estrutura de pastas e arquivos\n\n```bash\n├── backend\n│   ├── Dockerfile # arquivo de configuração do Docker\n│   ├── crud.py # arquivo com as funções de CRUD utilizando o SQL Alchemy ORM\n│   ├── database.py # arquivo com a configuração do banco de dados utilizando o SQL Alchemy \n│   ├── main.py\n│   ├── models.py\n│   ├── requirements.txt\n│   ├── router.py\n│   └── schemas.py\n```\n\n## Arquivo `database.py`\n\nO arquivo `database.py` é responsável por fazer a configuração do banco de dados utilizando o SQLAlchemy. Ele é responsável por criar a conexão com o banco de dados, e também por criar a sessão do banco de dados.\n\nCaso queira mudar de banco de dados, você só precisa mudar a URL de conexão, que está na variável SQLALCHEMY_DATABASE_URL. o SQLAlchemy é compatível com vários bancos de dados, como MySQL, PostgreSQL, SQLite, Oracle, Microsoft SQL Server, Firebird, Sybase e até mesmo o Microsoft Access.\n\nOs principais pontos desse arquivo é a engine, que é a conexão com o banco de dados, e o SessionLocal, que é a sessão do banco de dados. O SessionLocal é quem executada as queries no banco de dados.\n\nLembrar sempre de:\n\n1) Declarar a URL do banco\n2) Criar a engine usando o 'create_engine'\n3) Criar a sessão do banco\n4) Criar a Base do ORM (nosso Model vai herdar ele)\n5) Criar um gerador de sessão para ser reutilizado\n\n## Arquivo `models.py`\n\nO arquivo `models.py` é responsável por definir os modelos do SQLAlchemy, que são as classes que definem as tabelas do banco de dados. Esses modelos são utilizados para fazer a comunicação com o banco de dados.\n\nÉ aqui que definimos o nome da tabela, os campos e os tipos de dados. Conseguimos incluir campos gerados aleatoriamente, como o id e o created_at. Para o id, ao incluir o campo Integer, com o parâmetro primary_key=True, o SQLAlchemy já entende que esse campo é o id da tabela. Para o created_at, ao incluir o campo DateTime, com o parâmetro default=datetime, o SQLAlchemy já entende que esse campo é a data de criação da tabela.\n\nLembrar:\n\n1) O models é agnóstico ao banco, ele não sabe qual é o banco que é criado! Ele vai importar o base do database!\n\n2) Declarar sua Tabela\n\n## Arquivo `schemas.py`\n\nO arquivo `schemas.py` é responsável por definir os schemas do Pydantic, que são as classes que definem os tipos de dados que serão utilizados na API. Esses schemas são utilizados para fazer a validação dos dados que são recebidos na API, e também para definir os tipos de dados que são retornados pela API.\n\nO pydantic é a principal biblioteca para validação de dados em Python. Ela é utilizada pelo FastAPI para fazer a validação dos dados recebidos na API, e também para definir os tipos de dados que são retornados pela API.\n\nAlém disso, ela possui uma integração muito boa com o SQLAlchemy, que é a biblioteca que utilizamos para fazer a comunicação com o banco de dados.\n\nOutra vantagem são os seus tipos pré-definidos, que facilitam muito a nossa vida. Por exemplo, se você quer definir um campo que aceita apenas números positivos, você pode utilizar o PositiveInt. Se você quer definir um campo que aceita apenas determinadas categorias, você pode utilizar o construtor constrains.\n\nDetalhe que criamos schemas diferentes para os retornos da nossa API. Isso é uma boa prática, pois permite que você tenha mais flexibilidade para alterar os schemas no futuro.\n\nTemos o schema `ProductBase`, que é o schema base para o cadastro de produtos. Esse schema é utilizado para fazer a validação dos dados que são recebidos na API, e também para definir os tipos de dados que são retornados pela API.\n\nTemos o schema `ProductCreate`, que é o schema que é retornado pela API. Ele é uma classe que herda do schema `ProductBase`, e possui um campo a mais, que é o id. Esse campo é utilizado para identificar o produto no banco de dados.\n\nTemos o schema `ProductResponse`, que é o schema que é retornado pela API. Ele é uma classe que herda do schema `ProductBase`, e possui dois campos a mais, que é o id e o created_at. Esses campos são gerados pelo nosso banco de dados.\n\nTemos o schema `ProductUpdate`, que é o schema que é recebido pela API para update. Ele possui os campos opcionais, pois não é necessário enviar todos os campos para fazer o update.\n\n## Arquivo `crud.py`\n\nO arquivo `crud.py` é responsável por definir as funções de CRUD utilizando o SQLAlchemy ORM. Essas funções são utilizadas para fazer a comunicação com o banco de dados. É nele que definimos as funções de listagem, criação, atualização e remoção de produtos. É onde os dados são persistidos no banco de dados.\n\n## Arquivo `router.py`\n\nO arquivo `router.py` é responsável por definir as rotas da API utilizando o FastAPI. É aqui que definimos as rotas, e também as funções que serão executadas em cada rota. Todas as funções definidas aqui recebem um parâmetro, que é o parâmetro request, que é o objeto que contém os dados da requisição.\n\nOs principais parametros são o path, que é o caminho da rota, o methods, que são os métodos HTTP que a rota aceita, e o response_model, que é o schema que é retornado pela rota.\n\n```python\n@router.post(\"/products/\", response_model=ProductResponse)\n```\nImportante destacar que o FastAPI utiliza o conceito de type hints, que são as anotações de tipos. Isso permite que o FastAPI faça a validação dos dados que são recebidos na API, e também para definir os tipos de dados que são retornados pela API. Por exemplo, ao definir o parâmetro product do tipo ProductResponse, o FastAPI já entende que os dados recebidos nesse parâmetro devem ser do tipo ProductResponse.\n\nConseguimos também retornar parâmetros pelo nosso path, no caso do delete, por exemplo, precisamos passar o id do produto que queremos deletar. Para isso, utilizamos o path /products/{product_id}, e definimos o parâmetro product_id na função delete_product.\n\n```python\n@router.get(\"/products/{product_id}\", response_model=ProductResponse)\ndef read_product_route(product_id: int, db: Session = Depends(get_db)):\n    db_product = get_product(db, product_id=product_id)\n    if db_product is None:\n        raise HTTPException(status_code=404, detail=\"Product not found\")\n    return db_product\n```\n\n## Arquivo `main.py`\n\nO arquivo `main.py` é responsável por definir a aplicação do FastAPI, e também por definir o servidor web Uvicorn. É aqui que definimos o servidor web, e também as configurações do servidor web, como o host e a porta.\n\n\n## Nosso Frontend\n\nNosso frontend vai ser uma aplicação que vai consumir a nossa API, e vai ser responsável por fazer o cadastro, alteração e remoção de produtos. Vamos detalhar cada uma das pastas e arquivos do nosso frontend.\n\n### Streamlit\n\nO Streamlit é uma biblioteca para construir aplicações web com Python. Ele é muito utilizado para construir dashboards, e também para construir aplicações que consomem APIs.\n\n### Requests\n\nO Requests é uma biblioteca para fazer requisições HTTP com Python. Ele é muito utilizado para consumir APIs, e também para fazer web scraping.\n\n### Pandas\n\nO Pandas é uma biblioteca para manipulação de dados com Python. Ele é muito utilizado para fazer análise de dados, e também para construir dashboards.\n\n## **Melhorias Futuras no Projeto**\n- Construção de Dashboard Streamlit com os principais KPIs\n- Deploy do Projeto AWS\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftsffarias%2Fcrud-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftsffarias%2Fcrud-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftsffarias%2Fcrud-api/lists"}