Skip to content

AGENTS.md

Latest commit

 

History

History
89 lines (61 loc) · 3.61 KB

AGENTS.md

File metadata and controls

89 lines (61 loc) · 3.61 KB
Raw

Repository Guidelines

Contexto do Projeto

Este repositorio apoia um curso feito originalmente em Windows. O objetivo final nao e produzir uma aplicacao, mas aprender e reproduzir localmente o uso de Oracle, MySQL, ODI, SQL Developer, DBeaver e ferramentas relacionadas em um ambiente Ubuntu.

Ao adaptar instrucoes do curso, sempre documente a equivalencia entre o que o instrutor faz no Windows e como isso fica neste setup.

Estrutura do Projeto

  • compose/oracle.yml: Oracle XE 18c em Docker.
  • compose/mysql.yml: MySQL 8 em Docker.
  • mysql/migrations/: migrations Flyway do MySQL. V1__sakila_base.sql e a baseline Sakila 1.5 incorporada em 2026-05-21.
  • scripts/: helpers para carregar env vars e executar Docker Compose.
  • docs/: documentacao ativa do ambiente do curso, conexoes e compatibilidade.
  • .env.development: valores padrao versionados.
  • .env.local: overrides locais ignorados pelo Git.

Documentacao Ativa

Mantenha estes arquivos atualizados quando o setup mudar:

  • README.md: comandos principais e visao rapida.
  • docs/course-environment.md: mapa curso Windows versus setup Ubuntu.
  • docs/connections.md: credenciais, portas, services e como conectar.
  • docs/odi-versioning.md: onde o ODI salva estado e como versionar exports.
  • docs/mysql-odbc-ubuntu.md: notas sobre MySQL Connector/ODBC no Ubuntu.

Ao adicionar uma nova ferramenta do curso, registre:

  • nome usado no curso;
  • equivalente neste ambiente;
  • onde executar, host ou VM;
  • configuracoes de conexao;
  • limitacoes ou diferencas importantes.

Quando uma senha ou credencial operacional for descoberta durante o curso, registre em docs/connections.md com o contexto correto. Diferencie senha de wallet, senha de banco e senha de usuario interno do ODI.

Quando objetos ODI forem criados no curso, mantenha exports XML/Smart Export em odi/exports/ apenas como backup local. Essa pasta e ignorada pelo Git; documente o processo, nao o estado exportado. Nao trate a VM, wallet local ou dumps binarios como fonte principal de versionamento.

Comandos

  • npm install: instala dependencias locais.
  • npm run oracle:up: inicia Oracle XE.
  • npm run oracle:connect: conecta no Oracle usando ORACLE_CONNECT_*.
  • npm run oracle:down: para Oracle.
  • npm run mysql:up: inicia MySQL.
  • npm run mysql:connect: conecta como usuario app.
  • npm run mysql:connect:root: conecta como root.
  • npm run mysql:migrate: aplica migrations Flyway.
  • npm run mysql:migrate:info: mostra estado das migrations.
  • npm run odi:exports:sync: copia exports ODI da VM para odi/exports/.

Variaveis de Ambiente

Scripts devem carregar .env.local quando existir e permitir que ele sobrescreva .env.development.

Use:

  • scripts/with-env.sh para comandos que precisam de env vars.
  • scripts/compose.sh para comandos Docker Compose.

Nao duplique a logica de leitura de .env.local diretamente no package.json.

Padroes de Edicao

Use YAML, JSON, Shell e Markdown simples. Preserve indentacao de 2 espacos em JSON/YAML. Para novas migrations MySQL, siga o padrao Flyway:

V2__descricao_da_mudanca.sql

Depois que uma migration for aplicada, trate o arquivo como append-only: crie uma nova migration para mudancas futuras.

Validacao

Nao ha testes automatizados. Valide mudancas com comandos praticos:

  • node -e "JSON.parse(require('fs').readFileSync('package.json', 'utf8'))"
  • scripts/compose.sh compose/oracle.yml config
  • scripts/compose.sh compose/mysql.yml config
  • npm run mysql:migrate:info
  • npm run oracle:connect

Quando alterar conexoes, confirme no banco:

SELECT sys_context('USERENV', 'CON_NAME') FROM dual;