> For the complete documentation index, see [llms.txt](https://quantumphp.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://quantumphp.gitbook.io/docs/packages/database/schema-builder.md).

# Schema Builder

The Database package includes a small SQL schema builder used by migrations through `Quantum\Database\Factories\TableFactory` and `Quantum\Database\Schemas\Table`.

## `TableFactory`

`TableFactory` is a guard layer around `Table`.

It provides four operations:

* `create($name)`
* `get($name)`
* `rename($oldName, $newName)`
* `drop($name)`

Before acting, it checks table existence by running `Database::query('SELECT 1 FROM ' . $name)`.

That means:

* existence checks rely on the active relational adapter
* a failed probe is treated as "table does not exist"
* this factory is not intended for SleekDB stores

## `Table` lifecycle

A `Table` instance accumulates schema changes and executes them when the object is destroyed.

That is the most important behavior in this API: **SQL execution is destructor-driven**.

Typical flow:

1. `TableFactory` creates or resolves a `Table`
2. the table action is set to create, alter, rename, or drop
3. column and index operations are chained on the object
4. `Table::__destruct()` calls `save()`
5. `save()` generates SQL and sends it to `Database::execute(...)`

If the generated SQL is empty, nothing is executed.

## Supported table actions

`Table` supports these action constants:

* `CREATE`
* `ALTER`
* `DROP`
* `RENAME`

The generated SQL differs by action:

* create → `CREATE TABLE ...`
* alter → `ALTER TABLE ...`
* rename → `RENAME TABLE ... TO ...`
* drop → `DROP TABLE ...`

## Column operations

The fluent API can:

* `addColumn($name, $type, $constraint)`
* `modifyColumn($name, $type, $constraint)`
* `renameColumn($oldName, $newName)`
* `dropColumn($name)`
* `addIndex($columnName, $indexType, $indexName = null)`
* `dropIndex($indexName)`
* `after($columnName)`

After adding or modifying a column, `Table::__call()` forwards column modifiers to `Quantum\Database\Schemas\Column`.

Supported column modifiers include:

* `autoIncrement()`
* `primary()`
* `index()`
* `unique()`
* `fulltext()`
* `spatial()`
* `nullable()`
* `default($value, $quoted = true)`
* `attribute($value)`
* `comment($value)`

## SQL generation details

A few implementation details matter when writing migrations:

* type names are uppercased by `Column`
* enum constraints become `ENUM('a', 'b', ...)`
* `autoIncrement()` also marks the column as a primary key
* default values are quoted unless `default(..., false)` is used
* rename and drop column actions intentionally omit unrelated column attributes
* indexes are emitted after column definitions in create/alter SQL
* dropped indexes are appended as `DROP INDEX ...`

## Caveats

* Because execution happens in `__destruct()`, work is applied when the object goes out of scope, not when each fluent method is called.
* `rename()` and `drop()` on `TableFactory` return `true` after preparing the `Table`; the actual SQL is still performed by the temporary object's destructor.
* `Table::checkColumnExists()` exists internally but is not used to block duplicate or missing column operations.
* The builder emits MySQL-style SQL such as backtick-quoted identifiers and `RENAME TABLE`, so it is a relational migration helper rather than a cross-adapter abstraction.


---

# 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://quantumphp.gitbook.io/docs/packages/database/schema-builder.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.