---
title: blossom database:query
url: "/docs/reference/cli/database/query/"
canonical_url: https://docs.blossom88.com/docs/reference/cli/database/query/
markdown_url: https://docs.blossom88.com/docs/reference/cli/database/query.md
summary: Run bounded read-only PostgreSQL queries
categories:
- cli
- reference
---

# blossom database:query

Run bounded read-only PostgreSQL queries

## Usage

    blossom database:query --database DATABASE --request_key REQUEST_KEY [--sql SQL] [--data DATA] [--timeout_seconds TIMEOUT_SECONDS] [--max_rows MAX_ROWS] [--follow]

## Flags

| Flag | Description |
| --- | --- |
| `--database (required)` | Exact Database id, not Database instance id |
| `--request_key (required)` | Unique request identity (16–100 letters, digits, underscores or hyphens); reuse after transport failure |
| `--sql` | One SQL statement; alternative to --data |
| `--data, -d` | YAML or JSON data, a path to a data file, or an HTTP(S) URL |
| `--timeout_seconds` | Transaction deadline, 1–30 seconds. Default: 10. |
| `--max_rows` | Returned rows across all statements, 1–1000. Default: 100. |
| `--follow, -f` | Wait for the SQL Run and show its results |

SQL runs on the private primary as the Database's application role. Query needs
database_sql:read; execute needs database_sql:write. General Read only access
does not grant access to application records. Results expire after one hour.

    blossom database:query --database database-100 --request_key inspect_contacts_01 --sql 'SELECT * FROM public.test_contacts' --follow

For several statements, use --data with an sql.statements array. Each array entry
must be exactly one SQL statement. No psql commands, COPY or transaction control.
INSERT and CREATE TABLE/INDEX need no extra confirmation. Other supported changes
need --yes after reviewing their effect on the exact Database and its consumers.

Reuse request_key with the identical request after connection loss. Inspect the
SQL Run with database:sql:show. An unknown write outcome must never be retried
automatically under a new key. Values are returned as PostgreSQL text or null.