East-surrealdb NPM

Introducing the SurrealDB adapter for east – seamlessly integrate SurrealDB, the cloud-native database designed for modern applications, into your migration workflow. With this adapter, east facilitates smooth database migrations, connecting your application to SurrealDB effortlessly. Streamline your development process, reduce complexity, and ensure secure, high-performance migrations with SurrealDB and east.

🤓 Prerequisites:

To be able to use this you need the surreal.js, east packages installed.

💻 Installation:

pnpm add east-surrealdb
# Or
yarn add east-surrealdb
# Or
npm install east-surrealdb

⚙️ Configuration:

To make it work with your database you need to configure the adapter using the .eastrc file. Here's an example of what it could look like:

!NOTE
Always keep your database credentials safe and secure and never commit them to GitHub. You can do this by storing them in a .env file and adding that file to your .gitignore.

// .eastrc

require('dotenv').config();

module.exports = {
  adapter: "east-surrealdb", // [Required] Tells east to use this adapter
  url: process.env.DB_URL ?? "http://127.0.0.1:8000/rpc", // [Required] The url where your SurrealDB lives at
  credentials: { // [Required] The credentials used to log into SurrealDB
    username: process.env.DB_USERNAME, // [Required]
    password: process.env.DB_PASSWORD, // [Required]
    namespace: process.env.DB_NAMESPACE, // [Required]
    database: process.env.DB_DATABASE, // [Required]
    scope: process.env.DB_SCOPE // [Optional]
  },
  migrationTable: '_migration' // [Optional] Allows you to set a custom name for the table that will contain the migrations
}

🚀 Usage:

For using east I would like to refer you to their documentation!

Create a migration using the east create <name>. With this adapter in use it will generate a migration file that looks like this:

const { Surreal } = require('surrealdb.js')

exports.migrate = async (db) => {
  db = Object.assign(new Surreal(), db)
  
  // Migration instructions
}

exports.rollback = async (db) => {
  db = Object.assign(new Surreal(), db)

  // Rollback instructions
}

Inside the migrate and rollback sections you can write SurrealDB queries using the Surreal instance.

!NOTE I used db = Object.assign(new Surreal(), db) to inject the configuration into a new instance as the instance returned is not a Surreal class but an object. If someone knows a cleaner solution please feel free to PR or let me know.

For example:

// migrations/1_create_test_table.js

const { Surreal } = require("surrealdb.js")

exports.migrate = async (db) => {
  db = Object.assign(new Surreal(), db)
  
  await db.query('DEFINE TABLE test SCHEMAFULL')
  await db.query('DEFINE FIELD name ON TABLE test TYPE string')

  // OR (use transactions)
  
  await db.query(`
    BEGIN TRANSACTION;
    DEFINE TABLE test SCHEMAFULL;
    DEFINE FIELD name ON TABLE test TYPE string;
    COMMIT TRANSACTION; 
  `)
}

exports.rollback = async (db) => {
  db = Object.assign(new Surreal(), db)

  await db.query('REMOVE TABLE test')
}

This example creates a schemafull table named "test" and adds a field named "name" to it with type "string". When rolling back this migration it will "remove" the table making this migration undone.

🤝 Contributing:

Pull requests are welcome! For major changes, please open an issue first to discuss what you would like to change.

⚠️ Disclaimer:

I am not part of or affiliated with the SurrealDB team. I am simply an enthusiast of SurrealDB, eager to share my passion and insights. Any views or opinions expressed are solely my own and do not reflect the official stance of SurrealDB or its developers.

📜 License:

Copyright © 2023, Tim Youri van Herwijnen

Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.