Gruber

WORK IN PROGRESS — DO NOT USE

Postgres

This module provides an abstraction over postgres called PostgresService along with utilities to integrate it with other Gruber modules.

There are methods like getPostgresMigrations, executePostgresMigration and postgresBootstrapMigration to help platforms like Deno and Node.js implement a Migrator.

There is also PostgresStore that implements the Store interface.

getPostgresMigrations

Query the postgres database to find migrations that have already been performed. Returning an array of PostgresMigrationRecord.

const sql // SqlDependency
const records = await getPostgresMigrations(sql)

executePostgresMigration

Perform either the up or down postgres migration and record what happened. This will first start a transaction, so if anything goes wrong the whole operation is aborted. Within the transaction, it attempts the run the action (either up or down) as specified.

After the action is ran, it will follow up with updating the migration records. For an up action, it will create a new PostgresMigrationRecord and insert it into the database. For a down action, it will remove the corresponding PostgresMigrationRecord.

There is an edge case where it will not remove the record if running the postgresBootstrapMigration action, because that migration deletes the migration table itself so would be pointless.

const sql // SqlDependency
const definition = definePostgresMigration(...)

await executePostgresMigration(definition, "up", sql)

PostgresMigrationRecord type

A record in a postgres database containing information about a migration that has been run.

const record = {
  name: '001-add-users-table.js',
  created: new Date()
}

postgresBootstrapMigration

This is a MigrationDefinition to bootstrap postgres migrations. It sets up the initial "migrations" table that all other migrations will be recorded in.

definePostgresMigration

A typed version of defineMigration that specalizes for a PostgresService. This is mostly useful to get a strongly typed sql parameter.

import { definePostgresMigration } from "gruber"

export default definePostgresMigration({
  async up(sql) {
    await sql.execute`
      CREATE TABLE users ...
    `
  },
  async down(sql) {
    await sql.execute`
      DROP TABLE users
    `
  }
})
debug 
{
  "getPostgresMigrations": {
    "entrypoint": "postgres/mod.ts",
    "id": "getPostgresMigrations",
    "name": "getPostgresMigrations",
    "content": "Query the postgres database to find migrations that have already been performed.\nReturning an array of `PostgresMigrationRecord`.\n\n```js\nconst sql // SqlDependency\nconst records = await getPostgresMigrations(sql)\n```",
    "tags": {
      "group": "Miscellaneous"
    },
    "children": {}
  },
  "executePostgresMigration": {
    "entrypoint": "postgres/mod.ts",
    "id": "executePostgresMigration",
    "name": "executePostgresMigration",
    "content": "Perform either the **up** or **down** postgres migration and record what happened.\nThis will first start a transaction, so if anything goes wrong the whole operation is aborted.\nWithin the transaction, it attempts the run the action (either **up** or **down**) as specified.\n\nAfter the action is ran, it will follow up with updating the migration records.\nFor an **up** action, it will create a new `PostgresMigrationRecord`\nand insert it into the database.\nFor a **down** action, it will remove the corresponding `PostgresMigrationRecord`.\n\n> There is an edge case where it will not remove the record if running the `postgresBootstrapMigration` action,\n> because that migration deletes the migration table itself so would be pointless.\n\n```js\nconst sql // SqlDependency\nconst definition = definePostgresMigration(...)\n\nawait executePostgresMigration(definition, \"up\", sql)\n```",
    "tags": {
      "group": "Miscellaneous"
    },
    "children": {}
  },
  "PostgresMigrationRecord": {
    "entrypoint": "postgres/mod.ts",
    "id": "PostgresMigrationRecord",
    "name": "PostgresMigrationRecord",
    "content": "A record in a postgres database containing information about a migration that has been run.\n\n```js\nconst record = {\n  name: '001-add-users-table.js',\n  created: new Date()\n}\n```",
    "tags": {
      "group": "Miscellaneous",
      "type": "true"
    },
    "children": {}
  },
  "postgresBootstrapMigration": {
    "entrypoint": "postgres/mod.ts",
    "id": "postgresBootstrapMigration",
    "name": "postgresBootstrapMigration",
    "content": "This is a `MigrationDefinition` to bootstrap postgres migrations.\nIt sets up the initial \"migrations\" table that all other\nmigrations will be recorded in.",
    "tags": {
      "group": "Miscellaneous"
    },
    "children": {}
  },
  "definePostgresMigration": {
    "entrypoint": "postgres/mod.ts",
    "id": "definePostgresMigration",
    "name": "definePostgresMigration",
    "content": "A typed version of `defineMigration` that specalizes for a ` PostgresService`.\nThis is mostly useful to get a strongly typed `sql` parameter.\n\n```js\nimport { definePostgresMigration } from \"gruber\"\n\nexport default definePostgresMigration({\n  async up(sql) {\n    await sql.execute`\n      CREATE TABLE users ...\n    `\n  },\n  async down(sql) {\n    await sql.execute`\n      DROP TABLE users\n    `\n  }\n})\n```",
    "tags": {
      "group": "Miscellaneous"
    },
    "children": {}
  }
}