Schema Introspection: Stop Hand-Typing Your Database Structure

Automatic schema introspection means your BI tool reads the structure of your database, the tables, columns, and types, directly from the source instead of making you transcribe all of it by hand. Hand-maintained schema is slow to write, easy to get wrong, and stale almost immediately, because the database keeps changing and the config does not. Introspection removes that toil and keeps your models honest about what the data actually contains.

Let me make the case for why hand-typing database structure is the most thankless part of BI setup, what introspection actually reads, and how it changes both onboarding and the day-to-day job of keeping models in sync.

The most boring part of BI setup

Every BI project starts the same way: you connect to a database, and then you tell the tool what is in it. In a lot of tools, "tell the tool what is in it" means typing. You name the table. You list its columns. You specify each column's type. You do this for the next table, and the one after that, and you do it again for the warehouse with two hundred tables that someone wants a dashboard on by Thursday.

This is pure transcription. The information already exists, perfectly, authoritatively, in the database's own catalog. You are copying it from a place that knows it into a place that does not, by hand, line by line. It is the data-tooling equivalent of re-typing a document instead of pasting it. Nobody enjoys it, nobody is good at it, and it adds zero insight. It is just the toll you pay before the actual work starts.

And it is not a one-time toll. It is rent.

Why hand-maintained schema goes stale

The deeper problem with transcribing schema is not the initial effort. It is that the moment you finish, the copy starts drifting from the original.

Databases are not static. A column gets renamed in a migration. A new table appears. A type changes from int to bigint. An engineer drops a column you were depending on. Every one of these changes happens in the database, on its own schedule, and none of them update your hand-typed config. So the config rots. It describes a database that no longer exists, and the gap grows every sprint.

The failure mode is nasty because it is silent. Your config still looks fine. It still references customer_email long after the column was renamed to email. You do not find out until a query fails in production, or worse, until a query silently returns nothing and a dashboard shows zero instead of an error. Hand-maintained schema does not fail loudly. It fails the way a stale cache fails: by confidently serving the wrong thing. The same drift dynamic that makes hand-copied metric definitions dangerous applies to schema, just one level down.

This is why "we documented the schema" is never a durable answer. Documentation that has to be manually kept in sync with a moving system will, with certainty, fall out of sync. The only documentation that stays true is documentation generated from the source.

What automatic introspection reads

Introspection flips the relationship. Instead of you describing the database to the tool, the tool asks the database to describe itself, using the catalog every relational database already maintains for its own internal use.

When you point an introspecting tool at a source, it reads the structural metadata directly:

• Tables and views that exist in the schema you have access to.
• Columns on each table, in order, with their names exactly as the database spells them today.
• Types for each column, so the tool knows what is a date, what is a number, and what is text without you asserting it.

That metadata is authoritative because it comes from the same place the query engine reads when it runs your SQL. There is no transcription step, so there is no transcription error. The tool's picture of the database is, by construction, the database's own picture of itself. You get the schema for free, and you get it correct.

Faster onboarding to a new source

The most immediate payoff is speed when you connect a new database. Connecting a source and then hand-modeling its schema can take an afternoon for a real warehouse. With introspection, connecting the source is loading the schema. You authenticate, the tool reads the catalog, and you are looking at the real tables and columns in seconds, ready to build.

This matters most exactly when the stakes are highest: the first hour with a new data source. That first hour sets whether a tool feels fast or feels like a chore, and a tool that drops you straight into the real schema feels fast. It also lowers the bar for exploration. When seeing what is in a database costs nothing, you actually look, instead of building only against the handful of tables you already happened to know about. Introspection makes the whole warehouse legible, not just the corner you started in.

It pairs naturally with a notebook-style explorer: introspect to see what exists, query to understand it, then promote what you learned into a model. We touched on that on-ramp in the v1.0.76 recap, and introspection is the piece that makes the first step instant.

Keeping models in sync as schemas change

Onboarding speed is the obvious win. The durable win is staying correct over time.

Because introspection reads the live database, it is not a one-shot import you do once and forget. It is a continuously available source of truth about what the database currently contains. When a schema changes, re-introspecting surfaces the change instead of letting it hide. A renamed column, a new table, a dropped field: introspection sees the database as it is now, not as it was when someone last typed out the config.

That turns schema maintenance from a chase into a check. Instead of hoping your hand-written config still matches reality, you compare your models against what the source actually reports. The drift that used to surface as a 5pm production failure becomes something you can see and reconcile deliberately. Your data model, the metrics and relations you build on top, stays anchored to a real schema rather than a remembered one. And because your models are code in a repository, a schema change that requires a model change is a reviewable pull request, not a silent mismatch.

Introspection in Visivo

Automatic source schema introspection shipped in Visivo with the semantic-layer release. When you connect a source, Visivo can read its tables, columns, and types directly, so you do not start by transcribing the database into config. You start by building on what is actually there.

It works across the supported sources the same way the rest of the model does, whether the data lives in PostgreSQL, BigQuery, Snowflake, DuckDB, ClickHouse, or another supported source. The semantic layer sits above the source, so the schema introspection feeds straight into the models, metrics, dimensions, and relations you define on top. And it sets up the Explorer schema jobs that arrive in a later release, where introspected structure becomes part of an interactive workflow rather than a setup step.

If you want to feel the difference between connecting a database and hand-modeling one, /get-started takes you from install to a connected, introspected source in a few minutes, the examples gallery shows what gets built on top, and the full source and modeling reference lives in the Visivo documentation.

The structure of your database already exists, written down perfectly, inside the database. Stop re-typing it. Let the tool read it.

Previously in Visivo

This continues the thread from relations: why joins belong in your data model, not every query, which covers another piece of the same semantic-layer release. For the release itself, see Visivo v1.0.76-78: the semantic layer lands.