Skip to main content
Laravel connects to Neki through its Postgres database driver. Eloquent and the query builder work through the same connection. Before you start, you need:
  • A Neki database with a ready branch.
  • An application role for that branch. Use pg_read_all_data for read traffic and add pg_write_all_data when the application writes rows. These inherited data roles do not grant CREATE or ALTER, so application credentials cannot change the schema.
  • A separate migration role, if you run schema changes against the branch. DDL requires the postgres inherited role. Neki restricts execution of the cross-router DDL barrier function __neki.wait_for_ddl to its neki_viewer role, so add neki_viewer, which requires pg_read_all_data, to the same role. Keep the migration credentials out of the application’s runtime configuration.
  • The Primary connection details from the database’s Connect page.
Use the complete generated username. It contains the branch routing information required by Neki.

​
Enable the Postgres PDO driver

Laravel’s Postgres connector requires PHP’s pdo_pgsql extension. Install or enable the extension for every environment that runs the application, then confirm that PHP loaded it:

​
Add the connection details

Add the values from the Connect page to .env. Set DB_SSLROOTCERT to the path of the system CA bundle:
.env
Do not commit this file. Set the same values through your deployment platform’s secret manager in production.

​
Configure the Postgres connection

Make sure the pgsql entry in config/database.php reads the TLS settings:
config/database.php
Confirm the connection with Tinker:
Framework migration commands send DDL through a normal Neki connection. The router fans that DDL out to the managed shards, but it does not create a managed schema-change workflow. Use a schema-change workflow when you want Neki to prepare and coordinate an Online DDL change.
Run migrations with the migration role described in the prerequisites. An application role that inherits only pg_read_all_data and pg_write_all_data cannot run CREATE or ALTER, so a migration that uses application credentials fails on its first DDL statement. Apply migration DDL with psql and the migration role so the client prints PostgreSQL notices:
The router that commits the DDL emits a NOTICE containing the barrier call for that transaction:
The schema and cluster versions belong to that transaction, and the notice is the only place Neki reports them. Before you deploy application code that depends on the new schema, run the emitted call verbatim on a primary connection that uses the migration role:
The call returns after every router has applied both versions. A successful migration only confirms that the DDL committed and is visible through the router that ran it; it does not replace this cross-router barrier. Some framework migration commands discard notices. Generate migration SQL with the framework, but apply it with psql when the framework cannot preserve the notice. If the notice is lost, its version pair cannot be reconstructed.

​
Route a Laravel process to replicas

Laravel 12’s PostgresConnector does not add arbitrary libpq startup parameters from config/database.php to its PDO DSN. Set PGOPTIONS in the process environment before PHP starts so pdo_pgsql sends the Neki target when it opens each connection:
Confirm the target in Tinker:
In production, set the same PGOPTIONS value on a dedicated read-only worker or service. The setting applies to every pdo_pgsql connection created by that PHP process, so do not set it on a process that also handles writes. Replica-routed connections reject inserts, updates, and deletes, and reads can return stale data. See Primary and replica routing.

​
Need help?

Get help from the PlanetScale Support team, or join our Discord community to see how others are using PlanetScale.