Skip to main content

Deploy a Database

Now that you have a web application running, it's time to add data persistence with a managed database using Viduli's Orbit Database Service. Orbit provides production-ready PostgreSQL databases with automated backups, high availability, and seamless scaling - all without the complexity of managing database infrastructure yourself.

In this tutorial, you'll deploy a PostgreSQL database and connect it to your FastAPI application from the previous tutorial. You'll see how Viduli automatically handles database configuration and makes connection details available to your applications. For comprehensive information about Orbit's capabilities, see the complete Orbit documentation.

Prerequisites​

Before deploying your database, ensure you have:

  • A Viduli project with a web application: Complete the Deploy a Web App tutorial first
  • Basic understanding of databases: Helpful for understanding configuration options
  • Familiarity with PostgreSQL: Not required, but useful for advanced configurations

Database Overview​

For this tutorial, we'll deploy a PostgreSQL database that will store articles for your FastAPI application. PostgreSQL is an excellent choice for web applications because it provides:

  • ACID compliance: Ensures data integrity and consistency
  • JSON support: Perfect for modern web applications
  • Powerful querying: Advanced SQL capabilities and indexing
  • Reliability: Battle-tested in production environments worldwide

Your database will be automatically configured with secure connections, regular backups, and monitoring - everything you need for a production-ready data store.

Step-by-Step Instructions​

1. Access Your Project​

Navigate to your project by clicking on the project name in the sidebar. You should see your FastAPI application from the previous tutorial already deployed on the canvas.

2. Start Database Creation​

In the project overview, click the New Resource button in the sidebar. This opens the resource creation dialog where you can choose from different types of resources.

3. Select Orbit Database Service​

From the resource type options, select Orbit to create a new managed database. This will open the Orbit database configuration form.

4. Choose PostgreSQL Engine​

Since we're building a web application that will store articles, select PostgreSQL as your database engine. PostgreSQL is ideal for web applications due to its reliability, feature set, and excellent performance characteristics.

5. Configure Database Version​

In the Database Configuration section, select your PostgreSQL version:

  • Version: Select 17 (latest) from the version dropdown

PostgreSQL 17 is the most recent version and includes the latest performance improvements, security enhancements, and features. Using the latest version ensures you have access to the most current capabilities and security patches.

6. Configure Compute Resources​

In the Compute section, set appropriate resources for your database:

  • CPU: Select 250m (250 millicpu = 25% of a CPU core)
  • Memory: Select 512mb RAM
  • Disk: Select 20GB storage

These resources provide sufficient capacity for a test database and small production workloads, with room to scale as your application grows.

7. Configure Scaling​

In the Scaling section, configure your database deployment:

  • Region: Choose US East (or match the region of your web application)
  • Replication: Set to Active-Passive for high availability with automatic failover
  • Replicas: Set to 1 (primary only, no read replicas for this tutorial).

Keeping your database and application in the same region minimizes latency and improves performance. Active-Passive replication ensures your database remains available even if the primary instance fails.

tip

Set replicas 2 or more for high availability (HA) and read scaling.

8. Configure Database Identity​

In the General section, set up your database identity:

  • Label: Enter Articles DB (this is the display name)
  • Name: This will automatically populate as articles-db based on the label

Choose a descriptive name that makes it easy to identify this database's purpose within your project.

9. Review Cost Estimates​

Before creating your database, review the total estimated cost displayed in the interface. Viduli shows a single combined monthly price that includes the base instance, storage, and backup costs.

10. Deploy Your Database​

Click the Create button to deploy your database. Viduli will now:

  • Provision PostgreSQL infrastructure
  • Configure networking and security
  • Set up automated backups
  • Initialize the database with your specified settings
  • Generate connection credentials

Monitor Database Deployment​

After clicking Create, your database will appear on the project canvas:

  1. Select the database if it's not already selected
  2. Check the status in the right sidebar - it should show Launching
  3. Wait for completion - database deployment typically takes under a minute
  4. Verify success - the status will change to Healthy when ready

Database provisioning takes longer than applications because it involves setting up persistent storage, configuring replication, and initializing the database system.

Automatic Environment Variable Export​

Once your database is running, Viduli automatically exports connection details as environment variables to your project. These variables become available to all resources in the same project:

  • ARTICLES_DB_HOST: Database server hostname
  • ARTICLES_DB_PORT: Database port (typically 5432)
  • ARTICLES_DB_NAME: Database name
  • ARTICLES_DB_USER: Database username
  • ARTICLES_DB_PASSWORD: Database password
  • ARTICLES_DB_URL: Complete connection string

Update Your Web Application​

To make your FastAPI application use the new database:

1. Redeploy Your Application​

Since environment variables are only updated when resources are deployed:

  1. Select your FastAPI application on the canvas
  2. Click the deploy button in the application controls
  3. Wait for redeployment to complete

This ensures your application receives the new database environment variables.

2. Verify Database Connection​

Your application can now access the database using the automatically provided environment variables. In your FastAPI code, you would typically use:

import os
database_url = os.getenv('ARTICLES_DB_URL')

Test Database Connectivity​

Once both your application and database are running, you can verify the connection:

1. Check Application Logs​

  1. Select your FastAPI application on the canvas
  2. Open the resource details by double-clicking or using the sidebar
  3. Navigate to the Logs tab to see connection status
  4. Look for database connection messages in the application startup logs

2. Test Database Operations​

If your FastAPI application includes database operations, test them:

# Create an article (if your API supports it)
curl -X POST https://organization-team-project.viduli.app/api/articles \
  -H "Content-Type: application/json" \
  -d '{"title": "My First Article", "content": "Hello from the database!"}'

# Retrieve articles
curl https://organization-team-project.viduli.app/api/articles

Database Management​

Access Database Shell​

You can connect directly to your database for administration:

  1. Select your database on the canvas
  2. Open the resource details view
  3. Navigate to the Shell tab
  4. Use the psql interface for direct database access

Monitor Database Performance​

Track your database performance through the monitoring interface:

  1. Open the database details view
  2. Navigate to the Monitoring tab
  3. Review metrics like CPU usage, memory consumption, and query performance

What You've Accomplished​

Congratulations! You've successfully deployed a production-ready PostgreSQL database. Your database now provides:

  • Managed Infrastructure: No server maintenance or patching required
  • Automated Backups: Daily backups with point-in-time recovery
  • High Availability: Built-in redundancy and failover capabilities (if you allocated more than one replica)
  • Security: Encrypted connections and isolated networking
  • Monitoring: Real-time performance metrics and alerting
  • Seamless Integration: Automatic environment variable provisioning

Next Steps​

Now that you have both an application and database running, you can:

Your full-stack application is now ready for development and can handle real user data with confidence!