In this tutorial, you'll learn how to connect a Laravel application to a PlanetScale MySQL database using a sample Laravel starter app.

• 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

This guide will integrate a simple Laravel 8 app with PlanetScale that will display a list of stars stored in the database. If you have an existing application, you can also use that.

1. Clone the starter Laravel application:

Copied
git clone https://github.com/planetscale/laravel-example.git

2. Enter into the folder and install the dependencies:

Copied
cd laravel-example
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:

Copied
cp .env.example .env

4. Start the application:

Copied
php artisan serve

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

Next, you need to set up your PlanetScale database and connect to it in the Laravel application.

You can create a database either in the PlanetScale dashboard or from the PlanetScale CLI. This guide will use the CLI, but you can follow the database setup instructions in the PlanetScale quick start guide if you prefer the dashboard.

1. Authenticate the CLI with the following command:

Copied
pscale auth login

2. Create a new database with a default main branch with the following command:

Copied
pscale database create <DATABASE_NAME> --region <REGION_SLUG>

This tutorial uses laravel-example for DATABASE_NAME, but you can use any name with lowercase, alphanumeric characters, and dashes or underscores.

For REGION_SLUG, choose a region closest to you from the available regions or leave it blank.

That's it! Your database is ready to use. Next, let's connect it to the Laravel application and then add some data.

There are two ways to connect to PlanetScale:

• Using the PlanetScale proxy with the CLI
• With an auto-generated username and password

Both options are covered below.

1. Create a username and password with the PlanetScale CLI by running:

Copied
pscale password create <DATABASE_NAME> <BRANCH_NAME> <PASSWORD_NAME>

Take note of the values returned to you, as you won't be able to see this password again.

2. Open the .env file in your Laravel app, find the database connection section, and fill it in as follows:

Copied
DB_CONNECTION=mysql
DB_HOST=<ACCESS HOST URL> // outputted in the previous step
DB_PORT=3306
DB_DATABASE=<DATABASE_NAME> // this tutorial uses 'laravel-example'
DB_USERNAME=<USERNAME> // outputted in the previous step
DB_PASSWORD=<PLAIN TEXT> // outputted in the previous step
MYSQL_ATTR_SSL_CA=/etc/ssl/cert.pem

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

You can also get these exact values to to copy/paste from your PlanetScale dashboard. In the dashboard, click on the database > "Connect" > "Generate new password" > "General" dropdown > "Laravel".

Refresh your Laravel homepage and you should see the message that you're connected to your database!

To connect with the PlanetScale proxy, you'll need the PlanetScale CLI.

1. Open a connection by running the following:

Copied
pscale connect <DATABASE_NAME> <BRANCH_NAME>

If you're following this guide exactly and haven't created any branches, you can use the default branch, main.

2. A secure connection to your database will be established and you'll see a local address you can use to connect to your application.

3. Open the .env file in your Laravel app and update it as follows:

Copied
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306 // Get this from the output of the previous step
DB_DATABASE=<DATABASE_NAME>
DB_USERNAME=
DB_PASSWORD=

The connection uses port 3306 by default, but if that's being used, it will pick a random port. Make sure you paste in whatever port is returned in the terminal. You can leave DB_USERNAME and DB_PASSWORD blank.

Refresh your Laravel homepage and you should see the message that you're connected to your database!

Now that you're connected, let's add some data to see it in action. The sample application comes with a migration file at database/migrations/2021_12_20_194637_create_stars_table.php that will create a stars table in the database. There's also a database/seeders/StarSeeder.php file that will add two rows to the stars table. Let's run those now.

1. Make sure your database connection has been established. You'll see the message "You are connected to your-database-name" on the Laravel app homepage if everything is configured properly.

2. In your terminal in the root of the Laravel project, run the following to run the migration:

Copied
php artisan migrate

You should get a message that the migration table was successfully created.

3. Next, seed the database by running:

Copied
php artisan db:seed

You should get the message "Database seeding completed successfully".

4. Refresh your Laravel homepage and you'll see a list of stars and their constellations printed out.

The resources/views/home.blade.php file pulls this data from the stars table with the help of the app/Http/Controllers/StarController.php file.

Laravel PlanetScale starter app homepage

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

• PlanetScale CLI shell
• Laravel Tinker
• PlanetScale dashboard console
• Your favorite MySQL client (E.g. Arctype, TablePlus, DataGrip, etc.)

The first two options are covered below. To explore the dashboard console, go to your PlanetScale database in the dashboard, click on the branch, and click the "Console" tab.

You can use the PlanetScale CLI to open a MySQL shell to interact with your database.

1. You may need to install the MySQL command line client if you haven't already.

2. Run the following command in your terminal:

Copied
pscale shell <DATABASE_NAME> <BRANCH_NAME>

This will open up a MySQL shell connected to the specified database and branch.

3. Add a record to the stars table:

Copied
INSERT INTO `stars` (name, constellation)
VALUES  ('Sagittarius', 'Kaus Media');

The values id, created_at, and updated_at will be filled with default values.

4. Type exit to exit the shell.

5. Refresh the Laravel homepage to see the new record. You can also verify it was added in the PlanetScale CLI MySQL shell with:

Copied
select * from stars;

Laravel comes with a powerful tool called Tinker that lets you interact with your database from the command line. Let's add some data with it.

1. In your terminal, run the following command:

Copied
php artisan tinker

2. Insert a new record into the stars table with:

Copied
DB::table('stars')->insert(['name'=>'Sagitarrius', 'constellation'=>'Kaus Media']);

The id, created_at, and updated_at will be filled with default values.

3. Refresh your Laravel application homepage to see your new data. You can also run the following command in Tinker to see all records in the stars table.

Copied
App\Models\Star::all();

4. Type exit to exit Tinker.

Once you're done with development, you can promote your main branch to production to get a highly available branch protected by direct schema changes.

Learn more about how PlanetScale allows you to make non-blocking schema changes to your database tables without locking or causing downtime for production databases. If you're interested in learning how to secure your application when connecting to PlanetScale, please read Connecting to PlanetScale securely.

Get help from PlanetScale's support team, or join our GitHub Discussion board to see how others are using PlanetScale.