Pick a Convention and Stick With It

You know what’s worse than a bad naming convention? Two naming conventions in the same database.

I ran into this last week while writing a verification query for a PostgreSQL database. The query is a simple health check it counts rows across every table that our seeding scripts populate after deploying to a new environment. I wrote it, ran it in pgAdmin, and immediately got:

My first thought was a typo. My second thought was a permissions issue. My third thought the correct one was that the table is actually called productcategory. No underscore. One word.

Here’s the thing: in the same schema, these tables all exist side by side:

• payment_status
• recorded_transaction_type
• allowed_payment_methods
• volume_rate_categories
• productcategory
• productinstance
• feegroup
• invoicelineitem

Some tables use underscores to separate words. Some don’t. Same schema. Same database. Same development team.

Why This Matters

Naming conventions exist so that humans can predict object names without looking them up. When every table uses snake_case, I can confidently write product_category without checking the DDL first. When every table concatenates words, I know to write productcategory. Either convention works. The problem isn’t which one you pick it’s when you pick both.

Inconsistent naming creates a tax on every person who touches the database. Every query, every script, every code review requires a moment of “wait, is this one with underscores or without?” That moment adds up. Multiply it by every developer, every DBA, every ORM configuration, every migration script, and you’ve got a meaningful drag on productivity.

And it doesn’t just waste time it creates bugs. My verification query ran in pgAdmin against a production-adjacent environment. If I hadn’t caught the error in a health check, and instead had embedded that table name in application code or an automated monitoring script, it would have failed silently or thrown a runtime error in production.

The Pattern I’ve Seen

In my experience, mixed naming conventions usually emerge from one of two scenarios:

Multiple teams, no standard. Team A builds the billing tables and uses snake_case. Team B builds the product tables and concatenates words. Nobody establishes a convention before development starts, and by the time someone notices, there are too many tables to rename without breaking everything.

Schema evolution over time. The original developer used one convention. Years later, new tables get added by someone who either doesn’t know the original convention or doesn’t agree with it. Without a style guide or a code review process that catches it, the inconsistency creeps in.

Both scenarios have the same root cause: nobody wrote down the rules, or nobody enforced them.

What to Do About It

If you’re starting a new database, the answer is simple: pick a convention, document it, enforce it in code reviews. snake_case is the PostgreSQL community standard. PascalCase is common in SQL Server. Either is fine. Just pick one.

If you’re inheriting an existing database with mixed conventions which is what most of us are actually dealing with you have harder choices. Renaming tables is a breaking change that ripples through every application, ORM mapping, stored procedure, and ad-hoc script that references them. That’s usually not practical for a database in active production use.

What is practical:

1. Document the inconsistency. Create a schema reference that lists every table with its actual name. Make it searchable. This eliminates the guessing.
2. Standardize new objects. Even if you can’t rename existing tables, you can establish a convention for all new tables, views, and columns going forward. Eventually, the inconsistent tables become the minority.
3. Use views as an abstraction layer. If the inconsistency is causing real problems in application code, create views with consistent names that map to the underlying tables. This adds a layer, but it gives consumers a predictable API.
4. Add it to your DDL review checklist. Every new CREATE TABLE should be checked against the naming standard before it ships. Automated linting is even better if your tooling supports it.

The Takeaway

Database naming conventions are one of those things that feel trivial when you’re creating the first ten tables and feel deeply consequential when you’re maintaining three hundred. The ten minutes it takes to write down “we use snake_case for all object names” at the start of a project saves hours of confusion and debugging down the road.

And if you’re the person who just spent twenty minutes debugging a query that failed because you guessed wrong about an underscore well, now you have a blog post to passive-aggressively share with the team.

Have you inherited a database with mixed naming conventions? I’d love to hear your war stories and especially your strategies for taming the inconsistency. Find me on Bluesky, LinkedIn, or drop a comment below.