Use Node and databases? Want to do smart architecture decisions? Do not invent wheel, use Liquibase.
Liquibase is an open-source database-independent library for tracking, managing and applying database schema changes.
For a drastically smaller version of this package, be sure to check out our Zero-Dependency Peer-Dependency version. You can access this version under the tag @pd for Peer Dependency. This version of the package boasts an unpacked size of 359 kB. Just be sure to correctly configure your project!
- Installation
- Sandbox
- Usage
- Features
- Bundled Releases
- Peer Dependency (@pd)
- Want to Help?
- Getting More Knowledge About Liquibase
- Liquibase CLI
There is an easy way to integrate Liquibase power to Node application. All you need is NPM package.
yarn add liquibaseor:
$ NPM install --save liquibase"If this isn't making sense, it doesn't make it lies." (Cornell, 1994).
We have also provided a Small Sandbox Project where you can easily evaluate Liquibase and node-liquibase against a Postgres Database.
The Sandbox project includes startup scripts, and examples to demonstrate how to use node-liquibase in TypeScript, JavaScript, and as a CLI tool.
Liquibase support rich pool of commands to keep your database up-to-date, like update, rollback, diff check out full list here: https://docs.liquibase.com/commands/home.html.
This package exposes both a CLI tool and a Library to help you in your Database Migration efforts!
You can use this NPM package as a CLI tool under the namespace node-liquibase if you wish.
node-liquibase
--changeLogFile="/path/to/my/changelog.xml"
--url="jdbc:postgresql://localhost:5432/postgres"
--username="yourusername"
--password="yoursecurepassword"
--classpath="/Users/me/path/to/my/db-drivers/postgresql-42.2.8.jar"
statusnode-liquibase /Users/me/path/to/my/executable/for/liquibase
--changeLogFile="/path/to/my/changelog.xml"
--url="jdbc:postgresql://localhost:5432/postgres"
--username="yourusername"
--password="yoursecurepassword"
--classpath="/Users/me/path/to/my/db-drivers/postgresql-42.2.8.jar"
statusimport {
LiquibaseConfig,
Liquibase,
POSTGRESQL_DEFAULT_CONFIG,
} from 'liquibase';
const myConfig: LiquibaseConfig = {
...POSTGRESQL_DEFAULT_CONFIG,
url: 'jdbc:postgresql://localhost:5432/node_liquibase_testing',
username: 'yourusername',
password: 'yoursecurepassword',
};
const instance = new Liquibase(myConfig);
async function doEet() {
await instance.status();
// await instance.update();
// await instance.dropAll();
}
doEet();const Liquibase = require('liquibase').Liquibase;
const POSTGRESQL_DEFAULT_CONFIG = require('liquibase').POSTGRESQL_DEFAULT_CONFIG;
const myConfig = {
...POSTGRESQL_DEFAULT_CONFIG,
changeLogFile: './changelog.xml',
url: 'jdbc:postgresql://localhost:5432/node_liquibase_testing',
username: 'yourusername',
password: 'yoursecurepassword',
}
const instTs = new Liquibase(myConfig);
instTs.status();The previous project did not have the greatest experience for TypeScript environments. In addition, one of our goals was improving the DX for JavaScript engineers as well. Luckily, a lot of popular Text Editors are improving their IntelliSense featuresets.
With the new package you can will get:
- Liquibase command documentation right at your fingertips
- Liquibase command Parameter documentation
- Liquibase CLI Command API Parity
node-liquibase.mp4
In order to keep the DX as smooth as possible without deprecating the project that inspired the re-write, we've provided both an NPM package and a CLI tool. We did this by transpiling both an ES Module and a Common JS module in the dist code. The Node CLI of this package can be used with node-liquibase.
However, when importing the modules to use them in a JavaScript or TypeScript file, be sure to import from the correct module name: liquibase. We are forced to keep this package name for now due to dependent projects.
We were careful to ensure that all 'top level' Liquibase commands are implemented in this package. No more magic strings!
Here's a complete listing of commands that have been implemented.
WIP
The original fork of this project has been left intact to give credit where credit is due. As an Organization, Liquibase can be summarized as follows: No punks, no jerks. Because of this, we cannot ignore pablodenadai/node-liquibase. It was these efforts that ultimately led to the decision to improve on that project.
At Liquibase we are avid TypeScript users, so naturally we expect the developer experience we're accustomed to out of our own packages. In order to provide the DX we would want, we needed to rethink how this library was implemented.
Adding TypeScript support was at the core of this.
Magic strings, while functional, are error prone. Instead of passing a string of the command and parameters to Liquibase, we've replicated the top level Liquibase CLI API within this package.
Our aim is to provide a more stable and guided API for new Liquibase users operating in a Node context.
This means no more of this:
liquibase.run('status');and more of this:
liquibase.status();In order to make installation of Liquibase easier for people who are new to the Liquibase toolset, we've chosen to release 'bundled' versions of this project, node-liquibase. This means that if you are beholden to a particular version of Liquibase Core you will be able to install a related specific version of node-liquibase and have Liquibase Core ready at your fingertips.
This makes the assumption that a consumer of node-liquibase wants that. If this is not true and you prefer to make use of a more peer dependency type of experience, we offer a version of node-liquibase that DOES NOT bundle an associated version of Liquibase Core.
Because Liquibase Core and node-liquibase both use a similar versioning strategy, and because NPM requires a version number bump for even the smallest change, there will not be 100% alignment between the version numbers of each project.
It is safe to assume that the Major and Minor version numbers between the two projects will match on any given npm installation of node-liquibase.
For example:
- Let's assume you are required to use Liquibase Core
v4.3.3 node-liquibasereleased4.3.3alongside Liquibase Core, but needed to update documentation after the factnode-liquibasepatches its version number and releases4.3.4- As a User, you could run
yarn add liquibase@4.3which would install the latest patch version of4.3in this case4.3.4 - The "Bundled Liquibase" version would still be
4.3.3butnode-liquibasewould be4.3.4
If you wish to opt-out of the "Bundled Version" you can check out our Peer Dependency release.
In order to use this p[eer]-d[ependency] version of node-liquibase you can install with:
yarn add liquibase@pdor
npm i liquibase@pdDepending on your implementation method of choice (TS, JS, or CLI), you will need to let node-liquibase know where it can find your liquibase executable. This should be an absolute path to the executable.
Additionally, we removed the bundled drivers from the @pd release to further reduce the size of your node_modules. There is a chance you will need to update your configurations to provide an absolute path on the classpath property to the drivers you need.
Using the liquibase property on your config object.
import { Liquibase, LiquibaseConfig, POSTGRESQL_DEFAULT_CONFIG } from 'liquibase';
const myConfig: LiquibaseConfig = {
...POSTGRESQL_DEFAULT_CONFIG,
changeLogFile: './changelog.xml',
url: 'jdbc:postgresql://localhost:5432/node_liquibase_testing',
username: 'yourusername',
password: 'yoursecurepassword',
}
const inst = new Liquibase(myConfig);
inst.status();import { Liquibase, LiquibaseConfig, POSTGRESQL_DEFAULT_CONFIG } from 'liquibase';
const myConfig: LiquibaseConfig = {
...POSTGRESQL_DEFAULT_CONFIG,
changeLogFile: './changelog.xml',
url: 'jdbc:postgresql://localhost:5432/node_liquibase_testing',
username: 'yourusername',
password: 'yoursecurepassword',
liquibase: 'Users/me/absolute/path/to/executable/directory'
}
const inst = new Liquibase(myConfig);
inst.status();Using the --liquibase flag on your CLI command.
yarn node-liquibase --changeLogFile="changelog.xml" --url="jdbc:postgresql://localhost:5432/node_liquibase_testing" --username="yourusername" --password="yoursecurepassword" --classpath="/Users/me/path/to/my/db-drivers/postgresql-42.2.8.jar" statusyarn node-liquibase --liquibase="Users/me/absolute/path/to/executable/directory" --changeLogFile="changelog.xml" --url="jdbc:postgresql://localhost:5432/node_liquibase_testing" --username="yourusername" --password="yoursecurepassword" --classpath="/Users/me/path/to/my/db-drivers/postgresql-42.2.8.jar" statusIf you'd like to see a working setup of liquibase@pd be sure to check out the peer-dependency branch of the Node Liquibase Sandbox. You can see a diff of the two approaches (Bundled v. Peer) Here
This project needs some work on the infrastructure and build tooling side. For now the workflow to test an 'end user ready' version of the project, you'll first need to build/compile the code, and then you can run it using the Node CLI's REPL node path/to/something.js.
There is an issue in path resolution within THIS application code in addition to the complexities in Liquibase Core. Until this is resolved the resolved path for the Liquibase executable will differ between compiled and source code. This will affect your experience if you try to transpile the code on the fly using ts-node. I have not resolved the issue yet.
To build all of the things:
yarn buildRun tests with:
yarn testTo substitute your own user/pass for a given environment, make a copy of .env.example in root directory as .env and update accordingly.