> ## Documentation Index
> Fetch the complete documentation index at: https://cloud.laravel.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Laravel MySQL
> Fully managed MySQL database.
## Introduction
Laravel MySQL provides a fully managed MySQL database for your application. Each Laravel MySQL database cluster is assigned a compute and storage size, and can be scaled at any time. Storage can also be [upsized automatically](#automatic-upsizing) as your data grows. Flex sizes can [scale to zero](#scale-to-zero) when idle.
## Creating MySQL databases
To create and attach a MySQL database to an environment:
1. Navigate to your environment's infrastructure canvas dashboard
2. Click "Add database"
3. Select an existing database cluster or create a new one:
* **To create a new cluster**: Select "Laravel MySQL" as your database cluster type and configure:
* **Cluster name**: A unique name for your database cluster
* **Instance size**: Choose from available compute options (Flex or Pro sizes)
* **Storage**: Configure storage from 5GB to 1,000GB
* **Region**: Must match your compute cluster's region
4. Select an existing database within the cluster or create a new one:
* **Database name**: The name of the database within the cluster
You can also create MySQL databases from your organization's **Resources** page, but they will need to be attached to an environment separately.
Once created, you can attach the database to any environment in the same region. When attaching a database to an environment, you will need to re-deploy the environment for the changes to take effect.
Visit the [pricing](/docs/pricing#laravel-mysql) docs for information on compute and storage prices by region.
A database cluster must be in the same region as the environments that attach to its databases.
### Database clusters vs. databases
When creating a new database cluster, you will be asked to provide the desired name of the cluster and the desired name of the initial "database" that will be created within the cluster. Each database cluster can have as many databases as needed within the cluster. In web development, these databases are sometimes referred to as "schemas".
Environments attach to a database, not to a cluster. When attaching, you first choose the database cluster and then select the database within it that you want to make available through the `DB_DATABASE` environment variable.
### Editing and resizing database clusters
To edit your database clusters and adjust their compute / storage settings, navigate to **Organization > Resources > Databases** and click the **...** icon for the database cluster you would like to edit or resize. Then, click **Edit settings**.
Changing the compute size restarts your database cluster. Expect under a minute of downtime while the cluster restarts. Your data is not affected.
Laravel MySQL storage can only be increased once every 6 hours and cannot be decreased.
### Automatic upsizing
Laravel MySQL databases can automatically increase their storage **once they reach 90% of their allocated space**. The database stays online while the increase is applied and the additional storage becomes available immediately.
Each increase grows storage by 50% of the current allocation, rounded to the nearest 5GB, so larger databases receive proportionally more headroom. You can also set a maximum size for each database, and automatic upsizing will not grow a database past that limit. Each database is automatically upsized at most once every 6 hours.
Laravel Cloud sends a [notification](/docs/notifications) when a database reaches 75% of its allocated storage, and another at 90%, when the upsize takes place. Each notification states the size the database will grow to and what the change adds to your monthly cost.
Automatic upsizing is enabled by default on all newly created databases.
### Monitoring database cluster metrics
To view metrics such as CPU, write throughput, and storage for your database cluster, navigate to **Organization > Resources > Databases**, click the database cluster card, and review the **Metrics** section. Use the time range selector to adjust the period shown.
### Deleting database clusters
To delete a database cluster, navigate to **Organization > Resources > Databases** and click the **...** icon for the database cluster you would like to delete. Then, click **Delete** and confirm your action.
## Scale-to-Zero
Laravel MySQL Flex sizes can scale to zero, sleeping when your database cluster is idle so that you are not billed for compute. The cluster's storage stays online the entire time it sleeps, so your data is always preserved. Storage is billed as usual while the cluster sleeps.
A database cluster goes to sleep when it has received no connections for its configured idle timeout, which may be set between 1 minute and 1 hour. The next connection wakes the cluster automatically. Because every Laravel MySQL database cluster is fronted by a proxy layer, the incoming connection is held while compute resumes and forwarded once the cluster is awake, so your application sees a slightly slower first query instead of a connection error. Waking typically adds a few hundred milliseconds to that first query, increasing with the amount of RAM used by the cluster. Scheduled backups and manual snapshots briefly wake a sleeping cluster and let it return to sleep once complete.
Scale-to-Zero is available on the Flex sizes in all regions. New database clusters use the current generation of Flex and Pro sizes, and previous-generation sizes are no longer offered. Existing clusters continue to run on their current size and pricing unchanged. Pro sizes are always-on and do not scale to zero.
Pairing a Flex database cluster that scales to zero with [application compute](/docs/compute#scale-to-zero) and a [Laravel Valkey cache](/docs/resources/caches/valkey#scale-to-zero) that scale to zero helps minimize costs on development environments and side projects.
## Importing MySQL data
After enabling your [MySQL Public Endpoint](#mysql-public-endpoints), you can use any standard database tools to import your SQL data. For optimal performance, we recommend generating database dumps with the `--skip-extended-insert` option, especially for smaller Laravel MySQL instances, to reduce memory usage.
### Recommended MySQL import tools
The following tool offers efficient and reliable database imports, particularly for larger datasets:
* [mydumper](https://github.com/mydumper/mydumper)
This tool supports parallel execution, making it significantly faster than the traditional `mysqldump` and `mysql` commands when handling large databases. Additionally, GUI-based tools like **TablePlus** can be used for imports. However, be aware that smaller Laravel MySQL instances may encounter memory limitations when using such tools.
## Database sizing and performance
### Choosing the right cluster size
Several key factors influence the right database cluster size for your workload: connection requirements, queue workload, backup retention needs, and planned database migrations.
### Connection limits
The amount of RAM your database cluster has determines how many simultaneous connections it can support:
| Server Memory | MySQL Connection Limit |
| - | - |
| 512 MB | 51 |
| 1 GB | 102 |
| 2 GB | 204 |
| 4 GB | 408 |
| 8 GB | 816 |
| 16 GB | 1,632 |
| 32 GB | 3,264 |
All database clusters are fronted by a proxy layer in Laravel Cloud, which helps multiplex connections for read-only queries, enabling up to 10,000 connections in some conditions. However, writes and transactions cannot be multiplexed, so those count against your MySQL connection limit. Plan your cluster size based on your expected mix of reads and writes.
### Queue workload considerations
If your application runs queue workers with a low `--sleep` interval (such as `--sleep=1` or lower), expect high CPU usage. That's acceptable for development environments, but in production, we recommend a minimum of 2 vCPUs, possibly more for high-throughput jobs.
### Backup retention planning
Backups are essential—especially for production databases. If you're working with a disposable or development database, it's fine to set the retention period to 0 days.
For anything else, we recommend at least 2 days of backup retention for basic protection and recovery.
### Database migrations and imports
Planning to transfer or import a database? You may need to temporarily scale up your database cluster's CPU and memory to handle large or fast MySQL imports.
* **CPU and memory** can be scaled up and down at any time, with under a minute of downtime while the cluster restarts
* **Storage size** can only be increased—not decreased—so plan for long-term needs before import
For smoother imports, consider using optimized dump commands:
```bash theme={null}
mysqldump -u USER -h HOSTNAME -p --single-transaction --set-gtid-purged=OFF --databases my_database > backup_my_database.sql
```
## Database backups
Laravel MySQL database clusters support automated and manual backups.
### Backup configuration
To configure backups for your MySQL database cluster:
1. Navigate to **Organization > Resources > Databases**.
2. Click your Laravel MySQL database cluster.
3. In the **Backups** section, click **Settings**.
4. Enable or disable the **Backups** toggle. When enabled, configure **Backup retention** to choose how long to keep automatic daily backups.
5. Click **Update** to save your settings.
### Backup retention period
When automatic backups are enabled, you can configure the retention period from 1–30 days. Automatic backups occur during a daily 3-hour backup window, scheduled between 3AM and 6AM EDT.
### Manual backups
To create a manual backup, click **New backup** in your database cluster's **Backups** section, provide a name and an optional description, and click **Create backup**. You can create manual backups at any time, regardless of your automatic backup settings.
### Restoring from backups
Backups restore to a new database cluster rather than overwriting the existing cluster. In your cluster's **Backups** section, find the backup you want to restore, click its **...** menu, and select **Restore**.
Enter a name for the new database cluster and click **Restore backup** to confirm.
Once the backup has been restored, you will now have two database clusters, the original database cluster and a database cluster restored from the backup you selected.
At this point, you can either detach the original database from your environment and attach the corresponding database from the restored cluster, or [connect to each database](#connecting-to-database-clusters) and selectively restore any missing information you might have. When you no longer need one of the database clusters, you may delete it.
#### How to download a backup
Laravel Cloud stores backups as internal snapshots and does not expose them as raw `mysqldump` files. To download a copy of your data:
1. Restore the desired backup into a new database cluster so your production cluster remains untouched.
2. Enable the restored cluster's public endpoint and copy the credentials (see [Connecting to database clusters](#connecting-to-database-clusters)).
3. Use your preferred tool (TablePlus, `mysqldump`, [mydumper](https://github.com/mydumper/mydumper), etc.) to export or download the data to your machine.
Once you've downloaded the data, you can disable the public endpoint again and delete the temporary cluster if it is no longer needed.
### Backup pricing
Laravel MySQL backup storage is billed separately from database storage:
* **Storage pricing**: `$0.10/GB-mo` (US regions) and `$0.12/GB-mo` (other regions)
* **Backup pricing**: Billed at the same rate as storage pricing
Backups are billed for the amount of gigabyte-months used. Total backup storage is calculated by daily summing up all manual snapshots and automated snapshots, then averaging those values across the billing period.
Laravel MySQL database clusters default to 7-day backup retention. To adjust this retention period or disable automatic backups, click **Settings** in your database cluster's **Backups** section.
## Connecting to database clusters
### From your application
When a database is attached to an environment, Laravel Cloud automatically injects database connection environment variables, including `DB_HOST`, `DB_USERNAME`, `DB_PASSWORD`, and `DB_DATABASE`. You may view these variables in your environment's General Settings.
### From your local machine
To connect to your database from your local machine using a database management client like [TablePlus](https://tableplus.com/), navigate to **Organization > Resources > Databases**, click your database cluster, and click **View credentials** at the top of the page. To view credentials for a specific database, use its **... > View credentials** menu in the **Databases** section.
The credentials dialog provides the connection details for your database. Use the **Open in database client** button in the **Deeplink** field to open your database in your local machine's default database management client, if you have one installed.
### MySQL public endpoints
Before connecting to a MySQL database cluster, you must enable its public endpoint. From your organization's **Resources** page, navigate to the **Databases** tab and click the **...** icon for the MySQL database cluster you would like to connect to. Then, click **Edit settings** and enable the **Enable public endpoint** toggle.
Once the public endpoint has been enabled, open the MySQL database cluster page and click **View credentials**. When you are finished interacting with your database from your local machine, you may disable the public endpoint.
### Laravel MySQL SSL connections
Laravel applications that connect to MySQL databases over SSL should add the following [environment variable](/docs/environments#environment-variables):
```ini theme={null}
MYSQL_ATTR_SSL_CA="/etc/ssl/certs/ca-certificates.crt"
```
## Database users
Every database cluster is created with a default user, whose credentials Laravel Cloud injects into your environment as the `DB_USERNAME` and `DB_PASSWORD` [environment variables](/docs/environments#environment-variables). In addition to this default user, you may create additional users with their own credentials and access level. For example, you might create a read-only user for a reporting tool or a scoped user for a background service. Database users are supported on both [RDS MySQL, RDS Postgres](/docs/private-cloud/rds) and Laravel MySQL clusters.
### Creating a database user
To create a new database user:
1. Navigate to **Organization > Resources > Databases** and click the database cluster.
2. In the **Database users** section, click **New user**.
3. Configure the user:
* **Username**: A unique username for the user
* **Permission**: Choose **Read-only** or **Read-write**
* **Access** (optional): Restrict the user to specific databases within the cluster
4. Click **Create database user**.
You provide the username, and Laravel Cloud automatically generates a secure password, which it displays after the user is created. Be sure to copy the password and store it somewhere safe, as it grants access to your database.
The default user injected into your environment cannot be edited or deleted.
### Read-only vs. read-write access
* **Read-only** users may query data but cannot insert, update, or delete records or modify the schema. This is ideal for reporting dashboards or teammates who only need to inspect data.
* **Read-write** users have full read and write access to the schemas they are scoped to.
## Database upgrades
Laravel MySQL database clusters may periodically require an upgrade to stay secure and compatible with our latest features. To check if your cluster requires an upgrade, go to **Organization > Resources > Databases** and click the **...** menu for your database cluster. If an **Upgrade Database** option is present, an upgrade is required.
To upgrade your database cluster:
1. Click the "..." menu
2. Select "Upgrade Database"
3. Confirm the upgrade
The upgrade process will cause several minutes of downtime depending on the size of your data.
### Maintenance window
For critical security fixes, Laravel Cloud may need to apply updates to your database cluster during its maintenance window.
Updates may take up to a minute, during which **your database cluster will be briefly unavailable**. We recommend setting your 30-min maintenance window during a low-traffic window.
To set your maintenance window:
1. Click the "..." menu
2. Select "Edit settings"
3. Select "Set time" in your maintenance window dropdown
4. Select a day and a timeslot (UTC)
By default, your Laravel MySQL database cluster's maintenance window starts at 2AM in the location of your database.
## Binary logs and storage usage
Your database's storage figure covers more than your tables. MySQL writes a binary log, an ordered record of every change made to your data, and those files live on the same volume as the data itself. Laravel Cloud reports the two together as a single storage number.
Binary logs are what make replication and point-in-time recovery possible, so they are not optional. They do mean that a database can grow toward its storage limit even when the amount of data you are storing has not changed. A write-heavy workload produces binary log volume out of proportion to the rows that end up stored, so a queue table churning through jobs or a repeated bulk import can leave the storage figure well above the size of your tables.
**How binary logs are cleaned up**
You do not need to manage this. Two mechanisms keep binary logs from filling your volume:
* **Scheduled rotation.** Binary logs are retained for roughly 8 days, then removed automatically.
* **Emergency cleanup.** Disk usage is checked every minute. If a volume passes 90% used, all but the most recent binary log is cleared immediately.
Because of the second mechanism, a write-heavy workload with little stored data will not run out of space from binary logs alone.
**Why your storage figure can move on its own**
Cleanup runs without prompting you, so the reported figure can fall as well as rise:
* A scheduled rotation or an emergency cleanup releases space, and usage drops.
* A busy period pushes usage back up as new logs accumulate.
A drop of this kind is normal and does not mean data was lost. It is also why a database sitting near a storage [notification](/docs/notifications) threshold can cross it and fall back below more than once.
**Working out what's using your storage**
Binary log usage is not reported separately, so the storage figure is the total of both. To see how much of it is your data, query your table and index sizes:
```sql theme={null}
SELECT table_name,
ROUND((data_length + index_length) / 1024 / 1024, 1) AS mb
FROM information_schema.tables
WHERE table_schema = DATABASE()
ORDER BY data_length + index_length DESC;
```
If that total sits well below your reported storage usage, the difference is largely binary logs, and it will come back down at the next rotation or cleanup.
**If binary logs are consistently taking up space**
Sustained binary log volume is a signal about write patterns rather than a fault. A few patterns commonly account for it:
* High-churn tables such as queues, sessions, caches, and logs kept in the same database as your application data.
* Batch jobs that rewrite large numbers of rows on a schedule.
* Bulk imports run repeatedly rather than once.
If the workload is what you want and you simply need more headroom, [automatic upsizing](#automatic-upsizing) grows the volume for you before the database runs out of space.
## Troubleshooting
### Common error messages
#### Too many connections error
```
SQLSTATE[HY000]: General error: 1040 Too many connections
```
**Solution**: Increase your database RAM, decrease the number of replicas your app has, or contact support. You may have exceeded the connection limit or have a database query that has locked the database requiring a restart.
#### Connection timeout error
```
SQLSTATE[HY000]: General error: 9001 Max connect timeout reached while reaching hostgroup...
```
**Solutions**:
* If your database [scales to zero](#scale-to-zero), a query against a sleeping database may take slightly longer while the database wakes. This is expected, adds only a few hundred milliseconds, and should not trigger this error.
* If this message appears constantly, confirm you have plenty of disk space and allow 15 minutes for the database to restart after changing disk space limits.
* Check notifications to be alerted before reaching these limits.
* If this message appears occasionally, you may need to increase your database RAM, as the database likely hit an out-of-memory error and restarted during a query or connection burst.
* Contact support if issues persist.
### Performance monitoring
Monitor your database performance in the **Metrics** section of your database cluster page. Watch for:
* **High CPU usage**: May indicate inefficient queries or insufficient compute resources
* **High memory usage**: Could lead to connection issues or query failures
* **Low disk space**: Can cause database failures and connection timeouts
Enable notifications in your organization settings to receive alerts before reaching resource limits.