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. |