Find First Row
db_find_firstRetrieves a single database row matching a JSON filter. Returns the first match as an object, or null when none exists, making single-row lookups clear.
Instructions
Finds a single row matching the given filter. Returns the first matching row or null if no rows match. Use this instead of db_find_many when you expect exactly one result and want a single object rather than an array. Sensitive columns are automatically redacted.
When to use:
"Get user with ID 42", "Find the order with this tracking number"
Lookups by unique identifier (primary key or unique constraint)
When you need exactly one row, not a list
Parameter guidance:
where: JSON filter object (required). Must be specific enough to target one row. Example: {"id": 42} or {"email": "user@example.com"}
select: optional JSON array of column names to return
Behavioral notes:
Returns a single JSON object, not an array.
Returns null (not an error) when no row matches the filter.
For queries that should return multiple rows, use db_find_many instead.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| table | Yes | Name of the table to query | |
| where | Yes | JSON filter object to find a single row | |
| select | No | ||
| database | No | Name of the database to query (from pgautopilot.json). Omit to use the current default database. |