> For the complete documentation index, see [llms.txt](https://xoops.gitbook.io/xmf-cookbook/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://xoops.gitbook.io/xmf-cookbook/reference/database/migrate.md).

# Migrate

## Migrate

`Xmf\Database\Migrate` is a class to simplify synchronizing database changes between versions of a module. It builds on the [Tables](/xmf-cookbook/reference/database/tables.md) class, and adds support for building a module schema directly from the database, saving that schema, and generating the DDL to convert the current database for a module into a saved schema definition.

## Basic Usage

### $migrate = new Migrate(*$dirname*)

Creates a new Migrate object that considers the tables specified in the module definition for the module identified by *$dirname*.

### synchronizeSchema()

Compare the current database tables to the target schema and execute any DDl/SLQ needed to synchronize the database with the target schema.

The synchronizeSchema() method should normally be called during the modules onUpdate processing. In most cases this should be invoked in the xoops*module\_pre\_update$dirname* function.

### getSynchronizeDDL()

Gets an array of DDL/SQL statements that when executed sequentially will synchronize the existing database to match the taget schema. This may be useful if extensive changes to a large database need to be run as batches or from the command line.

### preSyncActions()

Simple schema changes, such a changing the length of a VARCHAR column, can be handled automatically. Some changes, such as renaming a table or a column need to be performed explicitly before synchronizing, or data loss will result. (A renamed entity looks like a dropped entity under the old name and a new entity of the new name.)

The intended pattern is for a module to extend the Migrate class for use in its own module update process, and perform any needed conversion logic, such a renames in the preSyncActions() method.

## Utility methods

### getCurrentSchema()

Builds a schema representation from the current database that includes all tables declared for the module specified when the object was instantiated.

### getTargetDefinitions()

Loads a saved schema definition corresponding to the current version of the module specified when the object was instantiated.

### saveCurrentSchema()

Saves the schema definition obtained from the current state of the database as the schema target for the current module version.

**This method is intended for use by module developers/publishers.** The format of the saved schema is subject to change. Editing the generated file may cause inconsistencies in the synchronization process. Changes should be made to the current database, and then saveCurrentSchema() invoked to capture any updates.

## Error Information

### getLastError()

Return message from last error encountered

### getLastErrNo()

Return code from last error encountered


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://xoops.gitbook.io/xmf-cookbook/reference/database/migrate.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.