{"id":16401074,"url":"https://github.com/flodlc/pg-mate","last_synced_at":"2025-07-15T01:06:17.705Z","repository":{"id":143196673,"uuid":"606147769","full_name":"flodlc/pg-mate","owner":"flodlc","description":"First class migrations for PostgreSQL. Typescript friendly, zapatos friendly, zero-abstraction friendly.","archived":false,"fork":false,"pushed_at":"2023-03-24T16:11:16.000Z","size":176,"stargazers_count":10,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-21T23:33:11.224Z","etag":null,"topics":["database","knex","migrations","node","nodejs","pg","postgresql","typescript","zapatos"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/pg-mate","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/flodlc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2023-02-24T17:55:18.000Z","updated_at":"2024-09-08T17:52:29.000Z","dependencies_parsed_at":null,"dependency_job_id":"c5ff0132-4c4b-4194-a822-d6cb109feb45","html_url":"https://github.com/flodlc/pg-mate","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/flodlc/pg-mate","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flodlc%2Fpg-mate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flodlc%2Fpg-mate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flodlc%2Fpg-mate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flodlc%2Fpg-mate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/flodlc","download_url":"https://codeload.github.com/flodlc/pg-mate/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flodlc%2Fpg-mate/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265383050,"owners_count":23756461,"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":["database","knex","migrations","node","nodejs","pg","postgresql","typescript","zapatos"],"created_at":"2024-10-11T05:29:21.351Z","updated_at":"2025-07-15T01:06:17.650Z","avatar_url":"https://github.com/flodlc.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003ePg-mate\u003c/h1\u003e\n\u003cp align=\"center\"\u003e\u003ca href=\"https://git.io/typing-svg\"\u003e\u003cimg src=\"https://readme-typing-svg.demolab.com?font=Fira+Code\u0026size=18\u0026duration=2000\u0026pause=2000\u0026center=true\u0026width=450\u0026height=80\u0026lines=First+class+migrations+for+PostgreSQL.\" alt=\"Typing SVG\" /\u003e\u003c/a\u003e\u003c/p\u003e\n\n### Pg-mate is a migration management tool for PostgreSQL databases with the following features:\n\n- Up and down migrations\n- Customizable client injection for migrations (native pg driver, zapatos, or any other client you want)\n- First-class CLI and programmatic usage\n- Fully written in TypeScript\n\n---\n\nTable of Contents:\n\n- [Installation](#installation)\n- [Setup](#setup)\n- [Programmatic Usage](#programmatic-usage)\n- [Using the CLI with ts-node](#using-the-cli-with-ts-node)\n- [Using the CLI with node](#using-the-cli-with-node)\n- [Configuration](#configuration)\n- [Commands](#commands)\n  - [Creating a Migration](#creating-a-migration)\n  - [Running Migrations](#running-migrations)\n  - [Rolling Back Migrations](#rolling-back-migrations)\n  - [Refreshing the Index](#refreshing-the-index)\n\n---\n\n## Installation\n\nTo get started, install Pg-mate using npm or yarn:\n\n```sh\nnpm install pg-mate\n# or\nyarn add pg-mate\n```\n\n## Setup\n\nNext, create a migrations directory with the following structure:\n\n```\nmigrations\n  ├── index.ts\n  └── pg-mate.ts\n```\n\nIn migrations/index.ts, add the following code:\n\n```typescript\n// migrations/index.ts:\nexport const migrations = {};\n```\n\nIn migrations/pg-mate.ts, add the following code:\n\n```typescript\n// migrations/pg-mate.ts:\nimport { pgMate, PgMateConfig } from \"pg-mate\";\nimport { migrations } from \"./index\";\n\nexport const config: PgMateConfig = {\n  connexionUrl: \"postgresql://postgres:password@localhost:5432/postgres\",\n  migrationImports: migrations,\n  migrationDir: __dirname,\n  esm: false,\n  ts: true,\n};\npgMate.cli(config);\n```\n\n\u003e Note that `pgMate.cli(config);` enables the use of this file as a CLI\n\n## Programmatic Usage\n\nTo use pg-mate programmatically:\n\n```typescript\nimport { pgMate } from \"pg-mate\";\nimport { config } from \"./migrations/pg-mate\";\n\n(async () =\u003e {\n  const pgMateClient = await pgMate.init(config);\n  await pgMateClient.migrate();\n})();\n```\n\n## Using the CLI with ts-node\n\nYou can use ts-node to execute `pg-mate.ts` directly:\n\n```sh\nts-node pg-mate.js \u003ccommand\u003e\n```\n\nIf your `package.json` is configured for `commonjs`, it should work easily.  \nIf it's configured for `modules`, you will need to add the `--esm` flag:\n\n```sh\nts-node --esm pg-mate.js \u003ccommand\u003e\n```\n\n## Using the CLI with node\n\nYou can compile the `pg-mate.ts` file as you would with your app. Then, invoke the CLI as follows:\n\n```sh\nnode dist/pg-mate.js \u003ccommand\u003e\n```\n\n---\n\n## Configuration\n\nBelow is the `PgMateConfig` definition with default values:\n\n```typescript\ntype PgMateConfig = {\n  /**\n   * Exemple: \"postgresql://postgres:password@localhost:5432/postgres\"\n   */\n  connexionUrl: string;\n  /**\n   * Allows injecting a custom db client in migration functions.\n   * Default: native pg driver\n   * Exemple: () =\u003e knexClient\n   */\n  getClient?: () =\u003e Promise\u003cany\u003e;\n  /**\n   * Should not be modified except for very specific reasons.\n   * Default: __dirname\n   */\n  migrationDir: string;\n  /**\n   * Must be the migrations import (required)\n   */\n  migrationImports: MigrationFiles;\n  /**\n   * If type: \"module\" in package.json =\u003e true\n   * Default: false\n   */\n  esm?: boolean;\n  /**\n   * Used to use the correction extension in migrations directory.\n   * Default: false\n   */\n  ts?: boolean;\n};\n```\n\n## Commands\n\n### Creating a Migration\n\n```sh\npgMateClient.create({ name: 'hello' })\n# or\nnode pg-mate.js create \u003cname\u003e\n# or\nts-node pg-mate.ts create \u003cname\u003e\n```\n\n```typescript\nimport { Client } from \"pg\";\n\nexport const up = async (pg: Client) =\u003e {\n  pg.query(`\n        CREATE TABLE users(\n            id SERIAL PRIMARY KEY,\n            name varchar NOT NULL\n        );\n    `);\n};\n\nexport const down = async (pg: Client) =\u003e {\n  pg.query(`DROP TABLE users;`);\n};\n```\n\n### Running Migrations\n\nTo run migrations, use the following command:\n\n```sh\npgMateClient.migrate()\n# or\nnode pg-mate.js migrate\n# or\nts-node pg-mate.ts migrate\n```\n\n### Rolling Back Migrations\n\nTo rollback a migration, use the following command:\n\n```sh\npgMateClient.rollback()\n# or\nnode pg-mate.js rollback\n# or\nts-node pg-mate.ts rollback\n```\n\n### Refreshing the Index\n\nThe migrations are imported using the index file in the migrations directory. This file is automatically updated after a new migration is created.  \nIf needed, the refreshIndex command can trigger an update of the index.\n\n\u003e In the index, migrations should be listed in the same order as the migration files (alphabetical-ordered).  \n\u003e If the index is corrupted, an exception will be thrown during command execution.\n\n```sh\npgMateClient.refreshIndex()\n# or\nnode pg-mate.js refreshIndex\n# or\nts-node pg-mate.ts refreshIndex\n```\n\n---\n\nThat's it! You can now use pg-mate to manage your Postgresql database migrations.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflodlc%2Fpg-mate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fflodlc%2Fpg-mate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflodlc%2Fpg-mate/lists"}