A Complete Example
IObjectContainer db =
// Store a few Person objects
// Retrieve the Person
var results = db.Query<Person>(x => x.Name == "Petra");
Person p = result.First();
// Update the Person
p.Name = "Peter";
// Delete the person
// Don't forget to commit!
// Close the db cleanly
Create or Open a Database File
IObjectContainer container = Db4oFactory.OpenFile([filename]);
While a db4o database file is open, it is locked and cannot be accessed by another application at the same time.
It's important to know that db4o works best if you open the database file when you start working with data, and close the db when all posible operations are completed.
In traditional relational databases, it's common to open a connection, get/update data, close connection, and then perform your operation. Because db4o uses the native object (or referential) identity, it's better to open the database or connection when your application begins, do all your work, then close the database when your program is shutting down. You'll see why when we get to updating an object with our changes.
Starting a db4o Server
By default, the db4o server runs in-process within your application. To start a db4o server, place this code into your application:
IObjectServer server =
To shut down the server:
The port parameter specifies the network port number. Acceptable values are any number above 1024 which are not already in use.
Using Port 0 for your server creates an "Embedded" server which will not be available remotely. This is useful for multi-threaded operations or web-server style environments where you wish to handle parallel operations in a single process.
The GrantAccess() method must be called for each username/ password combination. It is not required at all for embedded servers.
Connecting to a db4o Server
After starting a db4o server instance, use either of the commands below to open a db4o client connection:
// In-Process mode (embedded server)
IObjectContainer client = server.OpenClient();
// Client/Server mode (remote server)
IObjectContainer client =
Db4oFactory.OpenClient([serverAddress], [port], [user],
To close the client connection to the server:
Storing an Object
Just one line of code is all it takes. All of an object's properties and child objects will be stored.
Updating an Object
Looks familiar? You can use the same Store(object) command to update an object. One difference, however, is that db4o will (for performance reasons) not automatically check child objects for changes.
By default, db4o will NOT descend into child objects. Store() must be called for each modified object unless you change the default UpdateDepth (see the UpdateDepth parameter in the Configuration section, below) or configure cascading update for the persisted class.
There is one more thing to be aware of: db4o uses an object's native identity (referential identity) to identify an object and map it to the stored instance of the object. This means that there is only ever 1 instance of an object in memory for each stored instance of the object. (per ObjectContainer or connection) This is important when dealing with class instances that may come from ASP.NET ViewState, Web Services, Interop, or any other serialized source of object data.
Avoid Confusion: Always make sure that the object you are trying to update or delete was previously stored or retrieved in the database. Calling Store() with 2 User objects both with an ID of "jack" will result in 2 separate instances. However, if you retrieve the user, and modify the first instance, then store it again, you will have only 1 updated instance in the database.
Deleting an Object
You didn't think it was any harder than that, did you? Like updates, db4o will not automatically delete child objects unless you configure cascading deletes for your object will remain in memory until the objects are refreshed or garbage collected.
Whenever you start making changes to your database (using the Store() and Delete() commands) you are automatically in an open transaction. To close the transaction, use the Commit() method:
Your changes will be permanently saved. If you wish to cancel or roll back any uncommitted changes, use the Rollback() method:
Useful for beginners: Rollback only undoes uncommitted changes in the database. It will not undo changes to any currently loaded objects. So, when you call Rollback() you will not see any difference to your objects. If concerned about consistency, use the Refresh(object) command to cause the objects to be refreshed with stored database values.
Closing a database cleanly will automatically call Commit() for you, so any uncommitted transactions are committed automatically.
If the database is not closed cleanly, or if the application crashes at any time and uncommitted (or incomplete) transactions are discarded.