{"id":31096616,"url":"https://github.com/npgsqlrest/pgmigrations","last_synced_at":"2025-09-16T18:46:50.141Z","repository":{"id":238259923,"uuid":"796199607","full_name":"NpgsqlRest/pgmigrations","owner":"NpgsqlRest","description":"Lightweight, Zero-Dependency, PostgreSQL Tool for Node.js and NPM. ","archived":false,"fork":false,"pushed_at":"2025-04-04T12:00:52.000Z","size":81,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-08-18T13:40:49.948Z","etag":null,"topics":["javascript","migrations","nodejs","postgresql","schema","sql","testing"],"latest_commit_sha":null,"homepage":"https://vb-consulting.github.io/pgmigrations/","language":"JavaScript","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/NpgsqlRest.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-05-05T08:35:46.000Z","updated_at":"2025-08-18T06:58:59.000Z","dependencies_parsed_at":"2025-08-18T13:40:57.020Z","dependency_job_id":"5d11c764-c929-49af-b37a-dba84386ab19","html_url":"https://github.com/NpgsqlRest/pgmigrations","commit_stats":{"total_commits":32,"total_committers":1,"mean_commits":32.0,"dds":0.0,"last_synced_commit":"8b8630f9b8c498ed5fe5892138259f07f67f4f18"},"previous_names":["vb-consulting/pgmigrations","npgsqlrest/pgmigrations"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/NpgsqlRest/pgmigrations","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NpgsqlRest%2Fpgmigrations","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NpgsqlRest%2Fpgmigrations/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NpgsqlRest%2Fpgmigrations/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NpgsqlRest%2Fpgmigrations/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NpgsqlRest","download_url":"https://codeload.github.com/NpgsqlRest/pgmigrations/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NpgsqlRest%2Fpgmigrations/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275465737,"owners_count":25469885,"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","status":"online","status_checked_at":"2025-09-16T02:00:10.229Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["javascript","migrations","nodejs","postgresql","schema","sql","testing"],"created_at":"2025-09-16T18:46:47.112Z","updated_at":"2025-09-16T18:46:50.114Z","avatar_url":"https://github.com/NpgsqlRest.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PgMigrations\n\n![npm version](https://badge.fury.io/js/pgmigrations.svg)\n![License](https://img.shields.io/badge/license-MIT-green)\n![GitHub Stars](https://img.shields.io/github/stars/vb-consulting/pgmigrations?style=social)\n![GitHub Forks](https://img.shields.io/github/forks/vb-consulting/pgmigrations?style=social)\n\nLightweight, Zero-Dependency, PostgreSQL Tool for Node.js and NPM. You can:\n\n- Run Migrations Up or Down (Repeatable, Version, Before or After).\n- Run Arbitrary `psql` Commands by using your Project Configuration.\n- Create Database Schema Dumps by using your Project Configuration.\n- Run PostgreSQL Database Unit Tests in Functions or Procedures.\n\nUse the `pgmigrations` command to manage migrations and run database commands:\n\n```console\n\u003e npx pgmigrations --help\nUsage:\n pgmigrations [command] [switches]\n\nCommands:\nup               Run migrations migrations in order: before, before repeatable, up, repeatable, after. Optional switches: --list, --dry, --full, --dump. \ndown             Run only down migrations. Optional switches: --list, --dry, --full, --dump. \nhistory          console.log the current migration schema history.\nrun | exec       Run a command or a script file or script directory with psql. Command text or a script file is required as the second argument. Any additional arguments will be passed to a psql command.\ndump | schema    Run pg_dump command with --schema-only --encoding=UTF8 swtiches on (plus schemaDumpAdditionalArgs from the config). Any additional arguments will be passed to pg_dump command. \npsql             Run arbitrary psql command or open psql shell. Any additional arguments will be passed to a psql. \ntest             Run database tests. \nconfig           console.log the current configuration. \n\nSwitches:\n-h, --help       Show help \n--list           List available migrations in this direction (up or down) or list available database tests. \n--dry            Run in the migrations dry run mode on database in this direction (up or down). No changes will be made to the database (rollbacks changes). \n--full           Executes all migrations in this direction (up or down). Schema history will be ignored.\n--dump           Dump the SQL for the migration to the console instead of executing it.\n--verbose        Run in verbose mode. This switch applies to all commands. Default is false.\n\nConfigurations files:\n                 ./db.js from the current dir is the default configuration file. It will be ignored if not found.\n--config=[file]  Set the custom config file or multiple files (multiple --config switches). Config files are merged in the order they are provided.\n```\n\nExamples:\n\n- Execute a query:\n  \n```console\n\u003e npx pgmigrations run \"select * from city\" \n```\n\n- Execute a script:\n  \n```console\n\u003e npx pgmigrations run ./script1.sql\n```\n\n- Execute a list of sql files in a dir:\n\n```console\n\u003e npx pgmigrations run ./dir\n```\n\n- List all tables\n  \n```console\n\u003e npx pgmigrations run \\dt\n```\n\n- Display psql help\n  \n```console\n\u003e npx pgmigrations run --help\n```\n\n- Enter the psql interactive mode\n\n```console\n\u003e npx pgmigrations psql\n```\n\n- Display database schema to console\n\n```console\n\u003e npx pgmigrations dump\n```\n\n- Write database schema to file\n\n```console\n\u003e npx pgmigrations dump --file schema.sql\n```\n\n- List all available migrations\n\n```console\n\u003e npx pgmigrations up --list\n```\n\n- Run all UP migrations\n\n```console\n\u003e npx pgmigrations up\n```\n\n- Run database tests\n\n```console\n\u003e npx pgmigrations test\n```\n\nEtc.\n\nNotes:\n\nThis tool spawns `psql` or `pg_dump` external processes to execute database commands. That means, that PostgreSQL client tools must be installed on the system to be able to use this package. PostgreSQL client tools are distributed with the default installation so most likely you already have them pre-installed.\n\nIf you don't, there is an option to install client tools only:\n- On Linux systems, there is a `postgresql-client` package, the apt installation would be then: `$ apt-get install -y postgresql-client` for the latest version.\n- On Windows systems, there is an option to install client tools only in the official installer.\n\nThe `db` tool from this package will pass your configuration to the PostgreSQL tools to be able to manage the database.\n\n## Migration Naming Convention\n\n### Versioned Migrations\n\n`[prefix][version][separator][description][suffix]`\n\nVersioned migrations run once per version number in order of the versions.\n\nVersioned migrations can be:\n\n1) Version (version up).\n2) Undo (version down).\n\n`V001__my_migration.sql`\n\n`U002__undo_my_migration.sql`\n\n- `V` is a prefix for migration up. This version migration. Prefix is configurable.\n- `U` is a prefix for migration down. This undo migration. Prefix is configurable.\n- `002` is version info or the version number but it can be any text or number.\n- `__` is a separator. Separator is configurable.\n- `my_migration` and `undo_my_migration` are migration descriptions. This goes to the migration table as the description without underscores.\n- `.sql` is the migration suffix. This goes to the migration table as the type with the removed dot and in uppercase.\n\n### Repeatable Migrations\n\n`[prefix][separator][description][suffix]`\n\nRepeatable migrations can be:\n\n1) Repeatable migration: executed only once per file content. This migration will be executed only if the content is changed.\n2) Repeatable before: as the normal repeatable, only run before version migration.\n3) Before and after migrations. Migrations are executed always regardless of content.\n\nExamples:\n\n`R__my_migration.sql`\n\n`_R__my_migration.sql`\n\n`_A__my_migration.sql`\n\n`_B__my_migration.sql`\n\n\n- `R` is a prefix for repeatable migration. Prefix is configurable.\n- `_R` is a prefix for repeatable before migration. Prefix is configurable.\n- `_B` is a prefix for before migration. Prefix is configurable.\n- `_A` is a prefix for before migration. Prefix is configurable.\n- `__` is a separator. Separator is configurable.\n- `my_migration` and `undo_my_migration` are migration descriptions. This goes to the migration table as the description without underscores.\n- `.sql` is the migration suffix. This goes to the migration table as the type with the removed dot and in uppercase.\n\n### Finalize Migrations\n\nFinalize migrations have defualt prefix `TEST`. \nFinalize migrations will always be executed as a separate files, not part of of the migration transaction.\n\nThis is convinient place to keep TEST scripts.\n\n## Migration Order\n\n1) Before Migrations\n2) Repeatable Before Migrations\n3) Repeatable Migrations\n4) Versioned Migrations\n5) After Migrations\n\n## Configuration\n\nThe tool will try to read the default configuration file from the running location:  `db.js`. \n\nAdditional configuration files can be loaded with a command line switch `--config=[file]`. They will be loaded and merged in the order they appear, while the default configuration `db.js` is always first (if it exists).\n\nExample of the configuration file:\n\n```js\nmodule.exports = {\n    host: \"localhost\",\n    port: \"5432\",\n    dbname: \"dvdrental\",\n    username: \"postgres\",\n    password: \"postgres\"\n}\n```\n\nAny key in this configuration will override the default values listed below.\n\n### Server Connection\n\nOptional connection parameters such as `host`, `port`, `dbname`, `username` and `passowrd`.\n\nIf connection parameters are not set, the PostgreSQL client tools will try to get them from the environment variables, so these parameters can be set in the environment. \n\nSee the [documentation](https://www.postgresql.org/docs/current/libpq-envars.html) for more information.\n\nAlternatively, they can be set from the `.ENV` file, if the `env` option is used.\n\n### Environment\n\n#### psql\n\nSets the name of the `psql` command executable. The default is `psql`.\n\nIf the correct command executable is not in the search path you may have to set the right path manually with this configuration:\n\n- For Linux systems that would be: `/usr/lib/postgresql/{major_version}/bin/psql` \n- For Windows systems that would be: `C:\\Program Files\\PostgreSQL\\{major_version}\\bin\\psql.exe`\n\n#### pgdump\n\nSets the name of the `pg_dump` command executable. The default is `pg_dump`.\n\nIf the correct command executable is not in the search path you may have to set the right path manually with this configuration:\n\n- For Linux systems that would be: `/usr/lib/postgresql/{major_version}/bin/pg_dump` \n- For Windows systems that would be: `C:\\Program Files\\PostgreSQL\\{major_version}\\bin\\pg_dump.exe`\n\n#### schemaDumpAdditionalArgs\n\nAdditional arguments for the dump schema command that will added by default when dumping the schema. The default value is `[\"--no-owner\", \"--no-acl\"]` (skip the object owners and the access control list). This value, when set, is expected to be an array of strings.\n\n#### verbose\n\nSet to true to log additional information, including all commands issued to client tools. The default is false. This switch can also be set from the command line.\n\n#### env\n\n- Set to true to load the enviorment file from `.env` by default.\n- Set to string value to load the enviorment file from the string value.\n- Set to false to ignore enviorment file.\n- Default is true.\n\n### Migrations\n\n#### migrationDir\n\nRelative directory name where the migration files are located. This value can be a string or array of strings for the multiple directory support.\n\nThe default value is not set (empty string). This value needs to be set for every migration project.\n\n#### upDirs\n\nList of directories for versioned UP migrations. Prefix and version number is mandatory.\n\n#### downDirs\n\nList of directories for versioned DOWN migrations. Prefix and version number is mandatory.\n\n#### repetableDirs\n\nList of directories for versioned REPETABLE migrations. Prefix is mandatory.\n\n#### repetableBeforeDirs\n\nList of directories for versioned REPETABLE BEFORE migrations. Prefix is mandatory.\n\n#### beforeDirs\n\nList of directories for versioned BEFORE migrations. Prefix is mandatory.\n\n#### afterDirs\n\nList of directories for versioned AFTER migrations. Prefix is mandatory.\n\n#### keepMigrationDirHistory\n\nMigration scripts are created with a unique name in a temporary directory. Set this value to true to never delete old migration files in a temporary directory. The default value is false, temporary directory is emptied before the start of every migration.\n\n#### upPrefix\n\nUp version migration type prefix. The default is `V` (V for version).\n\n#### downPrefix\n\nDown version migration type prefix. The default is `U` (U for undo).\n\n#### repetablePrefix\n\nRepeatable migration type prefix. The default is `R` (R for repeatable).\n\n#### repetableBeforePrefix\n\nRepeatable before migration type prefix. The default is `_R` (R for repeatable).\n\n#### beforePrefix\n\nBefore migration type prefix. The default is `B`.\n\n#### afterPrefix\n\nThe after migration type prefix. The default is `A`.\n\n#### separatorPrefix\n\nSeparator prefix. The default value is `__`\n\n#### migrationExtensions: [\".sql\"],\n\nAn array of file extensions that will be considered as the migration file. The default is `[\".sql\"]`.\n\n#### allFilesAreRepetable\n\nAll files that don't have valid prefix are repetable migrations.\n\n#### recursiveDirs\n\nSearch recursively trough migration subdirectories. The default is false.\n\n#### dirsOrderedByName\n\nWhen `recursiveDirs` is true, order the migrations based on the directory first and second based on migration type. Default is true.\n\n#### dirsNaturalOrder\n\nWhen `dirsOrderedByName` is true, order directories same as Visual Studio Code Explorer would (natural order), For example:\n\n```\nbackend/auth/file1.sql\nbackend/auth/file2.sql\nbackend/schema/subdir/file1.sql\nbackend/schema/file1.sql\nbackend/file1.sql\n```\n\nDefualt is true.\n\n#### dirsOrderReversed\n\nWhen `dirsOrderedByName` is true, this will reverse order of directories. Defualt is false.\n\n#### appendTopDirToVersion\n\nIf `migrationDir` is true and versioned migration - add the top level directory name to version number,\n\nDefault is false.\n\n#### appendTopDirToVersionSplitBy\n\nIf `migrationDir` is true and versioned migration:\nsplit the top level directory name by this string and the index `appendTopDirToVersionPart` to version number.\n\nDefault is \"__\".\n\n#### appendTopDirToVersionPart\n\nIf `migrationDir` is true and versioned migration:\nsplit the top level directory name by this string and the index `appendTopDirToVersionPart` to version number.\n\nDefault is 0.\n\n#### tmpDir\n\nTemporary directory for migration scripts. The Default value is your OS temp dir plus  `./___pgmigrations`.\n\n#### historyTableSchema\n\nSchema name for the history table. If this schema doesn't exist, it will be created. The default is `pgmigrations`.\n\n#### historyTableName\n\nName of the history table. If this table doesn't exist, it will be created. The default is `schema_history`.\n\n#### skipPattern\n\nRegex pattern to skip files.\n\n#### useProceduralScript\n\nSet to true to build a migration script with procedural extensions (PL/pgSQL script). Set to false to build a normal SQL transactional script. Default is false.\n\n#### hashFunction\n\nDefault hash function used for hashing the content. The default value is the `SHA1` function:\n\n```javascript\nfunction(data) {\n    const hash = crypto.createHash('sha1');\n    hash.update(data);\n    return hash.digest('hex');\n}\n```\n\n#### sortByPath\n\nDefault: `true`.\n\nSorts non-versioned migrations by path and then by name for migrations in multiple directories.\n\n#### sortFunction\n\nDefault sort function used for sorting migration names. The default value is `sortFunction: (a, b, config) =\u003e config.sortByPath ? a.script.localeCompare(b.script, \"en\") : a.name.localeCompare(b.name, \"en\")`.\n\n#### versionSortFunction\n\nDefault sort function used for sorting migration versions. The default value is `versionSortFunction: (a, b, config) =\u003e a.version.localeCompare(b.version, \"en\", {numeric: true})`.\n\n\n#### warnOnInvalidPrefix: true\n\nDisplay warning if some migration file with the migration extension (`.sql`) doesn't have a valid prefix. This may be just some script file that can be referenced with `# script` tag. The default is false.\n\n#### parseScriptTags\n\nParses migration scripts for special tags to be executed in the build time.\n\nFor now, the only tag that is implemented is `# import \u003cfile\u003e`.\n\nWhen parses finds `# import \u003cfile\u003e` tag, it will insert the content of that file in the next lines. This can be anywhere in the migration script. For example, you would normally put this in a comment like this:\n\n```sql\n-- # import ./test.sql\n```\n\nBuild will produce:\n\n```sql\n-- # import ./test.sql\ntest.sql content\n```\n\nBut if you do this:\n\n```sql\n/*\n# import ./test.sql\n*/\n```\n\n\nBuild will produce:\n\n```sql\n/*\n# import ./test.sql\ntest.sql content\n*/\n```\n\nThe default is true.\n\n#### parseEnvVars\n\nParses the enviroment variables in migration file content by replacing ${ENVVAR} placeholders.\n\nFor example: Enviroment variable called USERNAME will have this placeholder ${USERNAME} is replaced with the actual username.\n\nNote: if you have a .env file in a root, it will be automatically loaded.\n\nThe default is true.\n\n#### runOlderVersions\n\nSet to true to run versioned migration even when higher version was applied. Default is false.\n\n### Testing\n\nTest command will run tests on PostgreSQL functions and procedures: \n\n- Test functions and procedures are required to have no parameters.\n- The test is considered passed if:\n  - Doesn't raise any exceptions.\n  - The function doesn't return either boolean False, or text `f`, or return text doesn't start with `not ok` (case insensitive).\n\nTo assert a failed test:\n- Raise custom exception with a custom message: `raise exception 'failed message';`\n- Return false: `return false;`\n- Return text that starts with \"not ok\": `return 'not ok: failed message'`\n\n#### testFunctionsSchemaSimilarTo\n\nDefault: `%test%`\n\nTest function or procedure schema that is SIMILAR TO ([see ref](https://www.postgresql.org/docs/current/functions-matching.html#FUNCTIONS-SIMILARTO-REGEXP)) this text value or `null` for all non-system schemas.\n\nThe test list returns parameterless functions and procedures that match these schemas.\n\n#### testFunctionsNameSimilarTo\n\nDefault: `null`\n\nTest function or procedure name that is SIMILAR TO ([see ref](https://www.postgresql.org/docs/current/functions-matching.html#FUNCTIONS-SIMILARTO-REGEXP)) this text (case insensitive) or `null` for all function or procedure names without parameters.\n\nThe test list returns parameterless functions and procedures that match these names.\n\n#### testFunctionsCommentSimilarTo\n\nDefault: `test`\n\nTest function or procedure comment that is SIMILAR TO ([see ref](https://www.postgresql.org/docs/current/functions-matching.html#FUNCTIONS-SIMILARTO-REGEXP)) this text (case insensitive) or `null` for all function or procedure names without parameters.\n\nThe test list returns parameterless functions and procedures that match these comments.\n\n#### testAutomaticallyRollbackFunctionTests\n\nDefault: `false`.\n\nWhen the test routine is the Function type, automatically begin and rollback transaction.\n\n#### failureExitCode\n\nReturn this error code on failure. Default is -1.\n\n#### migrationAdditionalArgs\n\nAdditional psql arguments for migration and finalization. Deafault is nothing.\n\n## Contributing\n\nContributions from the community are welcomed.\nPlease make a pull request with a description if you wish to contribute.\n\n## License\n\nThis project is licensed under the terms of the MIT license.\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnpgsqlrest%2Fpgmigrations","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnpgsqlrest%2Fpgmigrations","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnpgsqlrest%2Fpgmigrations/lists"}