Skip to content

SYSTEM

Laravel

Laravel is a PHP web framework created by Taylor Otwell (2011). MVC-style, convention-over-configuration, batteries-included (ORM, migrations, queues, auth, mail, caching, testing). Uses Eloquent as its ActiveRecord-style ORM (compare Rails ActiveRecord) and Artisan as its CLI (compare rake / rails).

This page catalogues Laravel for cross-referencing from database-connectivity + serverless-deploy posts; it does not attempt to recapitulate the framework.

Relevant aspects for this wiki

  • Request-per-process lifecycle by default — Laravel, like most PHP frameworks, inherits PHP's concepts/shared-nothing-php-request-model. Each HTTP request boots the full Laravel application, handles the request, tears down. DB connections, caches, config resolution, route compilation — all re-done per request.
  • Laravel Octane (see systems/laravel-octane) is the official persistent-process handler that flips this — keeps the Laravel application in memory across requests, supports DB connection reuse via OCTANE_PERSIST_DATABASE_SESSIONS=1.
  • .env-driven database config — standard Laravel DB_CONNECTION / DB_HOST / DB_DATABASE / DB_USERNAME / DB_PASSWORD env-var set; PDO SSL configured via MYSQL_ATTR_SSL_CA.
  • Artisan CLI — php artisan migrate, php artisan db:seed, custom commands. Under Bref on Lambda, invoked via serverless bref:cli --args="migrate --force".

Serverless deploy shape (Bref + Lambda + PlanetScale)

# serverless.yml, generated via:
# php artisan vendor:publish --tag=serverless-config
# then edited as below for Octane
web:
  handler: Bref\LaravelBridge\Http\OctaneHandler
  runtime: php-81
  environment:
    BREF_LOOP_MAX: 250
    OCTANE_PERSIST_DATABASE_SESSIONS: 1
  events:
    - httpApi: '*'

DB_CONNECTION=mysql
DB_HOST=<planetscale-host>
DB_DATABASE=<db-or-@primary-for-sharded>
MYSQL_ATTR_SSL_CA=/opt/bref/ssl/cert.pem

(Source: .)

Measured performance against PlanetScale

Config p50 p95 Throughput
Classic (shares-nothing) 75 ms 130 ms 3,800 req/min
Octane (persistent) 14 ms 35 ms ~4,800 req/min

5.4× p50 improvement from switching to Octane on identical hardware + identical DB, driven by amortising TLS handshake + Laravel bootstrap across ~250 invocations per Lambda execution environment.

Schema migrations + PlanetScale

Laravel ships two migration primitives that are idiomatic inside the framework but dangerous against a production PlanetScale database:

  1. php artisan migrate executes ALTER TABLE / CREATE TABLE / DROP TABLE directly against the bound DB connection — direct DDL. Laravel's own deploy-tool Forge bakes this into its quick-deploy sequence (git pull → composer install → php artisan migrate), normalising the direct-DDL anti-pattern as canonical Laravel workflow.

  2. Migration files in database/migrations/ are PHP classes whose up() / down() methods invoke Schema::table(...) builder DSL; shape is database-agnostic but execution is synchronous + connection-held.

PlanetScale's safe-migrations feature (docs) blocks direct DDL on production branches by default — php artisan migrate against a production PlanetScale branch fails with an explicit error; verbatim: "in order to protect your production environment, PlanetScale does not support direct DDL on production branches, unless you disable safe migrations." The prescribed workflow is:

  • Connect dev Laravel env to a PlanetScale development branch (not production), run php artisan migrate against that dev branch.
  • Promote schema to production via deploy request, which PlanetScale applies using shadow-table online DDL — non-blocking, revertible inside a 30-minute window.

Laravel rename migration recipe (column or table) is a worked example of expand-migrate-contract: clone new column/table → deploy code that dual-writes → backfill old rows via artisan tinker or a queued job → deploy code that reads from new → deploy PlanetScale deploy-request that drops old. PlanetScale's schema-change deploy-order question ("when do I run my migrations?") answers by schema-change shape:

  • Add column / add table: schema-deploy first (PlanetScale deploy request completes) → code-deploy (Laravel app writes to new surface).
  • Drop column / drop table: code-deploy first (Laravel app stops writing) → schema-deploy (PlanetScale drops the surface).
  • Rename: neither order suffices; requires the eleven-step clone-dual-write-backfill-switch-drop sequence above.

(Source: .)

Seen in

  • — canonical worked example of a versioned-migration tool. Morrison II uses Laravel's default scaffold (4 migrations in database/migrations/ with YYYY_MM_DD_HHMMSS_description.php filename convention) to demonstrate all four mechanics of the versioned paradigm: (1) sequential numbered migration files whose lexical sort = apply order; (2) the migrations (id, migration, batch) table inserted on first run; (3) paired up() / down() closures (Blueprint DSL: Schema::table('users', fn ($t) => $t->string('nickname')) / $t->dropColumn('nickname')); (4) batch-column rollback grouping via artisan migrate:rollback --step=N. Also canonicalises Laravel's default-scaffold 4-migration set (users / password_resets / failed_jobs / personal_access_tokens) and the per-migration timing output 2023_01_13_000001_add_new_column .......... 32ms DONE. PlanetScale-composition framing: when safe-migrations is off, artisan migrate works unchanged; when on, the tool must run against a development branch and the diff promoted via deploy request — with PlanetScale's "automatically copy migration data between branches" setting keeping the migrations table rows synced across the schema-only merge.

  • — canonical Laravel-workflow instantiation of PlanetScale's shadow-table + deploy-request + 30-minute-revert doctrine. Frames Forge's quick-deploy php artisan migrate step as the direct-DDL anti-pattern; prescribes PlanetScale-dev-branch-plus-deploy-request workflow + expand-migrate-contract rename recipe.

  • — canonical Laravel + Bref + PlanetScale benchmark; introduces Laravel and its Octane variant as the request-per-process vs persistent-process comparison.

Last updated · 542 distilled / 1,571 read