Database Setup

To ensure accurate SQL generation and smooth query execution, your connected PostgreSQL database should follow some simple conventions. These practices make it easier for Billx-Agent’s AI to understand your schema and return the right results.

---

✅ DO

✔️ Use Descriptive Table & Column Names

Choose meaningful, self-explanatory names:

Good: orders, total_amount, signup_date Avoid: tbl1, xcol, data_1

This improves prompt-to-schema matching by the LLM.

---

✔️ Keep Names Lowercase and Underscored

Use lowercase names with underscores instead of spaces or CamelCase:

order_items, not OrderItems or Order Items

This aligns with PostgreSQL conventions and reduces token confusion.

---

✔️ Normalize When It Helps

Keep commonly queried entities in separate, well-linked tables:

• users, orders, products, transactions

This helps the AI produce accurate joins.

---

✔️ Maintain Clean Schemas

Remove unused tables, test columns, or temporary data. AI models may get distracted by irrelevant schema elements.

---

✔️ Use Consistent Data Types

Stick to predictable and typed columns:

Field	Recommended Type
amount	NUMERIC
created_at	TIMESTAMP
email	TEXT or VARCHAR
is_active	BOOLEAN

---

❌ AVOID

❌ Inconsistent Naming

Don't mix naming styles across the schema:

❌ UserTable, user_id, UserStatus, userStatus

Instead, stick to one style:

✅ users, user_id, user_status

---

❌ Exposing Sensitive Data

Never expose tables with passwords, tokens, PII, or billing info unless specifically filtered.

If your schema includes users with password_hash, ensure it's excluded from queries.

---

❌ Using Views Instead of Tables (unless necessary)

Views can obscure complexity and mislead the AI. Use actual tables for primary data sources unless the view is essential and well-named.

---

🧠 Pro Tip

Before going live, connect your database and test prompts like:

“Top 5 products by revenue last month” “Orders placed by inactive users in Q1”

This will confirm that your schema is AI-friendly and ready for use.

---