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 CHANGED
@@ -1,19 +1,27 @@
1
- # layerbase
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
  [![npm version](https://img.shields.io/npm/v/layerbase.svg)](https://www.npmjs.com/package/layerbase)
4
- [![license](https://img.shields.io/npm/l/layerbase.svg)](https://www.npmjs.com/package/layerbase)
10
+ [![npm downloads](https://img.shields.io/npm/dm/layerbase.svg)](https://www.npmjs.com/package/layerbase)
11
+ [![license](https://img.shields.io/npm/l/layerbase.svg)](#license)
12
+
13
+ **One CLI for local and cloud databases.**
5
14
 
6
- The Layerbase CLI is **local-first**: it is a drop-in for
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
- **The bare command namespace belongs to spindb.** Any command that is not one of
14
- layerbase's own verbs forwards straight to your local spindb install, verbatim,
15
- so `lbase create / ls / start / backup / branch ...` behave exactly like
16
- `spindb <same>`. Cloud database commands live under `lbase cloud <verb>`.
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
- lbase # database browser (local and cloud, in a terminal)
35
- lbase create my-db --engine postgres # any spindb command, verbatim
36
- lbase login # sign in through your browser
37
- lbase promote ./app.db # put a local database in the cloud, data included
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 my-cloud-db # connect with the right client, no password typed
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 postgres # == spindb create my-db --engine postgres
51
- lbase ls # == spindb list
52
- lbase start my-db # == spindb start my-db
53
- lbase backup my-db # == spindb backup my-db
54
- lbase branch my-db feature-x # == spindb branch my-db feature-x
55
- lbase <cmd> --help # == spindb <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 postgres # run any spindb command locally
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.0",
4
- "description": "Layerbase cloud CLI: connect to your managed databases without leaking the connection string into shell history.",
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