What Is a .dbs File? The DbSchema Design Model Explained

A .dbs file is the project file DbSchema writes to save a database design. It stores the tables, columns, indexes, foreign keys, virtual keys and one or more diagram layouts as plain XML, in a single file that does not need a database server. DbSchema opens it visually; any text editor opens it as XML.

What a .dbs file stores

The file holds a complete model, not a picture of one. Everything DbSchema needs to redraw the schema, generate SQL for it and compare it against a server is inside: the schema itself, the comments on it, and the layout of every diagram drawn over it.

• Schema objects: tables, columns and their types, defaults, indexes, primary keys, unique constraints, views, sequences, user-defined types, functions and triggers.
• Relations: each foreign key, the columns it pairs, and its delete action.
• Virtual keys: relations and columns that exist in the model only, for schemas where the database itself declares none.
• Diagram layouts: which tables appear on which diagram, at what coordinates, in what colour, plus the groups and callouts drawn around them.

The format is XML, the same text-based tag format used for configuration files everywhere. That choice is what makes the rest of this article possible: a .dbs file diffs, merges and greps like source code, because it is text.

Inside the file: an annotated .dbs excerpt

Below is a trimmed excerpt from a real .dbs file written against a PostgreSQL schema. Four things are worth locating, because they are where readers usually guess wrong.

<?xml version="1.0" encoding="UTF-8" ?>
<project name="PostgreSQL" database="PostgreSQL" id="f0050dec-40c1-42c6-9c6b-ed3780a00cb2">

  <!-- THE MODEL. One <schema> element holds every table, index and relation. -->
  <schema name="public" catalogname="dbschema_demo">

    <!-- A TABLE: columns first, then indexes, then the relations it owns. -->
    <table name="activity_log" row_count="0" spec="">
      <comment><![CDATA[Append-only audit trail.]]></comment>

      <column name="id" type="bigint" mandatory="y">
        <defo><![CDATA[nextval('activity_log_id_seq'::regclass)]]></defo>
      </column>
      <column name="team_id" type="integer" mandatory="y"/>

      <!-- VIRTUAL COLUMNS: fields DbSchema inferred inside a jsonb value.
           virtual="y" means the model knows them, the database never declared them. -->
      <column name="payload" type="jsonb">
        <column name="task_id" type="_number" virtual="y"/>
        <column name="sprint"  type="_string" virtual="y"/>
      </column>

      <!-- The primary key is an index, not an attribute on the column. -->
      <index name="activity_log_pkey" unique="PRIMARY_KEY">
        <column name="id"/>
      </index>

      <!-- RELATIONS live inside the table that owns the foreign key,
           not in a separate section of the file. -->
      <fk name="activity_log_team_id_fkey" to_schema="dbschema_demo.public"
          to_table="teams" delete_action="cascade">
        <fk_column name="team_id" pk="id"/>
      </fk>
    </table>
  </schema>

  <!-- DIAGRAM LAYOUTS, kept apart from the model: which boxes appear,
       where they sit, what colour they are. Deleting this branch would
       lose the drawing and leave the schema intact. -->
  <diagram_group name="Default" id="56354d1f-02a9-453d-ada1-b57e264ecb0e">
    <diagram name="Main Diagram" show_relation="columns">
      <entity schema="dbschema_demo.public" name="teams"
              color="C7F4BE" x="798" y="988"/>
      <group name="teams" color="EEF7EC">
        <entity schema="dbschema_demo.public" name="team_members"/>
      </group>
    </diagram>
  </diagram_group>
</project>

• Tables sit under <schema>, and each table carries its own columns, indexes and relations. There is no separate columns section to cross-reference.
• Relations are <fk> elements inside the table that owns the foreign key, with one <fk_column> per column pair. To find what points at a table, search for its name in to_table.
• Primary keys are indexes. Look for <index unique="PRIMARY_KEY">, not for an attribute on the column.
• Diagram layouts live in their own <diagram_group> branch at the end of the file, holding one <entity> per box with x and y coordinates. Model and drawing are stored separately, which is why moving a box never changes the schema.

Virtual keys in the file

Virtual means present in the model, absent from the database. Columns DbSchema infers inside a JSON value are written as nested <column> elements carrying virtual="y", as the excerpt shows for the payload field. Virtual foreign keys work the same way: you create one by dragging one column onto another in the diagram, it is saved to the model file, and the Relational Data Editor treats it exactly like a real foreign key. The database is never asked to enforce it, and no SQL is generated for it.

Reading a .dbs diff in a pull request

Because the file is XML, a schema change arrives in review as a readable diff. You can approve or reject a migration without opening DbSchema. Read the diff in this order.

1. Check for added or removed <table> blocks first. A whole table appears or disappears as one contiguous block, which is the largest change the file can carry.
2. Read changed <column> lines next. A widened field shows as a changed length attribute; a nullable column becoming required shows as mandatory="y" appearing.
3. Then look at <fk> elements. A new relation, or a changed delete_action, is a behaviour change at the database level and deserves the closest reading in the diff.
4. Treat changes under <diagram_group> as cosmetic. Moved boxes only change x and y coordinates and colours, so a diff that touches nothing else is a layout tidy-up, not a schema change.
5. Watch for renames. XML has no rename operation, so a renamed table reads as one block deleted and another added, and only the surrounding context tells you which it was.

Why the model is independent of the database

DbSchema Database Designer

The file records the design, not a connection. It names its target engine in the project element, but nothing in it requires a server to be reachable, so you can open, edit and review a .dbs file with no database running at all. The same model can be deployed to any of the engines DbSchema supports.

Saving the model to a file is a DbSchema Pro feature. The free Community Edition connects to a database, reverse-engineers it and draws interactive diagrams, but it does not write the project to disk.

Multiple diagrams in one project file

One .dbs file can carry several diagrams over the same schema. Build one view for orders, another for billing, another for the whole thing, and every view stays in step with the model because they all read the same tables. In the file, each is a separate <diagram> element inside the layout branch.

Keeping .dbs files in Git

Commit the .dbs file alongside the code that depends on it and the schema gets the same history, branches and review as everything else. DbSchema also has a native Git integration. For the full workflow, including how DbSchema compares against tools that version scripts instead of models, see the guide to database design tools with Git.

Comparing the model against a live database

Point the saved model at a server and DbSchema lists the differences in both directions, then writes the migration SQL for the direction you choose. The full procedure is covered in the offline design and schema synchronization guide.

Generating documentation from the model

Because the file already holds the constraints and the comments, it is what DbSchema reads to produce interactive HTML5, PDF or Markdown documentation. See the walkthrough on generating database documentation for the output formats and options. The HTML5 output is interactive and opens in any browser.

Key takeaways

• A .dbs file is DbSchema's design model: one XML file holding the schema and every diagram drawn over it.
• Tables carry their own columns, indexes and foreign keys. Primary keys are indexes, not column attributes.
• Diagram layouts sit in a separate branch, so moving a box on the diagram never touches the schema.
• Virtual columns and virtual foreign keys are stored in the model and never sent to the database.
• The file is text, so it diffs and reviews in a pull request like source code.
• Saving the model to a file is a Pro feature; Community connects, reverse-engineers and draws diagrams.

Download DbSchema to open a .dbs model and inspect the XML yourself. Reverse-engineering a database and drawing diagrams work in the free Community Edition; saving the project to a .dbs file is part of Pro.