https://github.com/emmanuelrosa/quickdb
Run rootless and portable way to run databases for development and demos.
https://github.com/emmanuelrosa/quickdb
couchdb mariadb nix nix-flake postgresql
Last synced: about 2 months ago
JSON representation
Run rootless and portable way to run databases for development and demos.
- Host: GitHub
- URL: https://github.com/emmanuelrosa/quickdb
- Owner: emmanuelrosa
- License: mit
- Created: 2025-06-18T13:23:00.000Z (about 1 year ago)
- Default Branch: master
- Last Pushed: 2026-03-29T19:42:54.000Z (3 months ago)
- Last Synced: 2026-03-29T21:29:58.802Z (3 months ago)
- Topics: couchdb, mariadb, nix, nix-flake, postgresql
- Language: Nix
- Homepage:
- Size: 16.6 KB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# quickdb
`quickdb` is a suite of [Nix](https://nixos.org) packages to easily start development instances of PostgreSQL, MariaDB, CouchDB, or neo4j (Community Edition) on GNU Linux.
## Features
- __No root needed__ - You need the [Nix](https://nixos.org) package manager to use `quickdb`, but if you don't already have it you can use the portable version [Nix portable](https://github.com/DavHau/nix-portable).
- __No additional dependencies__ - You don't need anything other than the [Nix](https://nixos.org) package manager.
- __Configured for development__ - The database is automatically configured to only listen on localhost, and (except for couchdb and neo4j) you can just log right in without credentials.
- __Multi-instance__ - You can easily set up multiple instances of a given database; Just run the script with different directory paths and then edit the config files to use different ports.
- __Runs like a normal process__ - Stdout goes to the console, and a simple CTRL-C stops the database. No weird daemons to deal with.
- __Multiple database major versions available__ - Using Nixpkgs snapshots as needed, this repo provides easy access to PostgreSQL 17, 18..., MariaDB 11.4, 11.8...
## Demo
[](https://asciinema.org/a/tfH8n3ALPkGMPE5avwIqVqGfG)
Note: In the demo I used localhost when connecting with `psql`. It's also possible to use a socket directory, which is the `run` directory within the database directory. ex` psql -h $PWD/testdb/run DBNAME`. However, `psql` doesn't seem to like relative paths, hence the `$PWD`.
## Use cases
- __Development__ - I developed `quickdb` in order to quickly and easily set up a database when I need it without having to have the database running 24/7. You can start a database the moment you need it, and shut it down the moment you're done. No root. No `sudo`.
- __Staging/testing__ - When your done with the database, just delete the directory.
- __Database migration tests__ - Want to see what happens when upgrading PostgreSQL from 17 to 18? Just make a copy your database directory, and run it with the new version. No sudo needed.
## Packages
To get a list of the available packages, run `nix flake show github:emmanuelrosa/quickdb`
## Usage
Each package has three modes of operation:
1. __Initialization__ - When executed with a path to a non-existent directory, the directory is created and the database system is initialized within the directory. After initialization, the database system can be configured by editing one or more configuration files.
2. __Execution__ - When executed with a path to an existing directory, it is assumed a database has been initialized within the directory, so the database is started in the foreground. This means standard output is printed to the screen, and a simple CTRL-C is all that's needed to stop the database.
3. __Shell__ - When executed without any arguments, a BASH shell is started with the database client tools in the PATH.
## Examples
### PostgreSQL
1. To create a PostgreSQL database, execute: `nix run github:emmanuelrosa/quickdb#quickdb-postgresql-17 -- ~/my-postgresql`
2. To configure the database, edit the `*.conf` files in `~/my-postgresql`.
3. To run the database, execute the same command: `nix run github:emmanuelrosa/quickdb#quickdb-postgresql-17 -- ~/my-postgresql`
4. To access the postgresql client tools, using another terminal execute `nix run github:emmanuelrosa/quickdb#quickdb-postgresql-17`
5. To stop postgresql, press CTRL-C.
### MariaDB
1. To create a MariaDB database, execute: `nix run github:emmanuelrosa/quickdb#quickdb-mariadb-114 -- ~/my-mariadb`
2. To configure the database, edit `~/my-mariadb/etc/my.cnf`.
3. To run the database, execute the same command: `nix run github:emmanuelrosa/quickdb#quickdb-mariadb-114 -- ~/my-mariadb`
4. To access the mariadb client tools, using another terminal execute `nix run github:emmanuelrosa/quickdb#quickdb-mariadb-114`. Before using the mariadb client, set the envirionment variable `MYSQL_UNIX_PORT` to the path to the socket file; ex. `export MYSQL_UNIX_PORT=~/my-mariadb/run/mariadb.sock`
5. To stop mariadb, press CTRL-C.
### CouchDB
1. To create a CouchDB database, execute: `nix run github:emmanuelrosa/quickdb#quickdb-couchdb-3 -- ~/my-couchdb`
2. To configure the database, edit `~/my-couchdb/etc/local.ini` and `~/my-couchdb/etc/epmd.env`. The default user name is _admin_ and the password is _password_.
3. To run the database, execute the same command: `nix run github:emmanuelrosa/quickdb#quickdb-couchdb-3 -- ~/my-couchdb`
4. To use `curl` and `jq` with couchdb, from another terminal execute `nix run github:emmanuelrosa/quickdb#quickdb-couchdb-3`
5. To stop couchdb, press CTRL-C.
### Neo4J
1. To create a neo4j database, execute: `nix run github:emmanuelrosa/quickdb#quickdb-neo4j-2026 -- ~/my-neo4j`
2. To configure the database, edit `~/my-neo4j/neo4j.conf`. The default username and password is 'neo4j'.
3. To run the database, execute the same command: `nix run github:emmanuelrosa/quickdb#quickdb-neo4j-2026 -- ~/my-neo4j`
4. To stop neo4j, press CTRL-C.