Skip to main content

Working with Issues

Issues are the core of Postgres copilot. When Postgres copilot detects a problem with your Postgres database, it creates an Issue with a specific, actionable recommendation.

What is an Issue?​

An Issue is not just an alert — it's a complete diagnosis with a solution. Each Issue contains:

  • Title: Clear description of the problem
  • Severity: Critical, High, Medium, or Low
  • Area: Which monitoring area detected it (e.g., Query Performance, Indexing, Configuration)
  • Recommendation: Specific fix (SQL command, config change, etc.)
  • Evidence: Metrics and data supporting the recommendation
  • Discussion: Comments from experts and AI analysis

Example Issue​

ISSUE: Missing index on orders.customer_id

Severity: High
Area: Indexing

PROBLEM:
Sequential scans on orders table are causing slow queries.
Query "SELECT * FROM orders WHERE customer_id = ?" averages
2.3 seconds with 50,000 calls/day.

RECOMMENDATION:
CREATE INDEX CONCURRENTLY idx_orders_customer_id
ON orders(customer_id);

EVIDENCE:
- pg_stat_user_tables shows 847,293 seq_scans on orders
- 0 index scans for queries filtering by customer_id
- Estimated improvement: 2.3s → 5ms per query

TESTED:
Index creation verified on DBLab clone.
No blocking operations detected.

Viewing Issues​

In PostgresAI Console​

  1. Go to https://console.postgres.ai
  2. Navigate to your organization
  3. Click Issues in the sidebar

Issues are organized by:

  • Status: Open, In Progress, Resolved
  • Severity: Critical issues first
  • Area: Group by monitoring area

Via API​

Issues can be accessed programmatically:

# List all issues
pai issues list

# View specific issue
pai issues view <issue-id>

# Add a comment
pai issues comment <issue-id> "Scheduled for next deployment"

Issue lifecycle​

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Created   │────▶│ In Progress │────▶│  Resolved   │
└─────────────┘     └─────────────┘     └─────────────┘
       │                   │
       │                   ▼
       │            ┌─────────────┐
       └───────────▶│   Ignored   │
                    └─────────────┘
  1. Created: Copilot detected an issue and generated a recommendation
  2. In Progress: Someone is working on the fix
  3. Resolved: Fix has been applied and verified
  4. Ignored: Issue acknowledged but won't be fixed (with reason)

Turning Issues into pull requests​

Using AI coding tools​

Issues are designed to be consumed by AI coding assistants. You can:

  1. Copy the Issue details into Cursor, GitHub Copilot, or similar tools
  2. Ask the AI to generate the migration/PR
  3. Review and submit

Example workflow with Cursor​

Prompt: "Create a database migration for this PostgresAI Issue:
[paste Issue details]
Use our standard migration format with up/down methods."

The AI generates:

# db/migrate/20241201_add_index_orders_customer_id.rb
class AddIndexOrdersCustomerId < ActiveRecord::Migration[7.0]
  disable_ddl_transaction!

  def change
    add_index :orders, :customer_id,
              algorithm: :concurrently,
              if_not_exists: true
  end
end

MCP Integration (coming soon)​

PostgresAI provides an MCP server that AI tools can connect to directly, allowing them to:

  • List open Issues
  • Read Issue details
  • Post comments and status updates

Prioritizing Issues​

Not all Issues need immediate attention. Consider:

Severity levels​

SeverityResponse timeExamples
CriticalImmediateDisk nearly full, wraparound risk
HighThis weekMissing indexes causing slow queries
MediumThis monthSuboptimal configuration
LowWhen convenientMinor optimizations

Impact assessment​

Each Issue includes:

  • Affected queries: How many queries are impacted
  • Performance impact: Estimated improvement
  • Risk level: How safe is the recommended fix

Resolving Issues​

When you've applied a fix:

  1. Update the Issue status to "In Progress"
  2. Add a comment with the PR/commit link
  3. After deployment, verify the fix worked
  4. Mark as "Resolved"

Postgres copilot will verify the resolution by checking if:

  • The recommended change was applied
  • The problem metrics improved

Ignoring Issues​

Some Issues may not apply to your situation. You can ignore an Issue with a reason:

  • Won't fix: Accepted behavior for your use case
  • False positive: Issue detection was incorrect
  • Deferred: Will address later

Ignored Issues can be reopened if circumstances change.

Issue comments and discussion​

Issues support threaded comments for:

  • Asking clarifying questions
  • Discussing alternative solutions
  • Documenting decisions

Both humans and AI can participate in Issue discussions.

Best practices​

  1. Review Issues weekly: Don't let the backlog grow
  2. Start with High severity: Get the biggest wins first
  3. Test before deploying: Use DBLab to validate changes
  4. Document decisions: Add comments explaining your choices
  5. Track resolution: Close Issues when fixes are verified

Next steps​