Search the Community

Once a ProcessWire site is live, the production database is not a deployable artifact. It is the source of truth for content, users, roles, module settings, and module-owned data. Deploy code from Git. Apply reviewed migrations to the production database. Preserve production data, uploads, configuration, and secrets. If an AI coding agent is involved, write these boundaries down in AGENTS.md and enforce them with scripts rather than relying on the agent to infer what “deploy” means. I arrived at this rule through a real incident. The incident I was rebuilding a ProcessWire site locally with an AI coding agent. The data model had changed substantially, the development site contained useful demo content, and the production site had little activity. I asked the agent to deploy the new version and replace the old data. Technically, the operation succeeded: the code was deployed; the new schema appeared; the development database was imported; development uploads replaced production uploads; the public pages worked. But a database is not just “content”. The import also replaced production-only module configuration, users, roles, support tickets, AI conversations, and records stored in custom module tables. SMTP happened to survive because its configuration matched in both environments. Other settings did not. Backups existed, so the incident was recoverable. The site also had almost no real activity. On a busy site, the same operation could have destroyed orders, form submissions, member accounts, unpublished editorial work, audit history, or messages created during the deployment window. The important lesson was not “the AI made a mistake”. The deployment process allowed an ambiguous instruction to become a destructive database operation. That is a systems problem. Why ProcessWire needs an explicit deployment model ProcessWire's file layout is deliberately clear: /wire/ contains the core, while /site/ contains site-specific templates, modules, configuration, and assets. The official documentation also identifies site/config.php as the site configuration file and site/assets/ as writable runtime storage. That filesystem separation is useful, but a mature ProcessWire project has another boundary that is easier to miss: Deployment ownership map Git release — templates, hooks, module code, and frontend assets. Source of truth: the repository. Database structure — fields, templates, fieldgroups, and module schemas. Source of truth: reviewed migrations. Production database — pages, users, roles, settings, submissions, and module-owned tables. Source of truth: production. Runtime configuration — database credentials, hostnames, and environment flags. Source of truth: the production runtime. Secrets — SMTP, API, and OIDC credentials. Source of truth: a secret store or protected runtime files. Writable assets — uploads, generated files, logs, sessions, and backups. Source of truth: production storage. The initial launch is special. If production is empty, cloning a reviewed development database may be reasonable. After the first real user, form submission, editor change, or module configuration, that direction must stop. Production may flow to development through a protected and preferably sanitized snapshot. Development must not flow back as a whole database. This is the same problem described in ProcessWire's own article introducing migrations: once the live server receives content while features continue to be developed locally, the databases diverge and changes must be merged rather than replaced. Use releases for code and migrations for change A production release should be an immutable Git commit, preferably accompanied by a tag. Build the deployable file list from that commit—not from the current working directory. A release manifest should include only public runtime code and static assets. It should explicitly exclude: .git/ and CI configuration; AGENTS.md and development documentation; site/config.php and environment-specific config; database dumps, credentials, and private keys; site/assets/files, caches, logs, sessions, and backups; tests, fixtures, local tooling, and editor configuration. ProcessWire fields and templates live in the database, so code deployment alone is not always sufficient. Represent structural changes as idempotent, versioned migrations. A migration may use ProcessWire's API, a migration module, or a project-specific CLI script. The important properties are the same: it has a preview or audit mode; it is safe to run more than once; it changes only named structures or records; it preserves unknown production configuration; large transformations are bounded and resumable; destructive steps require a fresh verified backup and rollback data; successful application is recorded. ProcessWire has community options such as ProcessDbMigrate and migration modules, but no tool removes the need to classify production data correctly. A backup is not verified until it can be restored “The backup command returned zero” is not enough. For every production release: create a timestamped database backup outside the document root; verify its size and checksum; verify compressed-stream integrity; periodically restore it into an isolated database; keep a backup of the exact files being replaced; record the rollback path before changing production. This matters because backup tools can produce syntactically valid-looking files that fail only during restoration. Test the recovery path, not merely the backup button. The official ProcessWire upgrade guide likewise recommends backing up both files and database and testing upgrades on a development or staging site first. Add a fail-closed deployment guard Documentation is necessary, but an executable invariant is better. Before deployment, create a private snapshot containing no secret values: row counts for protected tables; page counts by template; stable page IDs by template; installed module names; names and configured/empty state of module configuration keys; intended Git commit; production hostname; verified backup metadata. After code deployment and migrations, take the same measurements and compare them. Block completion if: a protected table disappeared or lost rows; a pre-existing page ID disappeared; a template or installed module disappeared; a module configuration key disappeared; a configured value became empty; the host or release commit does not match. Stable IDs matter. Row counts alone can miss a replacement database containing the same number of different records. Some legitimate migrations intentionally remove obsolete data. That should be an exceptional workflow requiring a change ID, a table-by-table impact report, a tested restore, and a second explicit approval. A generic “deploy everything” instruction must never authorize it. What to tell an AI coding agent An AI agent is fast enough to turn an ambiguous sentence into a complete deployment before a human notices the ambiguity. Give it a narrower contract. The repository instructions should state: development and production paths and hostnames; production is read-only unless a production change is explicitly requested; commit, push, deploy, migrate, publish, and replace data are separate actions; “deploy” means code-only unless named migrations are included; a development database must never overwrite a launched production database; production users, content, module configuration, custom tables, and uploads must be preserved; secrets must not be read, printed, hashed, copied locally, or committed; every mutation needs a fresh verified backup and exact rollback path; migrations run in preview first and must be bounded/idempotent; a data decrease is a blocker, not a warning; if scope is ambiguous, stop after read-only investigation; destructive approval is two-phase: impact report first, explicit confirmation of that report second; maintenance is not removed and success is not reported while checks fail. The open AGENTS.md format is useful here because it gives multiple coding agents a predictable repository-level instruction file. Its documentation explicitly recommends including build commands, testing, security concerns, and deployment details, and supports more specific nested files where needed. I prepared a reusable template and attached it to this post as ProcessWire-AGENTS-production-safety-template.zip. The archive contains a single AGENTS.md file. Download it, replace the placeholders, and commit it to the root of your project. Do not deploy it into the public document root. A practical release checklist Before maintenance Select an immutable Git commit. Review the diff and release manifest. List every migration and classify its risk. Create and verify database and file backups. Create the protected data snapshot. Write the rollback command/path. During maintenance Deploy only manifest files. Preserve production config, secrets, uploads, logs, sessions, and backups. Run migrations in preview, then apply. Run the fail-closed comparison. Stop on any unexplained decrease. Before reopening Test origin and CDN routes. Test authentication and representative member workflows. Verify email delivery readiness and background jobs. Inspect new logs without exposing secrets. Record commit, manifest checksum, migration results, backups, and rollback. Remove maintenance only when every blocker is resolved. Final principle The database is not “the backend version of the code”. On a live ProcessWire site it is accumulated production state. AI does not change this rule. AI makes it more important to encode the rule in files, scripts, permissions, and fail-closed checks—because the agent can execute a bad assumption much faster than a human can recognize it. References ProcessWire file and directory structure ProcessWire: migrating to production ProcessWire upgrade best practices ProcessWire file permissions and protecting site/config.php ProcessWire: Introduction to the Migrations module ProcessDbMigrate module directory entry AGENTS.md open format ProcessWire-AGENTS-production-safety-template.zip

