A collection of +180 reusable WebAssembly modules for building composable CI/CD pipelines with FluentCI fluentci.io/modules
2 folders · 18 files

src
test
.gitignore
build.mjs
COMMANDS.md
COMPONENT.md
entry.mjs
fluentci-module.toml
fluentci.lock
legacy-entry.mjs
legacy-schema.json
LICENSE
module-dependencies.json
OPTIONS.md
package-lock.json
package.json
README.md
schema.json
spago.lock
spago.yaml
README.md

pgroll #

Run PostgreSQL schema migrations through typed PureScript Wasm functions in CI/CD pipelines. Requires FluentCI v0.17.3+ and an installed pgroll CLI. Use setup-pgroll to install it.

fluentci run setup-pgroll setup --version 0.16.3
# Set PGROLL_PG_URL from the runner's secret environment first.
fluentci run pgroll init --run-dir /tmp/pgroll-init
fluentci run pgroll validate --file migrations/001.yaml --run-dir /tmp/pgroll-validate
fluentci run pgroll start --file migrations/001.yaml --run-dir /tmp/pgroll-start
# Deploy and verify the application before completing the active migration.
fluentci run pgroll complete --run-dir /tmp/pgroll-complete

For directory-based workflows, migrate --directory migrations applies outstanding migrations. The final migration stays active by default; pass --complete to complete it, or --expect-one to reject more than one pending migration. rollback reverts an active migration under pgroll's native limitations. A completed migration cannot be treated as an arbitrary reversible deployment history.

Functions also cover status, analyze, pull, baseline, convert, update, create, and latest-migration, latest-schema, and latest-url. create requires --name and always supplies --empty to avoid interactive operation selection. baseline --baseline-version NAME --directory DIR always supplies --yes: invoking it resets migration history and creates a placeholder file. update rewrites migration files in place. Review generated files before use.

init and complete do not require files despite upstream's historical help synopsis. Existing migration/SQL files and input directories are checked before execution. pull and baseline let pgroll create their destination directories. Migration validation uses PostgreSQL; it is not an offline syntax checker.

Configuration and complete CLI access #

Use inherited PGROLL_PG_URL for the database connection, with TLS and permissions appropriate to the migration. Native configuration also supports PGROLL_SCHEMA, PGROLL_STATE_SCHEMA, PGROLL_LOCK_TIMEOUT, PGROLL_ROLE, PGROLL_USE_VERSION_SCHEMA, and PGROLL_VERBOSE. Named functions expose the matching optional arguments, including --lock-timeout, --schema, --state-schema, and --use-version-schema=false. Omitted options retain native defaults. Explicit --postgres-url is available, but embeds the URL in the plan; secret environment variables remain inherited and are not serialized by the module.

All public lists are comma-separated strings. Each operation accepts additional literal tokens through --arguments; run accesses every native command, flag, or future feature. latest and completion expose their native subcommands.

fluentci run pgroll latest-schema --local migrations --run-dir /tmp/pgroll-schema
fluentci run pgroll create --name migrations/002_accounts --json --run-dir /tmp/pgroll-create
fluentci run pgroll run --arguments status,--verbose --run-dir /tmp/pgroll-native

Double-quote CSV entries containing commas and double embedded quotes. Shell-quote the whole CSV value when calling from a shell. Tokens are passed literally without shell expansion. Blank optional lists add no tokens; malformed or empty entries fail before host commands. Interactive native commands remain available through run and require a suitable runner lifecycle.

Results and prerequisites #

Each invocation requires a fresh --run-dir. --project selects the working directory; --timeout-ms defaults to 900000. Functions return typed execution outcome, report, stdout, and stderr paths. Nonzero exits, timeouts, transport errors, and cancellations fail the call. Use --artifacts migration=migrations/002_accounts.json to collect a generated file and its size/hash. latest-url can emit database credentials; control retention of its output and reports.

The adapter accepts Linux, macOS, FreeBSD, NetBSD, and OpenBSD when a compatible CLI is available. Database connectivity, PostgreSQL compatibility, permissions, and pgroll installation remain runner prerequisites. Setup does not install or start PostgreSQL. pgroll controls migration/backfill behavior; the wrapper does not independently guarantee a lock-free or zero-downtime rollout.

See COMPONENT.md for typed arguments and results, OPTIONS.md for native mappings, and COMMANDS.md for reviewed command coverage. Upstream pgroll · MIT wrapper license.

Setup component dependency #

This module declares setup-pgroll as typed native component dependencies. FluentCI v0.17.3+ resolves their source references while building and composes them into the published Wasm. Consumers need no relative source paths. Available tools are reused; missing prerequisites invoke setup with default arguments. Explicit executable overrides remain caller-managed. Configure pinned versions or privileged/custom installations in an earlier setup step. See dependency behavior and publishing for command-specific prerequisites, validation, credential skips, and CI coverage.

Compose this module from code #

Requires FluentCI 0.17.6 or newer for generated pipeline bindings. From your caller module's directory, add the dependency:

fluentci add pgroll --path /path/to/fluentci-modules/databases/pgroll

