Sessions

Create and manage database sessions with staged writes.

Create session

Start a new session to begin staging database changes.

terminal

POST /sessions

{
  "project_id": "my-project"
}

# Response
{
  "id": "sess_abc123",
  "project_id": "my-project",
  "status": "active",
  "created_at": "2024-01-15T10:30:00Z"
}

Connect via PostgreSQL

Pass the session ID via psql options. Use any standard PostgreSQL driver.

terminal

# Using psql
psql -h localhost -p 5433 -c "astapa_session=sess_abc123" mydb

# Using connection string
postgresql://user:pass@localhost:5433/mydb?options=-c%20astapa_session%3Dsess_abc123

# Reads go to production, writes are staged in the session

Get session

Retrieve session details and current status.

terminal

GET /sessions/sess_abc123

# Response
{
  "id": "sess_abc123",
  "project_id": "my-project",
  "status": "active",       # active, proposed, approved, rejected
  "mutation_count": 3,
  "created_at": "2024-01-15T10:30:00Z"
}

Destroy session

Delete a session and discard all staged changes.

terminal

DELETE /sessions/sess_abc123

# Response: 204 No Content

Session lifecycle

terminal

# 1. Create session
curl -X POST http://localhost:8080/sessions \
  -H "Content-Type: application/json" \
  -d '{"project_id": "my-project"}'

# 2. Execute queries through proxy (writes are staged)
psql -h localhost -p 5433 -c "astapa_session=sess_abc123" mydb \
  -c "UPDATE users SET role = 'admin' WHERE id = 5"

# 3. Review changes
curl http://localhost:8080/sessions/sess_abc123/diff

# 4. Submit for review
curl -X POST http://localhost:8080/sessions/sess_abc123/propose

# 5. Approve (apply to production) or reject (discard)
curl -X POST http://localhost:8080/sessions/sess_abc123/approve