Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/salsita/node-pg-migrate
Node.js database migration management for PostgreSQL
https://github.com/salsita/node-pg-migrate
api cockroach cockroachdb database db db-migrate expandable extensible migrate migration migrations migrator pg postgre postgres postgresql programable programatic sql
Last synced: 4 days ago
JSON representation
Node.js database migration management for PostgreSQL
- Host: GitHub
- URL: https://github.com/salsita/node-pg-migrate
- Owner: salsita
- License: mit
- Created: 2014-03-13T23:09:22.000Z (almost 11 years ago)
- Default Branch: main
- Last Pushed: 2024-12-09T18:09:04.000Z (4 days ago)
- Last Synced: 2024-12-09T19:21:16.827Z (4 days ago)
- Topics: api, cockroach, cockroachdb, database, db, db-migrate, expandable, extensible, migrate, migration, migrations, migrator, pg, postgre, postgres, postgresql, programable, programatic, sql
- Language: TypeScript
- Homepage: https://salsita.github.io/node-pg-migrate
- Size: 4.51 MB
- Stars: 1,301
- Watchers: 14
- Forks: 180
- Open Issues: 65
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# node-pg-migrate
> The core maintainer of this project moved to [@Shinigami92](https://github.com/Shinigami92) (also core maintainer of FakerJS and core member of Vite).
> The project is and remains under the MIT license.
[](https://www.npmjs.com/package/node-pg-migrate)
[](https://www.npmjs.com/package/node-pg-migrate)
[](https://github.com/salsita/node-pg-migrate/actions/workflows/ci.yml)
[](https://github.com/salsita/node-pg-migrate/actions/workflows/postgres-test.yml)
[](https://github.com/salsita/node-pg-migrate/actions/workflows/cockroach-test.yml)
Node.js database migration management built exclusively for postgres. (But can also be used for other DBs conforming to SQL standard - e.g. [CockroachDB](https://github.com/cockroachdb/cockroach).)
Started by [Theo Ephraim](https://github.com/theoephraim/), then handed over to [Salsita Software](https://www.salsitasoft.com/) and now maintained by [@Shinigami92](https://github.com/Shinigami92).
## Preconditions
- Node.js 18 or higher
- PostgreSQL 12.8 or higher (lower versions may work but are not supported officially)
If you don't already have the [`pg`](https://node-postgres.com/) library installed, you will need to add pg as either a direct or dev dependency
```bash
npm add pg
```
## Installation
```bash
npm add --save-dev node-pg-migrate
```
Installing this module adds a runnable file into your `node_modules/.bin` directory. If installed globally (with the -g option), you can run `node-pg-migrate` and if not, you can run `./node_modules/.bin/node-pg-migrate.js`
## Quick Example
Add `"migrate": "node-pg-migrate"` to `scripts` section of your `package.json` so you are able to quickly run commands.
Run `npm run migrate create my-first-migration`. It will create file `xxx_my-first-migration.js` in `migrations` folder.
Open it and change contents to:
```js
exports.up = (pgm) => {
pgm.createTable('users', {
id: 'id',
name: { type: 'varchar(1000)', notNull: true },
createdAt: {
type: 'timestamp',
notNull: true,
default: pgm.func('current_timestamp'),
},
});
pgm.createTable('posts', {
id: 'id',
userId: {
type: 'integer',
notNull: true,
references: '"users"',
onDelete: 'cascade',
},
body: { type: 'text', notNull: true },
createdAt: {
type: 'timestamp',
notNull: true,
default: pgm.func('current_timestamp'),
},
});
pgm.createIndex('posts', 'userId');
};
```
Save migration file.
Now you should put your DB connection string to `DATABASE_URL` environment variable and run `npm run migrate up`.
(e.g. `DATABASE_URL=postgres://test:test@localhost:5432/test npm run migrate up`)
You should now have two tables in your DB :tada:
If you want to change your schema later, you can e.g. add lead paragraph to posts:
Run `npm run migrate create posts_lead`, edit `xxx_posts_lead.js`:
```js
exports.up = (pgm) => {
pgm.addColumns('posts', {
lead: { type: 'text', notNull: true },
});
};
```
Run `npm run migrate up` and there will be a new column in `posts` table :tada:
Want to know more? Read docs:
## Docs
Full docs are available at https://salsita.github.io/node-pg-migrate
## Explanation & Goals
_Why only Postgres?_ - By writing this migration tool specifically for postgres instead of accommodating many databases, we can actually provide a full featured tool that is much simpler to use and maintain. I was tired of using crippled database tools just in case one day we switch our database.
_Async / Sync_ - Everything is async in node, and that's great, but a migration tool should really just be a fancy wrapper that generates SQL. Most other migration tools force you to bring in control flow libraries or wrap everything in callbacks as soon as you want to do more than a single operation in a migration. Plus by building up a stack of operations, we can automatically infer down migrations (sometimes) to save even more time.
_Naming / Raw Sql_ - Many tools force you to use their constants to do things like specify data types. Again, this tool should be a fancy wrapper that generates SQL, so whenever possible, it should just pass through user values directly to the SQL. The hard part is remembering the syntax of the specific operation, not remembering how to type "timestamp"!
## Contributing
[](https://github.com/salsita/node-pg-migrate/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) [](https://github.com/salsita/node-pg-migrate/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) [](https://github.com/salsita/node-pg-migrate/pulls?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) [](https://github.com/salsita/node-pg-migrate/issues?q=is%3Aopen)
👋 **Welcome, new contributors!**
Whether you're a seasoned developer or just getting started, your contributions are valuable to us. Don't hesitate to jump in, explore the project, and make an impact.
## License
[MIT](./LICENSE)