What is a database schema? (the floor plan of your data)

What it actually is

A database schema is the floor plan of your data: which tables exist, what columns live in each one, what type of value each column accepts, and how tables connect to each other. It gets agreed on before a single real row moves in, the same way a floor plan fixes where the walls and doors go before any furniture arrives.

Take a blog. A schema might say: a posts table with columns id (a number), title (text), body (text), and author_id (a number pointing at a row in the users table). That last part is a relationship: a foreign key linking one table to another, so the database knows “this post belongs to that person” without copying the author’s whole profile into every single post.

Nothing in that description is actual data yet. No real blog post, no real author. The schema is the shape; the rows you insert afterward are what fills it.

Why your AI just did this

Before writing code that touches real data, a careful agent proposes the schema first, in plain English or as a migration file, and waits for you to look at it. The reason: changing a schema after an app is live and full of real user rows is a much bigger job than changing it on a blank project. Renaming a column, or realizing author_id should have pointed at a teams table instead of users, means a migration that has to carry existing rows along with it, not just editing a line of code and refreshing the page.

So your agent shows you the plan for the same reason a contractor shows you a floor plan before pouring concrete: cheap to change a wall on paper, expensive once it’s built. If it’s using an ORM like Prisma or Drizzle, you’ll often see this as a schema.prisma file or equivalent, one plain-text file meant to be the single source of truth, that your agent edits and then turns into a migration that runs against the database.

When you’ll run into it

• Your agent describes it in words first: “I’ll create a users table with id, email, created_at, and a posts table with author_id referencing it.” That’s the schema, before any migration runs.
• A schema.prisma, schema.sql, or similar file shows up in your project, meant to be the one place your table structure is defined.
• Supabase Studio’s table editor or schema diagram view, showing your tables and how they connect, no SQL required to read it.
• An error like relation "posts" does not exist or column "author_id" does not exist. Usually means the code expects a schema that hasn’t been migrated yet, or was migrated under a different name.
• Confusion with “endpoint”: a schema is the shape of your data; an endpoint is the URL your app calls to reach it. Related, easy to blur together, not the same thing.

What to check

• Ask your agent to show you the schema in plain English before it runs a migration against a table that already holds real rows
• Open your provider’s table view (Supabase’s table editor, or \d tablename in psql) and confirm the actual schema matches what you asked for
• Check that relationships have a real foreign key, not just a column that happens to hold a matching ID. A real foreign key stops you from inserting an order for a user that doesn’t exist
• If you’re using an ORM, confirm the schema file and the live database agree. Hand-editing a table in a dashboard without updating the schema file is exactly how the two drift apart
• Notice which “schema” is being discussed: the table structure, or, in Postgres specifically, the public namespace grouping your tables. Same word, two meanings

Say it like a dev

Instead of: “just set up the database” Say: “show me the schema before you run the migration”

Instead of: “why isn’t my data showing up right” Say: “does the table’s actual schema match what the app is trying to read or write?”

Instead of: “add a new field to that thing” Say: “add a column to the schema and generate a migration for it”