Learn how to integrate PlanetScale with a sample Laravel application

This sample application demonstrates how to connect to a PlanetScale MySQL database, run migrations, seed the database, and display the data.

For the full tutorial, see the Laravel PlanetScale documentation.

Prerequisites

• PHP — This tutorial uses v8.1
• Composer
• A free PlanetScale account
• PlanetScale CLI —You can also follow this tutorial using just the PlanetScale admin dashboard, but the CLI will make setup quicker. For dashboard instructions, see the full tutorial.

Set up the Laravel app

1. Clone the starter Laravel application:

   git clone https://github.com/planetscale/planetscale-laravel-mysql.git

2. Enter into the folder and install the dependencies:

   cd planetscale-laravel-mysql
   composer install

   You may need to run composer update if you haven't updated in a while.

3. Copy the .env.example file into .env and generate the app key:

   cp .env.example .env
   php artisan key:generate

Set up the database

If this is your first time in the dashboard, you'll be prompted to create an organization and go through the database creation walkthrough. Otherwise, click "New database" > "Create new database".

• Name — You can use any name with lowercase, alphanumeric characters, or underscores. We also permit dashes, but don't recommend them, as they may need to be escaped in some instances.
• Region — Choose the region closest to you or your application. It's important to note if you intend to make this branch a production branch, you will not be able to change the region later, so choose the region with this in mind.
• Storage option — Choose a storage option. You can choose between network-attached storage or Metal for storage. For more information, see the [plans](plans documentation).
• Cluster size — Select the desired cluster size for your database.

Finally, click "Create database".

Connect to the Laravel app

First, you need to generate a database username and password so that you can use it to connect to your application.

You'll be presented with this option after creating your database. You can also access the password creation page by clicking "Connect" -> "Create password".

Click "Laravel" as the framework, then copy the contents of the .env tab and paste them into your own .env file in your Laravel application. The structure will look like this:

DB_CONNECTION=mysql
DB_HOST=<ACCESS HOST URL>
DB_PORT=3306
DB_DATABASE=<DATABASE_NAME>
DB_USERNAME=<USERNAME>
DB_PASSWORD=<PASSWORD>
MYSQL_ATTR_SSL_CA=/etc/ssl/cert.pem

The MYSQL_ATTR_SSL_CA value is platform-dependent. Please refer to our documentation around how to connect to PlanetScale securely for the platform you're using.

Run migrations and seeder

Laravel uses foreign key constraints by default. PlanetScale, however, has foreign key constraint support turned off by default. For this tutorial, we're keeping the Laravel defaults, so you need to enable foreign key constraint support in your database settings page. Click the checkbox next to "Allow foreign key constraints" and press "Save database settings".

Let's migrate and seed the database now.

1. In the root of the Laravel project, run the following to migrate and seed the database:

   php artisan migrate --seed

2. Start the application:

   php artisan serve

You can view the application at http://localhost:8000.

1. Refresh your Laravel homepage and you'll see a list of users.

Add data manually

If you want to continue to play around with adding data on the fly, you have a few options:

• PlanetScale dashboard console
• Laravel Tinker
• PlanetScale CLI shell
• Your favorite MySQL client (for a list of tested MySQL clients, review our article on how to connect MySQL GUI applications)

The first option is covered below.

Add data in PlanetScale dashboard console

PlanetScale has a built-in console where you can run MySQL commands against your branches.

By default, web console access to production branches is disabled to prevent accidental deletion. From your database's dashboard page, click on the "Settings" tab, check the box labelled "Allow web console access to production branches", and click "Save database settings".

To access it, click "Console" > select your branch > "Connect".

From here, you can run MySQL queries and DDL against your database branch.

1. Add a record to the users table:

   UPDATE users
   SET email = 'cyrus@planetscale.com'
   WHERE id=1;

2. Refresh the Laravel homepage to see the new record. You can also verify it was added in the console with:

   SELECT * FROM users;

What's next?

Once you're done with initial development, you can enable safe migrations to protect from accidental schema changes and enable zero-downtime deployments.

To learn more about PlanetScale, take a look at the following resources:

• PlanetScale workflow — Quick overview of the PlanetScale workflow: branching, non-blocking schema changes, deploy requests, and reverting a schema change.
• PlanetScale branching — Learn how to utilize branching to ship schema changes with no locking or downtime.
• PlanetScale CLI — Power up your workflow with the PlanetScale CLI. Every single action you just performed in this quickstart (and much more) can also be done with the CLI.