Confusing installation steps

[vanpet]

Trying to use this package, I'm lost in the installation phase, between copy pasting files and getting circular dependancies in the deps file.

I think the installation readme should be more straightforward.

[KyleJune]

Right now the setup is basically copying the example's migrate.ts file.

The current installation path is shown further down in the Postgres CLI section. I don't specify how to earlier in the CLI section.

However the example uses relative paths for the imports. They need to be changed to urls or jsr. If using jsr, I should make the import path "jsr:@udibo/migrate@0.2".

[kerimhudson]

Something I stumbled across when using this is that the use of the load step isn't really covered in the getting started. So when you're running apply, you just keep getting 0 migrations, which is slightly confusing.

I guess the steps should be:

1. Init
2. Create a migration
3. Load the migration
4. Apply the migration

If I understand how this works correctly? That seemed to work for me.

[KyleJune]

Something I stumbled across when using this is that the use of the load step isn't really covered in the getting started. So when you're running apply, you just keep getting 0 migrations, which is slightly confusing.

I guess the steps should be:

1. Init

2. Create a migration

3. Load the migration

4. Apply the migration

If I understand how this works correctly? That seemed to work for me.

Thanks for that feedback. I think I might just get rid of the init and load steps in the next release. Currently init is used to create the table for tracking migrations, load is used for checking the folder for any new/changed migrations, then all the other commands just go by what is in the table rather than checking the migrations directory. So currently, you must load the migrations before applying.

[kerimhudson]

Something I stumbled across when using this is that the use of the load step isn't really covered in the getting started. So when you're running apply, you just keep getting 0 migrations, which is slightly confusing.
I guess the steps should be:

1. Init

2. Create a migration

3. Load the migration

4. Apply the migration

If I understand how this works correctly? That seemed to work for me.

Thanks for that feedback. I think I might just get rid of the init and load steps in the next release. Currently init is used to create the table for tracking migrations, load is used for checking the folder for any new/changed migrations, then all the other commands just go by what is in the table rather than checking the migrations directory. So currently, you must load the migrations before applying.

I think that would definitely give it a bit more of an automatic feeling, similar to how prisma does it.

Personally, I'm a fan of an init step because it makes clear for the user of the CLI that something is going to happen. I think some people might frown on the idea of a table being generated without being informed.

I wonder if to make it feel a bit more magical you could have the init command also make the migrationsDir if it doesn't exist, so that it's very clear where the migrations need to go. And then just perhaps print out some helpful lines in the console like:

To get started, add in your first migration and run "migrate apply".

Or combining both:

Database has been initialized with a new migration table.
To get started, add in your first migration and run "migrate apply"

[gonzus]

If I may, I also found / find the instructions confusing.

• They don't show an import from JSR, instead the imports are from deno.land or github.
• They mention that "To use the command line interface, you must create a script that will initialize the Migrate instance and call the run command from cli.ts. An example can be found here." But the example does not mention cli.ts at all, and instead says: "To use this script, copy migrate.ts and update it with your migrate configuration."
• I am still not sure what I need to copy from where, and whether it needs to be modified or not.
• BTW, it seems to be a theme with Deno links that they will usually not open in the browser (Firefox for me), but download their target. Maybe that's just for the CDN links? Still, a bit surprising.

Now, this could all be a skill issue on my side -- I am just diving into Deno. But I think it would be much clearer if this package could just be installed (say, with deno add <something>) and then executed as a script, offering the basic functionality. Configuration / specialization could be an opt-in. Just my 2 cents.

[gonzus]

Also, I did not understand why there is a migrate_basic.ts, migrate.ts and cli.ts. Super confusing (to me).

[KyleJune]

If I may, I also found / find the instructions confusing.

* They don't show an import from JSR, instead the imports are from deno.land or github.

This was written before Deno created JSR. Originally with deno, people would publish packages to deno.land/x, then import them via url. Deno has moved away from that, it still works but they are pushing people towards using their module registry, JSR because it solves some dependency management problems that are difficult with plain urls. I believe they talk about that in their blog post where they announce JSR.

* They mention that "To use the command line interface, you must create a script that will initialize the Migrate instance and call the run command from [cli.ts](https://cdn.deno.land/migrate/versions/0.2.5/raw/cli.ts). An example can be found [here](https://deno.land/x/migrate@0.2.5#postgres-cli)." But the example does not mention `cli.ts` at all, and instead says: "To use this script, copy [migrate.ts](https://cdn.deno.land/migrate/versions/0.2.5/raw/examples/postgres/migrate.ts) and update it with your migrate configuration."

