Database Management

Serverpod Cloud provides fully managed PostgreSQL databases for your applications, handling connection configuration and automatic migrations while giving you control when needed.

Serverpod Cloud automatically configures your application to connect to the database:

1. Database connection parameters are automatically injected as environment variables
2. Your Serverpod application uses these variables to establish a connection
3. No manual configuration is required in your code

Enabling a Database

When you create a new project in Serverpod Cloud, you can choose whether to include a database.

You can control database creation in two ways:

• Using the interactive launch command which will prompt you about database creation

• Using the --enable-db or --no-enable-db flag with the project create command:

  # Create a project with a database
  scloud project create my-project-id --enable-db
  
  # Create a project without a database
  scloud project create my-project-id --no-enable-db

Database Migrations

Database migrations in your Serverpod project are applied automatically on deployment:

1. Create your migrations in the standard Serverpod way (serverpod create-migration)
2. When you deploy your application using scloud deploy, migrations are automatically applied

Accessing Your Database

You may want to access your database directly for several reasons:

• Data Inspection: View and query your tables directly to verify data integrity
• Manual Operations: Perform operations not easily done through your application
• Debugging: Troubleshoot database-related issues by examining the actual data
• Performance Analysis: Run EXPLAIN queries to analyze query performance

Popular PostgreSQL clients you can use include:

• Postico: A modern PostgreSQL client for macOS with an intuitive interface
• pgAdmin: A feature-rich open-source administration and management tool
• DBeaver: A universal database tool supporting multiple database types
• DataGrip: JetBrains' database IDE with advanced features

To connect to your database using these tools, you'll need the connection details and credentials described below.

Connection Details

You can connect to your database using any PostgreSQL client. You can retrieve your database connection details using the scloud db connection command. In addition to the host name and port you need to setup admin credentials.

Creating Admin Credentials

To connect directly to your database (for debugging or manual operations), create superuser credentials:

1. Create a database superuser:

   scloud db create-superuser

2. The command will output a password that you should save securely:

   DB superuser created. The password is only shown this once:
   mySuperSecurePassword123

Resetting Database Password

If you need to reset your database password:

scloud db reset-password --username johndoe

The new password will be displayed once and should be saved immediately:

DB password is reset. The new password is only shown this once:
newSuperSecurePassword456

🧪 Example Code

A typical database query using Serverpod would look like:

Future<List<Customer>> getCustomers(Session session) async {
  return await Customer.find(
    session,
    where: (c) => c.active.equals(true),
    orderBy: (c) => c.name,
  );
}