Introduction

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

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

Set up the Laravel app

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:

2. Enter into the folder and install the dependencies:

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

3. Copy the .env.example file into .env:

4. Start the application:

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

Set up the database

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 quickstart guide if you prefer the dashboard.

1. Authenticate the CLI with the following command:

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

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.

Connect to the Laravel app

There are two ways to connect to PlanetScale:

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

Both options are covered below.

Option 1: Connect with username and password (Recommended)

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

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:

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 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!

Option 2: Connect with the PlanetScale proxy

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

1. Open a connection by running the following:

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:

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!

Run migrations and seeder

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:

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

3. Next, seed the database by running:

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

Add data manually

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.

Add data with PlanetScale CLI

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:

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

3. Add a record to the stars table:

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:

Add data with Laravel Tinker

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:

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

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.

4. Type exit to exit Tinker.

What's next?

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.

Need help?

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