Workflo...er::DBI(3)

Workflow::Persister::DBI 💖

okay bestie so this is Workflow::Persister::DBI — and it lives in the User Contributed Perl Documentation section of your man pages, filed under section 3 (library calls, iykyk). It's the main character that persists your workflows and workflow history into a DBI database. 💅

---

✨ VERSION ✨

This documentation describes version 2.09 of this package. 🎀

---

🦋 SYNOPSIS 🦋

# persister.yaml
persister:
- name: MainDatabase
  class: Workflow::Persister::DBI
  dsn: DBI:mysql:database=workflows
  user: wf
  password: mypass
- name: BackupDatabase
  class: Workflow::Persister::DBI
  user: wf
  password: mypass
  date_format: '%Y-%m-%d %H:%M'
  autocommit: 0
  workflow_table: wf
  workflow_sequence: wf_seq
  history_table: wf_history
  history_sequence: wf_history_seq
- name: OtherDatabase
  class: My::Persester::DBHFromElsewhere
  driver: mysql

---

🌸 DESCRIPTION 🌸

This is the main persistence class — it stores your workflow and your workflow history records into a DBI-accessible datasource. That's the whole vibe. 💖

🫶 Subclassing: Getting handle from elsewhere

A super common reason to make a subclass is that you already have a database handle that was created some other way. Like, LedgerSMB (https://ledgersmb.org/) has a centrally managed database connection. So you can make a subclass that hands over the database handle from the central storage location LedgerSMB::App_State. Sample implementation below, bestie:

package Workflow::Persister::DBI::LedgerSMB_Handle;

use strict;
use parent qw( Workflow::Persister::DBI );
use LedgerSMB::App_State;

# override parent method, assuming that we set the 'datasource'
# parameter in the persister declaration

sub init {
   # expressly don't call the parent; we don't want to set
   # connection parameters...
}

# suppress the parent from trying to connect to the database
sub create_handle { return undef; }

sub handle {
    return LedgerSMB::App_State::DBH();
}

💅 Subclassing: Changing fieldnames

So like, earlier versions of Workflow used the field 'user' to record who made a state change or a comment in the history. But unfortunately 'user' is a reserved word in our favorite database, PostgreSQL. (Oops. 🙈) So on top of changing the field to an assuredly-unreserved word (workflow_user), we made the fieldnames customizable by subclasses. Slay.

Just override either or both of these methods:

get_workflow_fields()

Returns a list of fields in this order:

workflow_id, type, state, last_update

get_history_fields()

Returns a list of fields in this order:

workflow_hist_id, workflow_id, action, description,
state, workflow_user, history_date

heads up bestie: we may cache the results, so don't try and do anything weird like change the fieldnames based on the workflow user or something... 😭

---

👑 METHODS 👑

🌈 Public Methods

All public methods are inherited from Workflow::Persister. Periodt.

🧚 Private Methods

• init( \%params ) — Initializes the instance by setting the connection parameters and calling "create_handle". The only thing you're required to provide is 'dsn', which is the full DBI DSN you'd normally use as the first argument to connect().

You can set these parameters in your persister configuration file and they will get passed to init.

You may also use:

• user — Name of user to login with.
• password — Password for "user" to login with.
• date_format — Date format to use when working with the database. Accepts a format string that can be processed by the DateTime module. See DateTime's strftime Patterns (https://metacpan.org/pod/DateTime#strftime-Patterns) for the format options.

The default is '%Y-%m-%d %H:%M' for backward compatibility.

• autocommit — 0 or 1 to turn autocommit off or on for the database handle.

Setting autocommit to off will run Workflow with transactions. If there's a failure somewhere and the persister supports it, Workflow will attempt to roll back all database activity in the current transaction.

⚠️ If you turn autocommit off, you must still commit transactions for Workflow::Persister::DBI::ExtraData yourself. Also, if you're sharing the database handle, you must be careful to not pass control to the workflow engine with pending transactions, because they will be committed if the workflow actions are successful. 💀

The default autocommit value for the database handle is on.

• workflow_table — Table to use for persisting workflow. Default is 'workflow'.
• history_table — Table to use for persisting workflow history. Default is 'workflow_history'.

You may also use parameters for the different types of ID generators. See below under the "init_*_generator" for the necessary parameters for your database.

On top of creating a database handle, we parse the "dsn" to see what driver we're using, so we know how to generate IDs. We can use automatically generated IDs for PostgreSQL, MySQL, and SQLite. If your database isn't in that list, a randomly generated ID gets used instead. (Default length of 8 characters, which you can modify with an "id_length" parameter.)

You can also create your own adapter for a different type of database. Just check out the existing Workflow::Persister::DBI::AutoGeneratedId and Workflow::Persister::DBI::SequenceId classes for examples. 💖

• assign_generators( $driver, \%params ) — Given $driver and the persister parameters in "\%params", assign the appropriate ID generators for both the workflow and history tables.

Returns: nothing, but assigns the object properties "workflow_id_generator" and "history_id_generator".

• assign_tables( \%params ) — Assign the table names from "\%params" (using 'workflow_table' and 'history_table') or use the defaults 'workflow' and 'workflow_history'.

Returns: nothing, but assigns the object properties "workflow_table" and "history_table".

• init_postgres_generators( \%params ) — Create ID generators for the workflow and history tables using PostgreSQL sequences. You can specify the sequences used for the workflow and history tables:
  • workflow_sequence — Sequence for the workflow table. Default: 'workflow_seq'
  • history_sequence — Sequence for the workflow history table. Default: 'workflow_history_seq'
• init_mysql_generators( \%params ) — Create ID generators for the workflow and history tables using the MySQL 'auto_increment' type. No parameters are necessary. ✨
• init_sqlite_generators( \%params ) — Create ID generators for the workflow and history tables using the SQLite implicit increment. No parameters are necessary. ✨
• init_random_generators( \%params ) — Create ID generators for the workflow and history tables using a random set of characters. You can specify:
  • id_length — Length of character sequence to generate. Default: 8.
• init_oracle_generators — Create ID generators for the workflow and history tables using the Oracle sequences. No parameters are necessary. ✨
• create_handle — Creates a database connection using DBI's "connect" method and returns the resulting database handle. Override this method if you want to set different options than the hard-coded ones, or when you want to use a handle from elsewhere.

The default implementation hard-codes these database handle settings:

$dbh->{RaiseError} = 1;
$dbh->{PrintError} = 0;
$dbh->{ChopBlanks} = 1;

• create_workflow — Serializes a workflow into the persistence entity configured by our workflow.

Takes a single parameter: a workflow object.

Returns a single value, an id for unique identification of our serialized workflow, for possible deserialization.

• fetch_workflow — Deserializes a workflow from the persistence entity configured by our workflow.

Takes a single parameter: the unique id assigned to our workflow upon serialization (see "create_workflow").

Returns a hashref consisting of two keys:

• state, the workflow's current state
• last_update, date indicating last update

• update_workflow — Updates a serialized workflow in the persistence entity configured by our workflow.

Takes a single parameter: a workflow object.

Returns: Nothing.

• create_history — Serializes history records associated with a workflow object.

Takes two parameters: a workflow object and an array of workflow history objects.

Returns: provided array of workflow history objects upon success.

• fetch_history — Deserializes history records associated with a workflow object.

Takes a single parameter: a workflow object.

Returns an array of workflow history objects upon success.

• commit_transaction ( $wf ) — Commit the transaction for a workflow if autocommit is not enabled.

Returns nothing.

• rollback_transaction — Rolls back the transaction for a workflow if autocommit is not enabled.

Returns nothing.

---

🔥 SEE ALSO 🔥

• Workflow
• Workflow::Persister
• DBI

---

🎀 COPYRIGHT 🎀

Copyright (c) 2003-2021 Chris Winters. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Please see the LICENSE.

---

💜 AUTHORS 💜

Please see Workflow.

---

okay that's the whole thing bestie, you ate that 🫶 this was rendered by perl v5.42.0 on 2026-01-17, and yes the title got truncated to Workflo...er::DBI(3) on both sides of the header because man pages are dramatic like that. iconic, honestly. 💅✨🌸