Chapter 3 · about 3 to 5 minutes
Connect your database
This is the chapter everything else hangs on, and it is shorter than chapter 1. There is one real decision in it, on this page, and the guide will not let you make it blind.
What a database even is
A database is the filing cabinet your words and settings live in. The website is the shop window; the database is the stockroom behind it.
When you write a page in Comet, the words go into the database. When a visitor opens your site, Comet fetches the words back out. Without one, Comet is a shop window with nothing in it.
You are not installing anything
The database does not live on your web host and does not need MySQL, phpMyAdmin, or any of the things a hosting tutorial would ask you to set up. It is created for you, free, on a service called SpacetimeDB, and Comet does all the talking. You will not type a command at any point.
What happens in this chapter
- You name it. A short name, all lower case. Thirty seconds.
- You pick one of two doors. The only real decision. The whole next section is about it.
- Comet publishes. It sends a small program to SpacetimeDB, which creates the database and starts it. A few seconds.
- You take ownership and save your recovery code. The code chapter 2 told you to make room for.
Naming it
Every Comet database's name starts with comet-. Comet adds that part for
you; you only choose what comes after. Use your business or site name.
Good: comet-acme-arts, comet-riverside-yoga,
comet-jd-photo.
The rules, in plain words:
- Lower-case letters and numbers only. No capitals.
- Hyphens between words. No underscores, no spaces, no accents.
- No hyphen at the start or the end, and never two hyphens in a row.
Names are worldwide, not yours alone
Every SpacetimeDB database in the world shares one list of names, so
comet-photos may well be taken by a stranger. Comet checks as you type and
tells you before you commit. If the name you want is gone, add a word:
comet-photos-newcastle.
The decision: two doors
Both doors end with a working website. They differ in one thing only: who owns the database afterwards. Read both cards before choosing. There is no way to change your mind afterwards without starting the database again from scratch.
Door A — sign in with a free account
Comet opens spacetimedb.com in a new tab. You sign in there — GitHub or Google, no card, no forms — and press Approve. You come back to the Comet tab and it has already finished. Nothing to copy, nothing to paste.
What you get
- The database is yours, listed on your own SpacetimeDB dashboard, where you can see it, back it up, and delete it.
- If your web host disappears tomorrow, you still own the database and can point a fresh Comet install at it.
- The easier of the two ways back in if you lose your recovery code (chapter 2, tier 2).
What it costs
Three minutes and one free account. That is the entire price.
Door B — no signup at all
Comet asks SpacetimeDB for an anonymous key and uses it immediately. You are not asked for an email address or anything else. It is the fastest possible route and it genuinely works.
What you get
- A working site in about thirty seconds with no account anywhere.
What it costs — read every line
- The database will not appear on any dashboard. Not yours — you do not have one — and not anybody's. There is no screen anywhere on the internet that lists it.
- The only key that can ever change or delete it lives inside this one install, in a file on your web host.
- If you lose the install, the database is gone permanently. A wiped host, a deleted folder, a cancelled hosting account, a “let's start fresh” — any of those and there is no recovery. There is no support desk that can help, because nobody can prove it was yours.
- You cannot upgrade it later. Signing in with an account afterwards throws the anonymous key away and strands the database for good. Comet blocks that on purpose and says so.
If you take Door B, do this one thing
Press the Download my database key button Comet shows you. It saves a small text
file named after your database — comet-database-key-comet-acme-arts.txt —
holding one long line of characters.
That line is the only credential in existence that can update or delete your database. It is not a password you will sign in with; Comet never asks you for it again in normal use. And it cannot be reissued, because there is no account for SpacetimeDB to reissue it to. Put the file with your important documents, alongside your setup key from chapter 2 — the step-by-step below says exactly where. Comet asks you to tick a box confirming you saved it, and the box is not a formality.
The plain recommendation: take Door A. Door B exists for the person who wants a site online in the next five minutes and will accept the risk knowingly. It is not the “simple” option; it is the option with a bill attached that arrives much later.
Door A, step by step
Type your database name and press Continue
Comet checks the name against SpacetimeDB while you type. A green tick means it is free. If it comes back taken, add a word and try again — see Naming it.
Choose “Sign in with a free account”
Comet opens a new browser tab at spacetimedb.com. Do not close the Comet tab — it is waiting for you and will notice the moment you approve.
Sign in and press Approve
Sign in with GitHub or Google, whichever you already have. Then press Approve. That is the whole account setup.
Switch back to the Comet tab. It shows “waiting for approval” until you approve, then moves on by itself within a couple of seconds. If it is still waiting after half a minute, press its retry button — Comet says Not approved yet. Approve the login in the tab that opened, then poll again. when the approval has not landed.
Where your key is kept
The key that comes back is written to a file on your own web host that only your hosting account can read, and is never handed to the browser. If someone else uses your computer, there is nothing in the browser for them to steal.
Door B, step by step
Type your database name and press Continue
Same as Door A: same rules, same live check.
Choose “Just get me running” and read the warning
Comet shows the price again at this exact moment, in these words:
This database will belong to an anonymous SpacetimeDB identity with no account behind it. It will not appear on any dashboard, and if this install is lost there is no way to recover or delete it. Door A (sign in) is the recoverable choice.
Download your database key, and put it somewhere permanent
Press Download my database key. A small text file lands in your Downloads folder,
named after the database you just chose — for example
comet-database-key-comet-acme-arts.txt. Move it out of Downloads before you
carry on. Downloads is the folder people empty.
What it actually is
One long line of characters, and the only thing anywhere that can update or delete
comet-acme-arts. Comet keeps its own copy on your web host — that copy is what
your site runs on — so the file you just downloaded is the second copy, held
somewhere the host cannot take down with it. That is its entire job.
It is not the recovery code, and not the setup key from chapter 2. Those two get you back into the site. This one is the deed to the database underneath it.
Where to keep it
- A password manager. Attach the file, or paste the line into a secure note, filed under your site's web address. Best place: it is encrypted, and it is backed up.
- With your documents backup — wherever your real paperwork lives and actually
gets backed up. Not the desktop, not a folder called
stuff. - Printed, as a second copy. It runs to several hundred characters, so retyping it would be miserable, but a printout survives things a hard disk does not.
Not these: your Downloads folder; an email to yourself; a shared team drive or a chat message; and above all not only on the same web host as the install — if that host goes, both copies go with it, which is the exact disaster the download exists to prevent.
Treat it like a house key
Anyone holding that file can change or delete your database. Do not email it to yourself, do not put it in a shared team folder, do not paste it into a chat.
You can fetch another copy later
This is not a one-shot screen. As long as the install is still working, Comet will hand you the same file again from the admin settings, under Settings → Database → Download my database key. It gives you the same key, not a new one — the key never changes and cannot be replaced.
Which is also the catch: that button lives inside the install. If the install is gone, so is the button, and so is the last way to reach the database. Save the file now, while there is nothing to worry about.
Door A users have the same button and the same file. It matters far less for them: the database is listed on their SpacetimeDB dashboard, so a lost copy is an inconvenience rather than the end of the database.
Then tick the box that says you have saved it.
Publishing — what the last button does
When you press the final button, Comet sends a small program — the file
package/module/comet.wasm that came in your download — to SpacetimeDB. That
program is your database: it defines the drawers in the filing cabinet, and
SpacetimeDB runs it for you. It takes a few seconds.
comet-acme-artsCOMET-4K7QM-9XB2R-TF08D-WZ3HNTake ownership immediately, and save the code
The moment the database exists, the site can be claimed by whoever claims it first. Comet puts the ownership step directly after publishing for that reason. Do it now, in this sitting, before you go and make a cup of tea.
The recovery code appears once. Write it down or print it before you press Continue — chapter 2 explains what it is for and why nobody can email you a new one.
Check before you move on
Comet is showing a green Connected badge with your database
name — the one starting comet- — beside it, the red “not claimed”
banner is gone, and your recovery code is written down somewhere outside this browser.
If the badge is red, or publishing stopped with a message, find that exact message in Something went wrong → chapter 3. Every failure in this chapter has a named entry there.
Two normal things that look like faults
A slow first load after a quiet week
Free databases go to sleep after about a week with no visitors. The next visit wakes it up, which takes a few seconds — so the first page load after a quiet spell can feel slow, and every load after it is normal again.
This is not broken. Nothing is lost while it sleeps, you are not being charged, and there is nothing to switch back on. Reload once and carry on.
Your database is not on your host
If you go looking in cPanel for a database called comet-something, you
will not find one, and phpMyAdmin will not know about it either. That is expected: your
database lives on SpacetimeDB, not on your web host.
With Door A you can see it on your spacetimedb.com dashboard. With Door B there is nowhere to see it, which is the price you accepted.
Free-tier limits, briefly
The free tier is generous for a normal small site: it comfortably carries a text-based
site with hundreds of thousands of page views a month. The one thing that eats it is
pictures — so Comet never puts your images in the database. Uploads go into the
media folder on your own web host, where they cost you nothing extra. You do
not have to manage this; it is just how Comet is built.