Skip to main content

Quick Start

Create a PostgreSQL service and connect to it in under 5 minutes.

What happens when you create a service​

When you submit a create request, the controller runs your service through a state machine. It walks left to right through each state below, and the whole sequence completes in a few minutes. You do not drive any of these steps yourself: the controller orchestrates them and the service reports running when it is ready to accept connections.

From create to Running in minutes
READY Service provisioned · Running
Pendingrequest queued→Configure nodeinstall database→Provision computecreate instance→Private networkattach network→TLS + endpointserving address→Health gatereadiness check→DNS recordpublish hostname→Runningready to connect
Provisioning stepRunning (ready)Periodic health checkhealth-check loop (dashed)

Each step does real work:

  • Pending: the request is validated and queued. Takes seconds.
  • SetupAgent: the on-VM agent starts and brings up the database engine (PostgreSQL, MySQL, MongoDB, Valkey, or Kafka), including any requested extensions (such as pgvector) and addons (such as pgbouncer). Under a minute.
  • SetupServer: the VM is provisioned from a pre-built database image, with its three disks (OS, data, backup). This is the longest step, on the order of a couple of minutes.
  • SetupNetwork: a private SDN network is allocated for the service so its internal traffic never crosses the public Internet. Takes seconds.
  • SetupLB: the public endpoint and TLS certificate are configured so client connections are encrypted end to end. Under a minute.
  • Checkup: an intermediate health gate validates the service before it is published. Takes seconds.
  • SetupDns: a stable DNS record (for example my-first-db.db.foundrydb.com) is created so you connect by name rather than by raw IP. Seconds.
  • Running: the service is live and ready to connect. From here it enters a separate periodic health Checkup loop that keeps watching the cluster.

Total time from create to running is typically a few minutes.

1. Create a service​

curl -u admin:password -X POST https://api.foundrydb.com/managed-services \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-first-db",
    "database_type": "postgresql",
    "version": "17",
    "plan_name": "tier-2",
    "zone": "se-sto1",
    "storage_size_gb": 50,
    "storage_tier": "maxiops"
  }'

The response includes the service id. Provisioning takes typically a few minutes.

2. Check status​

curl -u admin:password https://api.foundrydb.com/managed-services/{id}

Wait until status is running. Until then the response reflects the current provisioning state shown in the timeline above. Polling every few seconds is enough; there is nothing to do but wait for the controller to finish.

Once the service is running, the next three steps get you connected: open your network access, fetch credentials, and connect over TLS.

3. Allow your IP​

A new service accepts no inbound connections by default. Add your public IP to allowed_cidrs so the service firewall lets you in. Find your IP with curl -s ifconfig.me, then:

curl -u admin:password -X PATCH https://api.foundrydb.com/managed-services/{id} \
  -H "Content-Type: application/json" \
  -d '{"allowed_cidrs": ["YOUR_IP/32"]}'

4. Get credentials​

Each service is created with a database user. List the users, then reveal the password for the one you want to connect as. Passwords are stored encrypted and only returned through the explicit reveal endpoint.

# List users
curl -u admin:password https://api.foundrydb.com/managed-services/{id}/database-users

# Reveal password
curl -u admin:password -X POST \
  https://api.foundrydb.com/managed-services/{id}/database-users/{username}/reveal-password

5. Connect​

Connect using the DNS name created during SetupDns and the credentials from the previous step. TLS is configured during SetupLB, so use sslmode=verify-full for a fully verified, encrypted connection.

PGPASSWORD=your_password psql \
  "host=my-first-db.db.foundrydb.com \
   user=app_user \
   dbname=defaultdb \
   sslmode=verify-full"

That is the full path: create, wait for running, allow your IP, get credentials, and connect.

Next steps​