CLI

CLI

The Linked QL CLI is a beautiful little utility that comes with your Linked QL installation. It gives you a seamless command-line interface over some of Linked QL's most powerful features: Automatic Schema Savepoints and Rollbacks and Diff-Based Migrations!

The command name is linkedql.

Overview

The linkedql command operates at the scope of your Linked QL installation, and so, for non-global installation of Linked QL, you'll need the npx prefix to run. E.g.

npx linkedql commit

If you have chosen a different location for your "database" directory (where you have your schema.json and driver.js files defined) other than the default ./database location, you can use the --dir flag along with each command to point Linked QL to this location:

npx linkedql commit --dir="./src/database-stuff"

(Relative paths will resolve against your current working directory (CWD).)

To turn off prompts and get Linked QL to take a predefined sensible-default action, use the flag --yes:

npx linkedql commit --yes

Commands

linkedql commit

Interactively commit your local file changes to your DB.

What it does: looks through your local schema file and diffs against your active database structure to see what changed, and commits said changes; works interactively by default and lets you preview each query to be run.

Usage

Use the --desc flag to provide a commit description. (REQUIRED)

npx linkedql commit --desc="Initial DB creation"

(On ommitting the --desc flag, you are prompted on a db-by-db basis for a commit description. This can be useful, depending!)

Use the --select flag to explicitly list local schemas to commit:

npx linkedql commit --select=database_1,database_3 --desc="Initial DB creations"

(In this case, any changes ommitted by the selection are discarded!)

Use the --quiet flag to turn off SQL previews:

npx linkedql commit --quiet

linkedql rollback

Interactively perform a rollback operation.

What it does: loops through each database and initiates a rollback to their latest savepoint if any; works interactively by default and lets you preview each query to be run.

Usage

Use the --desc flag to provide a rollback description. (REQUIRED):

npx linkedql rollback --desc="Changes no more relevant"

(On ommitting the --desc flag, you are prompted on a db-by-db basis for a rollback description. This can be useful, depending!)

Use the --select flag to explicitly list databases to roll back:

npx linkedql rollback --select=database_1,database_3

Use the --quiet flag to turn off SQL previews:

npx linkedql rollback --quiet

linkedql rollforward

Interactively perform a rollforward operation.

What it does: loops through each database and initiates a rollforward to its latest restore point if any; works interactively by default and lets you preview each query to be run.

Usage

Use the --desc flag to provide a re-commit description. (REQUIRED)

npx linkedql rollforward --desc="Changes relevant again"

(On ommitting the --desc flag, you are prompted on a db-by-db basis for a re-commit description. This can be useful, depending!)

Use the --select flag to explicitly list databases to roll forward:

npx linkedql rollforward --select=database_1,database_3

Use the --quiet flag to turn off SQL previews:

npx linkedql rollforward --quiet

linkedql restore

Interactively perform a rollback or rollforward operation.

What it does: works as an alias of the linkedql rollback and linkedql rollforward commands.

By default, linkedql rollback is implied, but you can add the flag --forward to imply linkedql rollforward.

Usage

Use the --desc flag to provide a restore description. (REQUIRED)

npx linkedql restore --desc="Rollback description"

Use the --forward flag to specify a rollforward operation:

npx linkedql restore --forward --desc="Re-commit description"

(On ommitting the --desc flag, you are prompted on a db-by-db basis for a restore description. This can be useful, depending!)

Use the --select flag to explicitly list databases to restore:

npx linkedql restore --select=database_1,database_3

Use the --quiet flag to turn off SQL previews:

npx linkedql restore --quiet

linkedql refresh

Refresh local schema file.

What it does: updates your local schema file to reflect current state of the DB (with local file changes that have not been committed discarded).

Usage

npx linkedql refresh

Use the --select flag to explicitly list schemas to refresh:

npx linkedql refresh --select=database_1,database_3

Use the --live flag to automatically refresh in realtime for changes made by other Linked QL clients:

npx linkedql refresh --live

linkedql generate

Generate arbitrary schemas into local schema file

What it does: generates schemas not yet managed by Linked QL into local schema file.

Usage

npx linkedql generate

Use the --select flag to explicitly list schemas to generate:

npx linkedql generate --select=database_1,database_3

linkedql savepoints

View all latest savepoints across databases.

What it does: displays a table of the latest savepoints across databases.

Usage

npx linkedql savepoints

Use the --select flag to explicitly list schemas to display:

npx linkedql savepoints --select=database_1,database_3

Use the --forward flag to specify a forward lookup:

npx linkedql savepoints --forward

linkedql dump-histories

Dump database histories to a local histories file.

What it does: dumps all database histories to a local histories file: histories.json (or histories.yml if found already exists); typically used in combination with linkedql replicate to perform a migration.

Usage

npx linkedql dump-histories

linkedql clear-histories

Permanently erase savepoint histories.

What it does: irreversibly deletes savepoint records for all databases.

Usage

Use the --select flag to explicitly list histories to clear. (REQUIRED)

npx linkedql clear-histories --select=database_1,database_3

npx linkedql clear-histories --select=*

linkedql replicate

Replicate schema histories in a second database.

What it does: diffs two database instances by schema histories and replicates any changes in first database in second database; typically used for migration.

Concepts

Target and origin databases

• Target database: the database where changes are to be replicated; typically, your production database.
• Origin database: the database where changes have been made; typically, your development database.

Online and offline replication

• Online replication: "target database" replicates "origin database" using "origin database"'s Linked QL client. This is applicable where "origin database" is reachable from "target database"; e.g. where both databases are online databases or where both are local databases.

  Here, you export the additional database client (i.e. the "origin database"'s Linked QL client) from your driver.js file as origin:

  ./database/driver.js

  export default async function() {
      return // your default Linked QL client (being the "target database")
  }
  export async function origin() {
      return // your origin Linked QL client (being the "origin database")
  }

• Offline replication: "target database" replicates "origin database" using "origin database"'s histories dump.

  Here, you have your "origin database"'s histories dumped ahead of replication, typically during your application's build process:

  ./package.json

  {
      "scripts": {
          "build": "linkedql dump-histories && other things"
      }
  }

Replication

The final execution of the linkedql replicate command, typically done as part of your application's deployment process:

./package.json

{
    "scripts": {
        "deploy": "linkedql replicate --origin && other things"
    }
}

Usage

For online replication, use the --origin flag. (REQUIRED)

npx linkedql replicate --origin

Use the --swap flag to have the databases switch roles:

npx linkedql replicate --origin --swap

For offline replication, use the --histories flag. (REQUIRED)

npx linkedql replicate --histories