why feature of writing migrations in plain SQL is HIDDEN?

[mrl5]

hello,

Context

So I was looking for a npm package for handling postgres migrations. One of the first packages that I found was node-pg-migrate. It was also referenced in https://github.com/gajus/slonik#user-content-slonik-migrations.

After quickly checking docs I almost rejected node-pg-migrate because I assumed that I can't write my migrations in SQL. Even migration-file-language described in https://github.com/salsita/node-pg-migrate/blob/master/docs/cli.md doesn't mention sql.

Luckily I came across this article https://synvinkel.org/notes/node-postgres-migrations and discovered that I can actually write my migrations in SQL. Also discovered that when migrations folder contain .sql file then node-pg-migrate create will automatically also create .sql files.

Question

Why are you hiding this cool feature? If I didn't stumble upon above mentioned article I would probably not use this cool library. You should really consider documenting it somewhere.

Final words

That being said - I plan to use node-pg-migrate in my nodejs project(s) together with sql migrations :) Other feature that I love is that you can define schema, where migrations table lives.

[mrl5]

looks like "hidden feature" was introduced in #242
and there is already #786 that mentions similar topic to this discussion