From 535a91d4bec978ba5a94cae388acc283eb7297b0 Mon Sep 17 00:00:00 2001 From: Hein Date: Wed, 8 Apr 2026 22:21:24 +0200 Subject: [PATCH] feat(docs): add comprehensive story of RelSpecGo's development journey --- Story.md | 219 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 219 insertions(+) create mode 100644 Story.md diff --git a/Story.md b/Story.md new file mode 100644 index 0000000..eb6fb79 --- /dev/null +++ b/Story.md @@ -0,0 +1,219 @@ + +# 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*.