Certimate utilizes the PocketBase migration system to manage schema evolutions and data transformations. As the application transitioned through the v0.4.x series, the migration system became responsible for complex structural changes, particularly within the workflow graph definitions, ACME account configurations, and data retention settings.
The migration system is built on top of the PocketBase migrations package. Migrations are registered during the application initialization phase and executed sequentially when the backend starts up.
| Component | Role |
|---|---|
m.Register | Registers a new migration with an Up function (and optionally Down) migrations/1757476800_upgrade_v0.4.0.go21 |
Tracer | A specialized logger used to provide feedback during long-running or complex migrations migrations/1757476800_upgrade_v0.4.0.go29 |
Snapshot Files | JSON-based definitions of the entire database schema used for clean initializations migrations/1757476801_initialize_v0.4.0.go23 |
WorkflowGraphWalker | A utility class used to traverse and modify nested workflow graph structures during migrations migrations/1762142400_upgrade_v0.4.3.go87 |
The following diagram illustrates how the PocketBase application handles migrations during bootstrap.
Database Migration Lifecycle
Sources: migrations/1757476800_upgrade_v0.4.0.go20-30 migrations/1757476801_initialize_v0.4.0.go12-17
The v0.4.x series introduced significant breaking changes to the data model. Migrations in this series typically perform three types of operations:
collection.Fields.AddMarshaledJSONAt migrations/1762142400_upgrade_v0.4.3.go33-70validityInterval from date strings using SQLite STRFTIME migrations/1762142400_upgrade_v0.4.3.go78v0.4.11 removes entries from the _migrations table for files that have been consolidated or superseded migrations/1766592000_upgrade_v0.4.11.go136-151Because workflow graphs are stored as complex JSON blobs, Certimate uses a WorkflowGraphWalker to perform deep updates on node configurations without corrupting the graph structure.
Workflow Migration Entity Mapping
Sources: migrations/1762142400_upgrade_v0.4.3.go87-106 migrations/1769313600_upgrade_v0.4.15.go174-205
In migration v0.4.15, the walker is used to adapt provider configurations, such as splitting rainyun-rcdn into rainyun-sslcenter based on the resourceType migrations/1769313600_upgrade_v0.4.15.go185-202 Similarly, migration v0.4.11 uses the walker to infer the identifier type (IP vs Domain) for bizApply nodes based on existing domains field content migrations/1766592000_upgrade_v0.4.11.go21-45
Snapshot files provide a baseline for the database schema. Instead of running hundreds of incremental SQL changes for a new installation, the system can initialize the collections from a JSON snapshot.
migrations/1757476801_initialize_v0.4.0.go contains a massive JSON blob representing the collection structures for access, settings, acme_accounts, and others migrations/1757476801_initialize_v0.4.0.go23-285WorkflowNode are imported from migrations/snaps/ to ensure that migrations written for older versions of the code continue to work even if the primary domain models change migrations/1757476800_upgrade_v0.4.0.go16-17 migrations/1762142400_upgrade_v0.4.3.go10The Tracer is a utility used within migration files to provide structured logging to the console during the migration process.
tracer := NewTracer("v0.4.0") migrations/1757476800_upgrade_v0.4.0.go29Printf to log specific actions, such as "collection 'settings' updated" or "record #xyz in collection 'acme_accounts' updated" migrations/1757476800_upgrade_v0.4.0.go49-212The migration to v0.4.0 involved a complex transformation of ACME account data. It extracted the acmeAcctUrl and acmeDirUrl from nested JSON structures and mapped legacy provider names to their respective ACME directory endpoints (e.g., mapping googletrustservices to https://dv.acme-v02.api.pki.goog/directory) migrations/1757476800_upgrade_v0.4.0.go133-205
In migration v0.4.25, the field acmeAccount was renamed to resourceObj within the acme_accounts collection to better reflect its content as a serialized acme.Account object internal/repository/acme_account.go79-112
Migration v0.4.4 updated the settings collection to ensure persistence configurations were consistent across version updates, often involving the migration of notification settings and retention policies migrations/1762516800_upgrade_v0.4.4.go1-100
Several migrations target the workflow, workflow_run, and workflow_output collections to ensure that the JSON-stored graph and nodeConfig remain consistent with code changes:
keySource to bizApply nodes and source to bizUpload nodes migrations/1762142400_upgrade_v0.4.3.go92-125nodeId references in workflow_output caused by ID truncation issues in previous migrations by traversing the workflow_run graph to find the matching node migrations/1769313600_upgrade_v0.4.15.go91-170ftp, local, ssh, and s3 providers to ensure consistency in how node configuration is handled across different deployment targets.issuerOrg, keyAlgorithm, and validityInterval for records that were created or imported without this metadata using the PopulateFromPEM logic internal/domain/certificate.go45-82Sources:
Refresh this wiki