Skip to main content
Powered by Neon

​
Introduction

Laravel Serverless Postgres provides a full-managed, autoscaling and serverless Postgres database for your application. Serverless Postgres databases autoscale their compute resources and storage to automatically accommodate the demand from your application. Laravel Serverless Postgres supports a wide range of PostgreSQL extensions, including pgvector for AI and vector similarity search capabilities. To learn more about using pgvector for storing and searching vector embeddings, see Neon’s pgvector documentation.

​
Creating Serverless Postgres databases

To create and attach a Serverless Postgres 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 Serverless Postgres” 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 Serverless Postgres 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 for information on compute and storage prices by region.
MySQL databases can only be attached to compute clusters in the same region.

​
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”. When attaching a database cluster to an environment, you will actually be selecting a particular database within the cluster that you would like to make available to the environment via the DB_DATABASE environment variable used by Laravel.

​
Editing and resizing database clusters

To edit your database clusters and adjust their compute / storage settings, navigate to “Org > Resources > Databases” and click the ”…” icon for the database cluster you would like to edit or resize. Then, click “Edit settings”.

​
Monitoring database cluster metrics

To view metrics such as CPU, write throughput, and storage for database clusters, navigate to “Org > Resources > Databases”, click the database cluster card, and click the “Metrics” option.

​
Deleting database clusters

To delete a database cluster, navigate to “Org > Resources > Databases” and click the ”…” icon for the database cluster you would like to delete. Then, click “Delete” and confirm your action.

​
Compute units

When creating a Laravel Serverless Postgres database cluster, you may configure the range of “compute units” your cluster should scale between based on demand. Compute units correspond to the following vCPU / RAM configurations:
Compute UnitsvCPUsRAM
.25.251 GB
.5.52 GB
114 GB
228 GB
3312 GB
4416 GB

​
Connection pooler

Laravel Serverless Postgres offers connection pooling via pgbouncer, enabling up to 10,000 concurrent connections to your cluster. To connect to the pgbouncer endpoint of your database cluster, append -pooler to the first segment of the cluster’s host name. For example, if your database cluster’s host name is ep-frosty-shadow-a57j6ubb.us-east-2.pg.laravel.cloud, the corresponding pgbouncer endpoint is ep-frosty-shadow-a57j6ubb-pooler.us-east-2.pg.laravel.cloud. Then, add the new host name as the DB_HOST environment variable in your environment’s General Settings: 
DB_HOST="frosty-shadow-a57j6ubb-pooler.us-east-2.pg.laravel.cloud"

​
Hibernation

Laravel Serverless Postgres databases may be configured to automatically hibernate after not receiving any incoming database queries for a given number of seconds. When a Serverless Postgres database is hibernating, you will not be billed for its compute resources. If the database receives an incoming query while it is hibernating, the database will automatically wake up within a few hundred milliseconds.

​
Autoscaling compute

Serverless compute can autoscale up and down based on your database cluster’s utilization. Set a minimum and maximum range and only pay for the compute resources you actually need.

​
Connecting to database clusters

​
From your application

When a database is attached to an environment, Laravel Cloud will automatically inject the environment variables needed by the Laravel application to connect to the database, including the DB_HOST, DB_USERNAME, DB_PASSWORD, and DB_DATABASE variables. You may view these environment 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, navigate to your organization’s “Resources” page, then to your desired database cluster, and finally click the ”…” icon next to an available database. Then, click “View credentials”.
The database credentials modal window will provide you with the credentials needed to connect to your database, in addition to a “DeepLink” which will open your database in your local machine’s default database management client if you have one installed.

​
Postgres SSL connections

Neon, which powers Laravel Serverless Postgres, uses the public ISRG Root X1 certificate issued by Let’s Encrypt. Due to this, you can create an SSL Connection with your Postgres cluster by using the appropriate CA certificate for your operating system. If you are using macOS, this certificate should already be located within your /etc/ssl/cert.pem path.

​
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 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 through the metrics dashboard available in your database cluster settings. 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.