Running Quino applications with a local database

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.¹

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.² 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.³ 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 anyway⁴.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 file⁵, 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!