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

[MainaMwangiy]

I agree with you. This feature is the reason why we are using this library for some of us. It should be well documented.

[Shinigami92]

I'm happy to review any contributions in this regard