https://github.com/getkirby/database-storage
Adds support for pages stored in a database
https://github.com/getkirby/database-storage
database kirby-cms kirby-plugin kirby5
Last synced: 5 months ago
JSON representation
Adds support for pages stored in a database
- Host: GitHub
- URL: https://github.com/getkirby/database-storage
- Owner: getkirby
- Created: 2025-07-10T12:29:46.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2025-07-10T13:55:29.000Z (6 months ago)
- Last Synced: 2025-07-10T19:56:26.716Z (6 months ago)
- Topics: database, kirby-cms, kirby-plugin, kirby5
- Language: PHP
- Homepage: https://getkirby.com
- Size: 71.3 KB
- Stars: 9
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Kirby Database Storage Plugin
Adds support for pages stored in a database.
> [!IMPORTANT]
> This plugin is still in an early alpha state. Use with caution.
## Features
This plugin already provides good support for pages from databases, but has still some limitations. Here is a list of supported page features:
- [x] Content Changes & Translations
- [x] Changing the page title
- [x] Changing the slug
- [x] Translating the slug
- [x] Deleting pages
- [x] Sorting pages
- [x] Changing the page status
- [ ] Duplicating pages
- [ ] Moving pages
- [ ] Changing templates
### File support
Files are stored in the content folder. A folder for each page is created as soon as files are uploaded. The UUID is used as folder name. File information is still stored in text files and not yet in the database.
> [!WARNING]
> This plugin requires UUIDs to be switched on
## Installation
### Download
Download and copy this repository to `/site/plugins/database-storage`.
### Composer
```
composer require getkirby/database-storage
```
### Git submodule
```
git submodule add https://github.com/getkirby/database-storage.git site/plugins/database-storage
```
## How it works?
### Setting up a database
For this example, we are creating a new SQLite database in `/site/db` and call it `comments.sqlite`. But you can place it everywhere you like and then later change the path in the config. (see below)
### Required fields
Our database models require a couple core fields to work correctly:
| Field name | Type | Config
| - | - | - |
| id | INTEGER | primary key, autoincrement, not null, unique
| title | TEXT |
| slug | TEXT | not null
| uuid | TEXT | not null
| created | TEXT | not null, default: CURRENT_TIMESTAMP
| modified | TEXT | not null, default: CURRENT_TIMESTAMP
| version | TEXT | not null
| language | TEXT | not null
| parent | TEXT |
| template | TEXT |
| num | INTEGER | default: NULL
| lock | TEXT |
| draft | INTEGER | not null, default: 1
SQLite has a very limited set of column types. You might want to choose more appropriate types for MySQL or other databases.
Once all those columns are in place, you can add your own custom columns for custom fields. For our comments example, we will create a `text` and an `email` column.
Here's a full SQL query to create our comments database.
```sql
CREATE TABLE "comments" (
"id" INTEGER UNIQUE NOT NULL PRIMARY KEY ASC AUTOINCREMENT,
"title" TEXT,
"slug" TEXT NOT NULL,
"uuid" TEXT NOT NULL,
"created" TEXT DEFAULT CURRENT_TIMESTAMP NOT NULL,
"modified" TEXT DEFAULT CURRENT_TIMESTAMP NOT NULL,
"version" TEXT NOT NULL,
"language" TEXT NOT NULL,
"parent" TEXT,
"template" TEXT,
"num" INTEGER DEFAULT NULL,
"lock" TEXT,
"draft" INTEGER DEFAULT 1 NOT NULL
"text" TEXT,
"email" TEXT
);
```
### Create a table using the Kirby CLI
If you are using the Kirby CLI, you can create a new table via the `table:create` command:
```bash
kirby table:create
```
You will be asked to specify the database connection, the table name and the list of custom fields.
You can also provide database connection and table name immediately via arguments:
```bash
kirby table:create myDatabase myTable
```
`myDatabase` is referencing the config `key` for the database connection defined in your config (see below)
### Database Connection
We need to define the connection to our database in the `/site/config/config.php` under the `database` key. The name for the connection can be defined by you, but needs to match later with the `DATABASE_NAME` constant in our page model (see below)
```php
[
'comments' => new Database([
'type' => 'sqlite',
'database' => dirname(__DIR__) . '/db/comments.sqlite'
])
]
];
```
### Parent page
First, create a regular Kirby page that serves as the parent for your database pages. For our comments example, we create a new content folder called `/content/comments` with a text file called `comments.txt`. This will connect the page to a new `comments.php` template and – more importantly – a new `CommentsPage` model. This model is the key to load our child pages from the database (see the setup below)
### Models
For the new comments page, the model will use the `HasDatabaseChildren` trait from our plugin. This trait will replace the `$page->children()` method and load children from our database. All we need to do is to define the child model with the `DATABASE_CHILD_MODEL` constant.
**`/site/models/comments.php`**
```php