For a published module, use fluentci add @fluentci.io/pgroll@VERSION with an available version. Commit the caller's manifest and lockfile. FluentCI generates named bindings from the installed component's WIT; no handwritten FFI or CLI subprocess is needed. Include generated source directories in the caller's SDK project. The callee can use a different SDK from the caller.

Validate a migration file against the target database before application.

Replace the sample organization, paths and identifiers with your own. Configure credentials through your CI secret provider before running authenticated operations. Optional arguments use the callee's defaults, and public list fields use comma-separated strings. See COMPONENT.md for argument descriptions and return types.

These examples use the generated composition API and builder chaining in FluentCI 0.17.6; full cross-SDK compilation and execution coverage is still pending. See composition support and limitations.

PureScript #

module Main where

import Prelude
import Effect (Effect)
import FluentCI.Flow as Flow
import FluentCI.Modules.Pgroll as Pgroll

run :: Effect String
run =
  Flow.pipeline "pgroll-validate"
    # Flow.workdir "."
    # Pgroll.validate (Pgroll.validateArgs { "file": "dist/app.tar.gz" })
    # Flow.map (\result -> result.reportPath)
    # Flow.run

Gleam #

import fluentci/flow
import fluentci_modules/pgroll

pub fn run() -> String {
  flow.pipeline("pgroll-validate")
  |> flow.workdir(".")
  |> pgroll.validate(pgroll.validate_args("dist/app.tar.gz"))
  |> flow.map(fn(result) { result.report_path })
  |> flow.run
}

Use Gleam's JavaScript target for the Wasm guest. BEAM escripts used for repository automation are separate from component guests.

Elixir #

defmodule Main do
  use FluentCI.Plugin
  alias FluentCI.Flow
  alias FluentCI.Modules.Pgroll

  defplugin run do
    Flow.pipeline("pgroll-validate")
    |> Flow.workdir(".")
    |> Pgroll.validate(%{"file" => "dist/app.tar.gz"})
    |> Flow.stdout()
  end
end

Elixir compiles this sequence to Rust/Wasm. Its initial Flow API does not yet provide the typed result callbacks or cleanup combinators of the other examples.

ClojureScript #

(ns main.plugin
  (:require [fluentci.flow :as flow]
            [fluentci-modules.pgroll :as pgroll]))

(defn run []
  (-> (flow/pipeline "pgroll-validate")
      (flow/workdir ".")
      (pgroll/validate {:file "dist/app.tar.gz"})
      flow/run!))

ReScript #

let run = (): string =>
  Flow.pipeline("pgroll-validate")
  ->Flow.workdir(".")
  ->FluentciModulesPgroll.validate(FluentciModulesPgroll.validateArgs(~file="dist/app.tar.gz"))
  ->Flow.map(result => result.reportPath)
  ->Flow.run

Python #

from fluentci.flow import pipeline
from fluentci_modules import pgroll


def run() -> str:
    return (
        pipeline("pgroll-validate")
        .workdir(".")
        .pipe(pgroll.validate, {"file": "dist/app.tar.gz"})
        .map(lambda result: result.report_path)
        .run()
    )

TypeScript #

import * as flow from "./fluentci_modules/flow";
import * as pgroll from "./fluentci_modules/pgroll/index";

export function run(): string {
  return flow.pipeline("pgroll-validate")
    .workdir(".")
    .pipe(pgroll.validate, {"file":"dist/app.tar.gz"})
    .map(result => result.reportPath)
    .run();
}

Python and TypeScript use FluentCI builder chains: .pipe(module.function, args) composes generated module functions with .workdir, .env, and .exec. Functions return a pipeline carrying their typed result. Use a generated result callback (With/_with, or a callback argument in TypeScript/Python) when a later module needs a preceding result; use Flow's map operation to select a result field. Execution begins at run (or the Elixir plugin terminal), in declared order.

Exported functions #

Function Purpose
run Execute any pgroll feature with literal CSV arguments.
version Print the installed pgroll version.
init Initialize pgroll state in the target database; no migration file is required.
validate Validate a migration file against the target database before application.
start Start a migration, backfill data, and optionally complete it.
complete Complete the currently active migration in the database; no migration file is required.
rollback Roll back the currently active migration; completed migrations retain native rollback limitations.
migrate Apply outstanding migrations from a directory and propagate native failures.
status Report active migration and schema state in the target database.
analyze Analyze the target database SQL schema using the native hidden diagnostic command.
baseline Reset migration history to a baseline and write its placeholder file without a confirmation prompt.
pull Pull missing migration history from the database into local files.
convert Convert SQL statements from a file to a pgroll migration using native conversion rules.
update Rewrite outdated migration files in place; review changes before committing them.
create Create an empty named migration file noninteractively in the working directory.
latest Access native latest subcommands through the CSV arguments string.
latest_migration Print the latest migration from the target database or local migration directory.
latest_schema Print the latest schema from the target database or local migration directory.
latest_url Print the latest connection URL with version schema search_path from the target database or local migration directory.
completion Generate shell completion scripts through literal native CSV arguments.