Running Quino applications with a local database

  Subscribe
11/28/2012 - Marco (updated on 11/13/2017)

The instructions below explain how to set up a Quino application to use a local database driver in Quino 1.8.5 and higher.

The implementation in this version uses a Mongo database as a backing store, so there a few limitations of which you should be aware:

  • Mongo has no native support for foreign-key constraints. Quino enforces some of these constraints without relying on the database (especially when using the Winform UI components) but there is no guarantee that foreign-key constraints will be enforced locally.
  • Mongo also has no native support for transactions. An application that relies on transactions in its business logic will execute, but will not roll back in case of error.
  • Mongo does not publish a schema, as such, and Quino provides neither schema-checking and nor schema-migration for Mongo databases. If the schema changes, data will continue to load and store, but default values for new properties are not added to existing data, as with databases that support schema-migration.

The Mongo driver sounds quite limited compared to a full-fledged driver like that for PostgreSql or SQL Server. So why would you want to use it? There are situations where non-ACID, schema-less persistence is acceptable. In these cases, the lack of support for the features listed above is not a deal-breaker.1

The following situations lend themselves to using a local database:

  • Quick prototyping: you can give your customer a prototype that works with a model you created without setting up a database server.2 This can be especially useful when a rapid prototyping session with a customer has yielded a result that he or she would like to share with other stakeholders before moving on to the next iteration.
  • Downloadable demos: you can provide access to demos of your applications that only work with local data so that users can very quickly get a feel for how the application works.
  • Development: developers are also very interested in data persistence (so you don't have to constantly re-generate or enter data) but may not want to run a local PostgreSql or SQL Server on their machines.3 The developer is presumably aware that a refresh of the data after large model changes might be required.

If you're convinced, you can try it out in your own application by following the instructions below.

  1. Call configuration.IntegrateLocalDatabase() (an extension method defined in Encodo.Quino.App.MetaConfigurationTools). This simply includes code in the application startup that will start and run a local Mongo database if it detects that the configuration requires it. That's all the .NET code you have to write; the rest is configuration.
  2. Add an entry to your configuration file for the Mongo database driver:
<Mongo>
  <Title>Mongo</Title>
  <typename>Encodo.Quino.Data.Mongo.MongoMetaDatabase, Quino.Data.Mongo</typename>
  <Resource>MyAppDatabaseName</Resource>
</Mongo>

You can change the resource name to something that makes sense for your application. It doesn't really matter because, by default, the database is stored in the user's AppData/Local/... folder and they never see the name anyway4.Again in the configuration file, set the default connection settings to "Mongo":

<?xml version="1.0" encoding="utf-8" ?>
<config>
  <servers>
    <default>Mongo</default>
    <!-- other connection settings -->
    <Mongo>
      <Title>Mongo</Title>
      <typename>Encodo.Quino.Data.Mongo.MongoMetaDatabase, Quino.Data.Mongo</typename>
      <Resource>MyAppDatabaseName</Resource>
    </Mongo>
  </servers>
</config>

Let your application know where to find the Mongo executable. You can either copy the Mongo database daemon to Mongo\mongod.exe next to your application executable or you can specify a location from the configuration file, as shown below.

<mongo>
  <executable>C:\Tools\MongoDB\bin\mongod.exe</executable>
</mongo>

Optional: choose a location to store the local database. By default, the database is stored in a "Data" subfolder of the user's local data for the application. You can specify an alternate location from the configuration file5, as shown below.

<mongo>
  <executable>C:\Tools\MongoDB\bin\mongod.exe</executable>
  <databasepath>U:\Bob\Prototype23\Data</databasepath>
</mongo>

Now you can start your application and store data locally using Mongo.

Happy modeling!



  1. Mongo is also quite fast -- partly due to the fact that it doesn't support transactions and doesn't need to check foreign keys. Just to be clear, we understand that, for many large-data situations, a fast, non-ACID driver is exactly what you want. That's kind of why Quino supports Mongo out-of-the-box.

  2. Since Quino also supports remoting out of the box, you could also run a server either on your own infrastructure or in the cloud (Azure) but that involves a lot more work. It's also not guaranteed because the customer may not have access to the server from their internal network.

  3. This is becoming more and more common as some developers use super-lightweight netbooks without a lot of memory. Naturally, we recommend that developers work with the primary target database as much as possible.

  4. Unless it's shown in the title bar of the main window in debug mode or in the about window

  5. Be aware that, since each running instance of the application has its own Mongo database daemon, it is not possible for multiple users to access data in the same directory. You still need a server for that.

Sign up for our Newsletter