The default Waterline adapter

Summary

Sails.js simplifies full-stack JavaScript application development by including a default database adapter, Sails Disk, which is perfect for prototyping and testing. Sails Disk uses neDB, a JavaScript database, to persist data locally on your hard disk. It is ideal for development and testing but not recommended for production due to its temporary nature.

By default, when you create a new Sails application, Sails Disk is already configured as the datastore in config/datastores.js. You can immediately interact with your models without worrying about setting up external databases, allowing you to focus on business logic during the early stages of your application.

Here's a quick overview of how to work with Sails Disk:

1. Enable schema validation in config/models.js for stricter control over data.

2. Generate a model (e.g., User) with the sails generate model user command.

3. Interact with your model using Waterline queries, such as User.create() or User.find().

4. Data created with Sails Disk is stored in the .tmp/localDiskDb folder in your project.

This setup allows for a smooth development workflow. Sails Disk's zero-configuration nature enables rapid prototyping without needing to decide on a production database upfront. It’s a development-friendly solution that ensures you can test your application effectively, even in CI/CD pipelines like GitHub Actions, without setting up external databases.

Transcript

So, because Sails wants you to develop full-stack JavaScript applications with a minimum learning curve and configurations you need to do as far as databases go and working with data, Sails comes bundled up with a default adapter for Waterline called Sails Disk. What this is, is an in-memory local adapter, which will write to your hard disk.

So it will write to your computer, your local computer. So this makes developing data-driven applications pretty easy so that when you install a new Sails application, you can forget about configuring an adapter. You just go straight to running sails lift, and you can start interacting with models to create and prototype.

So if you're still thinking about, "Do I need to use MongoDB or PostgreSQL?" before you make all those decisions, Sails says there's no need to worry about that in the early stage of your application. Just focus on your business logic. And we've given you this development-friendly, zero-configuration-needed adapter called Sails Disk.

Under the hood, this adapter uses something called NeDB, which is the JavaScript database. So that's what it boasts itself as. This is the JavaScript database. So it writes and persists to your hard disk, or you could say it could be in memory. This means when Sails lifts, the database is available, but when you shut down Sails, all that data is wiped from memory, which is pretty convenient.

I really like Sails Disk a lot in my setup when I'm developing with Sails. Because of how flexible Sails Disk is, I'm mostly in development mode. I'm mostly using Sails Disk, even in test mode. That means I can run my tests in something like GitHub Actions without worrying about configuring PostgreSQL, MySQL, or whatever production DB I want to use for my application.

I can do all that later and just focus on developing or testing my app. Like I said, the adapter comes bundled in with Sails. So I’ve made a new project, a Sails project for this course, called getting-started-with-waterline, proactively named as the title of the course. If we open this up in Visual Studio Code.

If you go to config/datastores.js, this is where you configure the datastore you want to use. One thing about Sails is how brilliant it is with these comments. It’s like a mini documentation. You can just see what each token or concept is, what they are tackling, how it's implemented, and the reasoning behind it, which is super helpful.

So, as I said, Waterline allows you to have multiple databases in one application. There is a concept called a datastore. Whatever the database is—key-value store, document, or relational—they are all called datastores, and you can set as many as you want, each pointing to different adapters for different databases.

By default, you have the default datastore. So if you don’t set anything here, Sails is already configured to use the Sails Disk adapter as your default adapter, which is what it says here. This is a local disk adapter. Like I said, it writes to your file system, which you will see pretty soon.

The Sails core team and the Sails Disk documentation advise not to use it in production for obvious reasons. You can’t trust it. You might shut down Sails, or there’s an error in the application, and your data will be wiped. So this is mostly suitable for development and testing, like I said, because those data can easily be wiped.

Now, let's see this adapter at work. Okay, so now I'm here in a brand-new Sails app. This is brand new—nothing has been made. So let’s do some quick setup. First, I’m going to go to config/models.js. This is where you do global settings for models.

I want to use a schema, right? So this is just a quick setting you set to true. This means that whatever is in my model, those are the columns or attributes Sails will allow when creating data with that model. Then the migration is just a migration strategy. Don’t worry about that. But I like turning it on for now. I will explain a whole bunch of these in future lessons or courses. But for now, just know we turn on the schema, which you can see in the brilliant documentation on what it does, and also migrate: "alter". This is the default advisable migration strategy when you’re in development.

Next, I’m going to create a model. Let’s create a model called models/User.js. The User model. Going back to my terminal, you type sails generate model, and we’ll call this user. It creates a model for me, which I can see in Visual Studio Code. Sure enough, we have a User model.

Let me add a single definition here—don’t worry about it. We’ll talk more about attributes and these settings later. For now, I just want to demonstrate how the local disk or Sails Disk adapter works. So, let’s add an attribute with type: "string". This takes a string and is enough for this demo.

I’ve opened this project in Guppy, a developer tool for working with Waterline queries and Sails application info. It provides a nice interface with a bunch of features. Now, if I run await User.create({ name: "Kelvin" }) and then fetch it, you’ll see we have a record showing up.

Now, let’s see how this record is represented in our file system. If I go back to Visual Studio Code and look at the .tmp folder, this is where Sails writes Waterline’s Sails Disk data. By default, it’s saved in .tmp/localDiskDb. For every model, there’s an equivalent db file. If you open it, you’ll see the data persisted there.

How easy and convenient is that? You just start up Sails, create a new Sails project, and you don’t need to configure any database. As you continue developing, you might change your mind and want to switch databases. Why waste time deciding when you can just get started with Sails Disk, like I always do? I still use it for all my Sails projects.

That’s how the Sails Disk adapter works. It comes bundled in with every Sails project by default. You don’t need any setup for it. You just create models, use User.create(), User.find(), and all the other Waterline queries. It’s super convenient and perfect for development or testing!