Introduction
Vapor allows you to easily create and manage RDS and Aurora Serverless databases directly from the Vapor UI or using the Vapor CLI. Database backups are automatically performed and you may restore a database to any point in time (down to the second) within the backup retention window.Creating Databases
You may create databases using the Vapor UI or using thedatabase
CLI command. When using the CLI command, the command will prompt you for more details about the database such as its desired performance class and maximum storage space.
The Default Database
Vapor will automatically create a “vapor” database within each database instance that you create. You are free to create additional databases using the database management tool of your choice.Database Types
When creating Vapor databases, you may choose from two different types of databases: fixed size and auto-scaling serverless databases.Fixed Size Databases
Fixed sized databases are RDS MySQL 5.7 / RDS MySQL 8 / Postgres 17 databases that have a fixed amount of RAM and disk space. These databases may be scaled up or down after creation, but not without incurring downtime. In addition, these databases may be publicly accessible (with a long, random password automatically assigned by Vapor) or private. Private databases may not typically be accessed from the public Internet. To access them from your local machine, you will need to create a Vapor jumpbox.Vapor will place any application that uses a private database in a network with a NAT Gateway. Later, if you no longer plan to use the database and are using no other private resources from your application, you may remove the NAT Gateway from your network via the network’s management screen.
Serverless Databases
Serverless databases are auto-scaling Aurora MySQL 5.7 / MySQL 8.0 / Postgres 11 / Postgres 16 databases which do not have a fixed amount of RAM or disk space. Instead, these databases automatically scale based on the needs of your application. At their smallest scale, they are allocated 1GB of RAM.AWS requires all serverless databases to be private, meaning Vapor will place any application that uses them in a network with a NAT Gateway. If you no longer plan to use a serverless database and are using no other private resources from your application, you may remove the NAT Gateway from your network via the network’s management screen.
Quick Development Databases
To quickly create a publicly accessible database of the smallest performance class, you may use the--dev
flag when creating your database. These small, affordable databases are perfect for testing or staging environments:
Using Databases
To attach a database to an environment, add adatabase
key to the environment’s configuration in your vapor.yml
file and deploy your application. The value of this key should be the name of the database. When the environment is deployed, Vapor will automatically inject the necessary Laravel environment variables for connecting to the database, allowing your application to start using it immediately:
vapor.yml
Connecting To Private Databases Locally
If you would like to connect to your private database from your local machine, you can either use a Vapor jumpbox in combination with a GUI database management tool or thedatabase:shell
CLI command. Jumpboxes are very small, SSH accessible servers that are placed within your private network.
Jumpboxes + GUI Tool
Once a jumpbox has been created, you may configure your database management tool to connect to your database through the jumpbox SSH connection:
Shell Command
After provisioning a jumpbox, you may use thedatabase:shell
command to quickly access a command line database shell that lets you interact with your database:
Existing Databases
If you wish to use an RDS database that was not created by Vapor, you have two options:- Exporting and importing the contents of your existing database into a new database created by Vapor. We recommend this approach as it allows you to use your existing data within a database and network managed by Vapor.
- Connecting your existing database to a Vapor environment.
Database Proxies
Even though your serverless Laravel applications running on Vapor can handle extreme amounts of web traffic, traditional relational databases such as MySQL can become overwhelmed and crash due to connection limit restrictions. To solve this, you may use an RDS proxy to efficiently manage your database connections and allow many more connections than would typically be possible. The database proxy can be added via the Vapor UI or thedatabase:proxy
CLI command:
database-proxy
configuration option within your vapor.yml
file:
vapor.yml
database:delete-proxy
CLI command. Before deleting a proxy, make sure none of your applications are using the associated proxy:
Before considering the usage of database proxies in Vapor, please consult Amazon’s list of limitations.
Database Users
When a database is created, Vapor creates a “vapor” master user. You may create additional database users, which will automatically be assigned a secure, random password, using the Vapor UI or thedatabase:user
CLI command:
database-user
configuration option within your vapor.yml
file:
vapor.yml
You may use the
database:password
CLI command to rotate the password of a database. Alternatively, you may leverage users to “rotate” the password of a database without downtime by creating a new user, updating the environment to use that user, deploying the environment, and then deleting the old database user.Scaling Databases
You may scale fixed size databases via the Vapor UI’s database detail screen or thedatabase:scale
CLI command. When scaling a fixed size database, the database will be unavailable, and the amount of time it takes to scale the database could vary based on the size of the database. Therefore, you should place your application in maintenance mode before beginning the scaling operation:
Restoring Databases
Vapor database backups are performed automatically and you may restore databases to any point in time within the database backup retention period, which is three days by default. You can change the database backup retention period at any time via the Vapor UI’s database details screen. Database restoration may be initiated via the Vapor UI or thedatabase:restore
CLI command:
database
key in your vapor.yml
file and deploy the environment.
Once you are satisfied with the database restoration, you may delete the old database.
Upgrading Databases
You may upgrade a Vapor managed MySQL database via the Vapor UI or thedatabase:upgrade
CLI command. When upgrading a database, a new database is created with the same configuration and credentials as the original database:
Metrics
A variety of database performance metrics are available via the Vapor UI’s database detail screen or using thedatabase:metrics
CLI command:
Alarms
You may configure alarms for all database metrics using the Vapor UI. These alarms will notify you via the notification method of your choice when an alarm’s configured threshold is broken and when an alarm recovers.Deleting Databases
Databases may be deleted via the Vapor UI or using thedatabase:delete
CLI command. Once a database has been deleted, it can not be recovered, so take extra caution before deleting a database:
When deleting a database via the UI, you can choose to preserve the resource on AWS. Enabling this option only removes the database record in Laravel Vapor; the AWS resource remains intact.