Working with Projects

Projects are the top-level containers in OstrichDB that organize your databases and provide user isolation. This guide covers everything you need to know about managing projects.

Understanding Projects

What is a Project?

A project in OstrichDB is:

Top-level container: The highest level in the data hierarchy
Isolation boundary: Each project is completely separate from others
Access control unit: Projects define security and access permissions
Organization tool: Logical grouping for related databases and applications

Project Hierarchy

Project (Your Application)
├── Collection (Database/Table equivalent)
    ├── Cluster (Data Group/Category)
        ├── Record (Individual Data Entry)
            ├── Name: unique identifier
            ├── Type: explicit data type
            └── Value: the actual data

Creating Projects

Step-by-Step Project Creation

From the dashboard, click “Create New Project”
Enter a project name following the naming rules
Set a password (optional but recommended for security)
Click “Create Project” to finalize creation

Project Naming Rules

Projects must follow strict naming conventions:

Maximum length: 32 characters
Allowed characters: Letters (a-z, A-Z), numbers (0-9), underscores (_), hyphens (-)
No spaces: Use underscores or hyphens instead
Unique names: Must be unique within your account
Case sensitive: “MyProject” and “myproject” are different

Valid Examples:

ecommerce-app
user_management_system
blog_v2
inventory2024

Invalid Examples:

my project (contains space)
app@work (contains special character @)
super-long-project-name-that-exceeds-limits (too long)

Project Security

Project Passwords:

Optional but recommended: Adds an extra layer of security
Encryption key: Used for collection-level encryption
Recovery: Cannot be recovered if lost - store safely
Best practices: Use strong, unique passwords

Managing Projects

Project Operations

Each project card displays an actions menu (three dots ⋮) with these options:

Rename a Project

Click the three-dot menu (⋮) on the project card
Select “Rename Project”
Enter the new name (following naming rules)
Click “Rename Project” to confirm

Important Notes:

Renaming affects all API endpoints and references
Collections and clusters remain unchanged
Update any external integrations after renaming

Delete a Project

Click the three-dot menu (⋮) on the project card
Select “Delete Project”
Type the exact project name to confirm deletion
Click “Delete Project” to permanently remove

⚠️ Critical Warning:

Deletion is permanent and irreversible
Removes all collections, clusters, and records
Cannot be undone - ensure you have backups
Consider exporting important data first

Project Information

Each project card displays:

Basic Information:

Project Name: Unique identifier
Creation Date: When the project was created
Last Modified: Most recent update timestamp
Collection Count: Number of collections in the project

Storage Information:

Project Size: Total storage used
Record Count: Total number of individual records
Cluster Count: Total number of data clusters

Status Indicators:

Encryption Status: Whether collections use encryption
Backup Status: Last backup timestamp
Connection Status: Current database connection state

Project Organization

Sorting and Filtering

Sort Options:

Alphabetical (A-Z): Default sorting by name
Number of Collections: Projects with most collections first
Project Size: Largest projects first
Last Modified: Most recently updated first

Quick Filters:

Recently Modified: Projects updated in last 7 days
Large Projects: Projects over certain size threshold
Encrypted Projects: Projects with encrypted collections
Empty Projects: Projects with no collections

Best Practices for Project Organization

Naming Conventions:

Use descriptive names that indicate purpose
Include version numbers for iterations (app_v2, blog_v3)
Use environment prefixes (dev_, staging_, prod_)
Be consistent across your organization

Project Structure:

Separate environments: Different projects for development, staging, production
Group by application: One project per major application or service
Consider team access: Structure based on who needs access
Plan for growth: Start with clear organization from the beginning

Examples of Good Organization:

ecommerce_dev
ecommerce_staging
ecommerce_prod
blog_v2
user_auth_service
analytics_dashboard
mobile_app_backend

Project Limits by Plan

Free Tier

Maximum Projects: 1 project
Collections per Project: 1 collection maximum
Storage per Project: 500MB total
Backup Frequency: 1 backup per day

Pro Tier ($25/month)

Maximum Projects: 3 projects
Collections per Project: 3 collections maximum
Storage per Project: 3GB total
Backup Frequency: 5 backups per day
Collaboration: 3 users per project

Enterprise Tier (Custom)

Maximum Projects: 30 projects
Collections per Project: 100 collections maximum
Storage per Project: 64TB total
Backup Frequency: 10 backups per day
Collaboration: 50 users per project

Project Security

Access Control

User Isolation:

Each user has complete isolation from other users
Projects are private by default
No cross-user access without explicit sharing

Authentication:

JWT-based authentication for API access
Session management for web interface
Two-factor authentication available for enhanced security

Encryption Options

Collection-Level Encryption:

Each collection can be independently encrypted
Uses AES-256 encryption standard
User-specific master keys derived from project passwords
Automatic encrypt/decrypt during operations

Best Security Practices:

Use strong project passwords when encryption is enabled
Enable two-factor authentication on your account
Regularly rotate passwords for sensitive projects
Monitor access logs for unusual activity

Working with Project Data

Navigating Project Contents

From a project view, you can:

View all collections in the project
Create new collections directly
Access collection statistics and metadata
Navigate to cluster editor for specific collections
Run queries across project data

Project-Level Operations

Bulk Operations:

Export entire project data
Import data into project
Backup project manually
Clone project structure (Enterprise)

Monitoring:

Track storage usage and growth
Monitor query performance
Review access logs and activity
Set up alerts for thresholds

Troubleshooting Projects

Common Issues

“Project name already exists”

Solution: Choose a unique name within your account
Check: Verify you haven’t used this name before
Alternative: Add version numbers or dates to differentiate

“Project creation failed”

Solution: Check your plan limits - you may have reached maximum projects
Upgrade: Consider upgrading to Pro or Enterprise for more projects
Clean up: Delete unused projects to free up slots

“Cannot access project”

Solution: Verify you’re logged into the correct account
Password: Check if project requires a password you’ve forgotten
Support: Contact support if you believe this is an error

Project Recovery

Accidental Deletion:

No recovery possible: Deletion is permanent
Prevention: Always type the exact name to confirm
Backups: Restore from automatic backups if available
Support: Contact support immediately, though recovery is unlikely

Data Corruption:

Automatic backups: Restore from most recent backup
Export/Import: Use data export if corruption is partial
Support: Contact support for assistance with recovery

Next Steps

Once you understand projects:

Learn about Collections - Organize data within projects
Explore the Cluster Editor - Visual data management
Set up API Access - Programmatic project interaction
Configure Security - Secure your projects