[data-reveal]{opacity:1!important;transform:none!important}
AntelopeJS DMS
DocumentationExisting database

Start from an existing database

Connect the PostgreSQL, MySQL, MariaDB, MongoDB or RethinkDB database your product already runs from the assistant's onboarding, and get its admin pages as TypeScript in your repository.

The DMS can serve pages over a database it does not own, such as the one your product already uses. You connect it from the onboarding of the assistant, with Start from an existing database. The DMS analyses the database, proposes a screen for each table, and writes the pages as TypeScript into a module of your project. Your application and its database stay as they are.

This page walks through the flow once. Database connection documents the routes behind it, and External databases the operations they call.

Before you start

You need:

  • A DMS project that loads @antelopejs/dms-assistant, running in development. Both templates below have it. The connect flow runs only in development.
  • Claude Code or Codex for the assistant. The onboarding connects one of them before it offers a starting point. A Claude Pro or Max subscription, or a ChatGPT Plus, Pro or Team plan, is enough.
  • A PostgreSQL, MySQL, MariaDB, MongoDB or RethinkDB database that the DMS backend can reach over the network.
  • An account on that database that can read it. An account that can only read is enough.

Try it on the demo template

The connect demo template runs the DMS and the assistant next to a sample database: the online orders of a coffee brand, in 12 tables. It is the quickest way to see the flow before you point it at your own data.

Terminal bash
npx @antelopejs/core project init my-demo --template dms-connect-demo
cd my-demo
docker compose up

You need git, Node.js 24 and Docker with Compose v2. docker compose up starts the PostgreSQL sample. Add --profile mysql, --profile mariadb, --profile mongodb or --profile rethinkdb for the same data in another engine. Each sample account can only read.

SampleConnection URL
PostgreSQLpostgres://dms_reader:dms_reader@sample-db:5432/shop
MongoDBmongodb://shop_reader:shop_reader@sample-mongodb:27017/shop?authSource=admin
RethinkDBrethinkdb://shop_reader:shop_reader@sample-rethinkdb:28015/shop
MySQLmysql://shop_reader:shop_reader@sample-mysql:3306/shop
MariaDBmysql://shop_reader:shop_reader@sample-mariadb:3306/shop

The template's README covers running the DMS outside Docker, where the URLs use localhost, and starting over.

Use your own database

The starter template runs the same DMS and assistant with no sample data. Start your project from it, then connect your database as the next section shows.

Terminal bash
npx @antelopejs/core project init my-project --template dms-starter
cd my-project
docker compose up

With Docker, the DMS runs in a container. Use host.docker.internal as the host of a database on your machine. Without Docker, use localhost. Quickstart walks through the first run.

The connection check opens the database with the engine's client library: pg for PostgreSQL, mysql2 for MySQL and MariaDB, mongodb for MongoDB, rethinkdb-ts for RethinkDB. When the project cannot load it, the check answers with a message such as Install pg to connect a PostgreSQL database. Add the library to the project's dependencies, at the range that peerDependencies of @antelopejs/dms gives.

Connect the database

Create the administrator

When the backend starts with no administrator, its log prints an onboarding address. With Docker, it is in the dms log:

text
[DMS] No owner exists yet. To create it, open http://localhost:3001/onboarding?token=...

Open it and create the administrator account. The password needs at least 8 characters, an uppercase letter, a digit and one of @$!%*?&, and no other symbol. Then press Open the dashboard.

Connect Claude or Codex

The assistant's window opens on the dashboard. It runs on your own subscription.

  • When it finds a login on the machine, it shows Your assistant is ready. Press Use this login, or Use Codex or another account instead.
  • Otherwise, press Get started and answer Which AI do you use?. Claude asks you to run claude setup-token in a terminal and paste the token it prints. Codex signs in with your ChatGPT account through Continue with ChatGPT.

With Docker, the container keeps its own logins. To skip this step, put CLAUDE_CODE_OAUTH_TOKEN=<the output of claude setup-token> in a .env file next to compose.yaml. To sign in to Codex from the container, open DMS running on another machine? and paste the address of the page ChatGPT sends you back to, which does not load.

Choose Start from an existing database

Use this login leads to Where do you start from?. After a new sign-in, press Choose a starting point first. Then choose Start from an existing database.

Paste the connection URL

Pick the engine: PostgreSQL, MongoDB, RethinkDB or MySQL / MariaDB. Paste the URL into Connection URL. The URL is saved in the project's .env.

Press Connect and analyse

The window checks the database and shows each step:

  1. Server reachable, with the round trip.
  2. Signed in as, with the account the server reports.
  3. Read access, or Read and write access when the account can write. Then the window asks What may the DMS do with this database?: Read only, where the DMS writes nothing, or Read and write, to edit rows from the DMS.
  4. Reading the schema. The project restarts to load the connection, then the DMS analyses the tables.

The analysis runs in the DMS, with no AI model involved. It reads the schema and the row counts. It also reads values from the tables: the values of a column that holds few distinct values, such as a status, and the minimum and maximum values of columns.

The connection is named after the database in the URL, such as shop.

Choose the screens

Here's what's in lists the tables with their row counts, and the screens it proposes for them. Each screen is a table, a table + status, a table + tabs, or statistics. Untick the screens you don't need.

Then choose how to build them:

  • Build directly writes the pages and opens the first one. Some of the values the analysis read, such as the values of a status column, are written into the generated code as badges and tabs.
  • Generate a first mockup hands the chosen screens to the assistant in the chat. It drafts a live mockup from the data before anything is built. In that chat and in any later turn, the AI model can read the values the analysis found, without asking.

The pages appear in the menu, in a group named after the connection.

What lands in your repository

For a PostgreSQL connection named shop:

  • antelope.config.ts gets the builder-db-shop module, an @antelopejs/postgres driver that reads its URL from a variable, and the builder-db-shop-tables module. The dms entry records the connection.
  • .env gets BUILDER_DB_SHOP_URL. The templates' .gitignore leaves .env out of git.
  • modules/builder-db-shop-tables/ holds the generated TypeScript: a table definition and a data API for each table you kept, and a page for each screen that is not statistics. Its package.json records the connection and the tables you left out.

These are ordinary DMS files. Review them, commit them except .env, and edit them in your editor or with the assistant.

Pages start read-only

A mapped table gets list, detail and export routes, and no create, edit or delete route, until you ask the assistant to let its rows be edited. Editing rows also needs a database account that can write.

Come back later

The window opens on its own until onboarding is done, then once each time the server starts. Don't show on startup turns that off. Open it again with Assistant at the bottom left. Once the project has pages, it opens on Welcome back, where Connect a DB connects another database.

Pitfalls

  • The project restarts to load the connection. Run the backend with ajs project dev -w, as the templates' pnpm dev and Docker setups do. Without -w, the window asks you to stop the project and start it again with ajs project dev -w.
  • Every environment needs the variable. Set BUILDER_DB_<NAME>_URL wherever each deployed environment keeps its secrets, never in git. A deployment without it cannot reach the database.
  • The connect flow is a development tool. A project started from its build with ajs project start mounts none of its routes, and the assistant does not run with NODE_ENV=production. The generated pages run anywhere.
  • The first page can stay empty. After Build directly, the page that opens can show its title and no table. Reload the page.
  • Some types lose precision. A PostgreSQL numeric is read as a number, and a timestamp keeps milliseconds only. The backend log names each column read this way.

Next steps