Skip to main content

Quickstart (Docker)

Point DB-X at a plain Postgres container and apply a schema. This is pure DB-X — a docker-compose.yml that runs only Postgres, and the db-x CLI applying a JSX schema against it. No Infra-X, no <Service>, no Compose orchestration from the runtime.

Experimental

DB-X is an early prototype — do not point it at a database you care about.

Prerequisites​

  • Docker (for the Postgres container)
  • Node + pnpm
  • psql on your PATH — db-x apply shells out to it to run the DDL

1. Clone and build​

DB-X isn't on npm yet, so the db-x binary comes from the workspace build:

git clone https://github.com/rtorcato/db-x.git
cd db-x
pnpm install && pnpm build

2. Start Postgres​

The standalone example ships a minimal Compose file — just Postgres, matching the demo's default credentials (todos / todos / todos on :5432):

cd examples/postgres
docker compose up -d --wait   # starts Postgres, waits until it accepts connections

3. Inspect the schema​

examples/postgres/dbx.tsx is standalone DB-X — it imports only @db-x/postgres-library and connects via <DatabaseTarget url=...>, reading the URL from .env (auto-created from .env.example on first run):

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

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

export default (
  <DatabaseTarget url={process.env.DATABASE_URL}>
    <Postgres name="todos-db" user="todos" password="todos" database="todos">
      <Table name="todos">
        <Column name="id" type="uuid" primaryKey default="gen_random_uuid()" />
        <Column name="title" type="citext" notNull />
        <Column name="done" type="boolean" notNull default="false" />
      </Table>
    </Postgres>
  </DatabaseTarget>
);

4. Preview the plan​

pnpm preview        # db-x preview — picks up ./dbx.tsx

Renders the JSX, diffs it against .dbx/state.json, and prints what would change. Preview is offline — it does not touch Postgres.

5. Apply​

pnpm apply          # db-x apply — picks up ./dbx.tsx

Connects to the container, creates the database objects (extensions, tables, columns, indexes, seed rows), and persists the new state to .dbx/state.json.

6. Tear down​

pnpm destroy                 # drop the schema objects in reverse order
docker compose down -v       # stop Postgres and wipe its volume

Next steps​