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

Database connection

The routes behind the onboarding's Start from an existing database path, the key that mounts them, the DMS operations they call, and what they write into the project.

Start from an existing database in the assistant's onboarding popup connects a database you already run. The popup calls the module's routes under /api/builder/database. Each route but GET /database/reload calls one external-database operation of @antelopejs/dms through @antelopejs/interface-dms-builder. Those operations wire the database into antelope.config.ts, analyse its tables and map them into pages. External databases and Connect a database in the builder interface docs describe them. This page lists the routes, the key that mounts them and what they write.

Every route requires an authenticated tenant owner. The routes need a module that implements @antelopejs/interface-api, such as @antelopejs/api.

Configuration

The module reads one key for the routes, under builder in the config block of its entry in antelope.config.ts.

OptionTypeDefaultDescription
builder.api.enabledbooleanthe project's development modeMounts the /api/builder/database routes, or keeps them off.

@antelopejs/dms reads the builder's own settings under builder on its own entry. builder.projectRoot is the folder that holds antelope.config.ts and the sources a connection writes. builder.enabled turns the operations the routes call on or off. Configuration in the DMS docs lists both.

Note

The module does not read a factoring option. Remove it if an older configuration still holds one.

When the routes are on

The routes rewrite source files. When builder.api.enabled is unset, they follow the core's development flag (GetRuntimeInfo().dev). The DMS reads the same flag for dev reload. The module does not read NODE_ENV.

CommandRoutes
ajs project dev, ajs project dev -wOn
ajs project start, which starts the project from its buildOff. The process mounts no /api/builder/database routes, so they answer 404.

builder.api.enabled: true mounts the routes on a started build. builder.api.enabled: false keeps them off in development. When the routes are off, the module never imports their controller.

@antelopejs/dms serves the operations the routes call when builder.enabled on its own entry is true, or in development when that key is unset. To mount the routes on a started build, set both keys. With only builder.api.enabled, no module serves the operations.

Before a route calls its operation, it asks @antelopejs/dms for the project, once per process. When nothing answers within 10 s, the route answers 503 with { code: "unavailable", message }, and the message says to set builder.enabled to true on the dms entry. The next request asks again. Each unanswered request leaves its call waiting in @antelopejs/interface-core, which holds at most 1,000 such calls and rejects the next one at once. A route then answers the same 503 at once. Once @antelopejs/dms has answered, the routes stop asking.

A DMS that includes dms#896 serves the operations even with its builder off, and rejects each of them at once with a message that starts with The DMS builder is not enabled in this environment. A route then answers the same 503 at once, with that message, and the next request asks again. The 10 s wait remains only for a DMS that serves no builder operations at all.

Warning

With builder.api.enabled: true on a deployment, tenant owners can rewrite the deployed sources. Do not turn the routes on in a deployment only to make them answer.

GET /api/builder/database/connections answers the catalog connections of the project, [] before you connect one. A 404 means the routes are off in this process.

Routes

Every path below sits under /api/builder. No route answers rows of the external database.

MethodPathBody or queryCallsAnswer
GET/database/connectionsListDatabaseConnectionsEach catalog connection, with id and what its provider reports (engine, version, database, role) or an error
POST/database/connections/repair{ dryRun? }RepairDatabaseConnectionsAn OpResult of the configuration change, or an empty success when nothing is missing. See Repair a connection made before.
POST/database/connections/check{ engine, url }CheckDatabaseConnection{ reachable, latencyMs?, user?, canRead, canWrite, reason?, install? }. 403 outside development. 400 for an engine other than postgres, mysql, mongodb or rethinkdb, or a url that is not of that engine. See Check a connection before writing it.
POST/database/analyseAnalyseDatabaseInputAnalyseDatabaseIts OpResult
GET/database/analysis?id=GetAnalysisIts OpResult
GET/database/analysis?connection=GetLatestAnalysisIts OpResult. 404 with its not_found error when no analysis of the connection ran since the start.
POST/database/mapMapResourcesInputMapResourcesIts OpResult
GET/database/mapping?connection=&module=GetMappingIts OpResult
GET/database/projectGetDatabaseProject{ modules, self, ownDatabase?, databasePins, dmsDatabase?, interfaceDatabase?, drivers }. See What connecting a database writes.
POST/database/project{ steps, opts?, variables? }ConfigureProjectIts OpResult. With variables, @antelopejs/dms first writes their development values into .env.
GET/database/connection?connection=GetDatabaseConnection{ wiring, details? }. 404 for an unknown connection.
POST/database/connection/remove{ connection, dryRun? }RemoveDatabaseConnectionIts OpResult
POST/database/connection/url{ connection, url }SetDatabaseConnectionUrlIts OpResult, with the variable it set. A URL without a password keeps the current one.
GET/database/reload{ due }: true when the values of the project's .env changed since the running project loaded them. Under ajs project dev -w the core restarts the project on that change. While due is true, the popup counts the connection as not loaded yet, since the running project still serves the old URL.

