Database development tutorial

Hi all

I am newbie in Nextcloud development and it has been years since I have developed using PHP. I have read the Nextcloud development manual but one thing that I don’t understand is that how can I extend the Nextcloud database with my own app ?

Do I need to do some kind of migration or can I just use entity classes? I would appreciate a tutorial for dummies. If I want to create a app with controllers that are storing data to database, how would I get started?

Thank you

I just want to mention that we are aware we need to create a tutorial that covers this topic and creating such a tutorial is on our roadmap for the developer programme. Unfortunately I’m not aware of a good tutorial ready available for you and I hope some people on this forum will be able to answer your questions.

Maybe to give you some starting point:
the database handling is covered in the old/deprecated tutorial which is still available in our developer documentation: Tutorial — Nextcloud latest Developer Manual latest documentation
I’m not sure if this is still the recommended way to do things but maybe it can serve as a starting point. Maybe you could also have a look at existing apps that look a bit like what you want to design as a starting point

Edit, you might also be interested in first learning in general about Nextcloud app development. You can find all the tutorials we do have available on Develop for Nextcloud


See this section of the developer manual: Storage and database — Nextcloud latest Developer Manual latest documentation

It is fine to create your own tables when needed. Use migrations to do that. But first look at e.g. IConfig and the rest of the API documentation there to see if you can make use of existing features, e.g. if you just want to store some configuration or values for your app or for individual users.

Of course finding an app that does something similar to what you want to do, and digging into its source code, is highly useful.


Follow Migrations — Nextcloud latest Developer Manual latest documentation.

Then use entity and mappers as described at Database access — Nextcloud latest Developer Manual latest documentation.


The query builder seems undocumented so I’ve raised Query builder docs · Issue #10009 · nextcloud/documentation · GitHub


So if I understand correct, I create migrations first to create the tables and then entities to represent those? Then I use Query Builder to populate those entities with specific queries? Is this some Nextcloud specific “kinda” ORM? This seems quite straight forward but I was wondering is there a example on how I can create a controller that accepts JSON payload deserializes it to entity and then persists that ? And the same for update?

These kind of tutorials and instructions would be great. :smiley: And for now if there is a example of this it would be greatly appreciated.

This is a wonderful project and it got me to relearn PHP for this. :laughing: It was more than 10 years when I last touched it. Even if I more prefer Node.js or C#, PHP has developed a lot and it is intriguing to “relearn” it. :slightly_smiling_face:


Also, I would appreciate tips on how to debug my code when running the Nextcloud development environment in the Docker? I have mapped the apps folder to my host, but if would like debug my code and set breakpoints in the custom controllers etc. How could I do it easily ? :smiley:

Thank you

hello there, I just wanted you to know we added a tutorial on the database topic!