Skip to content

Commit 0494222

Browse files
mychidarkomychidarko
committed
feat: update migration docs
1 parent a045985 commit 0494222

File tree

1 file changed

+140
-70
lines changed

1 file changed

+140
-70
lines changed

‎src/docs/database/files.md‎

Lines changed: 140 additions & 70 deletions
Original file line numberDiff line numberDiff line change
@@ -65,23 +65,7 @@ seeds:
6565

6666
Breaking this file down, there are three main sections:
6767

68-
- `columns`: This is used to set the columns of the table. The key is the column name and the value is a key value pair of column properties. The available properties are:
69-
- `type`: The type of the column. This can be `string`, `integer`, `timestamp` or any type supported by Laravel's Eloquent.
70-
- `length`: The length of the column. This is only used for `string` columns.
71-
- `nullable`: This is used to set the column as nullable.
72-
- `default`: This is used to set the default value of the column.
73-
- `unsigned`: This is used to set the column as unsigned.
74-
- `index`: This is used to set the column as an index.
75-
- `unique`: This is used to set the column as unique.
76-
- `primary`: This is used to set the column as the primary key.
77-
- `foreign`: This is used to set the column as a foreign key. The value of this key is the table and column the column is a foreign key to.
78-
- `values`: This is used to set the values of the column. This is only used for `enum` and `set` columns.
79-
- `onDelete`: This is used to set the `ON DELETE` constraint of the foreign key.
80-
- `onUpdate`: This is used to set the `ON UPDATE` constraint of the foreign key.
81-
- `comment`: This is used to set the comment of the column.
82-
- `autoIncrement`: This is used to set the column as auto-incrementing.
83-
- `useCurrent`: This is used to set the column to use the current timestamp. This is only used for `timestamp` columns.
84-
- `useCurrentOnUpdate`: This is used to set the column to use the current timestamp on update. This is only used for `timestamp` columns.
68+
- `columns`: This is used to set the columns of the table. The key is the column name and the value is the type/properties of the column.
8569

8670
- `seeds`: This is used to set the seeders of the table. The available properties are:
8771
- `count`: This is used to set the number of seeds to generate.
@@ -90,29 +74,9 @@ Breaking this file down, there are three main sections:
9074

9175
- `relationships`: This is used to set the relationships of the table. The value is an array of models the table is related to. This is used to generate foreign keys for the table.
9276

93-
Besides these, Schema files also set a lot of defaults for you. For instance, the `id` column is set as the primary key and auto-incrementing by default. Timestamps are also added by default. You can override these defaults by adding the `id` and `timestamps` keys to your schema file. Here's an example:
77+
## Applying schema files
9478

95-
```yml:no-line-numbers [posts.yml]
96-
increments: false # this will remove the auto-incrementing id column
97-
timestamps: false # this will remove the timestamps columns
98-
```
99-
100-
Once you turn off auto-increments, you can add your own `id` column. Here's an example:
101-
102-
```yml:no-line-numbers [posts.yml]
103-
increments: false
104-
105-
columns:
106-
id:
107-
type: integer
108-
primary: true
109-
110-
...
111-
```
112-
113-
## Database tables
114-
115-
Traditionally, migrations are used to create database tables and modify them. In Leaf MVC, every schema file is tied to a particular table which is the name of the file. All you need to do is modify the columns of the table using the `columns` key in your schema file. Here's an example:
79+
Each schema file represents a single database table—just name the file after the table you’re creating. Inside, define your table structure under the `columns` key. Leaf takes care of the rest. No need for separate migration files or extra setup—just one clear, structured file for everything your table needs. Here's an example:
11680

11781
```yml [users.yml]
11882
columns:
@@ -137,45 +101,112 @@ You can have multiple schema files in your `app/database` directory, each tied t
137101
php leaf db:migrate users
138102
```
139103

140-
<!-- ## Database migrations vs data migrations
104+
## Database schema defaults
141105

142-
Usually, when making substancial changes to your database, you would create a migration file which is usually in charge of modifying the structure of your database. In some situations, you might want to run some kind of data migration which may copy data from one table to another, or run some kind of data manipulation on your recently migrated database. Some frameworks combine these two into one, but in Leaf MVC, we separate these two because we believe they are two different things. While database migrations are common, data migrations are not so common and are usually done manually.
106+
Schema Files come with smart defaults to make setup faster. Every table automatically includes an auto-incrementing `id` and `created_at`/`updated_at` timestamps—no need to add them manually. Want to change that? Use the `increments` and `timestamps` keys to disable them. Here's an example:
143107

