# Migration Guide: 9.11.0 → 9.12.0

Osumi Framework **9.12.0** adds native support for SQL `DATE`, `DATETIME` and `BIGINT` columns and redefines the meaning of `OField::DATE`.

This version includes an automatic migration step to preserve compatibility with existing models.

## DATE and DATETIME

Until Osumi Framework 9.11, `OField::DATE` actually generated an SQL `DATETIME` column.

Starting with 9.12, the types are represented independently:

```text
OField::DATE     → SQL DATE      → PHP ?string → Y-m-d
OField::DATETIME → SQL DATETIME  → PHP ?string → Y-m-d H:i:s
```

For example:

```php
#[OField(
	type: OField::DATE
)]
public ?string $event_date = null;

#[OField(
	type: OField::DATETIME
)]
public ?string $processed_at = null;
```

Temporal values are strictly validated and invalid calendar dates or times are rejected.

`#[OCreatedAt]`, `#[OUpdatedAt]` and `#[ODeletedAt]` fields continue to represent full timestamps and internally use `DATETIME`.

## Automatic OField::DATE Migration

Models created with versions earlier than 9.12 used `OField::DATE` with `DATETIME` semantics.

During the upgrade, migration step `9.12.0` automatically transforms:

```php
OField::DATE
```

into:

```php
OField::DATETIME
```

inside existing models under `src/Model/`.

The migration modifies only actual PHP code tokens and does not alter occurrences inside comments or string literals.

It does not modify the database schema: it preserves the `DATETIME` semantics those fields already had.

After the migration has completed, new uses of `OField::DATE` represent real SQL `DATE` columns.

## BIGINT

9.12 adds `OField::BIGINT`.

```php
#[OField(
	type: OField::BIGINT
)]
public ?int $external_id = null;
```

It can also be used with `#[OPK]`, including auto-increment primary keys.

`BIGINT` requires a 64-bit PHP environment.

`UNSIGNED` and `ZEROFILL` are not supported.

## generateModelFromDB

`generateModelFromDB` now recognizes:

```text
DATE     → OField::DATE
DATETIME → OField::DATETIME
BIGINT   → OField::BIGINT
```

SQL `TIMESTAMP` columns are still rejected because they cannot be represented faithfully by the ORM `DATETIME` semantics.

## Pipes and Formatting

The `date` template pipe supports both `DATE` and `DATETIME`.

Without an explicit mask:

```text
DATE     → d/m/Y
DATETIME → d/m/Y H:i:s
```

`OModel::get()` also supports both temporal types with an explicit formatting mask.

## Migration State

9.12 moves the authoritative migration state from:

```text
ofw/tmp/state.json
```

to:

```text
.ofw-migrations.json
```

at the project root.

This file is part of the versioned application state and must be committed to Git.

During the first upgrade to 9.12, when `.ofw-migrations.json` does not yet exist, the runner can read `ofw/tmp/state.json` to recover the last executed migration step.

Once a migration has completed under 9.12, the new file becomes the authoritative source.

This prevents cleaning `ofw/tmp/` from accidentally causing an old migration to run again.

## Updating

Before upgrading, make sure the application Git working tree is clean.

Update normally through Composer:

```bash
composer update osumionline/framework --with-dependencies
```

Migration step `9.12.0` will run automatically when applicable.

After upgrading:

1. Review the modified models.
2. Add `.ofw-migrations.json` to the repository.
3. Run the application's complete test suite.
4. Functionally verify any temporal and BIGINT fields used by the application.
