220 lines
5.1 KiB
Markdown
220 lines
5.1 KiB
Markdown
|
||
# From Scripts to RelSpec: What Years of Database Pain Taught Me
|
||
|
||
It started as a need.
|
||
A problem I’ve carried with me since my early PHP days.
|
||
|
||
Every project meant doing the same work again. Same patterns, same fixes—just in a different codebase.
|
||
It became frustrating fast.
|
||
|
||
I wanted something solid. Not another workaround.
|
||
|
||
## The Early Tools Phase
|
||
|
||
Like most things in development, it began small.
|
||
|
||
A simple PHP script.
|
||
Then a few Python scripts.
|
||
|
||
Just tools—nothing fancy. The goal was straightforward: generate code faster and remove repetitive work. I even experimented with Clarion templates at one point, trying to bend existing systems into something useful.
|
||
|
||
Then came SQL scripts.
|
||
Then PostgreSQL migration stored procedures.
|
||
Then small Go programs using templates.
|
||
|
||
Each step was solving a problem I had at the time. Nothing unified. Nothing polished. Just survival tools.
|
||
|
||
---
|
||
|
||
## Argitek: The First Real Attempt
|
||
|
||
Eventually, those scattered ideas turned into something more structured: Argitek.
|
||
|
||
Argitek powered a few real systems, including Powerbid. On paper, it sounded solid:
|
||
|
||
> “Argitek Next is a powerful code generation tool designed to streamline your development workflow.”
|
||
|
||
And technically, it worked.
|
||
|
||
It could generate code from predefined templates, adapt to different scenarios, and reduce repetitive work. But something was off.
|
||
|
||
It never felt *complete*.
|
||
Not something I could confidently release.
|
||
|
||
So I did what many developers do with almost-good-enough tools—I parked it.
|
||
|
||
---
|
||
|
||
## The Breaking Point: Database Migrations
|
||
|
||
Over the years, one problem kept coming back:
|
||
|
||
Database migrations.
|
||
|
||
Not the clean, theoretical kind. The real ones.
|
||
|
||
* PostgreSQL to ORM mismatches
|
||
* DBML to SQL hacks
|
||
* GORM inconsistencies
|
||
* Manual fixes after “automated” migrations failed
|
||
|
||
It was always messy. Always unpredictable. Always more work than expected.
|
||
|
||
By 2025, after a particularly tough year, I had accumulated enough of these problems to stop ignoring them.
|
||
|
||
---
|
||
|
||
## December 2025: RelSpecGo Begins
|
||
|
||
In December 2025, I bootstrapped something new:
|
||
|
||
**RelSpecGo**
|
||
|
||
It started simple:
|
||
|
||
* Initial LICENSE
|
||
* Basic configuration
|
||
* A direction
|
||
|
||
By late December:
|
||
|
||
* SQL writer implemented
|
||
* Diff command added
|
||
|
||
January 2026:
|
||
|
||
* Documentation
|
||
|
||
February 2026:
|
||
|
||
* Schema editor UI (focused on relationships)
|
||
* MSSQL DDL writer
|
||
* Template support with `--from-list`
|
||
|
||
---
|
||
|
||
## April 2026: A Real Tool Emerges
|
||
|
||
By April 2026, it became something I could finally stand behind.
|
||
|
||
RelSpecGo reached version **1.0.44**, with:
|
||
|
||
* Packaging for AUR, Debian, and RPM
|
||
* Updated documentation and README
|
||
* A full toolchain for:
|
||
|
||
* Convert
|
||
* Merge
|
||
* Inspect
|
||
* Diff
|
||
* Template
|
||
* Edit
|
||
|
||
Support includes:
|
||
|
||
* bun
|
||
* dbml
|
||
* drizzle
|
||
* gorm
|
||
* prisma
|
||
* mssql
|
||
* pgsql
|
||
* sqlite
|
||
|
||
Plus:
|
||
|
||
* TUI editor
|
||
* Template engine
|
||
* Bidirectional schema handling
|
||
|
||
👉 RelSpecGo: [https://git.warky.dev/wdevs/relspecgo](https://git.warky.dev/wdevs/relspecgo)
|
||
|
||
This wasn’t just another generator anymore.
|
||
It became a system for managing *database truth*.
|
||
|
||
---
|
||
|
||
## Lessons Learned (The Hard Way)
|
||
|
||
This journey wasn’t about tools. It was about understanding databases properly.
|
||
|
||
Here are the principles that stuck:
|
||
|
||
### 1. Data Loss Is Not Acceptable
|
||
|
||
Changing table structures should **never** result in lost data. If it does, the process is broken.
|
||
|
||
### 2. Minimal Beats Clever
|
||
|
||
The simpler the system, the easier it is to trust—and to fix.
|
||
|
||
### 3. Respect the Database
|
||
|
||
If you fight database rules, you will lose. Stay aligned with them.
|
||
|
||
### 4. Indexes and Keys Matter More Than You Think
|
||
|
||
Performance and correctness both depend on them. Ignore them at your own risk.
|
||
|
||
### 5. Version-Control Your Backend Logic
|
||
|
||
SQL scripts, functions, migrations—these must live in version control. No exceptions.
|
||
|
||
### 6. It’s Not Migration—It’s Adaptation
|
||
|
||
You’re not just moving data. You’re fixing inconsistencies and aligning systems.
|
||
|
||
### 7. Migrations Never Go as Planned
|
||
|
||
Always assume something will break. Plan for it.
|
||
|
||
### 8. One Source of Truth Is Non-Negotiable
|
||
|
||
Your database schema must have a single, authoritative definition.
|
||
|
||
### 9. ORM Mapping Is a First-Class Concern
|
||
|
||
Your application models must reflect the database correctly. Drift causes bugs.
|
||
|
||
### 10. Audit Trails Are Critical
|
||
|
||
If you can’t track changes, you can’t trust your system.
|
||
|
||
### 11. Manage Database Functions Properly
|
||
|
||
They are part of your system—not an afterthought.
|
||
|
||
### 12. If It’s Hard to Understand, It’s Too Complex
|
||
|
||
Clarity is a feature. Complexity is technical debt.
|
||
|
||
### 13. GUIDs Have Their Place
|
||
|
||
Especially when moving data across systems. They solve real problems.
|
||
|
||
### 14. But Simplicity Still Wins
|
||
|
||
Numbered primary keys are predictable, efficient, and easy to reason about.
|
||
|
||
### 15. JSON Is Power—Use It Carefully
|
||
|
||
It adds flexibility, but too much turns structure into chaos.
|
||
|
||
---
|
||
|
||
## Closing Thoughts
|
||
|
||
Looking back, this wasn’t about building a tool.
|
||
|
||
It was about:
|
||
|
||
* Reducing friction
|
||
* Making systems predictable
|
||
* Respecting the database as the core of the system
|
||
|
||
RelSpecGo is just the current result of that journey.
|
||
|
||
Not the end.
|
||
|
||
Just the first version that feels *right*.
|