Skip to content

Test in a dev Space

Unfinished work in Ronja uses real data. A draft workflow’s test run and a draft app’s preview use the databases their logins name. In your real Space, those are the live databases, so a test that writes changes live rows.

To try something risky without touching live data, build it in a dev Space: a separate Space in your organization, for example one called “Dev”, with its own feature, its own database and its own logins. Test there. When it works, build the finished work in your real Space.

A Space keeps more than the database apart. The workflows, apps and automations you build there belong to the dev Space too, and only the people included in it see them.

An Admin does this once.

  1. Open Admin → Spaces.
  2. Click New Space.
  3. Enter a Name, such as “Dev”, and click Create Space.
  4. On the new Space’s page, tick the people who will test in it, in the People section. A new Space starts with only admins in it.

See Spaces for the rest of what a Space can do.

  1. Switch to the dev Space: click Switch to this Space on its row on the Spaces page, or pick it from Spaces in your account menu.
  2. Start a chat in Build mode and describe what you want to build. Ronja builds it in the dev Space. Give the dev feature its own name, such as “Sales (dev)”: feature names are unique across the whole organization.
  3. If the work needs a managed database, an Admin creates one while in the dev Space. Use New database on the Databases page, or ask Ronja in a chat started in the dev Space. The database belongs to the dev Space, and Ronja uses it for work in that Space.
  4. Test the work there: run the draft workflow, open the app preview, let the automation fire.

From the command line, the CLI’s own sign-in can make the dev Space’s feature and database: send the Space’s ID in the X-Ronja-Space header, for example ronja api -X POST /api/v2/feature -H "X-Ronja-Space: <the dev Space's ID>" -d '{"name":"Sales (dev)","scope":"private"}', and the same for POST /api/v2/database as an Admin. An Admin can create the Space itself with ronja api -X POST /api/v2/space -d '{"name":"Dev"}'. Including people in the dev Space takes the Space’s page, in the browser. See Acting in a Space.

A database in a dev Space counts toward your organization’s limit of 10 managed databases, like any other.

When the work does what you want, build it again in your real Space.

  1. Switch back to your real Space.
  2. Start a chat in Build mode and ask Ronja to build the same thing, using the real Space’s database and tables. Tell her what you changed in the dev Space and what worked.
  3. Review and publish it as you would any other work.

If you keep the code in your own editor, one folder deploys to both Spaces with the CLI. Each Space is a stack of the folder, such as dev and main, and each command names the one it deploys with --stack.

  1. In the dev Space, create the dev Space’s own version of every secret and database the code uses. The CLI can only offer the dev Space’s rows once they exist. Give each secret the same name in both Spaces, so the CLI finds both.

  2. A folder made for your real Space with no stack name, by init or clone without --stack, is deployed once with --stack main first (ronja wf push --stack main, or its kind’s push), so the deployment it already has gets a name. Then, at the top of the repository, run ronja sync stack add --feature <the dev feature's ID>. It adds a stack named after the dev Space, such as dev, to every folder at once, records which Space it is for, and creates nothing in Ronja. It fills in only rows that belong to the dev Space: a table the code reads when exactly one of that name is in the Space, and a table it writes, or a workflow or Saved Agent it runs, when exactly one is in the dev feature. It lists everything else, folder by folder. To read a table of your real Space live, set its ID under stacks.dev.bind in that folder’s ronja.json.

    Under the same confirmation, it turns every ID written into the code, such as {{ ref('table-…') }}, into a name the folder declares, kept pointing at the same row for the stacks the folder already has. They keep reading and writing the same rows, and the dev stack gets its own. Another dev stack the folder already has keeps only what its Space allows: a table it would write, or a workflow it would run, in another Space is left for you to set, and listed. A table the code replaces by its ID becomes {{ write('<name>') }}: the stacks the folder already has still write that table, but their code changes in that one argument, so their next deploy is a new version. Commit the change and deploy those stacks after it, so an older checkout does not deploy the ID back. For a single folder, run ronja sync stack add --feature <the dev feature's ID> inside it. ronja bind --feature declares the dev stack and fills in its rows the same way, but leaves IDs written into the code as they are.

  3. Copy the production tables the code reads into the dev feature, from the folder that reads them: ronja copy erp_orders erp_items --to-stack dev. Each copy is a table in the dev feature holding the production rows as they are now, and the folder’s dev stack now uses it. For a table the code writes, copy only its columns: ronja copy board_notes --no-rows --to-stack dev. Run the same command again later to refresh a copy with today’s rows: it keeps the same table. sync stack add prints the ronja copy line for each table it could not fill.

  4. Run ronja sync apply --stack dev --allow-create, then test, for example with ronja wf test --stack dev or ronja app test --stack dev in a folder. The first deploy creates every row in the dev Space, and sync apply creates nothing without --allow-create. Later deploys to the dev Space don’t need the flag. A deploy stops with name_taken when the dev feature already has a row of the same kind and name: see Deploy to a second stack.

  5. When it works, run ronja sync apply --stack main from the same folder. Each stack keeps its own record of what it last deployed. If the dev work added something new, such as a new workflow or a new table file, add --allow-create the first time.

