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.
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.
| Sample | Connection URL |
|---|---|
| PostgreSQL | postgres://dms_reader:dms_reader@sample-db:5432/shop |
| MongoDB | mongodb://shop_reader:shop_reader@sample-mongodb:27017/shop?authSource=admin |
| RethinkDB | rethinkdb://shop_reader:shop_reader@sample-rethinkdb:28015/shop |
| MySQL | mysql://shop_reader:shop_reader@sample-mysql:3306/shop |
| MariaDB | mysql://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.
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:
[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-tokenin 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:
- Server reachable, with the round trip.
- Signed in as, with the account the server reports.
- 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.
- 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.tsgets thebuilder-db-shopmodule, an@antelopejs/postgresdriver that reads its URL from a variable, and thebuilder-db-shop-tablesmodule. Thedmsentry records the connection..envgetsBUILDER_DB_SHOP_URL. The templates'.gitignoreleaves.envout 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. Itspackage.jsonrecords 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 devand Docker setups do. Without-w, the window asks you to stop the project and start it again withajs project dev -w. - Every environment needs the variable. Set
BUILDER_DB_<NAME>_URLwherever 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 startmounts none of its routes, and the assistant does not run withNODE_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
numericis read as a number, and atimestampkeeps milliseconds only. The backend log names each column read this way.
Next steps
- Database connection lists the routes behind the flow and every change they write.
- External databases documents the analysis and the mapping, and the rules behind each proposed screen.