A companion Module for RockMigrations to gather and execute Migrations in one place. !Alpha RELEASE! Hi there, I just wanted to share my take on Migrations and how I am using RockMigrations to make my deployments somehow manageable. First of all, a big shoutout to @bernhard for his efforts and accomplishments for our beloved CMS. We recently had a video-call and talked about our daily problems and how to handle them, with a focus on Migrations. As of now you might think 'Gosh, not another Migrationsthingy' but wait. Wouldnt it be nice to have a nice overview or some kind of list regarding Migrations and stuff and one place to manage them? Speaking for my own, yes I would like to have something like this. So yeah, here we are with a Companion Module for RockMigrations. Product Requirements I want to manage Migrations on the Application level (done) I want to have one place in my FileSystem to place my Migrations (done) I want to see in which state my Migrations are (done) I want to have an execution order, execute migrations one by one (done) I want to trigger Migrations via CLI (open) I want to group multiple Migrations into One Migration to create Build Versions (open) I want to Rollback Migrations (open) I want to create a deliverable build out of migrations (open) I want to track changes to templates and fields and create migrations accordingly (open) I want to manage Migrations on the Module level (open) Module Requirements ProcessWire 3.0.178 RockMigrations latest PHP 7.4 Composer Current release: v1.0.2Alpha How does it work? On installation the Module will create a new Database Table, here we will hold information about migrations states. Your Migrations are empty on first installation, so just click on You can now choose which Type of Migration you want to create, be it Templates, Fields or Pages and a according Action. Im still working on this function, so yeah its a lil bit confusing right now. The philosophy here is, every Type of Migration could be easily identified and we can Migrate on a very sepcific and granular base. As you can see in my Screenshot, I am using migrations to build an entire App from Migrations. After creating the new Migration File, switch over to your IDE and find a timestamped .php file inside modules/FlowtiCore/migrations. This file just returns a simple Array. This is all the Info RockMigrations needs to do his thing while we keep track of the execution. Easy. Values Arrays have to follow PW and RockMigration field naming Conventions. To make a Migration Executable set 'boilerplate' to false. After creation of your first Migrations your overview should be filled so lets go. We have to migrate our files in a specific order just to make sure we can create page_references and Parent/Child connections. To achieve this, Migrations are timestamped on creation. The older the higher the priority. To enforce execution order, every migration needs to have his predecessor executed and installed. How could this help my workflow? My workflow is based on Git, Webhooks and Git Events. So whenever I merge 'staging' into 'master', a build will be created and a deliverable should be pushed to a Server via SSH. The Problem with ProcessWire is the lack of support for such Workflows and Toolchains due to its User-Friendly Admin Backend which is fine for a simple website but not suitable long-term if working in a multi-tenant environment or with more developers in a dev-staging-test-production setup. My Goal is to provide methods and ideas to support such workflows but also support a User-Friendly Interface to work with migrations. I really hope it could be of use for someone. Installation I will add the Module to the Directoy once it reached a stable state. But you can get current version at GitHub https://github.com/Luis85/FlowtiCore Just clone it to your Modules Directory. The Module will create a new Database-Table on creation. The Default Name will be 'flowti_core_migrations'. To change this just edit const DATABASE_TABLE = 'flowti_core_migrations'; Inside the Module Class. Thats it, from there on just create new Migration Files, edit them and execute them.

Hello guys, I'm trying to figure out how to sync fields and templates between staging and production environments. I've found Migrations module by Lostkobrakai, but with use of it all the fields and templates must be created by API, which is kind of uncomfortable. I also tried ProcessDatabaseBackups module which can export only certain tables, but I don't think it's the best practice to do that. How do you guys solve this problem? It's very annoying to setup everything three times (dev, staging, production). Thanks a lot :)

Hello everyone, Last night as a "saturday night shitty weather stay at home" project I attempted to migrate a project that was on PW 2.7.x to PW 3.x I use a lot of partials on the project so I have around 200 php files that needs to be namespaced. Compiler was giving me trouble with "Call undefined function" errors. Being the lazy developer I attempted to wrote a script after getting bored over pasting the namespace Processwire; line into around 10 files. Below you can find the script, that is very basically adds <?php namespace Processwire;?> as the first line of every .php and .module file in the given directory and shows you the results. Of course it checks for namespace Processwire first By default it assumes ./site/templates folder but I tried it with a module which is giving errors due to namespaces and worked fine. Be careful and remember to take backups first https://gist.github.com/borantula/e41c4b6ba36f78b1110d400a16754691