mosaicstack/stack
1
0
Fork 0
Code Issues 58 Pull Requests 1 Actions Packages Projects Releases 15 Wiki Activity

docs(#771): bind tier importer to verified target

Browse Source
This commit is contained in:
Hermes Agent
2026-07-15 03:58:02 -05:00
parent 186b44fb0e
commit d3832e454b
18 changed files with 260 additions and 205 deletions
Download Patch File Download Diff File Expand all files Collapse all files

29
docs/guides/dev-guide.md
View File

@@ -106,7 +106,8 @@ This starts:
Create a `.env` file in the monorepo root:
```env
# Database (matches docker-compose defaults)
# Runtime database connection (local-development placeholder only; never a production secret)
# KBN-101 production-like runtime injects DATABASE_URL from its dedicated secret mount.
DATABASE_URL=postgresql://mosaic:mosaic@localhost:5433/mosaic
# Auth (required — generate a random 32+ char string)
@@ -127,14 +128,16 @@ OLLAMA_MODELS=llama3.2
The gateway loads `.env` from the monorepo root via `dotenv` at startup
(`apps/gateway/src/main.ts`).
### 4. Push the Database Schema
### 4. Prepare the PostgreSQL Schema
```bash
pnpm --filter @mosaicstack/db db:push
mosaic-db-migrator --run
mosaic-db-migrator --verify
```
This applies the Drizzle schema directly to the database (development only; use
migrations in production).
KBN-101 makes this the sole PostgreSQL DDL/readiness sequence. Direct schema push is not an
operator workflow; a disposable local experiment is separately guarded and cannot use a
production-like tier or URL.
### 5. Start the Gateway
@@ -355,12 +358,13 @@ The schema lives in a single file:
The `insights` table uses a `vector(1536)` column (pgvector) for semantic search.
### Development: Push Schema
### Development: Prepare Schema
Apply schema changes directly to the dev database (no migration files created):
Prepare a PostgreSQL development target through the same sole runner:
```bash
pnpm --filter @mosaicstack/db db:push
mosaic-db-migrator --run
mosaic-db-migrator --verify
```
### Generating Migrations
@@ -376,7 +380,8 @@ This creates a new SQL migration file in `packages/db/drizzle/`.
### Running Migrations
```bash
pnpm --filter @mosaicstack/db db:migrate
mosaic-db-migrator --run
mosaic-db-migrator --verify
```
### Drizzle Config
@@ -388,9 +393,9 @@ directory are defined there.
1. Add the table definition to `packages/db/src/schema.ts`.
2. Export it from `packages/db/src/index.ts`.
3. Run `pnpm --filter @mosaicstack/db db:push` (dev) or
`pnpm --filter @mosaicstack/db db:generate && pnpm --filter @mosaicstack/db db:migrate`
(production).
3. Generate the offline artifact with `pnpm --filter @mosaicstack/db db:generate`, then run
`mosaic-db-migrator --run` and `mosaic-db-migrator --verify`. Direct schema push is not a
production-like workflow and the migration runner accepts no URL/SQL/schema/role argv.
---