newheap-database-development

Files (5)

• SKILL.md
• openai.yaml · agents/
• database-bulk-upsert.md · references/
• database-diagnostics.md · references/
• database-providers.md · references/

SKILL.md (first lines)

# NewHeap database development

Read [database providers](references/database-providers.md) for every query, schema, migration, raw SQL or provider-composition change.

Read [bulk upsert](references/database-bulk-upsert.md) for large, immediate and untracked imports through provider-native `ExecuteUpsertAsync`, including explicitly selected one-to-one and one-to-many dependents.

Read [database diagnostics](references/database-diagnostics.md) when a task investigates unexpected persisted state, missing or incorrect records, an API/database discrepancy, or unexplained staging or production behavior for which database evidence could answer the question. Do not wait for the user to name `newheap-db`, and do not stop after offering it: take the supported read-only route directly when the requested scope authorizes that local diagnostic. Do not use it for a bug that database evidence cannot materially clarify.

When the consumer repository pins the tool and checks in `.newheap/database-read.json`, local database-read instructions and request files, treat those files as the execution contract. When their location is not already explicit, make one bounded tracked-file search from the consumer repository root for `**/.newheap/database-read.json`, `**/Tooling/DatabaseRead/README.md`, and `**/Tooling/DatabaseRead/requests/*.json` before declaring the contract missing. If exactly one catalog is found, use the directory containing `.newheap` as the diagnostic working directory, even when the local .NET tool manifest is in an ancestor directory. Read the catalog only for its non-secret routing metadata. When it contains exactly one profile, omit `--profile` or the JSON `profile` and let `newheap-db` select it automatically. Its provider, configuration path, connection-string name and ceilings remain governed; its environment is the default. When the user explicitly requests another runtime environment, pass `--environment <name>` to both schema and query instead of refusing the diagnostic or requiring a second profile solely for that environment. Do not infer an override when the user did not name one. Let `newheap-db` resolve the governed connection-string name through the selected environment's normal NewHeap configuration and secrets flow; never read, echo or reconstruct the connection string. With multiple profiles, use the requested scope, a checked-in request's `profile`, or the local README to select one, pass `--profile` for direct schema discovery, and ask only when those sources leave a real ambiguity. Do not inspect controllers, entities, EF configuration, appsettings, secrets or NuGet package internals merely to reconstruct those choices or the JSON query shape. `dotnet tool list --local` proves only that a manifest entry exists; restore the tool only when `newheap-db` reports that the local command is unavailable.

`newheap-db validate` is a local contract check and does not open a database connection. `newheap-db query` and `newheap-db schema` require outbound network access to the configured database. In Codex, start the first `query` or `schema` invocation with network-enabled or escalated execution; do not probe the restricted sandbox first. Request a narrow reusable permission rule scoped only to the `newheap-db` command, such as the `dotnet tool run newheap-db` prefix, and do not broaden it to arbitrary `dotnet`, shell or network commands. The `network-access-required` retry hint states a capability requirement, not a diagnosis of the host: a sandbox policy, firewall, DNS failure or network ACL can produce the same safe response.

Prefer a structured MCP call for agent diagnostics. For direct CLI use, discover unknown identifiers with `newheap-db schema --search <term> --describe-if-single`, optionally restricted by `--schema-name`; do not look up or author schema-request JSON first. The command returns full metadata when one untruncated object matches and otherwise returns bounded summaries for one refinement. Stream query JSON through stdin or pass only a request path with `--request-file`; never inline serialized JSON in a shell or process-launch argument. `schema` and `query` validate internally, so do not call `validate` immediately before them. Reserve `validate` for CI, request-template checks or another intentional dry run. For a simple count/latest or record lookup, make one schema invocation and, only after it establishes the required identifiers and relationships, one query invocation. A non-success schema response is terminal except when `connection-string-unresolved` identifies a host-specific secrets-path mismatch. Inspect only `NewHeap.PlatformCommon.AppSecretsDirectoryPath` routing values when needed. If checked-in local instructions give the exact directory, or an existing non-secret local secrets-root variable can be joined with the configured deployment path's service-directory suffix without scanning, set `NewHeap__PlatformCommon__AppSecretsDirectoryPath` only for the `newheap-db` child process and retry the same schema command once. Never read secret or connection-string values, scan secret directories, or persistently edit application settings. If that retry fails, or for any other schema error, report the stable code, safe message and request identifier and stop without inspecting source code or a repository index, inferring entities, enum values, relationships or business semantics, or issuing a query. Stop when the requested database evidence is available. Do not repeat completed calls, switch to source or package investigation merely because the checked-in contract already answers a routing or request-shape question, or narrow a correct candidate set merely to fit a Windows command-line limit.

Treat staging and production as live, potentially large databases. Every diagnostic data query needs a provider-native SQL row cap as well as bounded request limits. When table size or predicate selectivity is uncertain, make at most one focused index-metadata check for the already-confirmed object. Use it when a suitable leading key is immediately clear; otherwise continue with a tightly bounded query. Do not spend additional calls tuning or resolving index ambiguity, and never compensate by broadening the query or automatically increasing timeouts.

Prefer provider-translatable LINQ and keep filtering, ordering and paging server-side. Provider choice belongs in the composition layer. Raw SQL is provider-specific until proven otherwise and every data value is parameterized.

Never hand-edit an existing migration or model snapshot. Generate new consumer-owned migrations only for schema changes explicitly in scope.

Test relational semantics on real SQL Server and PostgreSQL providers when translation, constraints, transactions, migrations or raw SQL matter. EF Core InMemory is not equivalent. Report the provider matrix actually exercised and any explicit provider gap.

From NewHeap/NewHeap-Platform, Apache-2.0.

More from NewHeap/NewHeap-Platform