doxa-life/doxa-maps
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

The joining page's database section, now that the team default is the shared one

Browse source 
repo END-REPO-PBDOC: the Driver's decision went live and REVERSED their earlier instruction to me. When I
first wrote this section repo said to leave DX_PB_URL out entirely, because it sat behind the team sign-in
and failed from a laptop. It is now the TEAM DEFAULT, and the local database is the fallback.

So the section is rewritten rather than appended to: a joiner is now told to set
DX_PB_URL=https://<your team's dev server>/pb, that they sign in with the same team account and there is no
separate password, and that leaving it unset still gives them a private local one — which is a fine way to
start. Placeholder host in the public text, not ours.

⚠ THE OPENING LINE WAS QUIETLY WRONG AFTER THE CHANGE and I nearly left it. "There are three databases and
you only ever touch one" was true when the local one was the only option a joiner had; now they touch the
shared one OR a local one depending on one env line. The claim that actually matters — and is still exactly
true — is that they never touch the third. Now reads "You work against one of the first two — never the
third." A sentence can survive an edit around it and stop being true without looking any different.

Added the detail repo gave that a reader needs and would not guess: new collections start LOCKED until a
migration opens them, deliberately, so nothing is public by accident. That reinforces the schema-as-commits
point the section already makes rather than sitting beside it.

Names unchanged and re-verified: DX_PB_URL points at the PocketBase root (.../pb), DX_PB_PORT for the
port-in-use case. No internal hostnames anywhere in the file.
This commit is contained in:
Doxa Maps 2026-09-27 23:49:38 +00:00
parent ed04175a5d
commit 674d56559a
1 changed files with 21 additions and 7 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

28
documentation/HOWTO-join-the-table.md
View file

@ -113,12 +113,12 @@ So it cannot surprise you mid-thought. You can also check that any time at `/api
## The database, and the one thing that surprises people
There are three databases and you only ever touch one.
There are three databases. You work against one of the first two — never the third.
| Where | What is in it | Who touches it |
|---|---|---|
| Your laptop | your own sandbox data | you, freely |
| The shared dev server | the team's shared test data | the team |
| The team's shared one | the team's shared test data | the team — this is usually the default |
| Production | what the public sees | nobody directly |
**You never publish a database.** Not yours, not anyone's. What travels is the *shape* — the tables and
@ -132,12 +132,26 @@ This is deliberate. A database rule that opens something to the public arrives a
read** rather than as a setting somebody clicked at midnight. If you have ever inherited a system where the
live config did not match the repo, you already know why.
**You do not have to set up the database at all.** The first time you run `bun run dev` it downloads and
starts one for you, on your laptop, with its data in `.pb/`. You can open its admin screen from the dev
server at `/api/pb/_/`.
### Which one your laptop talks to
The only time you touch this is if the log says port 8090 is already in use — then set `DX_PB_PORT` to
something else in `.env.local`.
Most teams point every laptop at the **shared** one, so you are all working against the same test data.
Put this in `.env.local`:
```
DX_PB_URL=https://<your team's dev server>/pb
```
You sign in with the same team account you use for everything else — there is no separate password. Ask
whoever set up your team for the address if you do not have it.
**Leave it unset and you get a private one instead.** The first time you run `bun run dev` it downloads and
starts a database on your laptop, with its data in `.pb/`, and you can open its admin screen at
`/api/pb/_/`. That is the fallback, and it is a fine way to work while you are finding your feet.
The only other thing here is `DX_PB_PORT`, which you set only if the log says port 8090 is already in use.
> **New collections start locked.** Your plugin's data is not readable until a migration opens it —
> deliberately, so nothing is public by accident. That migration is a commit like any other.
---