GET /database/project and GET /database/connection answer the data of their operation. When the operation refuses with invalid_config, they answer 422 with { code: "refused", message }. The message joins the messages of the refusal's issues with ; . A 404 answers { code: "not_found", ref }. The other routes answer their operation's OpResult as it is, a refusal included.

POST /database/connections/check answers 403 with { code: "forbidden", message } and 400 with { code: "bad_request", message }. Each message is the one CheckDatabaseConnection gives.

Every route answers 503 with { code: "unavailable", message } when @antelopejs/dms serves no builder operations. When the routes are on says when that happens.

POST /database/map writes only code that compiles across the whole project. When it answers typecheck_failed, nothing is written, and the error lists each diagnostic with its file and line. A type error elsewhere in the project blocks the write too.

Only the owner supplies a database URL

The connection check opens whatever its URL names, a socket file, a loopback port or a private address included. That is right for a URL the project's owner chose. An agent steered by a prompt injection could use the same check to probe the machine, so the assistant does not let the agent choose the URL through a route, a tool or a configuration file.

  • Every route under /api/builder/database requires a signed-in tenant owner. From a query it reads only the id of an analysis, a connection or a module. POST /database/connections/check, POST /database/connection/url and POST /database/project take their URLs from the body of the owner's request alone.
  • POST /database/connections/check, POST /database/connection/url, POST /database/project and POST /ai/onboarding/claude-token answer only a request that carries the header x-dms-ui-assistant: 1, which the assistant's own client sends. Without it the answer is 403 with code: "forbidden", before the request reaches @antelopejs/dms or the sidecar. The owner's session alone is not enough. An HTML form, a link, an image, a dashboard block or a page the agent builds sends the session, but none of them can set a request header. The DMS form, action and confirm dialog helpers set only content-language, and no block option takes a header. A request from another origin is refused by the frontend server before it reaches the backend, and the backend does not read the dashboard's session cookie.
  • The URL in that body is the one the owner typed in the Connect a database form. The form opens empty, also from a ?assistant=connect link, and does not keep a URL across page loads.
  • Only src/builder/routes/database.ts calls the external-database operations of @antelopejs/interface-dms-builder. In oxlint.config.ts, no-restricted-imports refuses them, and any subpath of the package, in every other file of the module, the sidecar's included. typescript/no-require-imports refuses a require of them in TypeScript.
  • The sidecar holds only its own token, and no route above accepts it. The tools of the chat's dms-assistant MCP server and the one command the agent sends the dashboard, a page path to open, take no database URL, host, port or socket. The one URL they take is the same-origin path of an image that preview_blocks shows. A test lists them on both of the server's bindings. It also refuses a record whose keys the model names, except the options of a block that preview_blocks draws in its sandboxed frame.
  • The agent may not read or change .env, where the connection URLs live. Every edit of antelope.config.ts, an antelope.*.json file (a scoped module's antelope.@scope/name.json included) or a file under .antelope/ asks the owner first, in every mode, through a symbolic link too, and with no rule to keep. AntelopeJS core reads each module's configuration from those files, including the variable or literal that supplies each URL.

These rules cover the URL itself, not the code that runs with it. In Code mode, Accept edits applies an edit of other source files unasked, and Auto review lets its safety check approve one. That includes a local module, a file that antelope.config.ts imports, and a file under node_modules, such as the bridge the sidecar starts for the dms MCP server. The project or the sidecar runs that code, and the code can open any connection. To see every edit before it is written, use Ask first and keep no rule that allows edits. Safe mode and Plan only write no source file.

The database_* and builder_analyse_database tools of the dms MCP server of @antelopejs/dms name a database by its connection id. builder_configure_project can write a literal URL into a module's config, and only after the owner approves its diff.

What connecting a database writes

The Connect a database form plans one ConfigureProject batch from the answer of GET /database/project, and sends it to POST /database/project. The answer holds these fields:

  • self is the id antelope.config.ts gives @antelopejs/dms.
  • ownDatabase is the project's default interface-database provider.
  • databasePins lists the modules to pin to it.
  • dmsDatabase is the id of the dms-database entry.
  • interfaceDatabase is the version of @antelopejs/interface-database the project resolves.
  • drivers gives each engine's driver package, with a range of only its releases built for interfaceDatabase.

ownDatabase and dmsDatabase are absent when the project has no such database or module. An engine with no driver built for interfaceDatabase is absent from drivers. The form shows that engine turned off, with the reason, and keeps Connect and analyse off for a URL of that engine. On interfaceDatabase 0.4, that engine is MySQL and MariaDB.

GET /database/project refuses with 422 in these cases:

  • The configuration does not say plainly which database is the default.
  • A module that imports interface-database and does not provide it is not written as an object literal. A version string, an entry with a spread and an entry with a member under a computed name all count, because @antelopejs/dms cannot write their pin.
  • dms-database is written that way under its id or its package name.
  • A module is keyed by a computed name, a method or an accessor. It may be dms-database or a module that needs a pin.

An entry with a spread that already pins interface-database in an importOverrides written after its last spread or computed name counts as pinned, since a later key wins.

The batch writes these steps in order:

  1. AddModule for the engine's driver, at the package and range drivers gives, with its URL read from a variable.
  2. CreateLocalModule for the module that holds the tables, pinned to the driver.
  3. ConfigureModule on self, declaring the catalog connection under the connection's id.
  4. ConfigureModule on dms-database, when the project has it and an own database. The entry then reads, for a connection erp served by the driver builder-db-erp over a project whose own database is mongodb:
    ts
    const modules = {
      "dms-database": {
        importOverrides: [
          { interface: "@antelopejs/interface-database", source: "mongodb" },
          { interface: "@antelopejs/interface-database", source: "builder-db-erp", id: "erp" },
          { interface: "@antelopejs/interface-database-catalog", source: "builder-db-erp", id: "erp" },
        ],
        config: { externalConnections: { erp: { access: "read" } } },
      },
    };
    

    The first entry of interface-database without an id is the binding a plain import reaches, so the own database comes first. The connection keeps one id on both interfaces and in externalConnections. access is read, or read-write when the form chose it, and read when absent.
  5. One ConfigureModule for each module in databasePins. Once a second interface-database provider exists, core refuses to start a module that imports interface-database without a pin. Each configured module that imports it, does not provide it and has no pin without an id therefore gets one to the own database.

Every file lands under the builder.projectRoot of the @antelopejs/dms entry, in the project's own sources:

  • the driver module and the module that holds the tables, in antelope.config.ts,
  • the connection's URL variable, in .env,
  • the mapped tables as Table, DataController and model files, and their pages as PageController classes.

Commit these files like any other code, except .env.

Repair a connection made before

A project connected before these steps has the catalog connection and nothing dms-database reads. POST /database/connections/repair adds what is missing for every catalog connection declared on the entry of @antelopejs/dms. It writes the dms-database overrides and the databasePins of step 5, and never access, so a value set in the dms-database console stays. Send { "dryRun": true } to read the changes without writing them. It refuses as GET /database/project does.

The answer is an OpResult like ConfigureProject. A configuration that already holds everything answers { ok: true, data: { files: [] }, changes: [] } and is not written, so a second call changes nothing.

Check a connection before writing it

POST /database/connections/check tests a database before anything is written to antelope.config.ts or .env. The driver module is not configured at that point, so @antelopejs/dms runs the probe that the engine's driver package exports, in a child process. It requires the driver only when its engine is checked, first from the DMS and then from the project. When neither installs the driver, the answer is reachable: false with a reason such as Install @antelopejs/postgres to connect a PostgreSQL database.

A project therefore needs, in its own dependencies, the driver package of each engine it connects:

EngineDriver package
PostgreSQL@antelopejs/postgres
MySQL and MariaDB@antelopejs/mysql
MongoDB@antelopejs/mongodb
RethinkDB@antelopejs/rethinkdb

When the check answers that sentence, the route adds install, { package, command }. command adds the driver with the project's package manager: the one packageManager names in the project's package.json, else the one whose lockfile the project holds, else npm. It uses the range GET /database/project gives the engine in drivers, as in pnpm add --save-prefix=~ "@antelopejs/postgres@<range>". With pnpm and npm, --save-prefix=~ saves the range with ~, which stays below the next minor. The onboarding shows the command with a copy button and asks to run it in the project folder, then to select Connect and analyse again. The check loads the driver afresh each time, so the next check finds it without a restart.

The repository's playground declares all four drivers.

The answer reads as follows:

  • reachable is true when a server answered, even to refuse the sign-in. latencyMs is the round trip of the first query of the signed-in account, and user is the account the server reports.
  • canWrite is true when the account may insert, update or delete in any relation it can see, as the catalog of the engine's driver decides. canRead is true when it may read any of them, or when it sees none. A MongoDB server without access control gives full privileges, whatever the database holds.
  • reason is a short sentence for the person who connects, present when the database is unreachable, refuses the sign-in or cannot be read. It never holds the URL, the password or a query a driver echoes in its message.

mysql checks MySQL and MariaDB alike, with mysql:// URLs. A MySQL, MariaDB or RethinkDB URL with no database after the port is answered once the account has signed in, with reachable: true, user, no access and a reason saying the URL names no database.

The check ends within three times the connect timeout of five seconds. It closes every connection it opened, both when the database answers and when the deadline passes first. It never waits for a server to close its end before it answers, and it shuts a socket still open a quarter of a second after its goodbye. For RethinkDB, it deletes a key no row has to learn whether the account may write, so it changes no row.

Languages

The texts of the database connect flow ship in frontend-vue/i18n/locales/builder-en-GB.json and builder-fr-FR.json, under the dms_builder namespace. The DMS frontend loader merges them into the app's catalog like the texts of any module. English is the fallback locale, so a language the module does not ship reads in English. An app can override any text by declaring the same key in its own locale files.