Connect a Laravel application to PlanetScale
Spin up a PlanetScale MySQL serverless database in seconds and connect to a Laravel application
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.
- Clone the starter Laravel application:
- Enter into the folder and install the dependencies:
You may need to run composer update
if you haven't updated in a while.
- Copy the
.env.example
file into.env
:
- 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.
- Authenticate the CLI with the following command:
- 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)
- Create a username and password with the PlanetScale CLI by running:
The PASSWORD_NAME
value represents the name of the username and password being generated. You can have multiple credentials for a branch, so this gives you a way to categorize them. To manage your passwords in the dashboard, go to your database overview page, click "Settings", and then click "Passwords".
Take note of the values returned to you, as you won't be able to see this password again.
- 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.
- 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
.
-
A secure connection to your database will be established and you'll see a local address you can use to connect to your application.
-
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.
-
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.
-
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.
- Next, seed the database by running:
You should get the message "Database seeding completed successfully".
- 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.
-
You may need to install the MySQL command line client if you haven't already.
-
Run the following command in your terminal:
This will open up a MySQL shell connected to the specified database and branch.
A branch, main
, was automatically created when you created your database, so you can use that for BRANCH_NAME
.
- Add a record to the
stars
table:
The values id
, created_at
, and updated_at
will be filled with default values.
-
Type
exit
to exit the shell. -
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.
- In your terminal, run the following command:
- Insert a new record into the
stars
table with:
The id
, created_at
, and updated_at
will be filled with default values.
- 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.
- 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.