144-
Leaf MVC provides database scripts which you can use to handle your data migrations. Separating database migrations from data migrations allows you to safely roll-back your data migrations without affecting your database structure. Here's an example of a database script:
108+
```yml:no-line-numbers [posts.yml]
109+
increments: false # this will remove the auto-incrementing id column
110+
timestamps: false # this will remove the timestamps columns
111+
```
145112

146-
```php [ImportUsersFromOldTable.php]
147-
<?php
113+
Once you turn off auto-increments, you can add your own `id` column. Here's an example:
148114

149-
use App\Models\User;
115+
```yml:no-line-numbers [posts.yml]
116+
increments: false
150117
151-
class ImportUsersFromOldTable
152-
{
153-
public function up()
154-
{
155-
$oldUsers = getOldUsersAndMapToNewUsers();
118+
columns:
119+
id:
120+
type: integer
121+
primary: true
156122
157-
foreach ($oldUsers as $oldUser) {
158-
User::create([
159-
'name' => $oldUser->name,
160-
'email' => $oldUser->email,
161-
'password' => $oldUser->password,
162-
'is_from_old_table' => true
163-
]);
164-
}
165-
}
123+
...
124+
```
166125

167-
public function down()
168-
{
169-
User::where('is_from_old_table', true)->delete();
170-
}
171-
}
126+
The same thing goes for timestamps. If you want to add your own timestamps, you can turn off the default timestamps and add your own. Here's an example:
127+
128+
```yml:no-line-numbers [posts.yml]
129+
timestamps: false
130+
131+
columns:
132+
...
133+
created_at: timestamp
172134
```
173135

174-
Now you just need to run the script using the `db:script` command:
136+
This example will add a `created_at` column to the `posts` table with the current timestamp as the default value.
175137

176-
```bash:no-line-numbers
177-
php leaf db:script ImportUsersFromOldTable
178-
``` -->
138+
## Schema columns
139+
140+
In a schema file, you can define the columns of your table under the `columns` key. The key is the column name and the value is the type of column or an array of properties for the column:
141+
142+
```yml:no-line-numbers [users.yml]
143+
columns:
144+
# directly defining the column type
145+
email: string
146+
147+
# defining the column type and properties
148+
email:
149+
type: string
150+
length: 255
151+
unique: true
152+
```
153+
154+
The schema builder blueprint offers a variety of methods that correspond to the different types of columns you can add to your database tables. Each of the available methods are listed in the table below:
155+
156+
| Method | Description | Method | Description |
157+
|--------|-------------| -------|-------------|
158+
| `boolean` | Creates a boolean column. | `increments` | Creates an auto-incrementing integer column. |
159+
| `integer` | Creates an integer column. | `bigIncrements` | Creates a big integer column. |
160+
| `bigInteger` | Creates a big integer column. | `smallIncrements` | Creates a small integer column. |
161+
| `char` | Creates a character column. | `decimal` | Creates a decimal column. |
162+
| `string` | Creates a string column. | `float` | Creates a float column. |
163+
| `text` | Creates a text column. | `double` | Creates a double column. |
164+
| `tinyText` | Creates a tiny text column. | `unsignedBigInteger` | Creates an unsigned big integer column. |
165+
| `mediumText` | Creates a medium text column. | `id` | Creates an auto-incrementing integer column. |
166+
| `longText` | Creates a long text column. | `uuid` | Creates a UUID column. |
167+
| `date` | Creates a date column. | `json` | Creates a JSON column. |
168+
| `enum` | Creates an enum column. | `jsonb` | Creates a JSONB column. |
169+
170+
You can check the [Laravel migration documentation](https://laravel.com/docs/12.x/migrations#available-column-types) for more information on the available types. Any method that is not present in the table above or not listed in the Laravel migration documentation is not supported in Leaf MVC.
171+
172+
## Column properties/modifiers
173+
174+
In addition to the column types, you can also add properties/modifiers to your columns to make them behave differently. The available properties are:
175+
176+
| Property | Description |
177+
|----------|-------------|
178+
| `type` | The type of the column. This is required for all columns |
179+
| `length` | The length of the column. This is optional and defaults to 255 for string columns |
180+
| `nullable` | This is used to set the column as nullable. This is optional and defaults to false |
181+
| `default` | This is used to set the default value of the column. |
182+
| `unsigned` | This is used to set the column as unsigned. This is optional and defaults to false |
183+
| `index` | This is used to set the column as an index. This is optional and defaults to false |
184+
| `unique` | This is used to set the column as unique. This is optional and defaults to false |
185+
| `primary` | This is used to set the column as the primary key. This is optional and defaults to false |
186+
| `values` | This is used to set the values of the column. This is only required for `enum` and `set` columns. |
187+
| `onDelete` | This is used to set the `ON DELETE` constraint of the foreign key. |
188+
| `onUpdate` | This is used to set the `ON UPDATE` constraint of the foreign key. |
189+
| `comment` | This is used to set the comment of the column. |
190+
| `autoIncrement` | This is used to set the column as auto-incrementing. This is optional and defaults to false |
191+
| `useCurrent` | This is used to set the column to use the current timestamp. This is only used for `timestamp` columns. |
192+
| `useCurrentOnUpdate` | This is used to set the column to use the current timestamp on update. This is only used for `timestamp` columns. |
193+
<!-- | `foreign` | This is used to set the column as a foreign key. The value of this key is the table and column the column is a foreign key to. | -->
194+
195+
You can use these properties to modify the behavior of your columns. For example, if you want to create a `name` column that is unique and has a default value of `John Doe`, you can do it like this:
196+
197+
```yml:no-line-numbers [users.yml]
198+
columns:
199+
name:
200+
type: string
201+
unique: true
202+
default: 'John Doe'
203+
```
204+
205+
When defining columns, it’s good to be mindful—some properties can affect performance or behave differently across databases. For example, setting a column as `unique` adds an index, which can slow down inserts and updates on large tables. And properties like `comment` aren’t supported in SQLite, which could lead to unexpected behavior. Leaf gives you the flexibility—you just want to use it wisely.
206+
207+
::: tip Missing some functionality?
208+
We are working on adding more properties/modifiers to the columns, just to make it easier to work with your database. If you have any suggestions, please let us know.
209+
:::
179210

180211
## Migration histories
181212

@@ -197,8 +228,7 @@ columns:
197228

198229
This example adds a new column `is_super_admin` to the `users` table. When you run `php leaf db:migrate`, Leaf will compare it to the previous version of the file, find the differences and automatically create the `is_super_admin` column for you in your database. You don't need to worry about writing migration files or keeping track of changes manually.
199230

200-
Every time you update a Schema File and run `db:migrate`, Leaf logs the changes for you. No more digging through migration files—just focus on building. And when you need to roll back? Simply run `php leaf db:rollback`.
201-
231+
And when you need to roll back? Simply run `php leaf db:rollback`.
202232

203233
## Seeding your database
204234

@@ -262,3 +292,43 @@ If you want to seed a specific table, you can pass the table name as an argument
262292
```bash:no-line-numbers
263293
php leaf db:seed users
264294
```
295+
296+
<!-- ## Database migrations vs data migrations
297+
298+
Usually, when making substancial changes to your database, you would create a migration file which is usually in charge of modifying the structure of your database. In some situations, you might want to run some kind of data migration which may copy data from one table to another, or run some kind of data manipulation on your recently migrated database. Some frameworks combine these two into one, but in Leaf MVC, we separate these two because we believe they are two different things. While database migrations are common, data migrations are not so common and are usually done manually.
299+
300+
Leaf MVC provides database scripts which you can use to handle your data migrations. Separating database migrations from data migrations allows you to safely roll-back your data migrations without affecting your database structure. Here's an example of a database script:
301+
302+
```php [ImportUsersFromOldTable.php]
303+
<?php
304+
305+
use App\Models\User;
306+
307+
class ImportUsersFromOldTable
308+
{
309+
public function up()
310+
{
311+
$oldUsers = getOldUsersAndMapToNewUsers();
312+
313+
foreach ($oldUsers as $oldUser) {
314+
User::create([
315+
'name' => $oldUser->name,
316+
'email' => $oldUser->email,
317+
'password' => $oldUser->password,
318+
'is_from_old_table' => true
319+
]);
320+
}
321+
}
322+
323+
public function down()
324+
{
325+
User::where('is_from_old_table', true)->delete();
326+
}
327+
}
328+
```
329+
330+
Now you just need to run the script using the `db:script` command:
331+
332+
```bash:no-line-numbers
333+
php leaf db:script ImportUsersFromOldTable
334+
``` -->

0 commit comments

Comments
 (0)