Confluent Director Adi Polak posted this tweet earlier today regarding SQL and understanding the data model.

Screenshot 2025-09-22 075403

I’m in agreement with her on both things, namely

  1. SQL is not a difficult thing to learn, no matter how much FUD is out there on social media about it being “impossible” for developers to learn.
  2. Understanding a data model can be challenge.

In particular, with respect to (2), before joining Oracle I spent a couple of decades as a freelance consultant, where the assignment was often to come in “blind” to a customer site and try diagnose performance problems with their database applications.  The core challenge in doing that was never the SQL, because SQL is just code – the challenge was always understanding the data model and the business requirements that it was trying to satisfy. Nothing was more soul-sapping than generating a data model using a tool such as SQL Developer and being presented with a screen full of yellow boxes (one for each table) and absolutely no lines between them. No lines meant no clues about how the tables related to each other.

It is not just the relationships between tables that is critical to help a fresh set of eyes understand the data model. The same things that improve the quality of the database in your database, namely

  • the NOT NULL constraints
  • the PRIMARY KEY constraints
  • the UNIQUE constraints
  • the CHECK constraints
  • the FOREIGN KEY constraints

do more than just keep your data clean. They also offer insight about what the data will look like, and what assumptions can be made when querying the data.

constraints

The importance of documenting your database within the database can most easily be seen by looking at the innovations we’ve been putting into the latest version of Oracle Database.

We’ve added support for Domains, to better define and coalesce common attribute definitions across the database.

and even though we have had the capability to add dictionary comments for decades, we have also added a means to have more rigorous metadata for tables and columns via the Annotations feature

The Big Change

But here is the real kicker… Do you know who the next new set of eyes for your data model is going to be? It is going to be the onslaught of AI engines that are being used to vibe-code your next application.

I’m sure you have seen a myriad of demos by every vendor where an AI tool takes your natural language input, looks into your database and amazingly deduces that the SALARY column in the EMPLOYEES table is how to query the salary for an employee. Amazing! 😂 But lets be honest – that’s nothing like the reality of modern databases and modern database applications.

Lets see how an AI tool fares when it is expected to know that an employee’s salary is column XF017A in the GL00X56 table, but only when the commission cycle date (stored in table AP876, column COMMCYC) is lower than the budget forecast end period defined as the maximum value of BUFDTE in table FCAST_EOY. I suspect it wont do well.

However, those database developers that have put in the time – adding comments to the database dictionary, adding annotations to the database dictionary, adding domains to the database dictionary, defining views to the database dictionary, and of course, doing all of this on top of a data model that has rigorously defined integrity constraints, are (perhaps unknowingly) about to reap huge benefits of having AI tools being able to comprehensively understand the data model and how applications can be automatically built to best utilize that model.

Conversely, if your database is “free” of constraints, comments, domains, annotations and the like, then I’m sorry, that lack of metadata that use to frustrate me as a consultant, is about to really frustrate your hopes to take advantage of AI.

4 responses to “The Moment for Database Documentation has come!”

  1. There used to be a product Oracle Designer which created a lot of the Data Model documentation. Unfortunately, the product was discontinued and replaced by SQL Data Modeller which does not have the same utilities. Generating DDL seems to have taken over the Modelling approach. And APEX with the quick DDL is not really helping.

  2. Bring back Oracle Designer !

  3. Designer wasn’t replaced by Modeler. Modeler just happened to have the largest set of complementary features that Designer had. Modeler does excel at generating schema documentation, not sure what you’re missing?

    We’re working on schema enrichment features in our tools so the AI can indeed make its way around your sloppy schemas, stay tuned for news there.

  4. I would like to add: meaningful naming and correct datatypes!

Leave a reply to John Cancel reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Trending