Skip to main content

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​

  1. Select your project from the project switcher
  2. Click Services in the left sidebar
  3. 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
Naming

Use lowercase letters, numbers, and hyphens. The name becomes part of the internal DNS.

PostgreSQL Version​

Select your PostgreSQL version:

VersionRecommendation
17Latest features, new projects
16Stable, recommended for production
15Widely tested, safe choice
14-13Legacy compatibility

3. Compute Configuration​

Compute Class​

Select a compute class based on your workload:

ClassDescriptionBest For
EcoShared resourcesDevelopment and testing
StandardBalanced performanceGeneral production databases
ProductionDedicated resourcesCritical databases requiring guaranteed performance

Flavor​

Choose a flavor that defines CPU and memory allocation:

FlavorDescription
SmallLight workloads
MediumStandard production
LargeHigh-traffic applications
XLargeEnterprise-scale databases

The exact resource values for each flavor vary by compute class. Pricing is shown when selecting a flavor.

Choosing Resources

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

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

Learn more about HA →

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:

  1. Toggle Public Access to ON
  2. Add CIDR ranges to the allowlist, with an optional note per entry to identify its purpose
  3. Only listed IPs can connect from outside your project
Security Best Practice

Keep public access disabled unless required. Use IP allowlisting to restrict access to known addresses only.

6. Create the Database​

  1. Review your configuration
  2. Click Create
  3. Wait for provisioning (~30 seconds)

Create a MariaDB Database​

1. Navigate to Services​

  1. Select your project from the project switcher
  2. Click Services in the left sidebar
  3. 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
Naming

Use lowercase letters, numbers, and hyphens. The name becomes part of the internal DNS.

MariaDB Version​

Select your MariaDB version:

VersionRecommendation
11.4 LTSRecommended for all workloads

3. Compute Configuration​

Compute Class​

Select a compute class based on your workload:

ClassDescriptionBest For
EcoShared resourcesDevelopment and testing
StandardBalanced performanceGeneral production databases
ProductionDedicated resourcesCritical databases requiring guaranteed performance

Flavor​

Choose a flavor that defines CPU and memory allocation:

FlavorDescription
SmallLight workloads
MediumStandard production
LargeHigh-traffic applications
XLargeEnterprise-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

Storage can only be increased, not decreased. Start with what you need.

4. Galera Cluster Configuration​

Choose the cluster topology for your MariaDB instance:

TopologyNodesBest For
Standalone1Development, testing, non-critical workloads
Galera (3 nodes)3Production with high availability
Galera (5 nodes)5Mission-critical workloads requiring maximum redundancy
Galera Cluster

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:

  1. Toggle Public Access to ON
  2. Add CIDR ranges to the allowlist, with an optional note per entry to identify its purpose
  3. The system automatically provisions a gateway with TLS encryption
Security Best Practice

Keep public access disabled unless required. Use IP allowlisting to restrict access to known addresses only.

6. Create the Database​

  1. Review your configuration
  2. Click Create
  3. Wait for provisioning (~60 seconds, longer for Galera clusters)

After Creation​

View Connection Details​

  1. Go to your database
  2. Click the Overview tab
  3. 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​

  1. Navigate to your PostgreSQL instance
  2. Click the Databases & Users tab
  3. Click Create Database
  4. Enter a database name
  5. Optionally select an owner from existing roles
  6. Click Create Database

Add More Users (Roles)​

  1. Navigate to your PostgreSQL instance
  2. Click the Databases & Users tab
  3. Click Create Role
  4. Enter a role name
  5. Optionally configure database access with permissions: Superuser, Full, Write, or Read Only
  6. Click Create Role
  7. 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.

Connection-provisioned roles

Roles created by a connection cannot be edited or deleted from this tab. Manage them through the connection that provisioned them.

Password Management

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​

  1. Navigate to your MariaDB instance
  2. Click the Databases & Users tab
  3. Click Create Database
  4. Enter a database name
  5. Optionally configure the character set (default: utf8mb4) and collation (default: utf8mb4_unicode_ci)
  6. Click Create Database

Add More Users​

  1. Navigate to your MariaDB instance
  2. Click the Databases & Users tab
  3. Click Create User
  4. Enter a username
  5. Configure database access with privilege presets: Read Only (SELECT), Write (SELECT, INSERT, UPDATE, DELETE), or All Privileges
  6. Click Create User
  7. A password is auto-generated and displayed once -- copy it immediately

Troubleshooting​

Connection Refused​

  • Verify the database is in Ready state
  • 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

Next Steps​