{"id":27286600,"url":"https://github.com/udibo/migrate","last_synced_at":"2025-07-25T13:42:36.649Z","repository":{"id":38418704,"uuid":"420583707","full_name":"udibo/migrate","owner":"udibo","description":"A postgres migration tool for Deno.","archived":false,"fork":false,"pushed_at":"2024-03-23T20:34:46.000Z","size":41,"stargazers_count":9,"open_issues_count":3,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-17T22:44:41.645Z","etag":null,"topics":["deno","migrations","postgres","postgresql","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/udibo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-10-24T04:09:50.000Z","updated_at":"2025-02-23T09:54:05.000Z","dependencies_parsed_at":"2023-01-21T13:02:40.857Z","dependency_job_id":null,"html_url":"https://github.com/udibo/migrate","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/udibo%2Fmigrate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/udibo%2Fmigrate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/udibo%2Fmigrate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/udibo%2Fmigrate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/udibo","download_url":"https://codeload.github.com/udibo/migrate/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248468781,"owners_count":21108889,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["deno","migrations","postgres","postgresql","typescript"],"created_at":"2025-04-11T19:43:24.453Z","updated_at":"2025-04-11T19:43:25.130Z","avatar_url":"https://github.com/udibo.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Migrate\n\n[![version](https://img.shields.io/badge/release-0.2.5-success)](https://deno.land/x/migrate@0.2.4)\n[![CI](https://github.com/udibo/migrate/workflows/CI/badge.svg)](https://github.com/udibo/migrate/actions?query=workflow%3ACI)\n[![codecov](https://codecov.io/gh/udibo/migrate/branch/main/graph/badge.svg?token=8Q7TSUFWUY)](https://codecov.io/gh/udibo/migrate)\n[![license](https://img.shields.io/github/license/udibo/migrate)](https://github.com/udibo/migrate/blob/master/LICENSE)\n\nA postgres migration tool for Deno.\n\nThis module was inspired by\n[postgres-migrations](https://www.npmjs.com/package/postgres-migrations).\n\n## Installation\n\nTo include this module in a Deno project, you can import directly from the TS\nfiles. This module is available in Deno's third part module registry but can\nalso be imported directly from GitHub using raw content URLs.\n\nCurrently migrate is only implemented for Postgres. The main entrypoint is\n`postgres.ts`.\n\n```ts\n// Import from Deno's third party module registry\nimport { PostgresMigrate } from \"https://deno.land/x/migrate@0.2.5/postgres.ts\";\n// Import from GitHub\nimport { PostgresMigrate } \"https://raw.githubusercontent.com/udibo/migrate/0.2.5/postgres.ts\";\n```\n\n## Usage\n\n### CLI\n\nTo use the command line interface, you must create a script that will initialize\nthe Migrate instance and call the run command from [cli.ts](cli.ts). An example\ncan be found [here](#postgres-cli).\n\nSee [deno docs](https://doc.deno.land/https/deno.land/x/migrate@0.2.5/cli.ts)\nfor more information.\n\n#### Command: init\n\nInitializes the migration table for tracking which migrations have been applied.\n\n```\n$ ./migrate.ts init\nConnecting to database\nCreating migration table if it does not exist\nCreated migration table\n```\n\n#### Command: load\n\nLoads all migrations current path values into the migration table.\n\n```\n$ ./migrate.ts load\nConnecting to database\nAcquiring migrate lock\nAcquired migrate lock\nLoading migrations\n2 new migrations found\n1 migration updated\nNo migrations deleted\nReleasing migrate lock\nReleased migrate lock\nDone\n```\n\n#### Command: status\n\nOutputs the status of all migrations. By default it just outputs the counts.\n\n```\n$ ./migrate.ts status\nConnecting to database\nChecking loaded migrations\nStatus:\n  Total: 5\n  Applied: 4\n  File moved: 1\n  File deleted: 1\n  Not applied: 1\n```\n\nIf the --details or -d flag is provided, it will log the filenames of migrations\nthat have not been applied or have been changed since being applied.\n\n```\n$ ./migrate.ts status --details\nConnecting to database\nChecking loaded migrations\nStatus:\n  Total: 5\n  Applied: 4\n  File moved: 1\n    2_user_add_kyle.sql -\u003e 2_user_add_kyle.ts\n  File deleted: 1\n    3_user_add_staff.sql\n  Not applied: 1\n    4_user_add_column_email.sql\n```\n\n#### Command: list\n\nOutputs a list of migrations. By default it outputs all migrations.\n\n```\n$ ./migrate.ts list\nConnecting to database\nChecking loaded migrations\nAll migrations:\n  0_user_create.sql\n    applied at: Tue Nov 09 2021 12:10:32 GMT-0600 (Central Standard Time)\n  1_user_add_admin.sql\n    applied at: Wed Nov 11 2021 18:31:08 GMT-0600 (Central Standard Time)\n  2_user_add_kyle.sql\n    applied at: Sat Nov 13 2021 05:31:08 GMT-0600 (Central Standard Time)\n    file moved to: 2_user_add_kyle.ts\n  3_user_add_staff.sql\n    applied at: Mon Nov 15 2021 15:31:08 GMT-0600 (Central Standard Time)\n    file deleted\n  4_user_add_column_email.sql\n    not applied\n```\n\nIf the --filter flag is provided, it will filter the migrations to only include\nmigrations that match the filter. The filter options are applied, unapplied,\nrenamed, and deleted.\n\n```\n$ ./migrate.ts list --filter=unapplied\nUnapplied migrations:\n  4_user_add_column_email.sql\n```\n\n#### Command: apply\n\nApplies all unapplied migrations and outputs the filenames.\n\n```\n$ ./migrate.ts apply\nConnecting to database\nAcquiring migrate lock\nAcquired migrate lock\nChecking loaded migrations\n2 unapplied migrations\nApplying migration: 0_user_create.sql\nApplying migration: 1_user_add_column_email.sql\nFinished applying all migrations\nReleasing migrate lock\nReleased migrate lock\nDone\n```\n\n### Postgres\n\nExamples of how to use migrate with postgres can be found\n[here](examples/postgres). There are 2 scripts in that folder to demonstrate\ndifferent ways to use the migrate module. Only one is required to use the\nmigrate tool.\n\nSee\n[deno docs](https://doc.deno.land/https/deno.land/x/migrate@0.2.5/postgres.ts)\nfor more information.\n\n#### Postgres script\n\nA basic migrate script that will apply all unapplied migrations.\n\nTo use this script, copy [migrate_basic.ts](examples/postgres/migrate_basic.ts)\nand update it with your migrate configuration.\n\n```\n$ ./migrate_basic.ts\nConnecting to database\nAcquiring migrate lock\nAcquired migrate lock\nCreating migration table if it does not exist\nCreated migration table\nLoading migrations\nChecking for unapplied migrations\n2 unapplied migrations found\nApplying migration: 0_user_create.sql\nApplying migration: 1_user_add_column_email.sql\nFinished applying all migrations\nReleasing migrate lock\nReleased migrate lock\nDone\n```\n\n#### Postgres CLI\n\nA CLI for the migration tool.\n\nTo use this script, copy [migrate.ts](examples/postgres/migrate.ts) and update\nit with your migrate configuration.\n\n```\n$ ./migrate.ts status\nConnecting to database\nChecking loaded migrations\nStatus:\n  Total: 5\n  Applied: 4\n  Not applied: 1\n```\n\nSee [CLI](#cli) for more information about available CLI commands.\n\n## Design decisions\n\n### Roll forward migrations only\n\nIf you need to reverse something, you can just push another migration to negate\nthe migration you want to undo.\n\n### Simple ordering\n\nAll migration file names start with an integer index that is used for\ndetermining the order to apply migrations in.\n\n### Easily organize migrations\n\nThe entire migrations directory is searched when looking for migration files. If\nyou would like to organize your migrations instead of having them all in a flat\ndirectory, you can create sub directories for them. You can move or rename the\nfiles before or after they are applied, as long as you don't change their index.\n\n### Each migration runs in a transaction (unless explicitly disabled)\n\nRunning in a transaction ensures each migration is atomic. It will either\ncomplete successfully or roll back any changes that were applied before a\nfailure.\n\nIf you have a migration that cannot be run inside a transaction, you can disable\nit for that file. This allows migrations such as `CREATE INDEX CONCURRENTLY`\nwhich cannot be run inside a transaction.\n\n### Multiple file formats\n\nMigrations can be stored in sql, json, js, or ts files. Naming your migrations\nis recommended but not required. An underscore is used to separate the migration\nindex from the name if there is one. For example, below is a list of valid\nmigration filenames.\n\n- 0.sql\n- 1_user_create.sql\n- 2_user_add_column.json\n- 3_user_add_admin.js\n- 4_user_add_kyle.ts\n\n#### SQL migration\n\nA SQL migration file should just contain plain SQL. It can have multiple queries\nin it. All queries will run in a transaction unless you explicitly disable using\ntransactions.\n\n```sql\nCREATE TABLE \"user\" (\n  id INT PRIMARY KEY,\n  username VARCHAR(256) UNIQUE NOT NULL\n);\n```\n\nTo disable the use of a transaction for a SQL migration file, add\n`-- migrate disableTransaction` as a SQL comment to the start of the file.\n\n#### JSON migration\n\nA JSON migration file should contain an object with an array of queries. The\nqueries can be strings or MigrationQueryConfig objects.\n\n```json\n{\n  \"queries\": [\n    \"INSERT INTO \\\"user\\\" (id, username) VALUES (1, 'admin')\",\n    {\n      \"text\": \"INSERT INTO \\\"user\\\" (id, username) VALUES (2, 'kyle')\"\n    },\n    {\n      \"text\": \"INSERT INTO \\\"user\\\" (id, username) VALUES ($1, $2)\",\n      \"args\": [3, \"bot\"]\n    }\n  ]\n}\n```\n\nTo disable the use of a transaction for a JSON migration file, set the\ndisableTransaction property to true.\n\n#### JS/TS migrations\n\nA JS or TS migration file should export a generateQueries function that returns\nan Iterable or AsyncIterable for queries. Like JSON migration files, the queries\ncan be strings or MigrationQueryConfig objects.\n\n```js\nexport function generateQueries() {\n  return [\n    `INSERT INTO \"user\" (id, username) VALUES (1, 'admin')`,\n    {\n      text: \"INSERT INTO \\\"user\\\" (id, username) VALUES (2, 'kyle')\",\n    },\n    {\n      text: 'INSERT INTO \"user\" (id, username) VALUES ($1, $2)',\n      args: [3, \"bot\"],\n    },\n  ];\n}\n```\n\nTo disable the use of a transaction for a JS or TS migration file, export a\ndisableTransaction constant that is set to true.\n\n### Concurrency\n\nA locking function is provided for preventing multiple migration scripts from\nrunning at the same time.\n\n## Recommendations\n\n### Migrations should be idempotent\n\nMigrations should only be applied once.\n\n### Migrations should be immutable\n\nOnce applied in production, a migration should not be changed. Modifying a\nmigration that has already been applied may result in you not being able to\nreproduce your database.\n\n## Contributing\n\nTo contribute, please read the [contributing instruction](CONTRIBUTING.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fudibo%2Fmigrate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fudibo%2Fmigrate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fudibo%2Fmigrate/lists"}