AI Designing Databases Directly? First Have It Explain Refunds and Duplicate Callbacks

Database table design goes wrong, and you only find out after launch that it cannot be changed. This kind of problem is even more common when AI writes code. The model is quick to add primary and foreign keys, but once it hits real queries, tenant isolation, and online migrations, the problems show up.

This tweet mentions a dedicated Agent for Claude Code: Database Architect. The project page gives it a very firm positioning: it should be used for any database schema work, including small changes and urgent requests. It defaults to PostgreSQL, and it first reads the existing migration directory, ORM schema, naming, and ID strategy before designing tables, indexes, constraints, and migrations.

Install command:

npx claude-code-templates@latest --agent database/database-architect

The project page shows 12,527 downloads and a single file of 12.9 KB. What it can do includes: data modeling—table structures, primary and foreign keys, indexes, and constraints; technology selection—PostgreSQL, MySQL, MongoDB, and vector databases; multi-tenant design—RLS, schema isolation, and separate databases; performance planning—read/write patterns, sharding/partitioning, and scaling plans; data migration—generating migration scripts and rollback plans.

Generating SQL is only one step. A more practical way to use it is to have it first analyze business access patterns, then design the table structure. In the comments, a developer mentioned that when AI generates table structures, it often focuses on primary and foreign keys and ignores WHERE, JOIN, ORDER BY, and execution plans, and that building too many indexes also slows down writes. Others suggest not starting with “help me design a database,” but first giving it a business flow: after an order is placed and then refunded, duplicate payment callbacks, a product being deleted—what should happen to the data in each case? If the Agent cannot explain these exception flows clearly, a complete ER diagram is useless.

Multi-tenancy is another place where it is easy to plant hidden risks. One commenter asked whether SaaS should choose tenant-level schemas or row-level tenant_id. The discussion leaned toward using tenant_id plus RLS in the early stage: development and migration costs are lower, and unified maintenance is easier. But the premise is that all queries must be constrained by tenant isolation and cannot rely only on application-layer filtering. Only when the number of tenants is small and isolation requirements are high should separate schemas be considered. What really causes trouble is cross-tenant data leakage and later migrations. The Agent’s rules also state: add tenant_id to every tenant table, use composite foreign keys to prevent cross-tenant references, enable RLS with FORCE, and the application role must not have BYPASSRLS. These details are more useful than the words “supports multi-tenancy.”

For databases that already contain real data, changing field types, splitting tables, and adding constraints can all affect online business. Migration scripts are not just about whether the SQL is correct; you also need to look at table lock duration, data compatibility, and rollback plans. It is best to run them once against a test database at production data scale. The rules on the project page mention that online changes should set lock_timeout, use CREATE INDEX CONCURRENTLY, first add constraints as NOT VALID and then VALIDATE them, use expand/contract for renames, and run migration tests on a real Postgres. Generated DDL and migration scripts still need human review, especially for data changes in production.

Also, do not let the Agent guess when to shard tables. In the comments, someone said that sharding cannot be based only on data volume; it must also combine query patterns, growth speed, index size, and actual performance bottlenecks, and be verified with real business data and execution plans.

A more stable process is: first define the core entities, business relationships, and data constraints, then let the Agent add index suggestions, DDL, and migration scripts. You can have it draw an ER diagram first, but do not rush to create tables. Explain the core business flows and exception scenarios clearly, then check indexes and constraints against actual queries and expected data growth, and generate DDL only after confirmation. When it comes to table structures, the time saved early on is easily paid back double later.

Now, when you use AI to develop projects, do you let it design the database directly, or do you define the table structure yourself first?