Passo a passo

Banco de dados

O projeto requer um banco de dados PostgreSQL, MongoDB ou Badger e os comandos que requerem banco de dados aceitam --database-uri (ou -u) como argumento com a URI de acesso ao banco de dados (o padrão é o valor da variável de ambiente DATABASE_URL).

Caso deseje usar o compose.yml do projeto para subir uma instância do banco de dados para desenvolvimento:

$ docker compose up -d postgres
$ docker compose up -d mongo

Usando PostgreSQL, a URI será postgres://minhareceita:minhareceita@localhost:5432/minhareceita?sslmode=disable.

Usando MongoDB, a URI será mongodb://minhareceita:minhareceita@localhost:27017/minhareceita?authSource=admin.

Usando Badger, a URI será o caminho para o diretório que armazenará o banco de dados, por exemplo /mnt/data/badger/.

Dados

Os dados são disponibilizados mensalmente pela Receita Federal. O comando download baixa os arquivos diretamente da Receita Federal, mais um arquivo do Tesouro Nacional com o código dos municípios do IBGE.

O comando requer o mês e ano no formato YYYY-MM e pode ser utilizado com a opção --directory (ou -d) com o diretório onde serão salvos os arquivos (o padrão é data/).

Exemplos de uso

Sem container:

$ minha-receita download 2026-06
$ minha-receita download 2026-06 -d /mnt/data/

Com container:

$ docker compose run --rm minha-receita download 2026-06 --directory /mnt/data/

Tratamento dos dados

O comando transform transforma os arquivos para o formato JSON, consolidando as informações de todos os arquivos CSV. Esse JSON é armazenado diretamente no banco de dados. Para tanto, é preciso criar a tabela no banco de dados com o comando create (o comando drop pode ser utilizado para excluir essa mesma tabela).

Esse comando também cria um arquivo graph.tar.gz (por padrão em data/). Esse arquivo é utilizado para a API de grafos.

Para especificar onde ficam os arquivos originais da Receita Federal e do Tesouro Nacional, o comando aceita como argumento --directory (ou -d), sendo o padrão data/.

Importante

Não existe “atualizar” o banco de dados. O processo de upsert mais o gerenciamento de registros ausentes nos novos lotes faria o comando transform extremamente lento. Como a ideia é reproduzir o estado atual dos dados oficiais divulgados pela Receita Federal, o recomendado é subir um novo banco de dados, apontar a API web para o novo banco de dados, e depois excluir o banco de dados antigo.

Exemplos de uso

Sem container, com a variável de ambiente DATABASE_URL configurada:

$ minha-receita drop  # caso necessário
$ minha-receita create
$ minha-receita transform

Com container:

$ docker compose run --rm minha-receita drop  # caso necessário
$ docker compose run --rm minha-receita create
$ docker compose run --rm minha-receita transform -d /mnt/data/

Questões de privacidade

Assim como o socios-brasil removemos alguns dados para evitar exposição de dados sensíveis de pessoas físicas, bem como SPAM. A opção --no-privacy do comando transform remove essa precaução de privacidade.

Iniciando a API web

A API web é uma aplicação super simples que, por padrão, ficará disponível em localhost:8000 se:

a variável DATABASE_URL estiver configurada
a variável GRAPH_DB_URL não estiver configurada

Exemplos de uso

Sem container, com a variável de ambiente DATABASE_URL configurada:

$ minha-receita api

Com container:

$ docker compose up

Iniciando a API de grafos

O mesmo comando minha-receita api pode iniciar a API de grafos se:

a variável DATABASE_URL não estiver configurada
a variável GRAPH_DB_URL estiver configurada

A variável GRAPH_DB_URL deve apontar para uma URL onde o servidor possa acessar o graph.tar.gz gerado anteriormente. A URL mantida pelo projeto publicamente para isso é https://bucket.minhareceita.org/graph.tar.gz.

Se o banco de dados do grafo (descompactado) já estiver presente em GRAPH_PATH, ele não será baixado novamente.