Object Model Overview

The user-facing SPG99 object model is fairly compact. It is important to understand several levels.

Account
  ├─ API keys
  └─ Tenants
       ├─ pg_user / pg_password / dsn_template
       └─ Databases
            ├─ state / status
            ├─ size
            ├─ timeline
            ├─ current_scale / target_scale
            ├─ current_profile / target_profile / scale_state
            ├─ worker_id / backend_addr / active_connections
            └─ timestamps / usage

Account

The top-level customer entity. It groups contact data, API keys, tenants, and part of usage.

API key

A Bearer token for access to the Control Plane. A key has a scope (global, account, tenant) and permissions (can_create_tenant, can_create_db, can_scale, can_delete, and so on).

Tenant

The main user isolation unit. A tenant has:

• a name;
• its own PostgreSQL credentials;
• a DSN template;
• a set of databases inside it.

Database

A specific PostgreSQL database inside a tenant. The important fields are:

• name;
• size;
• state;
• timeline;
• runtime fields such as worker_id, active_connections, current_scale, and target_scale.

What is new in the database runtime model

A database now also has new profile/autoscaler fields:

• current_profile
• target_profile
• candidate_profile
• scale_state
• freeze_new_checkouts

This makes it possible to see not only whether the database is running, but also whether a controlled handoff between writer generations is in progress.

Timeline

A timeline is the durable history of the database state on the storage side. For the user, one thing matters most: a new compute always starts for a specific timeline, not “from scratch with no memory.”

Worker and runtime fields

When a database is active, the user may also see:

• worker_id;
• backend_addr;
• backend_port;
• active_connections;
• last_used_at.

These fields are useful for diagnostics, but they should not be treated as a stable business contract.

Practical conclusion

The whole SPG99 model still reduces to a very clear chain:

account -> tenant -> database -> connect through gateway

But for production observability it is now especially useful to remember one more link:

database -> current_profile / target_profile / scale_state

That is exactly what shows that the writer now lives not only in a lifecycle model, but also in a profile handoff model.