* I am still not sure what I need to copy from where, and whether it needs to be modified or not.

* BTW, it seems to be a theme with Deno links that they will usually not open in the browser (Firefox for me), but download their target. Maybe that's just for the CDN links? Still, a bit surprising.

Also, I did not understand why there is a migrate_basic.ts, migrate.ts and cli.ts. Super confusing (to me).

The links on deno.land use to open the file viewable in the browser. I believe it was changed on their end to just download the file. You can see the files in this example folder. The general idea is that in your project, you would have the either of the 2 migrate script examples I included there along with a migrations folder.

https://github.com/udibo/migrate/tree/main/examples/postgres

The migrate.ts is an example of how to create a command line interface, where you can run the script in all the ways shown in the cli section of the documentation linked below.

https://deno.land/x/migrate@0.2.4#cli

The migrate_basic.ts is an example of a simpler script, where when you run it, it just applies any migrations that haven't been applied yet. Both are not needed, they are just 2 separate examples of how this library can be used.

Then the migrations folder is just an example that includes 2 sql migration files.

https://github.com/udibo/migrate/tree/main/examples/postgres/migrations

Both of those files import a deps.ts file. If you look at the deps.ts file, you'll see the functions they use are imported from this package. One of those files is the cli.ts file, that is where the run function comes from. The migrate.ts script that users would have in their project would use the run function it imports from cli.ts to parse the args and run the migrate tool. The documentation linked earlier show examples of args you can pass when calling your migrate.ts script and what will happen if you call it with those args.

Now, this could all be a skill issue on my side -- I am just diving into Deno. But I think it would be much clearer if this package could just be installed (say, with deno add <something>) and then executed as a script, offering the basic functionality. Configuration / specialization could be an opt-in. Just my 2 cents.

I agree my documentation for this package isn't very clear for beginners. At the time I created it, I wanted something like this npm package, but I tried to design it in a way that it could later be a common interface for running migrations for more than just postgres.

https://www.npmjs.com/package/postgres-migrations

I also wrote it to work with the following postgres driver for deno instead of the npm postgres package that the one above was using.

https://github.com/denodrivers/postgres

That package hasn't really been maintained. Someone from Deno published it to JSR, linked below. But it hasn't been updated in 11 months.

https://jsr.io/@bartlomieju/postgres

I believe the postgres driver and this migrate package still work. I've used it on a project of mine, but I haven't had a lot of time to work on side projects. I likely won't continue with this project since the driver it is based on appears to not be maintained either.

My recommendation would be to try drizzle. I plan on trying it out at some point when I have time to work on one of my side projects that use postgres. Drizzle is a very popular package on npm that is well maintained. Deno also has a blog post on how to get started with it.

https://deno.com/blog/build-database-app-drizzle

Then for topics the blog post doesn't cover, more info can be found on drizzle's documentation website.

https://orm.drizzle.team/docs/get-started/postgresql-new

[KyleJune]

If I end up not preferring drizzle over a simpler migrations folder approach like this package was designed for, I might revisit this at some point, updating it to use a newer or better maintained postgres driver. Updating it to use a different driver wouldn't be very difficult.

I'd also be open to someone else taking over the project if developing a CLI tool for simple postgres migrations is something they are interested in. Just adding this comment in case anyone comes across it and would like to build onto it. I'd respond if anyone created an issue or PR for a change they'd like to make to this package.

I basically started too many projects as an early adopter of deno, and have prioritized other ones that I have more interest in when I do have free time to code. I have published some packages to jsr, the current one I work on in my free time is linked below. I'm trying to make it easier to use React in Deno. I'm currently working on writing the documentation for it.

https://jsr.io/@udibo/react-app

[gonzus]

Thank you for those extremely detailed explanations -- they do fill in the / my gaps. You could consider adding them to the README -- but I understand maybe you would rather not do any more work on this package, as you mentioned. Cheers!

[KyleJune]

One other thing to mention if anyone decides to use this and the older postgres package from deno.land/x, my example uses a deps.ts file which was the old approach to dependency management in deno. Now you could just add an entry to your import map for importing the packages from deno.land. Remapping "migrate" to "https://deno.land/x/migrate@0.2.5", which I believe would allow you to import from "migrate/postgres.ts" and "migrate/cli.ts" or any of the other entrypoints used in the deps.ts file from the example.

More info about import maps for dependency management can be found here:
https://docs.deno.com/runtime/fundamentals/modules/