Create a Database
Create a managed PostgreSQL or MariaDB database in minutes.
Prerequisites
- A project created in your organization
- Understanding of your application's database needs
Create a PostgreSQL Database
1. Navigate to Services
- Select your project from the project switcher
- Click Services in the left sidebar
- Click Create Service and select PostgreSQL
2. Basic Configuration
Database Name
Enter a unique name for your database:
Valid: my-db, api-database, prod-postgres
Invalid: My DB, my_database, database.prod
Use lowercase letters, numbers, and hyphens. The name becomes part of the internal DNS.
PostgreSQL Version
Select your PostgreSQL version:
| Version | Recommendation |
|---|---|
| 17 | Latest features, new projects |
| 16 | Stable, recommended for production |
| 15 | Widely tested, safe choice |
| 14-13 | Legacy compatibility |
3. Compute Configuration
Compute Class
Select a compute class based on your workload:
| Class | Description | Best For |
|---|---|---|
| Eco | Shared resources | Development and testing |
| Standard | Balanced performance | General production databases |
| Production | Dedicated resources | Critical databases requiring guaranteed performance |
Flavor
Choose a flavor that defines CPU and memory allocation:
| Flavor | Description |
|---|---|
| Small | Light workloads |
| Medium | Standard production |
| Large | High-traffic applications |
| XLarge | Enterprise-scale databases |
The exact resource values for each flavor vary by compute class. Pricing is shown when selecting a flavor.
Start with Eco / Small for development. Use Standard or Production for production workloads.
Storage Size
Choose initial storage capacity:
- Minimum: 10 GB
- Maximum: 1000 GB
- Storage can be increased later (without downtime)
Storage can only be increased, not decreased. Start with what you need.
4. High Availability (Optional)
Enable for production workloads:
- Standby replicas in different zones
- Automatic failover on primary failure
- < 30 second recovery time
5. Access & Security
Databases
Create at least one database during setup:
- Enter a database name (e.g.,
app,production) - You can add multiple databases
Users
Create at least one user during setup:
- Enter a username
- A secure password is auto-generated
- You can add multiple users with different access levels
Public Access (Optional)
Enable external access to your database:
- Toggle Public Access to ON
- Add CIDR ranges to the allowlist, with an optional note per entry to identify its purpose
- Only listed IPs can connect from outside your project
Keep public access disabled unless required. Use IP allowlisting to restrict access to known addresses only.
6. Create the Database
- Review your configuration
- Click Create
- Wait for provisioning (~30 seconds)
Create a MariaDB Database
1. Navigate to Services
- Select your project from the project switcher
- Click Services in the left sidebar
- Click Create Service and select MariaDB
2. Basic Configuration
Database Name
Enter a unique name for your database:
Valid: my-db, api-database, prod-mariadb
Invalid: My DB, my_database, database.prod
Use lowercase letters, numbers, and hyphens. The name becomes part of the internal DNS.
MariaDB Version
Select your MariaDB version:
| Version | Recommendation |
|---|---|
| 11.4 LTS | Recommended for all workloads |
3. Compute Configuration
Compute Class
Select a compute class based on your workload:
| Class | Description | Best For |
|---|---|---|
| Eco | Shared resources | Development and testing |
| Standard | Balanced performance | General production databases |
| Production | Dedicated resources | Critical databases requiring guaranteed performance |
Flavor
Choose a flavor that defines CPU and memory allocation:
| Flavor | Description |
|---|---|
| Small | Light workloads |
| Medium | Standard production |
| Large | High-traffic applications |
| XLarge | Enterprise-scale databases |
The exact resource values for each flavor vary by compute class. Pricing is shown when selecting a flavor.
Storage Size
Choose initial storage capacity:
- Minimum: 10 GB
- Maximum: 1000 GB
- Storage can be increased later (without downtime)
Storage can only be increased, not decreased. Start with what you need.
4. Galera Cluster Configuration
Choose the cluster topology for your MariaDB instance:
| Topology | Nodes | Best For |
|---|---|---|
| Standalone | 1 | Development, testing, non-critical workloads |
| Galera (3 nodes) | 3 | Production with high availability |
| Galera (5 nodes) | 5 | Mission-critical workloads requiring maximum redundancy |
Galera provides synchronous multi-primary replication. All nodes can accept reads and writes, and data is replicated across all nodes in real time.
5. Access & Security
Databases
Create at least one database during setup:
- Enter a database name (e.g.,
app,production) - Optionally configure character set (default:
utf8mb4) and collation (default:utf8mb4_unicode_ci) - You can add multiple databases
Users
Create at least one user during setup:
- Enter a username
- A secure password is auto-generated
- Configure privilege presets: Read Only, Write, or All Privileges
Public Access (Optional)
Enable external access to your database:
- Toggle Public Access to ON
- Add CIDR ranges to the allowlist, with an optional note per entry to identify its purpose
- The system automatically provisions a gateway with TLS encryption
Keep public access disabled unless required. Use IP allowlisting to restrict access to known addresses only.
6. Create the Database
- Review your configuration
- Click Create
- Wait for provisioning (~60 seconds, longer for Galera clusters)
After Creation
View Connection Details
- Go to your database
- Click the Overview tab
- View or copy:
- Host
- Port
- Username
- Password
- Connection string
Test Connection (PostgreSQL)
From a container in the same project (using internal DNS format {service-name}.{namespace}):
# Using psql
psql postgresql://postgres:[email protected]:5432/postgres
# Test query
SELECT version();
Test Connection (MariaDB)
From a container in the same project:
# Using mysql client
mysql -h my-database.my-project-abc123 -P 3306 -u root -p
# Test query
SELECT VERSION();
Configure Your Application
Set the database connection environment variable in your container:
PostgreSQL:
DATABASE_URL=postgresql://postgres:[email protected]:5432/postgres
MariaDB:
DATABASE_URL=mysql://root:[email protected]:3306/myapp
The namespace is automatically assigned to your project. You can find the full connection string in the database Overview tab under "Connection Information".
Connection Examples
PostgreSQL
Node.js (pg)
const { Pool } = require('pg');
const pool = new Pool({
connectionString: process.env.DATABASE_URL,
ssl: false // Internal connections don't need SSL
});
// Query example
const result = await pool.query('SELECT * FROM users WHERE id = $1', [userId]);
Python (psycopg2)
import psycopg2
import os
conn = psycopg2.connect(os.environ['DATABASE_URL'])
cursor = conn.cursor()
cursor.execute('SELECT * FROM users WHERE id = %s', (user_id,))
Go (pgx)
import (
"context"
"os"
"github.com/jackc/pgx/v5/pgxpool"
)
pool, err := pgxpool.New(context.Background(), os.Getenv("DATABASE_URL"))
if err != nil {
log.Fatal(err)
}
Ruby (pg)
require 'pg'
conn = PG.connect(ENV['DATABASE_URL'])
result = conn.exec('SELECT * FROM users WHERE id = $1', [user_id])
MariaDB
Node.js (mysql2)
const mysql = require('mysql2/promise');
const pool = mysql.createPool({
uri: process.env.DATABASE_URL,
});
// Query example
const [rows] = await pool.execute('SELECT * FROM users WHERE id = ?', [userId]);
Python (mysql-connector)
import mysql.connector
import os
conn = mysql.connector.connect(
host=os.environ['DB_HOST'],
port=int(os.environ.get('DB_PORT', 3306)),
user=os.environ['DB_USER'],
password=os.environ['DB_PASSWORD'],
database=os.environ['DB_NAME']
)
cursor = conn.cursor()
cursor.execute('SELECT * FROM users WHERE id = %s', (user_id,))
Go (go-sql-driver/mysql)
import (
"database/sql"
"os"
_ "github.com/go-sql-driver/mysql"
)
db, err := sql.Open("mysql", os.Getenv("DATABASE_URL"))
if err != nil {
log.Fatal(err)
}
Ruby (mysql2)
require 'mysql2'
client = Mysql2::Client.new(
host: ENV['DB_HOST'],
port: ENV.fetch('DB_PORT', 3306).to_i,
username: ENV['DB_USER'],
password: ENV['DB_PASSWORD'],
database: ENV['DB_NAME']
)
result = client.query('SELECT * FROM users WHERE id = ?', [user_id])
Managing Databases & Users
After your database instance is created, you can add more databases and users directly from the UI.
PostgreSQL
Add More Databases
- Navigate to your PostgreSQL instance
- Click the Databases & Users tab
- Click Create Database
- Enter a database name
- Optionally select an owner from existing roles
- Click Create Database
Add More Users (Roles)
- Navigate to your PostgreSQL instance
- Click the Databases & Users tab
- Click Create Role
- Enter a role name
- Optionally configure database access with permissions: Superuser, Full, Write, or Read Only
- Click Create Role
- A password is auto-generated and displayed once -- copy it immediately
To change the access level of an existing role, click the pencil icon next to the role in the Databases & Users tab.
Roles created by a connection cannot be edited or deleted from this tab. Manage them through the connection that provisioned them.
To reset a role's password later, click the key icon next to the role in the Databases & Users tab.
Extensions
See PostgreSQL Extensions for available extensions and how to enable them.
MariaDB
Add More Databases
- Navigate to your MariaDB instance
- Click the Databases & Users tab
- Click Create Database
- Enter a database name
- Optionally configure the character set (default:
utf8mb4) and collation (default:utf8mb4_unicode_ci) - Click Create Database
Add More Users
- Navigate to your MariaDB instance
- Click the Databases & Users tab
- Click Create User
- Enter a username
- Configure database access with privilege presets: Read Only (SELECT), Write (SELECT, INSERT, UPDATE, DELETE), or All Privileges
- Click Create User
- A password is auto-generated and displayed once -- copy it immediately
Troubleshooting
Connection Refused
- Verify the database is in
Readystate - Check you're connecting from within the same project
- Verify the hostname and port
Authentication Failed
- Double-check the password (copy from Connection tab)
- Verify the username is correct
- Check for special characters in password
Connection Timeout
- Ensure your container is in the same project
- Check for network issues
- Verify the database is not overloaded
Too Many Connections
- Check your application's connection pooling
- Upgrade to a larger compute class
- Review and close idle connections
Best Practices
Use Connection Pooling
For production applications:
- Use a connection pool (PgBouncer, built into many drivers)
- Set appropriate pool sizes
- Close connections when done
Secure Your Database
- Use specific users for different apps
- Grant minimal permissions
- Rotate passwords regularly
Plan for Growth
- Monitor storage usage
- Set up alerts for high usage
- Plan compute upgrades ahead of time