Stop pasting your database into the prompt

If you want an AI tool to answer a question about your database, exporting the whole table into the prompt is an expensive place to start. The database can filter, count, join, and aggregate. Let it do that work, then give the model the result it needs to explain.

Matthew Brown illustrates the difference in Build a “Chat With Your Data” AI Agent in Python + Claude. His demo compares sending a dataset, sending its schema, and adding sample rows. The useful twist is that schema alone still produces a plausible wrong answer: a column name suggests yes/no values, while the stored values use true/false. At 4:05, he investigates the mismatch; a small sample gives the model missing context.

That is the inspiration for the independent Postgres example below. It is not a reproduction of Brown’s energy-data demo or a claim of endorsement. His data-loading step is also separate from Bufflehead’s role: reading data that already exists.

The useful context is not necessarily more rows

For a database question, three kinds of context usually matter:

• Structure: the relevant tables, columns, types, and relationships.
• Meaning: what stored values represent and how the business defines the metric.
• Evidence: the query and result that support the answer.

A table export mixes those together without necessarily explaining any of them. Ten thousand order rows will not tell the model whether “revenue” means cash collected, invoiced sales, or recognized revenue. A short definition and a focused query can be more useful.

A concrete question against existing Postgres data

Suppose an existing public.orders table has one row per order, with id, ordered_at, status, currency, and net_amount. The timestamps use Postgres timestamp with time zone, and amounts use numeric. This is a hypothetical schema, not customer data.

The question is: “What was our USD order revenue in August 2026?” For this example, the business definition is the sum of net_amount for paid orders placed during August, using UTC calendar boundaries. The amount is after discounts and excludes tax and shipping; refunded orders are excluded entirely. This is an order metric, not an accounting revenue-recognition policy.

Connect Bufflehead to the existing Postgres database with appropriately scoped credentials. The queries below can be reviewed in its SQL editor; an AI tool using Bufflehead’s SQL access can follow the same sequence. Bufflehead supplies the read-only connection, while the AI tool and the person reviewing it supply the reasoning.

1. Inspect only the relevant schema

SELECT column_name, data_type, is_nullable
FROM information_schema.columns
WHERE table_schema = 'public'
  AND table_name = 'orders'
ORDER BY ordinal_position;

Check that the types match the question before generating the final SQL. In a real schema, confirm the table’s grain as well: summing an order total after joining to multiple line items can count the same money more than once.

2. Inspect a small, relevant sample

SELECT status, currency, net_amount
FROM public.orders
WHERE ordered_at >= TIMESTAMPTZ '2026-08-01 00:00:00+00'
  AND ordered_at < TIMESTAMPTZ '2026-09-01 00:00:00+00'
ORDER BY ordered_at, id
LIMIT 5;

This deliberately leaves out names, email addresses, and other fields the question does not need. Suppose the sample contains statuses P and C, not the word paid. A filter such as status = 'paid' could run successfully and return no matching orders.

Do not turn the sample into another guess. Confirm the application’s documented mapping: in this example, P means paid, C means cancelled, R means refunded, and N means pending. Five rows may not include every status. A targeted count helps check what is present in the reporting period:

SELECT status, currency, COUNT(*) AS order_count
FROM public.orders
WHERE ordered_at >= TIMESTAMPTZ '2026-08-01 00:00:00+00'
  AND ordered_at < TIMESTAMPTZ '2026-09-01 00:00:00+00'
GROUP BY status, currency
ORDER BY status, currency;

This reveals values; it does not define them. Unexpected codes still need an explanation from the data owner or documentation.

3. Ask the database for the aggregate

SELECT
  COUNT(*) AS paid_orders,
  COUNT(net_amount) AS orders_with_amount,
  SUM(net_amount) AS usd_order_revenue
FROM public.orders
WHERE status = 'P'
  AND currency = 'USD'
  AND ordered_at >= TIMESTAMPTZ '2026-08-01 00:00:00+00'
  AND ordered_at < TIMESTAMPTZ '2026-09-01 00:00:00+00';

Now the model receives one result row instead of the order history. The two counts also expose missing amounts: if they differ, the sum is incomplete and should not be presented as a complete total. If there are no matching orders, SUM returns NULL; distinguish that from a measured zero before interpreting the result.

The answer should include the total, order count, currency, date boundaries, and paid-order definition, with the SQL available for inspection. For a business-critical report, reconcile it against a trusted report using the same definitions and data snapshot.

Read-only access and correct answers are different jobs

Bufflehead is read-only by design, but that does not make an ambiguous metric unambiguous. It does not automatically infer status mappings, validate business definitions, or guarantee the model’s answer. The example also does not require Bufflehead to create tables or manage an agent’s context database.

Keep the database credential scoped to the data the task needs. Read-only access still exposes whatever the credential can read, and a query returning one row can still scan a large table. Query results supplied to a hosted AI service are also data sent to that service; a local database connection does not change that.

The practical loop is simple: inspect the schema, check relevant values, confirm their meaning, run focused SQL, and inspect the result. Small samples help discover mistakes. Explicit definitions and verification keep those samples from becoming false confidence.

You do not need to paste your database into a prompt to give an AI useful context. Give it a way to ask a precise question of the data—and enough context to know which question it is actually answering.

Download Bufflehead to explore an existing database, or read about the connection-architecture tradeoffs for Claude and SQL databases.