A copy is made in one request: a table over 1 GB is refused, and a copy that takes longer than about 80 seconds stops with copy_timeout. Running it again is safe. For a large table, build a smaller table from it with only the rows and columns you need, and copy that. When the dev feature already has a table of the same name that is not a copy of this table, the copy is refused with name_taken: give it another name with --name. A copy keeps the production table’s personal-data labels, and refreshing it brings over any label changed since, except one you set on the copy itself, so the dev feature shows which columns hold personal data.

A new folder made with ronja wf init --feature <the dev feature's ID> (or ronja app init, ronja module init, ronja pipeline init, ronja automation init, or a clone of a dev Space row) gets its dev stack the same way. A folder for your real Space’s feature records no Space, so a teammate on an older ronja can keep working on it. A folder with a dev stack needs a current ronja: an older one asks for an update.

The dev stack never writes or runs anything in your real Space. Every deploy and test of the dev stack refuses, before it changes anything:

  • bind_space_mismatch: a table the code writes, a workflow or Saved Agent it runs, or a secret it uses, in another Space, and the folder’s own workflow, App, module or table when the dev stack names one in another Space;
  • space_mismatch: a stack whose feature is not in the Space it was declared for;
  • address_space_mismatch: a table named by the folder that builds it, when that folder’s row is in another Space, even to read it. To read a table of your real Space, set its ID in the dev stack’s bind instead.
  • bind_space_mismatch: a file the code saves. A run saves files in your organization’s default Space, whatever Space its feature is in, so a dev stack does not save files: write a table in the dev feature instead.

The CLI checks only the dev stack this way. Your real Space’s stack is deployed as before, and Ronja’s own checks still apply to it.

Every request the CLI makes for the dev stack names the dev Space, and Ronja’s answer confirms it acted there. When Ronja refuses, the CLI stops and sends nothing further for the dev stack, with:

  • space_unavailable: you can’t enter the dev Space, or it no longer exists. An Admin includes you on the Space’s page.
  • space_not_selectable: you’re signed in with an API token from the API Tokens page (one not marked Personal token), which can’t choose a Space. Sign in with ronja login, or use a personal access token.

In ronja sync check and ronja sync apply, the folder that met the refusal reports it, each later folder on the dev stack reports not attempted under the same reason, naming that folder, and the run exits with code 2.

Take an app built in the dev Space to your real Space

Section titled “Take an app built in the dev Space to your real Space”

An app someone built in the dev Space, in a chat or from the CLI, goes to your real Space in three commands. An Admin runs them, so the tables the app builds come along as files.

  1. ronja import feature --only <the app's ID> --stack dev ./region-board writes the app and everything it needs from the dev feature into a new folder: its workflows, the tables it builds from and their inputs, the workflows that fill the tables it reads, the modules the workflows use, and the automations that run them. Anything else it uses becomes a name the folder declares, such as a secret or a production table, and the import marks each table that is a copy with the table it was copied from. If a folder already keeps the app, such as one ronja app init made in the dev feature, the import stops and names that folder: run step 2 in that folder instead.
  2. In that folder, run ronja sync stack add main --feature <the real feature's ID>. It fills in each name with the row of your real Space that has it, and a copied table with the production table it was copied from. It prints a ronja copy <name> --no-rows --to-stack main line for each table the app writes that your real Space does not have yet: run those.
  3. Run ronja sync apply --stack main --allow-create. It creates the rows in your real Space and stops with name_taken if your real feature already has an app, workflow, module or automation of the same name.

The dev Space’s automations keep running after this, and so do the new ones in your real Space. The import lists each automation that will fire in both places: switch the dev one off if it should stop.

When you deploy with --stack and the stack belongs to an organization you are signed in to under another profile, the CLI asks before it deploys with that profile, and without a terminal it stops and names the --profile to pass. status and sync check switch profile and say so.

For a database’s schema, push your migrations to the dev Space’s database first, then to the real one: ronja db migrate push --stack dev --database <the dev database's ID>, then ronja db migrate push --stack main --database <the real database's ID>. Each stack remembers its database, so later pushes need only --stack. A push with --stack dev stops with bind_space_mismatch when the database is not in the Space the repository’s dev stack is for, before any migration runs. Run it inside the git repository that holds your folders: with --stack, a migrations folder outside one is refused, because the CLI cannot read which Space the stack is for. --database <the database's ID> without --stack runs with no Space check. A data change made with ronja db sql is not part of the migrations, so run it on the dev Space’s database and on the real one separately.

See Work on Ronja from your editor for folders and stacks.