Migrating from @infra-x/postgres-library

DB-X grew out of the work the @infra-x/postgres-library reference library needed, and has since become a separate project with its own vendored runtime. Whether and when the Infra-X-side Postgres library is deprecated is Infra-X's call — tracked upstream in infra-x#24.

caution

DB-X is 0.1.0-alpha.0 and not ready for real data. Treat this as a guide for trying DB-X alongside an existing setup, not for moving a production deployment onto it.

The migration is import swap + parent swap + CLI swap.

1. Swap the imports

- import {
-   Column,
-   Index,
-   Postgres,
-   Table,
- } from '@infra-x/postgres-library';
+ import {
+   Column,
+   Index,
+   Postgres,
+   Table,
+ } from '@db-x/postgres-library';

The component names and prop shapes match for the v0.x surface. Props specific to DB-X — <DatabaseTarget>, from= column renames, protect, snapshot — are additive.

You also need the JSX pragma pointing at DB-X's runtime, since it is no longer the same package:

/** @jsxImportSource @db-x/runtime */

2. Swap the parent

The Infra-X library assumed a <Service> running Postgres in Compose. DB-X does not ship a <Service> component — it never manages the database server lifecycle, only the schema. <DatabaseTarget> is the parent in both cases; only the URL changes.

<DatabaseTarget url={process.env.DATABASE_URL!}>
  <Postgres name="todos-db">{/* tables */}</Postgres>
</DatabaseTarget>

Point it at a local container for dev and CI (see the Docker quickstart) or at a managed instance for production (see the managed quickstart). Bring the container up however you already do — Compose, docker run, Testcontainers. DB-X connects to it; it does not start it.

3. Swap the CLI

The db-x CLI has shipped. This step is required, not optional: DB-X vendored the runtime, so @db-x/postgres-library components are not loadable by infra-x apply — they register against @db-x/runtime, a different package.

- pnpm infra-x apply ./infra.tsx
+ pnpm db-x apply ./dbx.tsx

Shipped today: preview · apply · refresh · destroy · restore · state · describe. Still planned: snapshot / history / diff (#6) and the MCP server (#9) — see the roadmap.

Running both

Nothing stops you keeping Infra-X for the rest of your infrastructure and using db-x for the database. They are separate binaries reading separate files, with separate state — DB-X keeps its own in .dbx/. What you cannot do is mix components from the two runtimes inside one tree.

@infra-x/php-library is unrelated (a PHP image builder, not a database) and is unaffected either way.