Database setup

Configure Stratus POS for SQLite, MySQL, or PostgreSQL, run migrations, and understand the database schema.

Stratus supports MySQL, PostgreSQL, and SQLite. The default connection is MySQL. SQLite is a zero-configuration option suitable for local development and testing. MySQL or PostgreSQL are recommended for production.

Choosing a database

MySQL (default)

Create a MySQL database, then add the connection details to .env:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=stratus
DB_USERNAME=root
DB_PASSWORD=

Then run migrations:

php artisan migrate

PostgreSQL

Create a PostgreSQL database, then add the connection details to .env:

DB_CONNECTION=pgsql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=stratus
DB_USERNAME=postgres
DB_PASSWORD=

Then run migrations:

php artisan migrate

SQLite

SQLite stores the entire database in a single file at database/database.sqlite. It requires no server process and is ready to use with zero configuration.

DB_CONNECTION=sqlite

Create the database file if it does not exist:

touch database/database.sqlite

Then run migrations:

php artisan migrate

SQLite is suitable for development and small single-server deployments. For high-traffic or multi-server production environments, use MySQL or PostgreSQL.

Running migrations

Migrations create and update the database schema. Run them after configuring your database connection:

php artisan migrate

To check migration status:

php artisan migrate:status

Database tables

The default migrations create the following tables:

Table	Migration file	Purpose
users	0001_01_01_000000	User accounts and authentication data.
password_reset_tokens	0001_01_01_000000	Tokens for the password reset flow.
sessions	0001_01_01_000000	Database-backed session storage.
cache	0001_01_01_000001	Key-value cache store.
cache_locks	0001_01_01_000001	Distributed cache lock management.
jobs	0001_01_01_000002	Pending queue jobs.
job_batches	0001_01_01_000002	Metadata for batched queue jobs.
failed_jobs	0001_01_01_000002	Jobs that failed after all retry attempts.

Resetting the database

migrate:fresh drops all tables and re-runs every migration from scratch. All data will be permanently destroyed. Never run this on a production database.

To reset the database during development:

php artisan migrate:fresh

To reset and re-seed with test data:

php artisan migrate:fresh --seed

Local development with Laravel Sail

Laravel Sail provides a Docker-based local environment with MySQL (or PostgreSQL) and other services configured out of the box. It is included as a dev dependency.

1. Start Sail

   ./vendor/bin/sail up -d
   

   This starts MySQL, Redis, Mailpit, and the PHP application container.

2. Update .env for Sail

   Sail sets the database host to the service name defined in docker-compose.yml. Update .env:

   DB_CONNECTION=mysql
   DB_HOST=mysql
   DB_PORT=3306
   DB_DATABASE=stratus
   DB_USERNAME=sail
   DB_PASSWORD=password
   
3. Run migrations inside the container

   ./vendor/bin/sail artisan migrate
   

Run ./vendor/bin/sail artisan instead of php artisan to execute Artisan commands inside the Sail container.

Advanced options

Connecting to an existing database

If you have an existing Stratus database (for example, when deploying to a new server), set the correct credentials in .env and run:

php artisan migrate

Laravel will only run migrations that have not been recorded in the migrations table, leaving existing data untouched.

Changing the default database connection

DB_CONNECTION sets the default connection. The full set of connection options for each driver is defined in config/database.php. You can define multiple connections there and reference them explicitly in model definitions or query builder calls.

SQLite in-memory database for testing

For fast test runs, configure phpunit.xml to use an in-memory SQLite database:

<env name="DB_CONNECTION" value="sqlite"/>
<env name="DB_DATABASE" value=":memory:"/>

Tests that use RefreshDatabase or DatabaseMigrations will run against the in-memory database and leave no files on disk.