# Quick Start Guide - PG-API
> Guia passo a passo para começar a usar o PG-API em 5 minutos.
---
## 📋 Pré-requisitos
- [Rust](https://rustup.rs/) (1.70 ou superior)
- [PostgreSQL](https://www.postgresql.org/download/) (12 ou superior)
- cURL (para testes)
---
## 🚀 Instalação
### 1. Clone o Repositório
```bash
git clone https://gitlab.com/aerunti/pg-api.git
cd pg-api
```
### 2. Compile o Projeto
```bash
# Build de desenvolvimento
cargo build
# Ou build otimizado para produção
cargo build --release
```
---
## ⚙️ Configuração Inicial
### 1. Configure o Servidor
Crie o arquivo `config/server.json`:
```bash
mkdir -p config
cat > config/server.json << 'EOF'
{
"host": "127.0.0.1",
"port": 8580,
"log_level": "info"
}
EOF
```
### 2. Configure as Contas
Crie o arquivo `config/accounts.json` com suas credenciais PostgreSQL:
```bash
cat > config/accounts.json << 'EOF'
{
"accounts": [
{
"id": "acc_001",
"name": "Development Account",
"api_keys": ["sk_dev_123456789"],
"role": "owner",
"rate_limit": 1000,
"max_connections": 10,
"databases": [
{
"database": "postgres",
"username": "postgres",
"password": "sua_senha_aqui",
"permissions": ["SELECT", "INSERT", "UPDATE", "DELETE", "CREATE"]
}
]
}
]
}
EOF
```
> ⚠️ **Importante:** Altere `sua_senha_aqui` para a senha real do seu PostgreSQL.
---
## ▶️ Executando o Servidor
### Modo Desenvolvimento
```bash
cargo run
```
Você verá algo como:
```
2025-02-16T14:30:00.000Z INFO pg_api: pg-api running on 127.0.0.1:8580
2025-02-16T14:30:00.000Z INFO pg_api: Documentation available at http://127.0.0.1:8580/docs
```
### Modo Produção
```bash
./target/release/pg-api
```
---
## 🧪 Primeira Requisição
### 1. Health Check
Verifique se o servidor está rodando:
```bash
curl http://localhost:8580/health
```
Resposta esperada:
```json
{
"status": "healthy",
"service": "pg-api",
"version": "0.1.1"
}
```
### 2. Informações da Conta
```bash
curl http://localhost:8580/v1/account \
-H "X-API-Key: sk_dev_123456789"
```
### 3. Executar uma Query
```bash
curl -X POST http://localhost:8580/v1/query \
-H "X-API-Key: sk_dev_123456789" \
-H "Content-Type: application/json" \
-d '{
"database": "postgres",
"query": "SELECT version()"
}'
```
Resposta esperada:
```json
{
"success": true,
"data": {
"rows": [
{"version": "PostgreSQL 15.2 on x86_64-pc-linux-gnu..."}
],
"columns": ["version"],
"row_count": 1
},
"error": null,
"metadata": {
"request_id": "...",
"execution_time_ms": 5,
"rows_affected": 1,
"instance_id": "acc_001",
"timestamp": "2025-02-16T14:30:00Z"
}
}
```
---
## 📝 Exemplos Práticos
### Criar uma Tabela
```bash
curl -X POST http://localhost:8580/v1/query \
-H "X-API-Key: sk_dev_123456789" \
-H "Content-Type: application/json" \
-d '{
"database": "postgres",
"query": "CREATE TABLE IF NOT EXISTS users (id SERIAL PRIMARY KEY, name VARCHAR(100), email VARCHAR(100))"
}'
```
### Inserir Dados
```bash
curl -X POST http://localhost:8580/v1/query \
-H "X-API-Key: sk_dev_123456789" \
-H "Content-Type: application/json" \
-d '{
"database": "postgres",
"query": "INSERT INTO users (name, email) VALUES ($1, $2) RETURNING *",
"params": ["John Doe", "john@example.com"]
}'
```
### Consultar Dados
```bash
curl -X POST http://localhost:8580/v1/query \
-H "X-API-Key: sk_dev_123456789" \
-H "Content-Type: application/json" \
-d '{
"database": "postgres",
"query": "SELECT * FROM users WHERE id = $1",
"params": [1]
}'
```
### Batch de Queries
```bash
curl -X POST http://localhost:8580/v1/batch \
-H "X-API-Key: sk_dev_123456789" \
-H "Content-Type: application/json" \
-d '[
{
"database": "postgres",
"query": "INSERT INTO users (name, email) VALUES ($1, $2)",
"params": ["Alice", "alice@example.com"]
},
{
"database": "postgres",
"query": "INSERT INTO users (name, email) VALUES ($1, $2)",
"params": ["Bob", "bob@example.com"]
}
]'
```
### Transação
```bash
curl -X POST http://localhost:8580/v1/transaction \
-H "X-API-Key: sk_dev_123456789" \
-H "Content-Type: application/json" \
-d '{
"database": "postgres",
"queries": [
{
"query": "UPDATE users SET name = $1 WHERE id = $2",
"params": ["Jane Doe", 1]
},
{
"query": "INSERT INTO logs (action) VALUES ($1)",
"params": ["user_updated"]
}
]
}'
```
---
## 🔍 Explorando a API
### Documentação Interativa
Abra no navegador:
```
http://localhost:8580/docs
```
### Especificação OpenAPI
```bash
### Listar Databases
```bash
curl http://localhost:8580/v1/databases \
-H "X-API-Key: sk_dev_123456789"
```
### Ver Schema
```bash
curl http://localhost:8580/v1/databases/postgres/schema \
-H "X-API-Key: sk_dev_123456789"
```
---
## 🛑 Parando o Servidor
Pressione `Ctrl+C` no terminal onde o servidor está rodando.
---
## 🐛 Troubleshooting
### Erro: "Connection refused"
**Problema:** O servidor não está rodando.
**Solução:** Execute `cargo run` e verifique se não há erros.
### Erro: "UNAUTHORIZED"
**Problema:** API key inválida ou ausente.
**Solução:** Verifique se o header `X-API-Key` está correto e corresponde ao configurado em `accounts.json`.
### Erro: "CONNECTION_ERROR"
**Problema:** Não foi possível conectar ao PostgreSQL.
**Solução:**
- Verifique se o PostgreSQL está rodando: `sudo systemctl status postgresql`
- Verifique as credenciais em `accounts.json`
- Teste a conexão manualmente: `psql -U postgres -h localhost`
### Erro: "PERMISSION_DENIED"
**Problema:** A conta não tem permissão para a operação.
**Solução:** Adicione a permissão necessária no array `permissions` em `accounts.json`.
### Erro de compilação
**Problema:** Dependências desatualizadas ou Rust desatualizado.
**Solução:**
```bash
rustup update
cargo clean
cargo build
```
---
## 📚 Próximos Passos
- Leia a [API Reference](API.md) completa
- Explore os [exemplos](../examples/)
- Configure [observabilidade](OBSERVABILITY.md)
- Veja o [Changelog](../CHANGELOG.md)
---
## 💡 Dicas
### Usando jq para formatar JSON
```bash
curl http://localhost:8580/v1/account \
### Salvando a resposta em arquivo
```bash
curl -X POST http://localhost:8580/v1/query \
-H "X-API-Key: sk_dev_123456789" \
-H "Content-Type: application/json" \
-d '{"database": "postgres", "query": "SELECT * FROM users"}' \
| jq > resultado.json
```
### Variáveis de ambiente úteis
```bash
# Modo debug
export RUST_LOG=debug
cargo run
# Porta diferente
export APP__ADDR=127.0.0.1:8080
cargo run
```
---
🎉 **Pronto!** Você está pronto para usar o PG-API!