layerbase 2.6.0 → 2.6.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +47 -26
- package/package.json +2 -2
- package/skills/layerbase/SKILL.md +67 -0
package/README.md
CHANGED
|
@@ -1,19 +1,27 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Layerbase CLI
|
|
2
|
+
|
|
3
|
+
<p align="center">
|
|
4
|
+
<a href="https://layerbase.com/docs/cli">
|
|
5
|
+
<img src="https://raw.githubusercontent.com/Layerbase-LLC/layerbase-cli/main/assets/social-preview.png" alt="Layerbase CLI: build locally, promote to the cloud" width="100%" />
|
|
6
|
+
</a>
|
|
7
|
+
</p>
|
|
2
8
|
|
|
3
9
|
[](https://www.npmjs.com/package/layerbase)
|
|
4
|
-
[](https://www.npmjs.com/package/layerbase)
|
|
11
|
+
[](#license)
|
|
12
|
+
|
|
13
|
+
**One CLI for local and cloud databases.**
|
|
5
14
|
|
|
6
|
-
The Layerbase CLI
|
|
7
|
-
[spindb](https://github.com/robertjbass/spindb) for local database work, plus a
|
|
8
|
-
`cloud` layer for your managed [**Layerbase cloud**](https://layerbase.com)
|
|
9
|
-
account. Connect with native
|
|
10
|
-
clients, drop into spindb, and never paste a connection string into your shell
|
|
11
|
-
history.
|
|
15
|
+
Moving a database from your laptop to the cloud usually means new tools, a dump and restore, and passwords in your shell history. The Layerbase CLI handles both sides: build locally, then promote to [Layerbase Cloud](https://layerbase.com) with your data.
|
|
12
16
|
|
|
13
|
-
**
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
+
- **Run databases locally:** every [spindb](https://github.com/robertjbass/spindb) command works, with no account
|
|
18
|
+
- **Promote in one command:** SQLite, DuckDB, SQL dumps and supported local databases, data included
|
|
19
|
+
- **Connect safely:** open `psql`, `mysql` or `redis-cli` without typing a password or pasting a connection string
|
|
20
|
+
- **Branch cloud databases:** create, reset and delete a copy per feature or pull request
|
|
21
|
+
- **Migrate from elsewhere:** Neon, Supabase, PlanetScale, Railway, Upstash and more
|
|
22
|
+
- **Built for CI and agents:** API keys, JSON output, meaningful exit codes and an installable agent skill
|
|
23
|
+
|
|
24
|
+
[Install](#install) | [Quick start](#quick-start) | [Commands](#cloud-account) | [Promote](#promote-a-local-database-to-the-cloud) | [Migrate](#migrations-and-imports) | [CI and agents](#headless-auth-ci-and-agents) | [License](#license)
|
|
17
25
|
|
|
18
26
|
## Install
|
|
19
27
|
|
|
@@ -31,14 +39,23 @@ This installs two commands, `layerbase` and a shorter `lbase`. For a two-letter
|
|
|
31
39
|
## Quick start
|
|
32
40
|
|
|
33
41
|
```bash
|
|
34
|
-
|
|
35
|
-
lbase create my-db --engine
|
|
36
|
-
|
|
37
|
-
|
|
42
|
+
# Local: no account needed
|
|
43
|
+
lbase create my-db --engine postgresql --start
|
|
44
|
+
|
|
45
|
+
# Cloud: save an API key from https://layerbase.com/cloud/settings
|
|
46
|
+
lbase login --api-key sk_...
|
|
47
|
+
lbase promote my-db # create it in the cloud, data included
|
|
38
48
|
lbase cloud ls # list your cloud databases
|
|
39
|
-
lbase psql
|
|
49
|
+
lbase psql <cloud-db> # connect, no password typed
|
|
40
50
|
```
|
|
41
51
|
|
|
52
|
+
Run `lbase` by itself to browse local and cloud databases in your terminal.
|
|
53
|
+
`lbase login` without a key signs in through your browser, which is enough to
|
|
54
|
+
list and connect. Promote needs an API key to import your data.
|
|
55
|
+
|
|
56
|
+
**The rule: bare commands are local, `lbase cloud <verb>` is cloud.** So
|
|
57
|
+
`lbase ls` lists local databases and `lbase cloud ls` lists cloud ones.
|
|
58
|
+
|
|
42
59
|
## Local databases (drop-in for spindb)
|
|
43
60
|
|
|
44
61
|
Every spindb command works. Anything that is not a layerbase verb (see the
|
|
@@ -47,12 +64,12 @@ Every spindb command works. Anything that is not a layerbase verb (see the
|
|
|
47
64
|
exit code preserved:
|
|
48
65
|
|
|
49
66
|
```bash
|
|
50
|
-
lbase create my-db --engine
|
|
51
|
-
lbase ls
|
|
52
|
-
lbase start my-db
|
|
53
|
-
lbase backup my-db
|
|
54
|
-
lbase branch my-db feature-x
|
|
55
|
-
lbase <cmd> --help
|
|
67
|
+
lbase create my-db --engine postgresql # == spindb create my-db --engine postgresql
|
|
68
|
+
lbase ls # == spindb list
|
|
69
|
+
lbase start my-db # == spindb start my-db
|
|
70
|
+
lbase backup my-db # == spindb backup my-db
|
|
71
|
+
lbase branch my-db feature-x # == spindb branch my-db feature-x
|
|
72
|
+
lbase <cmd> --help # == spindb <cmd> --help
|
|
56
73
|
```
|
|
57
74
|
|
|
58
75
|
Bare `lbase` with no arguments opens the database browser (`lbase tui`) only
|
|
@@ -449,7 +466,7 @@ containers; `layerbase` adds the cloud account layer around it.
|
|
|
449
466
|
|
|
450
467
|
```bash
|
|
451
468
|
layerbase spindb # open spindb's own menu
|
|
452
|
-
layerbase spindb create
|
|
469
|
+
layerbase spindb create my-db # run any spindb command locally
|
|
453
470
|
```
|
|
454
471
|
|
|
455
472
|
spindb is found on your `PATH`, or run through `npx` / `pnpx` / `bunx` if it is
|
|
@@ -506,7 +523,7 @@ alone and suggests a shell alias instead.
|
|
|
506
523
|
|
|
507
524
|
## Requirements
|
|
508
525
|
|
|
509
|
-
- Node.js 20 or newer.
|
|
526
|
+
- Node.js 20 or newer (22 or newer for local commands, which run spindb).
|
|
510
527
|
- For `cloud connect` / `psql` / `redis-cli` / `mysql`: the matching native
|
|
511
528
|
client on your `PATH`.
|
|
512
529
|
|
|
@@ -522,4 +539,8 @@ command. See `CLAUDE.md` for the full contract.
|
|
|
522
539
|
|
|
523
540
|
## License
|
|
524
541
|
|
|
525
|
-
ISC, [Layerbase, LLC](https://layerbase.com).
|
|
542
|
+
This CLI is ISC licensed, [Layerbase, LLC](https://layerbase.com).
|
|
543
|
+
|
|
544
|
+
Local commands run [spindb](https://github.com/robertjbass/spindb), a separate
|
|
545
|
+
program under [PolyForm Noncommercial 1.0.0](https://github.com/robertjbass/spindb/blob/main/LICENSE).
|
|
546
|
+
Commercial use of spindb requires a separate license.
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "layerbase",
|
|
3
|
-
"version": "2.6.
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "2.6.1",
|
|
4
|
+
"description": "One CLI for local and cloud databases. Build locally with spindb, promote to Layerbase Cloud with your data, and connect without pasting a connection string.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
7
7
|
"layerbase": "dist/cli.js",
|
|
@@ -265,6 +265,73 @@ Example GitHub Actions step:
|
|
|
265
265
|
echo "DATABASE_URL=$(layerbase cloud connection-string ci-$GITHUB_RUN_ID)" >> "$GITHUB_ENV"
|
|
266
266
|
```
|
|
267
267
|
|
|
268
|
+
### 4a. A database branch per pull request (GitHub, Vercel)
|
|
269
|
+
|
|
270
|
+
Users often want every pull request or preview deployment to get its own
|
|
271
|
+
database branch. There are two ways to set that up. Pick the one that needs no
|
|
272
|
+
human when the user is not around.
|
|
273
|
+
|
|
274
|
+
**Route A: no human needed (works today).** You do every step with access you
|
|
275
|
+
already have in the user's environment. The only exception is the
|
|
276
|
+
`LAYERBASE_API_KEY` secret from step 1 above, if the repository does not have
|
|
277
|
+
one yet.
|
|
278
|
+
|
|
279
|
+
1. Pick a durable, seeded parent database on a branchable engine (see
|
|
280
|
+
`agents.md`) and turn Branching on for it. A transient (`--ttl`) database
|
|
281
|
+
cannot be a branch parent.
|
|
282
|
+
2. Commit a workflow like this one, and set the secret with
|
|
283
|
+
`gh secret set LAYERBASE_API_KEY`:
|
|
284
|
+
|
|
285
|
+
```yaml
|
|
286
|
+
on:
|
|
287
|
+
pull_request:
|
|
288
|
+
types: [opened, synchronize, reopened, closed]
|
|
289
|
+
jobs:
|
|
290
|
+
preview-db:
|
|
291
|
+
runs-on: ubuntu-latest
|
|
292
|
+
env:
|
|
293
|
+
LAYERBASE_API_KEY: ${{ secrets.LAYERBASE_API_KEY }}
|
|
294
|
+
steps:
|
|
295
|
+
- run: npm i -g layerbase
|
|
296
|
+
- name: Create or reuse this PR's branch
|
|
297
|
+
if: github.event.action != 'closed'
|
|
298
|
+
run: |
|
|
299
|
+
URL=$(layerbase cloud branch seed-db pr-${{ github.event.number }} --json --show-secrets | jq -r '.connectionString')
|
|
300
|
+
echo "::add-mask::$URL"
|
|
301
|
+
echo "DATABASE_URL=$URL" >> "$GITHUB_ENV"
|
|
302
|
+
- name: Delete this PR's branch
|
|
303
|
+
if: github.event.action == 'closed'
|
|
304
|
+
run: layerbase cloud branch delete seed-db pr-${{ github.event.number }}
|
|
305
|
+
```
|
|
306
|
+
|
|
307
|
+
`layerbase cloud branch` is idempotent: re-running it reuses the branch.
|
|
308
|
+
Branch names start with a letter and use only letters, digits, `-` and `_`,
|
|
309
|
+
so map a git branch like `feat/login` to something like `feat-login`.
|
|
310
|
+
3. If the app's previews deploy on Vercel, give the preview of that git branch
|
|
311
|
+
the branch's connection string with the Vercel CLI you are already signed in
|
|
312
|
+
to: `vercel env add DATABASE_URL preview <git-branch>`. The next preview build
|
|
313
|
+
of that branch uses it. Remove it when the branch is deleted.
|
|
314
|
+
4. Each database has its own branch allowance. Delete branches when their pull
|
|
315
|
+
request closes, and check `layerbase cloud branch ls seed-db` for leftovers.
|
|
316
|
+
|
|
317
|
+
**Route B: the managed integrations (one click by the team owner).** Layerbase's
|
|
318
|
+
Vercel integration and GitHub App create, reset and delete branches for the
|
|
319
|
+
user and set the env var in Vercel themselves. Connecting either one is a
|
|
320
|
+
consent screen on GitHub or Vercel that only a person can approve, and only the
|
|
321
|
+
team owner can connect. You cannot do it, so never try to automate it. Tell the
|
|
322
|
+
user plainly that a human is needed and walk them through it:
|
|
323
|
+
|
|
324
|
+
1. The team owner opens https://layerbase.com/cloud/integrations and clicks
|
|
325
|
+
Connect for GitHub or Vercel.
|
|
326
|
+
2. On GitHub, they choose which repositories Layerbase may see, then Install. On
|
|
327
|
+
Vercel, they approve the integration for their team.
|
|
328
|
+
3. Back on Layerbase, they map the repository or Vercel project to the database
|
|
329
|
+
and pick the preview mode.
|
|
330
|
+
|
|
331
|
+
After that, the MCP tools `list_integrations`, `list_preview_mappings` and
|
|
332
|
+
`update_preview_mapping` let you check and adjust the setup. Creating or
|
|
333
|
+
deleting a mapping is done in the dashboard today.
|
|
334
|
+
|
|
268
335
|
## 5. Conduct rules
|
|
269
336
|
|
|
270
337
|
- Fetch `agents.md` before stating any price, limit, or capability. Never quote a
|