• The basics

Databases

On the Includable platform, every community (site) shares most of its data in database tables that are used by all communities, to allow giving the same user account access to multiple communities, etc.

Every community also has its own database however, that can be accessed by modules to create and utilize custom database tables specifically for those modules. This makes sure that tables that are specific to certain communities or resellers don't clutter the main Includable database.

Example code

The example below shows how to get access to this community-specific database.

// Get the database instance
$db = community()->getDatabase();

// You can now use $db to interact with the database, i.e.:
$tables = $db->query('SHOW TABLES')->result();

echo '<h3>Database tables</h3><pre>';
print_r($tables);
echo '</pre>';

Notes:

  • The $db variable contains an instance of class DB. Note however that DB::instance() will always return a reference to the main Inlcudable database, not to the most recently created instance of DB. Be careful with this, especially when chaning table structures!

Using your own ORM

You can also simply get an array with the MySQL connection details, so that you can set up a database connection via your favourite ORM:

$data = community()->getDatabaseCredentials();

This array will contain the fields hostname, database, username and password.

Reseller-specific databases

There are also situations where you want the different communities in your account to be able to share a database. Therefore, the Reseller object also has a getDatabase function, which is accessible in the same way as described above:

// Get the database instance
$db = reseller()->getDatabase();

Migrations

Includable has a built-in system for managing database migrations. This allows you to conveniently create tables in an empty database or alter the structure of an existing database, without any error-prone manual work. This is how it works:

  • Have a directory with SQL files that should be executed exactly once. The execution order is dependent on the file name, so we recommend using a format like 2017-01-01-0000-create-table-articles.sql.

  • Call the migrate() function on the Migrations class in your script whenever you want to execute any new migration files that might be present. The Migrations class will take care of checking what migrations it has already executed in the database (via a migrations table it creates on first run) and execute any SQL files it hasn't occurred before.

Complete code example for migrations in a community-specific database:

migrations/2017-01-01-0000-create-table-articles.sql

CREATE TABLE `articles` (
  `id` INT(11) UNSIGNED NOT NULL AUTO_INCREMENT,
  `title` VARCHAR(255) DEFAULT NULL,
  `body` TEXT
  PRIMARY KEY (`id`)
)
  ENGINE = InnoDB
  DEFAULT CHARSET = latin1;

web/index.php

// Import Migrations class
use Services\Database\Migrations;

// Get community database
$db = community()->getDatabase();

// Execute migrations
// Hint: change last parameter to `true` to output executed migration names for debugging
Migrations::migrate($db, $this->module->path . 'migrations', false);