Document "SQL migration file: must start with '-- +goose Up'" (and not goose Down)

[jjhbw]

Hi there, thanks for this great tool!

I noticed that new versions of Goose require SQL migration files to begin with the -- +goose Up statement. I made a few that started with -- +goose Down instead, and these used to work fine.

Couldn't find explicit mention of this in the docs. Maybe i missed something?

Thanks!

[VojtechVitek]

Interesting, what's the use case for Down-only migrations?

[jjhbw]

Oh, sorry, i think wasn't clear.
I meant that my files started with the -- +goose Down statements. They do include up statements though. Don't have a quick repro handy atm bc on mobile.

[VojtechVitek]

no problem; send it when you're back on desktop pls

[jjhbw]

Migration file ./migrations/001_example.sql

-- +goose Down
DROP TABLE example;

-- +goose Up
CREATE TABLE example;

Spun up postgres with:

docker run -p 5432:5432 -e "POSTGRES_USER=docker" -e "POSTGRES_PASSWORD=docker" -e "ALLOW_IP_RANGE=0.0.0.0/0" postgres

Apply the migration:

goose -dir=./migrations/ postgres "user=docker password=docker dbname=postgres sslmode=disable" up

Returns:

2019/03/22 16:40:50 goose run: ERROR 001_example.sql: failed to parse SQL migration file: must start with '-- +goose Up' annotation, stateMachine=0, see https://github.com/pressly/goose#sql-migrations

Note that using goose status instead of goose up seems to work.

[andor44]

Related: we had an extra space at the beginning of the file, i.e. " -- +goose Up" (minus the double quotes, just using it to emphasize the space). The migration was noticed but goose did nothing, no error message. It semeed to treat the migration as if it were empty.

[VojtechVitek]

@andor44 can you report this bug as a separate issue please?

[mfridman]

We typically don't write these files by hand, instead run something like this..

goose -dir ./some/dir/migrations create create_users_table sql

But we should fix this up. The order of the up vs down directives within a file should not matter.

[mfridman]

For brevity, #163 (comment) about empty lines will be fixed as part of #446