Connect an existing database

Connect the PostgreSQL, MongoDB or RethinkDB database your product already runs, let the Builder map its tables, and get 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, ERP or time clock already uses. You connect it in the Builder's Database workspace. The Builder reads the database's catalog, proposes a page or a statistics entry for each table or leaves it out, and writes the result as TypeScript into a module of its own. Your application and its database stay as they are: nothing creates or alters a table.

This page walks through the whole flow once. External databases in the Builder reference documents the operations behind it, for scripts and assistants.

Before you start

You need:

A DMS project with the Builder running in development. The starter template below has it. To add it to an existing project, follow Builder installation. The Database workspace is part of the Builder.
A tenant owner account on that project. Only an owner opens the Builder.
A PostgreSQL, MongoDB or RethinkDB database that the DMS backend can reach over the network.
An account on that database that can only read. A PostgreSQL role with SELECT, a MongoDB user with the built-in read role, or a RethinkDB user with read permission is enough to analyse and map it.
Optionally, the AI assistant (@antelopejs/dms-ai), to settle the mapping and build dashboards for you.

Try it on the demo template

The connect demo template runs the DMS, the Builder and the assistant next to a sample shop database, in Docker. It is the quickest way to see the flow before you point it at your own data.

Terminal bash

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

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

Sample	Connection string
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`

The dms log prints an onboarding address that creates the administrator account. Open it, then follow Connect the database with the connection string of your sample. The template's README covers running the DMS outside Docker and starting over.

Do it on your own database

The starter template runs the same DMS, Builder and assistant with no sample data. Start your own 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

The DMS runs in a container, so use host.docker.internal as the host of a database on your machine. Quickstart walks through the first run, and the template's README covers running it without Docker.

Connect the database

Open the Database workspace

Open any DMS page and click the hammer button in the page header, or press Ctrl B (⌘ B on macOS). Choose the Database tab, then Connect a database.

Describe the connection

Enter a Name, such as erp. It names the connection in the Builder and in the assistant. Pick the Database type.

Paste a connection URL into Connection and press Fill in to split it into host, port, database, user and password. You can also type the fields one by one.

Show the changes lists what Connect writes, before it writes anything. Advanced settings holds the names it derives from the connection name, which you can change:

Field	Default for `erp`	What it is
Driver module	`builder-db-erp`	The `@antelopejs/postgres`, `@antelopejs/mongodb` or `@antelopejs/rethinkdb` instance that connects to the database
Package version	Filled in	The range of that package to install
Tables module	`builder-db-erp-tables`	The local module the tables and pages are written into
Variable	`BUILDER_DB_ERP_URL`	Holds the URL in each environment. MongoDB adds a second variable for the database name

Press Connect

The Builder runs four steps and shows each one:

Adding the connection to the project. It writes the driver module and the tables module into antelope.config.ts, and the URL into .env. The configuration only names the variable.
Reloading the project. The project restarts to load the connection. This takes about 15 seconds.
Connecting. The Builder reaches the database through the driver module, with the account you gave.
Reading the database. It describes every table and profiles its columns. A profile holds counts, ranges and categories, never a row.

When it finishes, it lists how many tables become pages, how many are counted in statistics only, and how many questions are left.

Map the tables in the Builder

Choose who settles the mapping:

Review it myself opens the proposal in the Builder.
Let the assistant finish hands it to the assistant, described in the next section.

The proposal sorts the tables into three groups:

Pages. A table with a key, rows and a column that names them gets a page that lists its rows.
Stats only, no page. A table without a key, a join table, or a log with a time axis is counted and charted by statistics pages, with no page of its own.
Not added. A table with no rows, or one that belongs to a framework or a migration tool, is left out.

Pick a table to see its columns. Every suggestion names the rule that made it, under Suggested. The Builder proposes, for each table:

A Label, the column that names a row. It shows first in the list and in the columns of other tables that point at it.
A title for the page and for each relation column, from the database's comments, else from its names. Other columns are titled from their names.
Which columns are listed, filtered, sorted and searched. A column named like a secret is left out.
References between tables, from foreign keys or from values found in another table's key. They become relation columns.
Badges for a text column with a few known values, prices for an amount column, and tabs for a status column.

Answer the questions under To decide, such as what a table holds or which column names its rows. A question you leave open is applied with the proposal's answer meanwhile, and asked again next time.

Press Apply changes. The Builder writes the tables and pages into the tables module in one change, checked to compile. The pages appear in the menu under the connection's name once the module reloads, a few seconds later.

To change a table later, open it in the Database workspace again, edit its choices and apply. The Builder rewrites that table and its page from the new choices.

Let the assistant finish

With @antelopejs/dms-ai in the project, Let the assistant finish hands the proposal to the assistant. It answers the open questions from the catalog and the profiles, gives every page a title, an icon and the table features its data supports, and builds an analytics dashboard first in the menu.

The assistant starts in plan mode. It writes nothing until you approve its plan with Run. It reads the catalog and aggregates, never the rows. Its file tools are refused on .env, and its skill tells it never to read that file or print the environment.

To run the same work in your own Claude Code or Codex instead of the chat, use Copy prompt. The prompt names the dms-external-database and dms-page-design skills, which ship with dms-ai. AI and Claude Code shows how to set up your agent.

What lands in your repository

For a connection named erp:

antelope.config.ts gets the builder-db-erp driver module and the builder-db-erp-tables module, and pins the DMS to the project's own database when it is not pinned yet.
.env gets BUILDER_DB_ERP_URL. Git ignores .env.
modules/builder-db-erp-tables/ holds the generated TypeScript: a table class and a controller for each mapped table, and a page for each table that has one. Its package.json records the connection and the tables you left out.

These are ordinary DMS files. Review them, commit them, and edit them in your editor or with the Builder like any other page.

Pitfalls

.env must be ignored by git. In a repository, Connect writes the URL only when git ignores .env. Add it to .gitignore first, or Connect refuses to write it.
The connection exists after a restart. If the project does not come back within 3 minutes, stop the process that runs it and start it again.
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.
Pages start read-only. A mapped table gets list, detail and export routes only. Switch on Rows can be edited for a table to add create, edit and delete, and give the DMS an account that can write to it. The workspace shows what the current account can do beside the switch.
The tables module belongs to the database. In it, the Builder refuses to create a table, add a field or change a column's database field. Deleting a table there removes its files and keeps its rows.
Large databases are read by schema. With more than 200 tables left to profile, the analysis reads none and asks which schemas to analyse.
Document databases declare less. MongoDB and RethinkDB declare no field types and no references. The Builder reads types from a sample and finds references from the values. A field whose sampled values mix types, with none covering enough of them, is left out and gets a question. An embedded document is mapped as one field.
Some types lose precision. A bigint beyond 2^53 or a numeric read as a number is not exact, so declare it as a string. A timestamp without time zone is read as UTC. The workspace flags these columns.
The hammer button is missing. The Builder runs in development. Read the Builder FAQ before you turn it on in a production process.

Remove a connection

Remove in the Database workspace takes the connection out of the project: its tables module and its folder, and the driver module with its variables when it was added for this connection alone. The database itself is untouched.

Next steps

External databases documents ConfigureProject, AnalyseDatabase and MapResources, and every rule behind a proposal.
Builder tables covers the tables the mapping writes.
Security describes what the assistant may read and do on a connected database.